从一次生产事故说起

凌晨 3 点，某电商促销活动的 Agent 自动化系统突然失联。事后日志显示：网关守护进程因 OOM 崩溃后，虽然 Supervisor 尝试重启，但由于未正确处理遗留的 TCP 半连接状态，导致新进程持续被 RST 包阻断。这种因心跳检测与恢复机制不完善引发的级联故障，正是分布式 Agent 系统的高频痛点。

守护进程崩溃的四种死法

1. 资源泄漏型：未释放的 GPU 显存或文件描述符积累，典型如 Python 装饰器未正确关闭 TensorFlow 会话
2. 依赖反噬型：下游 API 响应超时导致线程池阻塞，最终耗尽工作线程（常见于未设置 requests 库超时参数）
3. 状态污染型：崩溃前未持久化的内存状态（如对话上下文）被新进程错误继承
4. 僵尸进程型：子进程未正确回收形成僵尸，占用 PID 空间

Heartbeat 设计的五个关键维度

1. 存活检测的拓扑感知

• 传统方案：简单的 GET /ping 接口检测（易被 Nginx 健康检查误导）
• 进阶实践：
• 在 ClawGateway 中部署 三维探针（进程内堆栈采样 + 子进程状态树 + 依赖服务连通性）
• 使用 eBPF 捕获关键系统调用异常（如 connect() 持续失败）
• 针对 GPU 计算型 Agent 增加 CUDA 设备状态轮询（通过 nvidia-smi 解析）

2. 状态隔离与清理

# 崩溃处理钩子示例（基于 ClawSDK）
def pre_restart_hook():
    claw.cleanup(
        force_kill_children=True,  # 递归终止子进程
        release_gpu_memory=True,   # 显存释放
        flush_redis_buffers=True,  # 持久化中间状态
        reset_iptables=True        # 清理残留网络规则
    )
    os.system('sync')  # 强制刷盘避免文件损坏

3. 渐进式恢复策略

• 首次崩溃：立即重启（可能伴随 5 秒降级）
• 二次崩溃：延迟 30 秒 + 关闭非核心功能（如关闭 Embedding 模型热加载）
• 三次崩溃：触发熔断并告警人工介入
• 特别场景：当检测到连续 5 次崩溃间隔小于 60 秒时，自动进入安全模式（仅保留基础路由功能）

4. 生产环境诊断开关

在 QClaw 的网关配置中推荐启用：

monitoring:
  pprof:
    enable: true         # 开启性能分析端点
    auth_token: "xxx"    # 避免暴露到公网
    sample_rate: 0.1     # 生产环境采样率
  core_dump:
    enabled: false       # 生产环境建议关闭
    path: /var/crashes   # 如需开启必须限制目录权限

5. 混沌工程验证

• 使用 chaosblade 模拟以下场景：
• 暴力杀死主进程观察子进程回收
• 注入 100% 的 GPU OOM 错误
• 随机丢弃 50% 的网络包
• 进阶测试：模拟磁盘满状态（dd if=/dev/zero of=/tmp/fill bs=1M）验证日志模块健壮性

崩溃恢复的权限边界设计

在 WorkBuddy 的沙箱实现中，崩溃恢复进程需要特别注意： 1. 文件系统隔离：新进程应继承只读的 /etc 挂载点 2. 能力集限制：移除 CAP_SYS_ADMIN 等高风险权限 3. 网络命名空间：重建时保留原有 iptables 规则但重置连接追踪表 4. 审计日志必选项：所有恢复操作必须记录到 /var/log/claw_audit.log（追加模式+文件锁）

典型故障排查流程

当收到恢复失败的告警时，按以下顺序检查： 1. dmesg -T | grep -i oom 查看内核日志 2. ls -l /proc/<pid>/fd 检查文件描述符泄漏 3. ss -tunap | grep <port> 验证端口占用 4. 对 Go 编写的网关使用 golang.org/x/net/http2/debug 包检测 HTTP/2 流状态

避坑检查清单

✅ 心跳检测是否覆盖进程内/外多层拓扑？ ✅ 崩溃恢复前是否执行资源清理原子操作？ ✅ 重试策略是否有抖动补偿（避免惊群）？ ✅ 诊断接口是否有权限管控？ ✅ 是否在预发布环境验证过崩溃场景？ ✅ 是否限制了 core dump 文件生成路径？ ✅ 沙箱环境下是否重置了 Linux capabilities？

TL;DR

1. 单纯检测 HTTP 端口存活不足以反映网关真实状态
2. 未清理的僵尸进程和 GPU 资源是崩溃恢复的隐形杀手
3. 生产环境必须限制 pprof 等诊断接口的访问范围
4. 恢复后的新进程应处于最小权限沙箱中