第 22-3 篇：vllm_mgr.py——进程守护与看门狗-育师

上一篇：22-2《/admin API——状态、配置、加载、转换》｜下一篇：23-1《国密 SM3——KAT 红线先于实现》

只读验证篇：本文仅板端 --help/status 只读实测；未对运行中的引擎演示 start/stop/kill（诚实边界见文内）

一句话导读：vllm_mgr 进程守护与看门狗：读 start/stop/restart、状态轮询与进程名精确匹配的坑；诚实边界是——本文仅板端只读验证，未对运行中的引擎演示启停操作。

关键词：vllm_mgr、进程守护、看门狗、start/stop、RK3588

admin API 是"手动挡"，tools/vllm_mgr.py是"自动挡"：一个stdlib-only的进程守护，负责 start/stop/restart、状态页、NPU 自检子进程。这篇读它的进程管理逻辑与"精确匹配进程名"的坑，并交代清楚：守护工具本身只该在部署机上跑，教程的启停实验要由你在自己的板上执行——我们这轮没有对着正在服务的引擎演示 kill。

1. 知识点：看门狗要回答的四个问题

进程守护的本质是四个问题：

怎么启动？nohup拉起引擎子进程，日志重定向；
怎么知道它还活着？轮询/health//admin/api/status的 HTTP 状态，而不是只看进程表；
死了怎么办？按配置自动拉起（或至少让你一条命令 restart）；
停？SIGTERM 优雅停 → 超时 SIGKILL，两级降级。

引擎还有一个特殊的"守护需求"：/admin/api/config/save落盘的配置文件是 mgr 的启动依据（vllm_mgr.py第 5–10 行注释：配置由 admin 页写、mgr 按它启停）——这样你在网页上改的配置，重启后依然生效，闭环成立。

2. 对应代码：mgr 的进程语义

tools/vllm_mgr.py头注释（12–25 行）把用法与配置 schema 写得很完整：

usage: vllm_mgr.py [-h] [--serve [SERVE]] [{start,stop,restart,status,selftest,serve}] config schema（由 /admin/api/config/save 写入）: { "model_dir": "...", "wmode": "q4", "port": 8080, "threads": 8, "npu": true, ..., "env": {"OMP_NUM_THREADS": "4"} }

start/stop/restart：nohup+ 进程表管理，stop 先 SIGTERM 再 SIGKILL（15–17 行注释）；
selftest：跑--npu-calib子进程并回读结果；
serve：一个纯 stdlib 的 HTTP 状态页（默认 8082 端口，ThreadingHTTPServer）——admin 页在引擎关机后靠它知道"守护还活着、可以点启动"。

"进程名精确匹配"的坑（本项目文档与代码反复强调）：守护脚本如果用pgrep vllm_kestrel这类宽匹配，很容易把自己的命令行/同名前缀进程算进去（bash -c pkill vllm_kestrel这种自匹配在 Day 11–17 的板端实验里反复出现，退出码被误杀成 -1）。成熟做法是匹配完整可执行路径或精确进程名 + PID 白名单，并在stop前先确认 PID 属于引擎而不是守护自身。

3. 改动后果：工具实测与"不该做什么"

实测口径：板端 RK3588 / 2026-09-07。只做只读实测。

$ python3 tools/vllm_mgr.py --help usage: vllm_mgr.py [-h] [--serve [SERVE]] [{start,stop,restart,status,selftest,serve}] vllm_kestrel supervisor positional arguments: {start,stop,restart,status,selftest,serve} options: -h, --help ... --serve [SERVE] run the HTTP supervisor (default port 8082)

为什么这轮不演示 start/stop：引擎正在为本系列的 HTTP/多模态实验服务（22-2 的uptime_s还在涨）。对着活引擎演示 kill → 拉起，会打断实验且无收益；守护语义的正确验证方式是在独立的部署机上（或专门开一个测试端口实例）执行。留给学员的任务里包含完整步骤。这一节本身想强调的"改动后果"是反面纪律：如果你在共享/生产实例上随手vllm_mgr.py restart，会踩中三类问题——配置没save导致重启后配置回滚、宽匹配误杀守护自身、以及 SIGKILL 时 KV/磁盘状态没落盘（Day 12 的 disk-kv 恢复机制就是为这种断电场景兜底的）。

4. 学员调试任务

A 档（板端动手，需独立实例）：

复制一份引擎与模型配置，用--port 8802起第二个测试实例（不碰生产实例）；
用vllm_mgr.py status看它如何判定"活着"（读源码找它探的是哪个端点/文件）；
stop→ 观察日志里的 SIGTERM 收尾输出 →start→status确认拉起；再模拟一次kill -9 <pid>看守护（或手动 restart）如何恢复；
故意把pgrep匹配改宽（如pgrep -f vllm），复现"误杀守护自身"的坑并记录。

B 档（纯读源码）：读vllm_mgr.py的 stop/start 与状态判定，回答：① stop 的 SIGTERM→SIGKILL 两级降级在什么条件下触发、为什么不能只用 SIGKILL？②serve模式的状态页与引擎/admin状态页是什么关系（谁依赖谁）？③ mgr 与/admin/api/config/save的"写配置 → 按配置启动"闭环里，如果配置文件损坏（JSON 解析失败），mgr 会怎么处理——读代码找错误分支。

预期输出：一次在独立实例上完成的 start/stop/restart 闭环日志，外加一张"守护设计四问"的自我检查表。