# 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 验证整条链路是否可用。

推荐默认顺序：

```bash
./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 命令

```bash
./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 重启后出现“短时间都不通”

先按默认顺序重新跑：

```bash
./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，再看详细日志