D131: 经验库封装 · Seedance全链路5个bug修复记录 + 数据路径修复

.workbuddy/skills/guanghuclip-video-generate/references/EXPERIENCE_BANK.md

@@ -0,0 +1,53 @@
+---
+name: guanghuclip-video-generate
+type: reference
+topic: 经验库 · Bug修复记录
+tcs: ICE-GL-ZY001
+created: D131 · 2026-06-12
+---
+
+# 光湖视频AI · 经验库
+
+每次踩坑修好后的经验记录，铸渊后续遇到类似问题可检索。
+
+## D131 — Seedance 视频生成全链路调试
+
+### Bug 1: 模型名不对 → API 404
+- **症状**: 调用火山方舟返回 `404 The model or endpoint XXX does not exist`
+- **根因**: 模型名格式错误。不是 `seedance-2-0` 也不是 `seedance-1-5-pro`，正确格式是 `doubao-seedance-2-0-260128`
+- **修复**: 修改 `.env` 的 `JIMENG_MODEL` 和 `video-api-adapter.js` 默认值
+- **经验**: 火山方舟的所有模型名都以 `doubao-` 开头，后面跟版本号日期。去控制台看开通页面的完整模型ID。
+
+### Bug 2: 安心体验模式额度耗尽
+- **症状**: `Your account has reached the set inference limit ... model service has been paused`
+- **根因**: 火山方舟开通模型时默认勾选「安心体验」，免费额度极低（几次调用后即耗尽）
+- **修复**: 去控制台关闭安心体验模式，切换到付费套餐
+- **经验**: 开通任何模型服务后第一步就是关安心体验。想用免费额度测试 = 第一次就烧光。
+
+### Bug 3: API返回了视频URL但代码拿不到
+- **症状**: 任务状态 `succeeded`，但代码报 `任务完成但未返回视频地址`
+- **根因**: Seedance 2.0 返回结构是 `{ content: { video_url: "..." } }`，代码只检查了 `output.video_url`、`data.data?.output?.video_url` 等旧格式
+- **修复**: 在 `queryTask()` 的 videoUrl 提取链最前面加 `data.content?.video_url`
+- **经验**: API版本升级时响应结构会变。每次换模型版本，先用 debug 脚本打完整返回确认字段路径。
+
+### Bug 4: 前端请求 /data/videos.json 拿不到JSON
+- **症状**: guanghuclip.cn 页面卡"加载中..."，JSON返回HTML
+- **根因**: videos.json 在 `/root/guanghuclip/frontend/public/data/`，但前端请求 `/data/videos.json`。Nginx root 是 `/root/guanghuclip/frontend/`，所以 `/data/` 映射到 `/frontend/data/` 而不是 `/frontend/public/data/`。`try_files $uri $uri/ /index.html` 兜底回SPA的HTML。
+- **修复**: `cp /root/guanghuclip/frontend/public/data/videos.json /root/guanghuclip/frontend/data/videos.json`
+- **经验**: 前端 fetch 路径要对照 Nginx root 确认文件实际位置。`public/` 是 Vite 构建时的约定，构建后文件在 dist 里。但如果直接部署源码不走构建，就要手动对齐路径。
+
+### Bug 5: Gatekeeper exec 超时
+- **症状**: `curl` Gatekeeper `/exec` 端点一直 timeout，但 `/health` 正常
+- **根因**: 本地代理 `127.0.0.1:55931` 阻断新加坡直连
+- **修复**: 所有 Gatekeeper curl 加 `--noproxy '*'`
+- **经验**: 新加坡四台服务器都有这个问题。记住 `--noproxy '*'` 是必备参数。广州不阻断可不加。
+
+### 工具链验证
+```
+✅ 腾讯文档 MCP → DeferExecuteTool(mcp__tencent-docs__get_content) → 读分镜
+✅ hldp-prompt.js → 台词→Seedance提示词转换
+✅ video-api-adapter.js → 提交任务 + 轮询 + 下载
+✅ Gatekeeper → curl --noproxy '*' → SG exec → 文件部署
+✅ sed 就地修改 → 更新 videos.json videoUrl
+⚠️ 前端部署 → Nginx root路径 + fetch路径对齐（已踩坑）
+```