159 lines
4.0 KiB
Markdown
159 lines
4.0 KiB
Markdown
# 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` 在线
|
||
- 前端工作台应恢复显示 `自动剪辑` 在线
|