krisolo/storyforge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
32bc94f924598622439bc632d43c142b25d3e01b
storyforge/docs/LAN_E2E_GUIDE_2026-03-18.md
kris 32bc94f924 feat: codify fnos cutvideo tunnel routing
2026-03-27 13:13:51 +08:00

12 KiB
Raw Blame History

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，用于你在宿主机单独运行 collector-service
  • COLLECTOR_N8N_BASE_URL=http://n8n:5678，用于 Docker 里的 collector
  • ORCHESTRATOR_SHARED_SECRET=your_strong_shared_secret
  • BOOTSTRAP_SUPERADMIN_USERNAME=storyforge-admin
  • BOOTSTRAP_SUPERADMIN_PASSWORD=your_strong_admin_password
  • STORYFORGE_INTERNAL_BASE_URL=http://collector:8081，用于 Docker 内的 n8n 回调 collector
  • CUTVIDEO_BASE_URL=http://<windows-lan-ip>:7860
  • CUTVIDEO_API_KEY= 如果 Windows 服务启用了鉴权
  • HUOBAO_BASE_URL=http://127.0.0.1:5678
  • WHISPER_BIN= 指向你现有本地 ASR 可执行文件时填写
  • ASR_HTTP_BASE_URL= 如果你已有常驻 ASR 服务，填写它的基地址
  • ASR_HTTP_TRANSCRIBE_PATH=/transcribe
  • ASR_HTTP_FIELD_NAME=wav
  • ASR_HTTP_TIMEOUT_SEC=120

说明：

  • 如果你单独重建 collector，要确保运行时仍带上 CUTVIDEO_BASE_URL，否则容器会退回空值
  • collector 容器不要直接复用宿主机的 N8N_BASE_URL=http://127.0.0.1:5670，否则容器内会连回自己并导致 webhook 调度失败
  • 当前更稳定的 NAS 转发地址是 http://192.168.31.188:19186
  • Windows 直连地址 http://192.168.31.18:7860 仍可作为主机内自检入口，但不再建议作为 StoryForge 主链默认值
  • 当前已验证可用的本机 HTTP ASR 入口是 http://host.docker.internal:8088/transcribe
  • 如果你用的是本机 mac-whisper-service，建议同时以 WHISPER_TIMEOUT_MS=120000 启动，否则长视频会直接 504

推荐先执行：

./scripts/deploy_fnos_cutvideo_tunnel.sh

它会做三件事：

  • 在 fnOS 上生成并持久化 Windows SSH 隧道密钥
  • 把 fnOS 公钥写入 Windows OpenSSH 管理员授权文件
  • 在 fnOS 上常驻 19186 -> Windows 127.0.0.1:7860 和 19181 -> Windows 127.0.0.1:8081，并写入 @reboot 自启动

cutvideo 维护补充（2026-03-27）：

  • 当前 Windows 主机 SSH 别名是 shuziren-win，对应 192.168.31.18
  • 如果 http://192.168.31.18:7860/api/bootstrap 超时，但主机 22 / 3389 / 5985 仍可达，优先判断为 cutvideo 服务未启动，不是局域网地址失效
  • 本次已确认的真实故障是 D:\ai-code\cutvideo\.venv 损坏，仍指向已不存在的 Python311
  • 修复后 cutvideo 已改由 Windows 任务计划程序 \Codex\cutvideo-web 托管，避免服务随 SSH 会话结束一起退出
  • 详细恢复步骤见 WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md

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
  • storyforge-content-source-sync.json

导入后：

  • 确认 n8n 运行环境里有 STORYFORGE_INTERNAL_BASE_URL
  • 确认 n8n 运行环境里有 STORYFORGE_ORCHESTRATOR_SECRET
  • 导入后的 HTTP Request 节点应从环境变量取值，不需要再逐个手改 secret

4. 登录与审批

首次启动前请先在 .env 或运行环境里设置 bootstrap 管理员：

  • 用户名：BOOTSTRAP_SUPERADMIN_USERNAME
  • 密码：BOOTSTRAP_SUPERADMIN_PASSWORD

首次启动后，用这组账号登录；新用户注册后，仍然需要超级管理员审批。

5. 内容分析链路验证

文本

调用 POST /v2/explore/text

预期：

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

已验证样例：

  • job_203bc8e9b20f4b1cbbc6cf7da79e46f4

视频链接

调用 POST /v2/explore/video-link

前提：

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

