# ComfyUI + MiniMax H3 远程服务器运维记录

> 服务器：192.168.31.25（SSH: zyw）｜ 记录日期：2026-08-24
> 本文记录 GPU 掉总线问题的完整排查过程、已生效的修复、启动脚本清单与操作要点。

---

## 一、环境概况

| 项目 | 详情 |
|---|---|
| 主板 | 尔英 ERYING Polestar Z690 M-ATX D4（**MoDT 方案**：移动 CPU i5-12600HX + 台式主板） |
| 电源 | 金牌 850W |
| GPU | RTX 5060 Ti 16GB（GB206） |
| 驱动 | **610.43.02**（open 内核模块，apt 安装 `nvidia-driver-610-open`） |
| 系统 | Ubuntu 24.04，内核 6.8.0-138，32GB RAM，NVMe 1.2TB |
| ComfyUI | 0.32.0（/home/zyw/ComfyUI，venv，端口 8189） |
| Docker | mumuainovel + postgres（restart=always，随系统自启） |

## 二、软件栈

- **H3 模型**：fl2va / ref2va（int8_convrot + w4a8_mixed 各一份）、qwen3vl_32b NVFP4 TE、video/audio VAE、3D latent upscaler、turbo LoRA（4step / 8step）
- **LTX 2.5**：22B distilled（nvfp4 + int8）+ 音频/视频 VAE + latent 放大
- **导演台**：ComfyUI_MiniMaxH3_Director（官方 main 分支，懒加载依赖齐全）
- 20+ 自定义节点（KJNodes、Spectrum、SolAttn、Impact、VideoHelperSuite 等）

## 三、核心问题：GPU 掉总线（已解决 ✅）

### 症状
ComfyUI 运行中随机出现 `CUDA error: unspecified launch failure` → 进程崩溃（`Fatal Python error: Aborted`）→ **GPU 从 PCIe 总线消失**（`nvidia-smi` 报 "No devices were found"）→ 必须重启/断电才能恢复。

三次崩溃记录（证明与启动参数无关）：
| 运行 | 配置 | 结果 |
|---|---|---|
| t2v 0.4MP×25步 | v5（全参数 + disable-pinned） | 💥 15 分钟崩 |
| rv2v 350帧 + Refine 2MP | v5 | 💥 采样中崩 |
| rv2v 350帧 + Refine 1MP（第2次） | **裸配置（零参数）** | 💥 2/8 步崩 |

### 排查过程
1. 尝试 PCI 重扫（`/sys/bus/pci/rescan`）、根端口重绑定 → **无效**
2. 驱动 595.84 → 610.43.02（apt 升级）→ 掉卡频率降低（连续跑 3 条重负载才崩，之前 1-2 条），但未根治
3. **关键发现**（`lspci -vv`）：
   ```
   LnkCap: Speed 32GT/s (Gen5), Width x16   ← 插槽能力
   LnkSta: Speed 2.5GT/s (Gen1, downgraded) ← 空闲时实际链路
   ```
   实测：**低负载 Gen1（2.5GT/s）↔ 高负载 Gen5（32GT/s）动态切换**，且 BIOS 设 Gen4 无效（被驱动运行时重协商覆盖）

### 根因
**NVIDIA 驱动的动态链路速率管理（Dynamic Power Management）在 MoDT 主板上导致 PCIe 链路 Gen1↔Gen5 反复震荡 → GSP 固件检测到链路不稳定 → 锁死 → GPU 掉总线。**
（社区同款实锤：RTX 5060 Ti + nvidia-open 595.x 的 GSP crash 报告、eGPU 论坛 SOLVED 帖）

### 修复（已生效 ✅）
在 `/etc/modprobe.d/nvidia.conf` 追加：
```
options nvidia NVreg_DynamicPowerManagement=0x00
```
然后 `sudo update-initramfs -u` + 重启。

**验证结果**：负载后链路**保持 32GT/s 不再掉回 Gen1**；连续多轮重负载生成（3 段 508 帧 + Refine）**零崩溃**，输出 89+ 条视频。

## 四、启动脚本清单（/home/zyw/）

