技能｜看门狗守护与自愈SOP

> 来源：本次「<我的知识库>工作台」看门狗 .kb_quit 死局修复（2026-09-28），端到端三场景实测通过。
> 症状：主动关闭程序后，第二天开机再也拉不起来，必须手动删标志文件。

适用场景

桌面应用配一个独立看门狗进程做存活探活与自动拉起（如 FastAPI 服务 + pywebview 壳 + kb_watchdog.pyw）。
需要处理：单实例锁、开机自启（计划任务）、用户主动退出与自动拉起的冲突。
不适用：系统级服务（用 systemd/Windows 服务更合适）。

触发词

看门狗、守护进程、自愈、拉不起来、开机自启失效、kb_watchdog、计划任务、ChenbinKBGuard、.kb_quit 死局、一次性标志、GetTickCount64、单实例锁、端口被占、僵尸实例、end-to-end 守护实测、单条命令跑完、只杀端口 PID

操作步骤

1. 先画出调用关系：谁拉起谁、谁清理标志。典型坑是"清理逻辑只存在于一个不被自启动覆盖的进程里"。
   - 本次结构：计划任务 ChenbinKBGuard（开机启动）→ 直接跑源码 pythonw.exe kb_watchdog.pyw（30s 探活 8765，单实例锁 8767）。
   - 桌面壳 kb_desktop.pyw 里有 _clear_quit()，但计划任务不启动它 ⇒ 它的清理逻辑等于不存在。

2. 一次性标志必须写三条失效兜底（治 .kb_quit 死局）：
   - ① 服务存活即清除：探到 8765 在监听，说明用户又开了，标志作废。
   - ② 早于本次开机即失效：用 GetTickCount64 反推本次开机时刻，标志文件的 mtime 早于它 ⇒ 是上次开机前写的，作废。
   - ③ 超保鲜期失效：超过如 2 小时自动作废（防止写完就关机，第二天成永久否决票）。
   - 三条任一命中即删除标志并正常拉起；不可只在"用户主动退出"那一个分支里清理。

3. 单实例锁：看门狗自己占一个端口（如 8767）做锁，第二个实例探测到即退出，避免两个 watchdog 互相拉起。

4. 探活与拉起：每 30s 探一次业务端口，探不到就 subprocess 拉起主程序；连续失败要给上限或退避，别做成 30s 一次的疯狂重启。

5. 端到端必测三场景（缺一不可，且必须写成脚本单条命令跑完）：
   - A 主进程病死 ⇒ 应在约 30s 内自动拉起（本次实测 27.2s）。
   - B 新鲜 .kb_quit ⇒ 应保持停止、不拉起（尊重用户主动退出）。
   - C 陈旧 .kb_quit ⇒ 应识别为过期、删除标志并恢复服务（本次实测 19.6s，修复前 45s+ 无动静）。

6. 实测三铁律：
   - ① 单条命令跑完——后台进程跨 Bash 命令就被会话回收。
   - ② 绝不批量杀 python 进程（会误伤工具自身与测试脚本自己），只杀占用目标端口的那一个 PID。
   - ③ 诊断期加 -u 免缓冲，否则进程被杀日志全空。
   - 枚举进程用 tasklist /FI ... /FO CSV /NH；误写成 taskkill 会缺 /PID|/IM 报错并返回空列表，导致"一个都没杀到"而结论全是假的。

注意边界

• 看门狗自身不参与界面、不写用户数据，职责只有"探活 + 拉起 + 清陈旧标志"。
• 计划任务跑的是源码，所以改看门狗不需要重新打包；改主程序才需要（见打包技能）。
• 拉起失败要有痕迹（写日志），否则用户只看到"没起来"而无从判断。
• 敏感/本机应用：自启项只作用于当前用户，不写系统级目录。

反例避雷

关联

• 知识库条目：05-技能库/技能｜看门狗守护与自愈SOP.md
• 同源：~/<运行时目录>/skills/web-app-aesthetics-hardening（步骤 O）
• 实证：<项目根目录>\<应用>\kb_watchdog.pyw、_watchdog_e2e.py
• 相关笔记：[[技能｜PyInstaller打包与取证SOP]]、[[技能｜全要素缺陷探针法]]

版本记录