已验证样例：

  • job_bb405e2e878849e38c4bb31f7781e1e3 (artifacts.asr_backend=http)

上传视频

调用 POST /v2/explore/upload-video

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

6. 内容源账号同步验证

调用 POST /v2/pipelines/content-source-sync

推荐最小请求体：

{
  "source_url": "https://space.bilibili.com/546195/video",
  "platform": "bilibili",
  "title": "Bilibili Creator Sync Smoke",
  "max_items": 2,
  "skip_existing": true,
  "auto_trigger_analysis": true
}

预期：

  • 创建一个 content_source_sync 父任务
  • n8n 触发 content_source_sync_pipeline
  • 父任务写回 discovered_videos / child_job_ids / queued_job_ids
  • 子任务以 parent_job_id 挂到父任务下，并自动进入分析主线

已验证样例：

  • 父任务：job_b02109cf9e8244fbb5b86f184a7c7574
  • 子任务：job_7f169db61af441f8a7f186d03db2d91c
  • 子任务：job_28c47774028441378a3974860c375ab7

6.1 douyin 账号工作台验证

基础接口：

  • POST /v2/douyin/accounts/sync
  • POST /v2/douyin/accounts/{account_id}/analysis

说明：

  • profile_url 现在支持直接传分享文案，后端会自动提取里面的 URL
  • 如果 public 页面命中抖音反爬挑战，接口会返回 public_profile_anti_bot_challenge
  • 遇到挑战页时，继续可用的路径是 manual_profile_payload、manual_work_payloads 和 manual_creator_pages

已验证样例：

  • public 页面 smoke：返回 public_profile_anti_bot_challenge
  • 手工导入账号：dyacct_c2b62842b228406cb48f05fac16fdfdf
  • 手工账号分析报告：dyreport_10d6b8d2d52a404192f54a3a05d44546
  • 相似账号搜索：dysearch_c247b75db0df49429a1d127407fe4486
  • 对标关系：dyrel_c8df266341e74237b99c880eb4b572d8

浏览器辅助采集：

cd /Users/kris/code/StoryForge-gitea/scripts/douyin-browser-capture
npm install
npx playwright install chromium
npm run control-panel

浏览器打开：

http://127.0.0.1:3618

控制台步骤：

  1. 填写抖音主页链接和 StoryForge 账号
  2. 如需查看采集结果，不用离开这个页面；下半部分 Douyin Workbench 会展示账号列表、Agent 结论、快照详情和对标结果
  3. 作品工作台 支持高分榜、最新榜和全部作品切换，并支持多种排序方式
  4. 点击“自动分析高分作品”后，每条高分作品下会补齐商业判断、复刻建议、运营动作和风险提醒
  5. 点击 开始采集
  6. 在弹出的 Chromium 里登录或通过挑战页
  7. 回到控制台点击 已完成登录，继续采集
  8. 等待 summary.json 和可选的 storyforge-sync-response.json

命令行方式仍然保留：

cd /Users/kris/code/StoryForge-gitea/scripts/douyin-browser-capture
npm run capture -- \
  --profile-url https://www.douyin.com/user/your_account \
  --storyforge-username storyforge-admin \
  --storyforge-password 'your_admin_password'

说明：

  • 脚本会打开真实 Chromium 会话，默认复用 ~/.storyforge/douyin-playwright 登录态
  • 如果出现扫码登录、滑块或挑战页，先在浏览器里人工完成，再回终端继续
  • 脚本会保存 profile-bundle.json、storyforge-sync-request.json 和同步响应
  • 当前已完成 headless 最小 smoke，输出目录：
    • /tmp/storyforge-douyin-capture-smoke/2026-03-20T06-49-37.705Z-storyforge_test_001
  • 当前已完成本地控制台 smoke，输出目录：
    • /Users/kris/code/StoryForge-gitea/output/playwright/douyin/control-panel/run-mmyzplxp-cw0o7q/2026-03-20T14-24-13.174Z-storyforge_test_001
    • /Users/kris/code/StoryForge-gitea/output/playwright/douyin/control-panel/run-mmyzshsp-c6vdhi/2026-03-20T14-26-27.792Z-storyforge_test_001
  • 控制台模式已经修复“提前点击继续导致 ready 信号丢失”的竞态，早于等待点按钮也不会卡死

7. cutvideo 实拍剪辑链路验证

调用 POST /v2/pipelines/real-cut

