349 lines
13 KiB
Markdown
349 lines
13 KiB
Markdown
# StoryForge 本地 / 局域网联调说明
|
||
|
||
日期：2026-03-18
|
||
|
||
## 1. 准备 `.env`
|
||
|
||
复制：
|
||
|
||
```bash
|
||
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://192.168.31.188:19186`，默认主链走 NAS SSH 隧道
|
||
- `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 主链默认值
|
||
- 只要是 StoryForge 的 fnOS / NAS 联调与交付，优先把 `CUTVIDEO_BASE_URL` 视为 `19186`，把 `7860` 视为 Windows 本机自检口
|
||
- 当前已验证可用的本机 HTTP ASR 入口是 `http://host.docker.internal:8088/transcribe`
|
||
- 如果你用的是本机 `mac-whisper-service`，建议同时以 `WHISPER_TIMEOUT_MS=120000` 启动，否则长视频会直接 504
|
||
|
||
推荐先执行：
|
||
|
||
```bash
|
||
./scripts/deploy_fnos_cutvideo_tunnel.sh
|
||
./scripts/deploy_fnos_storyforge_lan_stack.sh
|
||
./scripts/smoke_fnos_storyforge_lan.sh
|
||
```
|
||
|
||
如果你只想先把底座打通，也可以先跑前两步，再单独 smoke。
|
||
|
||
它们分别负责：
|
||
|
||
- 在 fnOS 上生成并持久化 Windows SSH 隧道密钥
|
||
- 把 fnOS 公钥写入 Windows OpenSSH 管理员授权文件
|
||
- 在 fnOS 上常驻 `19186 -> Windows 127.0.0.1:7860` 和 `19181 -> Windows 127.0.0.1:8081`，并写入 `@reboot` 自启动
|
||
- 把 StoryForge 的 NAS 侧服务统一切到 `http://192.168.31.188:19186` 的默认主链
|
||
- 通过一键 smoke 校验 `cutvideo`、`collector` 和整条 LAN 交付链路
|
||
|
||
`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`](/Users/kris/code/StoryForge-gitea/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md)
|
||
|
||
## 2. 启动基础服务
|
||
|
||
```bash
|
||
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`
|
||
|
||
推荐最小请求体：
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
浏览器辅助采集：
|
||
|
||
```bash
|
||
cd /Users/kris/code/StoryForge-gitea/scripts/douyin-browser-capture
|
||
npm install
|
||
npx playwright install chromium
|
||
npm run control-panel
|
||
```
|
||
|
||
浏览器打开：
|
||
|
||
```text
|
||
http://127.0.0.1:3618
|
||
```
|
||
|
||
控制台步骤：
|
||
|
||
1. 填写抖音主页链接和 StoryForge 账号
|
||
2. 如需查看采集结果，不用离开这个页面；下半部分 `Douyin Workbench` 会展示账号列表、Agent 结论、快照详情和对标结果
|
||
3. `作品工作台` 支持高分榜、最新榜和全部作品切换，并支持多种排序方式
|
||
4. 点击“自动分析高分作品”后，每条高分作品下会补齐商业判断、复刻建议、运营动作和风险提醒
|
||
2. 点击 `开始采集`
|
||
3. 在弹出的 Chromium 里登录或通过挑战页
|
||
4. 回到控制台点击 `已完成登录，继续采集`
|
||
5. 等待 `summary.json` 和可选的 `storyforge-sync-response.json`
|
||
|
||
命令行方式仍然保留：
|
||
|
||
```bash
|
||
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`](/Users/kris/code/StoryForge-gitea/docs/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`
|