| 脚本 | 状态 | 说明 |
|---|---|---|
| `start_comfyui_v2.sh` | 旧档 | 基础优化（--lowvram 等） |
| `start_comfyui_v3.sh` | 旧档 | 含有害参数（--cache-none / --disable-smart-memory），勿用 |
| `start_comfyui_v4.sh` | 旧档 | v2 + --fast-disk |
| `start_comfyui_v5.sh` | **已缴械** | 内含 --disable-pinned-memory，会报错提示用 v6 |
| `start_comfyui_v6.sh` | **推荐提速档** | v5 去掉 --disable-pinned-memory：`--force-fp16 --reserve-vram 1.0 --use-sage-attention --fast-disk --cache-lru 20 --preview-method none` |
| `start_comfyui_bare.sh` | **当前调试档** | 仅 `--listen 0.0.0.0 --port 8189`，零优化参数，最保守 |

> 备注：`--disable-pinned-memory` 曾被误判为元凶（v6 跑通 t2v 时），实际裸配置也崩，真凶是链路震荡。

## 五、操作要点

### 崩溃恢复流程
1. GPU 掉卡 → `sudo reboot`
2. 若 PCI 枚举消失（`lspci` 无 Nvidia）→ 需**完全断电**（`sudo shutdown -h now` + 手动开机）
3. 开机后 `bash /home/zyw/start_comfyui_bare.sh` 启动

### 监控命令（只读，不干扰运行）
```bash
pgrep -f "ComfyUI/venv/bin/python main[.]py" | wc -l        # 进程存活
nvidia-smi --query-gpu=utilization.gpu,memory.used,temperature.gpu --format=csv,noheader
grep -cE "Fatal Python|launch failure" /home/zyw/comfyui_h3.log  # 崩溃签名（应为 0）
lspci -vv -s 01:00.0 | grep LnkSta   # 链路速率（修复后应保持 32GT/s）
```

### 显存 OOM 对策（1MP×15s 目标）
- 工作流：`head_chunks=8` + ChunkFF 开启 + 分辨率 1280×736（0.94MP）起步
- 导演台官方 25 步路径峰值 ~14GB/15.46GB，16GB 上保持 0.4-0.5MP 档
- 降级阶梯：1344×768 → 1280×736 → 1152×640 → 960×544；15s → 10s → 5s

### rv2v 提示词经验
- 人物锁定：`<Picture N>` 标签**前置** + "Subject lock: ... only person in every frame" + **`ref_image_size=max`**（身份保真）
- 去字幕：显式列出 `lyrics subtitles, captions, all on-screen text`（只说 no text 不够）
- **已知限制**：rv2v "只去水印不换人" 是社区 issue #39（控制力衰减，未解决）；身份替换推荐 **ReActor 换脸后处理**（保表演/嘴型）

### 其他
- 模型缺失下载源（hf-mirror）：lightx2v/Minimax-h3-Turbo（turbo LoRA）、Kijai/MiniMax-H3-experimental（w4a8）、LBH-123-AI/Minimax_h3_latent_Upscaler（3D 放大）
- ComfyUI 落后 origin/master 57 提交，**暂不更新**（稳定优先，含无关大功能）
- 不要改回 595 驱动 / 不要加 --disable-pinned-memory / 不要关 DynamicPowerManagement

## 六、当前状态（2026-08-24 记录时）
- ✅ 610.43.02 + DPM 禁用，链路稳定 Gen5
- ✅ 连续多轮重负载生成零崩溃
- ComfyUI 裸配置运行中（本记录完成后已停用，需要时用 start_comfyui_bare.sh 或 v6 重启）

---

## 2026-09-03 大版本升级（ComfyUI 0.32 → 0.34 + 导演台全家桶）

### 背景
- 用户反馈：Director 面板改画面比例(9:16)不生效，提交始终为 16:9 默认 864×480（旧版面板回写缺陷）；要求放弃旧 V18 工作流，拉取上游最新并配置模型。