当前 MVP 前提：

  • 方式 A：直接传 input_dir，它必须是 Windows cutvideo 机器可访问的目录
  • 方式 B：传 source_job_id，collector-service 会把 upload_video 或已完成的 video_link 源素材自动上传到 Windows cutvideo，再继续发起任务
  • 如果走方式 B，大文件上传超时由 CUTVIDEO_UPLOAD_TIMEOUT_SEC 控制

预期：

  • 任务创建成功
  • 如果用了 source_job_id，任务 artifacts.cutvideo_upload 会记录 Windows staging 结果
  • n8n 调用 collector-service 内部 real-cut step
  • 后端记录 provider_task_id
  • 最终任务写回 cutvideo_run

已验证样例：

  • job_5ebd829c3f2144bca5c941183e75bdcd
  • job_01a6f283cbda42e4ae692b268b811a50 (source_job_id 自动 staging，本机 cutvideo 联调)
  • Windows 返回 task_id=8d8f4a0cd5d9
  • 运行目录 20260318-093520-Windows cutvideo 联调样例

补充说明（2026-03-27）：

  • GET /api/bootstrap 恢复为 200，GET /api/uploads 返回 405 Method Not Allowed
  • 上面的 405 是正常现象，说明上传接口存在且只接受 POST
  • StoryForge collector 的 /v2/integrations/health 已重新识别到 cutvideo.reachable=true、supports_uploads=true
  • fnOS 局域网调试链现在默认走 http://192.168.31.188:19186，不再依赖 Windows 机器直接开放 7860
  • 如果 UI 里 自动剪辑 再次掉线，先按 WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md 检查 Windows 任务计划程序和 .venv

8. 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

补充说明（2026-03-20）：

  • huobao-drama-upstream 已在隔离目录用复制的旧配置和数据库起过实例，/health 正常
  • fresh 图片/视频生成请求已能进入 provider 调用，但当前复制出的图片/视频凭证返回 403 invalid user
  • 同样的 fresh 图片请求已在旧改版隔离实例 http://127.0.0.1:5682 上重放，结论一致，所以当前不是 upstream 回归问题
  • huobao-drama-upstream 现在支持 HUOBAO_TEXT_* / HUOBAO_IMAGE_* / HUOBAO_VIDEO_* 运行时覆盖数据库里的 AI 配置
  • huobao-drama-upstream 已新增 /Users/kris/code/huobao-drama-upstream/scripts/run_storyforge_smoke.sh，可自动复制旧目录配置和数据，在默认 5681 端口起隔离实例并校验 /health
  • 如果你要重新验证 upstream fresh 生成，优先给 huobao 进程补这些环境变量，再复跑即可

推荐覆盖字段：

  • HUOBAO_TEXT_PROVIDER / BASE_URL / API_KEY / MODELS
  • HUOBAO_IMAGE_PROVIDER / BASE_URL / API_KEY / MODELS
  • HUOBAO_VIDEO_PROVIDER / BASE_URL / API_KEY / MODELS
  • 如需强制指定端点，还可补 ENDPOINT / QUERY_ENDPOINT

9. 当前已知卡点

  • 抖音 public 页面直抓会命中反爬挑战；生产接入仍需要 cookie 或人工页面采集协助
  • 小红书账号级内容源还未做真实平台验证
  • huobao-drama-upstream 代码已迁移完成，但 fresh 生成仍受外部图片/视频凭证 403 invalid user 阻塞

10. 旧运行链残留清理

  • 旧运行链残留容器已在 2026-03-20 实际清理完成：
    • storyforge-fastgpt-plugin
    • storyforge-sandbox
    • storyforge-pg
    • storyforge-minio
    • storyforge-redis
    • storyforge-mongo
  • 清理脚本已纳入仓库：
    • /Users/kris/code/StoryForge-gitea/deploy/cleanup_legacy_runtime.sh
  • 脚本会在清理前后校验：
    • http://127.0.0.1:8081/healthz
    • http://127.0.0.1:5670/healthz

11. Android 说明

android-app/ 已确认属于独立 AI Glasses 工程的叠加目录，现已从当前 StoryForge 主仓库拆出。

当前联调范围只包含：

  • collector-service
  • n8n
  • web/storyforge-web-v4
  • scripts/douyin-browser-capture

如果后续需要维护 Android / OTA 链路，请转到独立仓库：

  • Gitea：https://git.hyzq.site/krisolo/ai-glasses
  • 本机工作区：/Users/kris/code/AI-glasses