# Windows `cutvideo` 运维与恢复

日期：2026-03-27

## 1. 适用场景

当 StoryForge 局域网前端里 `自动剪辑` 显示 `不可达`，或者 `collector-service` 的 `/v2/integrations/health` 显示：

- `cutvideo.reachable = false`
- `cutvideo.url = http://192.168.31.18:7860/api/bootstrap`

优先按本文处理。

## 2. 当前基线

- Windows 主机：`192.168.31.18`
- SSH 别名：`shuziren-win`
- `cutvideo` 仓库目录：`D:\ai-code\cutvideo`
- 目标服务地址：`http://192.168.31.18:7860`
- 当前常驻方式：Windows 任务计划程序 `\Codex\cutvideo-web`

## 3. 本次故障根因

2026-03-27 这次实际故障不是网络不通，而是运行环境损坏：

- Windows 主机仍在线，`22 / 135 / 139 / 445 / 3389 / 5985` 都可达
- 只有 `7860` 超时
- `D:\ai-code\cutvideo\.venv` 内部仍引用已不存在的 `Python311`
- `start-cutvideo-web-background.ps1` 因为坏掉的 `.venv` 回退失败，导致 Web 服务无法启动

## 4. 快速判断

在 Mac 上执行：

```bash
ssh shuziren-win hostname
curl --max-time 5 http://192.168.31.18:7860/api/bootstrap
```

判断逻辑：

- 如果 SSH 能连，但 `api/bootstrap` 超时，优先怀疑 `cutvideo` 服务没起来
- 如果 `GET /api/uploads` 返回 `405 Method Not Allowed`，这是正常现象，表示接口存在且只接受 `POST`

## 5. 标准恢复步骤

### 5.1 重建 `cutvideo` 虚拟环境

在 Windows 上执行：

```powershell
Set-Location D:\ai-code\cutvideo
$ts = Get-Date -Format 'yyyyMMdd-HHmmss'
if (Test-Path .venv -PathType Container) {
  Rename-Item .venv (".venv-broken-$ts") -Force
}
C:\Program Files\Python312\python.exe -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -c "import cutvideo, typer, fastapi, uvicorn; print(cutvideo.__file__)"
```

预期：

- `pip install -e .` 成功
- 最后的导入检查不报错

### 5.2 直接启动一次 Web 服务

```powershell
powershell -ExecutionPolicy Bypass -File D:\ai-code\cutvideo\scripts\start-cutvideo-web-background.ps1 -Port 7860
```

预期：

- 返回 `PID=<number>`
- `curl http://192.168.31.18:7860/api/bootstrap` 返回 `200`

### 5.3 注册为常驻任务

这一步必须做。否则服务可能随着临时会话结束而退出。

```powershell
powershell -ExecutionPolicy Bypass -File D:\ai-code\cutvideo\scripts\register-resident-services.ps1 -StartNow
```

说明：

- 该脚本会写入 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`
- 当前恢复后额外补了任务计划程序 `\Codex\cutvideo-web`
- 建议后续把 `cutvideo-web` 继续作为主要常驻入口

## 6. 验证步骤

### 6.1 Windows 本机

```powershell
cmd /c "netstat -ano | findstr :7860"
```

预期：

- 出现 `0.0.0.0:7860 ... LISTENING`

### 6.2 Mac / NAS

```bash
curl http://192.168.31.18:7860/api/bootstrap
curl -i http://192.168.31.18:7860/api/uploads
```

预期：

- `/api/bootstrap` 返回 `200`
- `/api/uploads` 返回 `405`

### 6.3 StoryForge collector

调用：

```bash
POST /v2/auth/auto-session
GET /v2/integrations/health
```

预期：

- `cutvideo.reachable = true`
- `cutvideo.supports_uploads = true`
- `upload_status_code = 405`

## 7. 常用命令

Mac 上探测：

```bash
ssh shuziren-win hostname
ssh shuziren-win "cmd /c netstat -ano | findstr :7860"
curl --max-time 5 http://192.168.31.18:7860/api/bootstrap
```

Windows 上日志：

```powershell
Get-Content D:\ai-code\cutvideo\runs\service-logs\cutvideo-web.out.log -Tail 120
Get-Content D:\ai-code\cutvideo\runs\service-logs\cutvideo-web.err.log -Tail 120
Get-Content D:\ai-code\cutvideo\runs\service-logs\resident-supervisor.out.log -Tail 120
Get-Content D:\ai-code\cutvideo\runs\service-logs\resident-supervisor.err.log -Tail 120
```

## 8. 当前已验证状态

截至 2026-03-27：

- `http://192.168.31.18:7860/api/bootstrap` 已恢复
- `GET /api/uploads` 返回 `405`
- StoryForge NAS collector 已恢复识别 `cutvideo` 在线
- 前端工作台应恢复显示 `自动剪辑` 在线