起因:能看,不等于能修

我给家里的服务器做了一套巡检:13 个服务,每 10 分钟探一次,挂了就推手机。

用了一个月,发现问题不在”发现”,在”之后”。

手机上收到「Immich 不可达」,我点开看一眼,然后呢?要么去开电脑,要么假装没看见。AI 助手那边更尴尬——我问它”家里怎么样”,它能准确报出「13/13 个服务在线」;我问它”Immich 为什么挂了”,它只能说”当前是正常的”。

它看得见状态,但看不见原因,也伸不出手。

所以这一轮的目标很明确:给 AI 一个能动手的接口。但”能动手”三个字很危险——一个能执行 docker 的 AI,等于把服务器 root 交给一个会幻觉的模型。

这篇文章记录的就是这个矛盾怎么解:既要让它真的能修,又要保证它修不坏。

一、先把边界画出来

动手之前先定四条规矩,后面所有设计都是从这四条长出来的。

第一条:一个入口,不是五个。

AI 那边每加一个能力,就要新建一个「自定义连接器 + API 密钥」。加到第三个的时候我已经开始配错了——密钥填错、URL 少一段、方法写成 GET。

所以把读、写、推、记全部收进一个端点,用 intent 区分:

1
2
POST https://<你的域名>/webhook/muse
{"intent": "status"}

一个 URL,一个令牌,能力全在里面。

第二条:读和写分开限速。

读很便宜,而且 agent 会反复问(”现在呢?””那 immich 呢?”)。如果读写共用一个 6 次/5 分钟的桶,正常对话会被自己卡住。

所以分两个桶:读 60 次/5 分钟,写 6 次/5 分钟。写要防的是 agent 循环重启,那个必须收紧。

第三条:白名单写在文件里,不写在代码里。

1
2
3
4
5
6
# /opt/muse-jobs/actions.conf
mealie
freshrss
it-tools
dozzle
...

名单里刻意不含 n8n、cloudflared、nginx、vaultwarden 和各数据库——重启它们等于把调用方自己也弄死。

第四条:能改状态的操作,一律两步。

这条是整篇文章的重点,下面单独讲。

二、从”能看”到”能查”:单服务钻取

原来问”immich 还好吗”,AI 只能回一句”13/13 正常”。这句话没错,但没用——13 个里有一个半死不活它也这么说。

所以加了一个 service——一次把散在六个地方的数据拼成一张画像:

1
{"intent": "service", "name": "mealie"}
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"container": "mealie",
"image": "ghcr.io/mealie-recipes/mealie:latest",
"restarts": 0,
"exit_code": 0,
"oom_killed": false,
"now": {"status": "up", "code": 200, "ms": 193},
"image_update": "有新版本(摘要不同)",
"compose_file": "/opt/home-lab-mealie/compose.yaml",
"config_changes": ["11-12 00:23|配置快照:33 个文件变化"],
"evidence": ["20261111-235250-Mealie"],
"missing": ["日志错误签名(12 小时去重表里没有这个容器)"]
}

数据来自:docker inspect、探针、timeline、updates.json、git 记录、日志签名表。实测 2.9 秒。

这里最要紧的是最后那个 missing 字段。

查不到的项明确列出来,而不是省略。因为 agent 很擅长脑补——你不给它 missing,它就会把”没查到”说成”没有问题”。

我给它写的规则是:

service 返回里的 missing 表示「这项查不到」,必须如实说查不到,不要猜。

它照着做了。有一次日志签名查不到,它的回复是:

日志错误签名这一项没拿到。原因不是”确认没有报错”,是这一项暂时查不到。

这句话比我写过的所有 prompt 都值。

三、能动手,但不能自己决定:两步升级

这是整个设计里我花了最多心思的地方。

最直接的做法是给它一个 upgrade,它调一下,容器就升了。但我不敢——模型会幻觉,容器会起不来,而我可能在睡觉。

所以做成两步。

第一步:只出计划

1
{"intent": "upgrade", "name": "it-tools"}

返回:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
"phase": "plan",
"container": "it-tools",
"image": "docker.1ms.run/corentinth/it-tools:latest",
"image_update": "有新版本",
"will_run": [
"docker compose -f /opt/home-lab-it-tools/compose.yaml pull it-tools",
"docker compose -f /opt/home-lab-it-tools/compose.yaml up -d it-tools"
],
"rollback": "docker image tag sha256:bb7ba96... docker.1ms.run/... && docker compose -f ... up -d --force-recreate it-tools",
"confirm": "b110c5",
"expires_in_minutes": 10
}

这一步什么都不动。 它只是把”我打算做什么”写清楚,附上回滚命令,然后给一个 10 分钟内有效的确认码。

第二步:带码才执行

1
{"intent": "upgrade", "confirm": "b110c5"}

这时候才真的 pull + up -d。执行完检查容器状态,没起来就推一条 priority=4 的告警,并把回滚命令一起发给你。

实测一次:

1
2
3
[pull] ok  it-tools Pulling / Pulled
[up] ok Container it-tools Running
state: running|0|docker.1ms.run/corentinth/it-tools:latest|sha256:bb7ba96...

有意思的是这次镜像 ID 没变(镜像源返回的是同一摘要),所以 compose 判定”无需重建”,容器 uptime 一直没断。

这恰好证明了一件重要的事:它不会做无谓的重启。如果是”无脑 pull + 强制 recreate”的写法,这次就会白重启一次。

为什么”两步”比”确认按钮”更好

我本来想的是”执行前弹个确认”。但 agent 不是图形界面——你和它的交互是对话,不是点击。

