krisolo/storyforge

Fork 0

Files

kris b35d653610 feat: stabilize fnos lan delivery flow

2026-03-27 13:49:30 +08:00

3.7 KiB

Raw Blame History

StoryForge fnOS / NAS LAN Delivery Runbook

日期：2026-03-27

目标

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

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

默认链路

先把 Windows cutvideo 通过 fnOS 的 SSH 隧道暴露到 NAS。
再让 StoryForge 的 NAS 侧服务统一指向 NAS 隧道地址。
最后用一键 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，再看详细日志

3.7 KiB Raw Blame History Unescape Escape