storyforge/docs/FNOS_LAN_DELIVERY_RUNBOOK_2026-03-27.md

StoryForge fnOS / NAS LAN Delivery Runbook

日期：2026-03-27

目标

这份 runbook 统一说明 StoryForge 在 fnOS / NAS 局域网交付时的默认主链。

默认原则只有一条：NAS SSH 隧道是主链，Windows 7860 只做自检。

默认链路

1. 先把 Windows cutvideo 通过 fnOS 的 SSH 隧道暴露到 NAS。
2. 再让 StoryForge 的 NAS 侧服务统一指向 NAS 隧道地址。
3. 最后用一键 smoke 验证整条链路是否可用。

推荐默认顺序：

./scripts/deploy_fnos_cutvideo_tunnel.sh
./scripts/deploy_fnos_storyforge_lan_stack.sh
./scripts/smoke_fnos_storyforge_lan.sh

默认端口

• Windows cutvideo 自检口：http://192.168.31.18:7860
• NAS 主链 cutvideo 入口：http://192.168.31.188:19186
• NAS 兼容/上传入口：http://192.168.31.188:19181
• StoryForge collector：http://127.0.0.1:8081
• fnOS 内部 n8n：http://127.0.0.1:5670

默认路由

• StoryForge 的 CUTVIDEO_BASE_URL 默认应指向 http://192.168.31.188:19186
• 19186 是交付主链，不要再把 7860 当成 StoryForge 默认主入口
• 7860 仅用于确认 Windows 上的 cutvideo 服务本身是否活着
• 如果任务涉及上传或 staging，再顺带确认 19181 可达

重启后验证

Windows 重启后

• 先确认 22 / 3389 / 5985 仍可达
• 再检查 http://192.168.31.18:7860/api/bootstrap
• 如果 7860 超时，但管理通道正常，优先判断为 cutvideo 服务未起来
• 如果 7860 可达，再确认 Windows 任务计划程序 \Codex\cutvideo-web 仍在托管服务

fnOS 重启后

• 先跑 ./scripts/deploy_fnos_cutvideo_tunnel.sh
• 再跑 ./scripts/deploy_fnos_storyforge_lan_stack.sh
• 确认 19186 和 19181 都重新可达
• 确认 StoryForge collector 仍然把 CUTVIDEO_BASE_URL 指向 19186

StoryForge 服务重启后

• 检查 collector 还能正常返回 health
• 检查 NAS 侧服务没有回退到 Windows 直连 7860
• 检查 smoke 是否还能把 real-cut 链路跑通

Smoke 命令

./scripts/smoke_fnos_storyforge_lan.sh

这条 smoke 应该至少覆盖：

• 19186 可达
• 19181 可达
• cutvideo 在线
• StoryForge NAS 侧链路可用

故障分流

1. 19186 不通

先看 fnOS 的 SSH 隧道是否还在：

• 重新执行 ./scripts/deploy_fnos_cutvideo_tunnel.sh
• 确认 Windows 主机可连
• 再确认 Windows 7860 本身是否正常

2. 7860 不通，但 22 / 3389 / 5985 还通

这通常是 Windows 上的 cutvideo 没启动，不是网络地址失效。

优先检查：

• Windows 任务计划程序 \Codex\cutvideo-web
• D:\ai-code\cutvideo\.venv
• http://192.168.31.18:7860/api/bootstrap

3. 19186 通，但 StoryForge 链路失败

说明隧道大概率是好的，问题更可能在 NAS 侧服务配置。

优先检查：

• ./scripts/deploy_fnos_storyforge_lan_stack.sh 是否已重新跑过
• CUTVIDEO_BASE_URL 是否仍然是 http://192.168.31.188:19186
• collector 是否回退到了 Windows 直连 7860

4. 19186 和 7860 都正常，但 smoke 失败

优先看失败点属于哪一层：

• 只是 collector health 失败，先看 NAS 侧服务
• 只是上传失败，先看 19181
• 只是 cutvideo 任务失败，先看 Windows 服务日志

5. Windows 或 fnOS 重启后出现“短时间都不通”

先按默认顺序重新跑：

./scripts/deploy_fnos_cutvideo_tunnel.sh
./scripts/deploy_fnos_storyforge_lan_stack.sh
./scripts/smoke_fnos_storyforge_lan.sh

如果这三步后仍失败，再进入对应故障分流。

维护原则

• 默认主链永远是 NAS SSH 隧道
• Windows 7860 只做自检，不做 StoryForge 默认入口
• 交付时先保证 19186 稳，再谈其他端口
• 新人接手时，先跑 smoke，再看详细日志