用两次请求换一次确认,好处是:

  • 计划可以先给你看,你会看到回滚命令。看到回滚命令的那一刻,你对这次操作的信任度是不一样的
  • 过期机制天然存在(10 分钟),不用额外设计
  • 审计日志能完整记录「谁在什么时候申请了什么,谁在什么时候批了」

日志里长这样:

1
2
3
01:02:31 DENY  upgrade confirm=zzzzzz 无匹配计划
01:02:42 PLAN upgrade it-tools (...) id=b110c5
01:03:06 OK upgrade it-tools -> running|0|...

中间那条 PLAN 是”申请”,最后那条是”执行”。申请和执行分开了,责任就分开了。

四、还有一个我没想到的需求:让它闭嘴

接口做完没两天,我收到了一条推送,内容是”这条不该到你手机”——我自己写的测试。

但这暴露了一个真实场景:运维时手机被自己的告警轰炸。你在重启 n8n,告警当然满天飞,你全都知道,全都想忽略。

所以加了 mute:

1
{"intent": "mute", "minutes": 60}

静音状态写在一个文件里,三处读同一份:

  • 所有定时任务(Python,直接读文件)
  • 统一入口自己(say / remember)
  • 探针(n8n 读不了本地文件,所以走 HTTP 从静态服务读)

两个刻意的设计:

1. say 不受静音影响。 你明确让它说一句,那不算噪音。技术上就是 force=True 绕过闸门。

2. 读不到文件就当没静音。 文件缺失、JSON 坏了、until 不是数字——一律按”没静音”处理。

第二点很重要:静音是个”少做事”的功能,它的失败方向必须是”多推一条”,而不是”静默失效”。否则某天文件写坏了,你会以为家里一切正常,实际上是所有通知都被吞了。

五、五个真踩过的坑

1. n8n 的 publish:workflow 不会注册 webhook

现象:工作流 active=1,数据库里也看得到,但公网访问永远 404 not registered。

原因:CLI 的 publish 只写了 workflow_entity.active,没有写 webhook_entity,也没有设 triggerCount。n8n 启动时看 triggerCount=0 就跳过注册。

最后是停库、手写 webhook_entity 行、把 triggerCount 设成 1 才生效。

结论:新建 webhook 工作流请在 UI 里点 Active,别信 CLI。

2. Respond to Webhook 的状态码在 options 里

1
2
3
4
5
// 错:静默返回 200
{"responseCode": 401}

// 对
{"options": {"responseCode": 401}}

写错位置不会报错,只会让你以为 401 生效了,其实一直是 200。

3. grep -r /opt 要找 117 秒

我要在 compose 文件里找某个服务,第一版写了 grep -rl mealie /opt。

实测:117 秒,而且第一个命中的是 git 工作树里的副本(因为我把配置同步到了 /opt/muse-git/work),拿到的路径是错的。

改成直接读文件后:2.9 秒,结果准确。

4. Python 写文件是块缓冲

run_job 是异步执行任务的,job_status 用来查进度。但加完发现:任务跑完之前,日志永远是空的。

原因:subprocess.Popen 起子进程时,Python 的输出是块缓冲的,不到 4KB 不落盘。

改成 python3 -u 就好了。

5. /tmp 有 fs.protected_regular

root 覆盖不了别的用户在 /tmp 创建的文件:

1
curl: (23) client returned ERROR on write

第一次遇到时我以为是磁盘满,查了半天 df。

后来所有临时文件都放 /root/ 下面,不再用 /tmp。

六、现在的效果

三个真实对话:

“家里现在怎么样”

13 个服务全在线,全部正常,没有异常,也没有任何服务掉线。最慢的一个响应 334 毫秒。

“immich 还好吗”

容器状态:拿到了……刚刚实时测了一下,现在可达,响应 243 毫秒。镜像有新版本了,升不升你说了算,我没有动它。

“测一下网速”

先说清楚口径:这组数字是代理链路的带宽,不是你家宽带的真实带宽。测速服务器落在 CMHK/香港,说明出口在境外、走了代理,所以别拿这个数去判断运营商给了多少。
下载 4.2 Mbps,上传 4.1 Mbps,延迟 13.7 毫秒,丢包 3.69%。丢包这个偏高,视频通话和游戏会明显感觉到卡。

最后一条里,“先说清楚口径”是我在指令里要求的——因为第一次测出来 4 Mbps 时,我自己都以为运营商只给了 4M,实际是代理链路的问题。

七、复盘:什么该给 AI,什么不该

做完这一轮,我的判断标准变成三个问题:

1. 它做错了,后果可逆吗?

重启容器可逆(再起一次),删数据不可逆。所以 restart 给,rm 永远不给。

2. 它能不能在动手前把计划说清楚?

能,就说明这个操作是可解释的,可以做两步确认。说不清楚的操作(”优化一下性能”)就不该开放。

3. 出问题时,我能不能在 3 分钟内查清它做了什么?

靠审计日志。每个请求都记:谁、什么时候、想做什么、结果如何。没这条,前面两条都是空话。

按这三条筛,最后开放出去的其实很少:看状态、查单服务、跑只读任务、重启白名单容器、两步升级、推送、记日记。

但已经够用了。它现在能做的事,覆盖了我 80% 的”看一眼”需求,和 100% 的”重启一下试试”。

剩下的 20%,本来也需要我自己去看。


相关代码(全部在本机跑,不上云):

  • actiond.py — 统一入口,stdlib 实现,无框架
  • common.py — 静音闸门、推送、状态
  • n8n 工作流 — 探针、早报回传、历史追问

如果你也想给自己搭一套,我建议从最没用的那个能力开始——先做 status,跑一周,看看 agent 会怎么问、会怎么误解。你对它的信任边界,是在这些误解里长出来的,不是在设计文档里。