🐛 调试与运行指南

覆盖前端 Vue 调试、后端 Flask 调试、SSE 流式通信调试、常见问题排查。

一、本地开发工作流

推荐：双终端并行

终端 1：npm run dev --host（前端热更新，改动即生效）
终端 2：python3 backend/app.py（后端 API，改后需重启）

VSCode 终端面板支持分栏（点击右上角分割图标）

二、前端调试

2.1 Vue Devtools

安装浏览器扩展：Vue.js Devtools（Chrome 扩展商店搜索安装）
打开后可在 Components 面板查看组件状态、Props、响应式数据
可在 Console 中直接执行 $vm0 查看当前组件实例

2.2 浏览器调试技巧

// Console 中常用调试命令
// 查看 Vue 应用实例（如果已挂载）
document.querySelector("#app").__vue_app__

// 查看 Pinia store 状态
// 在组件中：import { useAppStore } from "@/stores/app"

// 查看 API 请求
fetch("/api/models").then(r => r.json()).then(console.log)

// 查看本地存储
localStorage.getItem("ascent_theme")
localStorage.getItem("workshop_prefs")

2.3 常见样式调试

问题	排查方法
样式不生效	检查 Tailwind 类名拼写，确认样式在 style.css 中有定义。调试时用浏览器 Elements 面板查看 computed 样式。
build 后 CSS 丢失	检查 style.css 中的类是否被 Tailwind purge 掉，可在 safelist 中配置或使用 @layer components。
白天模式异常	检查 style.css 中 html:not(.dark) 覆写是否完整，检查 localStorage 中 ascent_theme 值。

三、后端调试

3.1 日志查看

# 查看 Flask 实时日志
tail -f /root/models_20260529220733/ai-creator-platform/backend/app.log

# 查看所有后端日志
tail -f /root/models_20260529220733/ai-creator-platform/backend/backend.log

# 搜索错误
grep -i "error\|exception\|traceback" *.log

3.2 API 测试

# 测试服务器是否存活
curl http://localhost:5000/api/models

# 测试 LLM 对话
curl -X POST http://localhost:5000/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3_coder_30b","messages":[{"role":"user","content":"你好"}]}'

# 测试生成图片
curl -X POST http://localhost:5000/api/image/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一只猫","model":"sdxl"}'

# 测试视频生成
curl -X POST http://localhost:5000/api/video/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"bunny eating carrot","duration":5}'

3.3 常见后端问题

端口被占用：netstat -tlnp | grep 5000 查看占用进程，kill 后重启。

数据库锁定：SQLite 写操作时如果服务意外退出，可能产生锁文件，删除 *.db-shm / *.db-wal 后重启。

LLM 连接超时：检查 GPU 机是否在线 curl http://123.58.111.244:3990/v1/models。

跨域错误：前端开发服务器（5173）调后端 API（5000）会有 CORS 问题，Flask 已配置 CORS，如遇问题检查 Flask-CORS。

四、SSE 流式调试

4.1 SSE 协议说明

SSE (Server-Sent Events) 用于 AI 对话的消息流式输出。后端逐 token 返回，前端实时渲染。

Content-Type: text/event-stream
每行格式：data: {"token":"你好","done":false}
结束标记：data: {"done":true}

4.2 调试 SSE 连接

# 方法一：curl 直接测试（不自动解析 SSE）
curl -N -X POST http://localhost:5000/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3_coder_30b","messages":[{"role":"user","content":"你好"}],"stream":true}'

# 方法二：查看浏览器 Network 面板
# 在浏览器 DevTools -> Network -> 找到 /api/chat/completions -> Response 标签
# 切换到 EventStream 标签查看每个事件

4.3 常见 SSE 问题

连接中断：检查后端日志是否有报错，GPU 机 vLLM 是否正常。Nginx 代理下 SSE 需关闭缓冲 proxy_buffering off。

UI 不刷新：检查前端 EventSource / fetch 的流式处理逻辑是否正确。

乱码：确认 vLLM 和 Flask 端均使用 UTF-8 编码。

五、Git 提交工作流

# 查看当前状态
git status

# 查看改动内容
git diff

# 添加并提交
git add .
git commit -m "描述改了什么"

# 推送到 Gitee
git push origin main

# 拉取最新代码
git pull origin main

', 1, 'admin', '学习专区,调试,SSE,API,Ascent Creator', datetime('now', '+8 hours') )

调试与运行指南 | 前端 + 后端 + SSE 流式调试