
家庭 Homelab 的 Agent 全流程接管:Web 控制台服务篇
前几篇把主机层通道建完了:Windows 走 WinRM,Home Assistant 走系统层加应用层双通道。剩下的是量最大的一块:家里十几个 Web 控制台服务,雷池 WAF、GitLab、Zabbix、LiteLLM、WeKnora、DataEase,每个都有自己的登录页和 API,互不相通。
这块的接管原则一句话:API 是操作面,UI 是核对面。Agent 干活走 API,改完去 UI 对应的页面用真实请求核对一次——拆开理由是 UI 显示和 API 返回不一致的情况,这轮里真实出现过,不是多疑。真正花时间的不是建通道,是给十几项服务对齐一套判定标准:什么算探活、什么算写操作留痕、API 不可用时降级到哪一级算失败。
操作面四件套:每项服务同一套
统一做了四件事,所有服务照同一套走:
1. 凭据统一托管。 每项服务的 API token/密钥单独存一个 600 权限文件,路径进 Agent 全局基线,命名规则 ~/.config/<服务>-<标识>/api-token。不放在环境变量(会漏进日志),不放在共享配置(一个服务改密码不影响别人),脚本里读文件不回显。
2. 探活接口固定。 每项服务指定一个”最便宜的探活请求”(版本接口、健康检查端点),巡检只打这一个。探活失败才升级到深度检查——反直觉的地方是巡检本身可以变成对自家服务的压力源,不固定探活面,全量接口轮询比故障本身更伤库。
3. 写操作留痕。 所有经 API 的写操作(改规则、建用户、调策略),Agent 在执行前后各读一次相关状态,diff 写进报告。API 返回 200 不等于状态变了——雷池 WAF 上就遇到过返回成功但实际没生效的策略项。
4. 降级路径写死。 API 不可用时走什么通道、走到哪一级算失败,每项服务写死:
| 服务 | 降级通道 |
|---|---|
| 雷池 WAF | SSH 进容器看日志 |
| GitLab | 走 Runner 机器 |
| Zabbix | 查数据库 |
两个 API 通道救回来的故障
雷池 WAF 的管理 API 403。 一次 WAF 升级后管理 API 开始返回 403,UI 登录却正常。纯 UI 排查会卡在”到底是哪个权限”;走 API 逐接口二分,定位到是版本探测接口和授权接口的返回不一致——一个说社区版一个说商业版,两个接口的状态没对齐。这个不一致后来被当成已知状态记录在案,巡检里对该接口做了豁免。
Zabbix 的 systemd 队列死锁。 Zabbix 打补丁后 PHP 进程反复重启,systemd 的 job 队列堆死,服务”在跑但起不来”。API 层看是 apiinfo.version 超时,纯监控面看不出队列问题;SSH 进系统层 pkill -9 解除死锁后 API 恢复。这条写进了故障手册:监控面全绿的系统,系统层可能已经死锁,探活超时时不要只看服务状态。
巡检节奏:三段,产出的是归因链路
固定节奏的巡检代替”出事了再查”:
- 探活轮:所有服务的最便宜探活,一轮跑完,失败项升级深度检查;
- 深度检查:只针对失败项,走各自写明的那条降级路径;
- 报告:每轮一份,状态变化(不是全量状态)进 Agent 知识库存档。
这个节奏跑下来,真正值钱的产出不是”发现故障”,而是故障的归因链路完整:哪个接口、什么返回、系统层什么状态,三段都有记录,复盘不用重新翻。
边界:哪些不放
全部接管不是目标。明确不放的:
- 计费/配额类写操作(LiteLLM 的 key 额度调整):读可以,写要人工确认;
- 对外暴露的策略变更(WAF 对公网的规则):Agent 提 diff,人批准后执行;
- 证书签发:频率低、影响面大,保持人工。
放与不放的分界线就一条:错了能不能在十分钟内无痕回滚。能,放;不能,留人工确认环节。
成果:十几项服务同一套四件套,两个真实故障都靠 API 通道定位
现在家里十几项 Web 控制台服务(雷池 WAF、GitLab、Zabbix、LiteLLM、WeKnora、DataEase 等)全部跑在同一套四件套上:600 权限凭据文件、固定最便宜探活接口、写操作前后读状态留痕、降级路径写死。每项服务多出来的只有自己的连接串和降级通道一行。
- 两个真实故障都是靠 API 通道定位的,不是靠人开 UI 翻。 雷池 WAF 升级后管理 API 403 而 UI 登录正常,逐接口二分定位到版本探测接口与授权接口返回不一致(一个社区版一个商业版),该状态已记录在案并作为巡检豁免项;Zabbix 打补丁后 PHP 反复重启、systemd 队列堆死,API 层只表现为
apiinfo.version超时,SSH 进系统层pkill -9解除死锁后恢复——“监控面全绿、系统层已死锁”已写进故障手册。 - 巡检产出的归因链路是可直接复盘的。 探活轮 → 失败项深度检查 → 报告三段节奏,每轮记录”哪个接口、什么返回、系统层什么状态”,复盘不用重新翻日志;状态变化进 Agent 知识库存档,口径收敛在一份报告里。
- 哪些动作留给人,分界线只有一条。 错了能不能十分钟内无痕回滚:能,放给 Agent;不能,留人工确认环节。计费配额、对公网策略、证书签发三类已明确留在人工侧,边界写死、不靠临场判断。
未闭环清单
| 事项 | 状态 |
|---|---|
| 服务层统一告警面 | 未建。告警源分散,Zabbix 只覆盖主机层 |
| 服务层异常的实时发现 | 未闭环。API 探活失败、队列积压目前靠巡检轮发现,非实时 |
小结
十几项服务的接管没有新协议、新组件,难在判定标准的对齐:探活打哪个接口、写操作怎么证明生效、降级走到哪一级算失败、哪些动作留给人。
只留一条经验:Web 控制台服务交给 Agent,API 是操作面、UI 是核对面——200 不算数,前后读到的状态差才算数。
各服务的域名、IP 与凭据均已脱敏;行为与故障现象取自当时现场记录,未经二次复测,仅作口径参考。