### 升级清单（GPU 机 192.168.31.25）
| 组件 | 旧 | 新 | 说明 |
|---|---|---|---|
| ComfyUI repo | bd34f338 (v0.32.0, 08-12) | **ec803fc9 (v0.34.0, master 09-02)** | 落后 97 提交 → 已 reset --hard origin/master |
| comfyui-frontend-package | 1.48.7 | **1.51.9** | pip 升级 |
| ComfyUI_MiniMaxH3_Director | a267324 (08-20) | **b8f721c (09-02)** | git reset --hard origin/main（本地 __init__.py 改动被覆盖回官方：重新注册 MiniMaxH3Director） |
| ComfyUI-DaSiWa-Nodes | 08-28 (zip) | **08-29 zip (main)** | 目录整体替换 |
| comfyui-workflow-templates | 0.11.40 | 0.11.52 | pip |
| comfy-aimdo / comfy-kitchen / av | 0.4.13 / 0.2.30 / ≥16 | **0.4.15 / 0.2.31 / 18.0.0** | pip（**torch 未动**） |

### 备份/回滚
- 节点包备份：`~/comfy_backup_20260903/ComfyUI_MiniMaxH3_Director.tgz`、`ComfyUI-DaSiWa-Nodes.tgz`
- ComfyUI repo：git 本身可回退（`git reset --hard bd34f338`）；另有 stash@{0}（nodes_minimax_h3.py 试验补丁，未应用，保留）
- 启动方式不变：`venv/bin/python main.py --listen 0.0.0.0 --port 8189`（日志 /home/zyw/comfyui_h3.log，pip 日志 pip_upgrade_20260903.log）

### 模型核对（新官方示例工作流引用的文件，本机全部存在 ✓）
- UNET：`minimax_h3_fl2va_pruned_int8_convrot.safetensors`（t2v）/ `minimax_h3_ref2va_pruned_int8_convrot.safetensors`（r2v/加速版）
- CLIP：`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`（type 必须选 `minimax`）
- VAE：`minimax_h3_video_vae_fp16.safetensors` + `minimax_h3_audio_vae_fp32.safetensors`

### 新工作流位置
- 官方示例（9 个）：`/home/zyw/ComfyUI/custom_nodes/ComfyUI_MiniMaxH3_Director/example_workflows/`
- 已拷入网页可直接打开：`/home/zyw/ComfyUI/user/default/workflows/H3Director官方-20260903/`
  - t2v（文生视频/默认 124帧≈5s@24fps）、r2v（参考图生视频）、fl2v、v2v、rv2v、i2v/r2v external_groups、二采_加速、加速版

### ⚠️ 架构变化（重要）
- **新版 MiniMaxH3Director 输入 schema 已重构**：required 变为 `model/clip/video_vae/audio_vae/task_type/timeline_data/global_prompt/width/height/total_frames/...`，不再是旧的 `mode/prompt/builder_state/minimax_director_ui/width/height/...`
- **旧 V18 API 模板（v18_api_template.json / dsw-v18-generate skill / dasiwa-h3-research 脚本）与新版不兼容**，直接提交会 validation 失败；需按新 schema + 新示例工作流迁移后才可恢复无头调用
- 使用注意：打开新工作流后浏览器需**硬刷新（Ctrl+F5）**加载新前端；CLIP type=minimax

## 2026-09-14 晚：LLM 全停 → ComfyUI 拉起
- 操作：`bash ~/stop-ridge.sh` + `sudo pkill -f "llmste[r]"`；显存 15696 MiB → 18 MiB
- ComfyUI 启动：稳定档（LOW_VRAM、无 sage attention），PID 187454，日志 `/home/zyw/comfyui_8189_opt.log`
- 验证：`/system_stats` HTTP 200，RTX 5060 Ti 空闲显存 ~16.47GB（ComfyUI 常驻 ~156 MiB）

## 2026-09-25 11:00：GPU 机重启后 ComfyUI 自动恢复
- GPU 机于 10:57:36 重启（本次会话发现 uptime 仅数分钟）；LLM 未运行，无显存冲突
- 重启后 ComfyUI 已被机器上的启动脚本拉起（命令含 `--cache-lru 2 --disable-pinned-memory --enable-manager`，来自 `~/restart_comfy.sh` / `start_comfyui_v5.sh` / `v6`，并伴随 `ram_guard.sh`）
- ⚠️ 冷缓存启动慢：约 4 分钟才监听端口，进程长时间处于 D 状态（`__wait_on_buffer`，扫描模型头部 IO）；dmesg 无 IO 错误。**重启后请耐心等待 3~5 分钟再访问 8189**
- 验证：HTTP 200、端口监听、显存 free 9991MB/15866MB；启动时已有 1 个 H3 任务在跑（MiniMaxH3TEModel 已加载，GPU 30%）