From 195a5e5ff61896dc4d16c10d6aca1ba5b493128d Mon Sep 17 00:00:00 2001 From: kris Date: Fri, 27 Mar 2026 00:11:15 +0800 Subject: [PATCH] docs: add windows cutvideo recovery guide --- README.md | 1 + docs/LAN_E2E_GUIDE_2026-03-18.md | 15 ++ .../WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md | 158 ++++++++++++++++++ 3 files changed, 174 insertions(+) create mode 100644 docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md diff --git a/README.md b/README.md index 4201c28..7497ebc 100644 --- a/README.md +++ b/README.md @@ -198,3 +198,4 @@ N8N_BASE_URL=http://127.0.0.1:5670 - `cutvideo` 继续运行在 Windows 机器，本系统通过 API 调度 - `huobao-drama` 继续作为 AI 生成视频主链的核心引擎 - 详细审计、阶段计划和联调步骤见 `docs/` +- Windows `cutvideo` 的恢复与常驻维护见 [`WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md`](/Users/kris/code/StoryForge-gitea/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md) diff --git a/docs/LAN_E2E_GUIDE_2026-03-18.md b/docs/LAN_E2E_GUIDE_2026-03-18.md index 162bd10..e36be5b 100644 --- a/docs/LAN_E2E_GUIDE_2026-03-18.md +++ b/docs/LAN_E2E_GUIDE_2026-03-18.md @@ -36,6 +36,14 @@ cp .env.example .env - 当前已验证可用的本机 HTTP ASR 入口是 `http://host.docker.internal:8088/transcribe` - 如果你用的是本机 `mac-whisper-service`，建议同时以 `WHISPER_TIMEOUT_MS=120000` 启动，否则长视频会直接 504 +`cutvideo` 维护补充（2026-03-27）： + +- 当前 Windows 主机 SSH 别名是 `shuziren-win`，对应 `192.168.31.18` +- 如果 `http://192.168.31.18:7860/api/bootstrap` 超时，但主机 `22 / 3389 / 5985` 仍可达，优先判断为 `cutvideo` 服务未启动，不是局域网地址失效 +- 本次已确认的真实故障是 `D:\ai-code\cutvideo\.venv` 损坏，仍指向已不存在的 `Python311` +- 修复后 `cutvideo` 已改由 Windows 任务计划程序 `\Codex\cutvideo-web` 托管，避免服务随 SSH 会话结束一起退出 +- 详细恢复步骤见 [`WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md`](/Users/kris/code/StoryForge-gitea/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md) + ## 2. 启动基础服务 ```bash @@ -235,6 +243,13 @@ npm run capture -- \ - Windows 返回 `task_id=8d8f4a0cd5d9` - 运行目录 `20260318-093520-Windows cutvideo 联调样例` +补充说明（2026-03-27）： + +- `GET /api/bootstrap` 恢复为 `200`，`GET /api/uploads` 返回 `405 Method Not Allowed` +- 上面的 `405` 是正常现象，说明上传接口存在且只接受 `POST` +- `StoryForge collector` 的 `/v2/integrations/health` 已重新识别到 `cutvideo.reachable=true`、`supports_uploads=true` +- 如果 UI 里 `自动剪辑` 再次掉线，先按 [`WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md`](/Users/kris/code/StoryForge-gitea/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md) 检查 Windows 任务计划程序和 `.venv` + ## 8. `huobao-drama` AI 视频链路验证 调用 `POST /v2/pipelines/ai-video` diff --git a/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md b/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md new file mode 100644 index 0000000..0588729 --- /dev/null +++ b/docs/WINDOWS_CUTVIDEO_OPERATIONS_2026-03-27.md @@ -0,0 +1,158 @@ +# 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=` +- `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` 在线 +- 前端工作台应恢复显示 `自动剪辑` 在线