storyforge/docs/LAN_E2E_GUIDE_2026-03-18.md

StoryForge 本地 / 局域网联调说明

日期：2026-03-18

1. 准备 .env

复制：

cd /Users/kris/code/StoryForge-gitea
cp .env.example .env

至少确认这些变量：

• N8N_BASE_URL=http://127.0.0.1:5670
• ORCHESTRATOR_SHARED_SECRET=storyforge-local-secret
• CUTVIDEO_BASE_URL=http://<windows-lan-ip>:7860
• CUTVIDEO_API_KEY= 如果 Windows 服务启用了鉴权
• HUOBAO_BASE_URL=http://127.0.0.1:5678
• WHISPER_BIN= 指向你现有本地 ASR 可执行文件时填写

说明：

• 如果你单独重建 collector，要确保运行时仍带上 CUTVIDEO_BASE_URL，否则容器会退回空值
• 当前已验证可用的 Windows cutvideo 地址是 http://192.168.31.18:7860

2. 启动基础服务

cd /Users/kris/code/StoryForge-gitea
docker compose up -d --build

检查：

• collector-service：http://127.0.0.1:8081/healthz
• n8n：http://127.0.0.1:5670
• cli-proxy-api：http://127.0.0.1:8317
• 本机 huobao-drama：http://127.0.0.1:5678/health

3. 导入 n8n workflows

从 n8n/workflows/ 导入：

• storyforge-analysis.json
• storyforge-real-cut.json
• storyforge-ai-video.json

导入后：

• 检查每个 HTTP Request 节点的 X-Orchestrator-Secret
• 如果你改了 .env 的 secret，这里必须同步

4. 登录与审批

默认超级管理员：

• 用户名：kris
• 密码：Asd123456.

新用户注册后，需要用超级管理员审批。

5. 内容分析链路验证

文本

调用 POST /v2/explore/text

预期：

• 任务创建成功
• n8n webhook 被触发
• 任务最终进入 completed
• 知识库文档里出现 transcript / style_summary / analysis / storyboards

已验证样例：

• job_203bc8e9b20f4b1cbbc6cf7da79e46f4

视频链接

调用 POST /v2/explore/video-link

前提：

• yt-dlp 可用
• ffmpeg 可用
• ASR 可调用

上传视频

调用 POST /v2/explore/upload-video

预期与视频链接类似，但素材来源为本地上传

6. cutvideo 实拍剪辑链路验证

调用 POST /v2/pipelines/real-cut

当前 MVP 前提：

• input_dir 必须是 Windows cutvideo 机器可访问的目录
• 该目录中的素材已准备好

预期：

• 任务创建成功
• n8n 调用 collector-service 内部 real-cut step
• 后端记录 provider_task_id
• 最终任务写回 cutvideo_run

已验证样例：

• job_5ebd829c3f2144bca5c941183e75bdcd
• Windows 返回 task_id=8d8f4a0cd5d9
• 运行目录 20260318-093520-Windows cutvideo 联调样例

7. huobao-drama AI 视频链路验证

调用 POST /v2/pipelines/ai-video

推荐方式：

• 先完成一个分析任务
• 再把该分析任务的 source_job_id 传给 AI 视频任务

预期：

• 创建 drama
• 每个分镜生成首帧、尾帧
• 每个分镜生成视频
• 最终 job.result.rendered_scenes 有完整结果

已验证样例：

• job_01828c40377747cf914b51be360cc333
• provider_task_id=10
• video.task_id=qvideo-1380265978-1773799215825814468
• 最终视频已回写到 job.result.rendered_scenes[0].video.video_url

8. 当前已知卡点

• cutvideo 端到端“上传素材后自动送到 Windows 机器”还未彻底闭环
• ASR 如果不是命令行模式，而是你现有常驻服务模式，需要再做一次入口绑定
• huobao-drama 目前跑通依赖本地旧改版中的 qnaigc 兼容补丁，下一步要迁到 upstream 仓库