krisolo/storyforge

Fork 0

Files

kris 195a5e5ff6 docs: add windows cutvideo recovery guide

2026-03-27 00:11:15 +08:00

4.0 KiB

Raw Blame History

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 上执行：

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 上执行：

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 -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 -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 本机

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

预期：

出现 0.0.0.0:7860 ... LISTENING

6.2 Mac / NAS

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

调用：

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

预期：

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

7. 常用命令

Mac 上探测：

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 上日志：

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 在线
前端工作台应恢复显示 自动剪辑 在线

4.0 KiB Raw Blame History Unescape Escape

Windows cutvideo 运维与恢复