告警系统的产出是一个事实:某台机器某个指标越线了。它不是结论,更不是动作。从「磁盘 95%」到「该清哪个目录、清完会不会更糟、谁来签字、出问题怎么退回去」,这一段基本靠人肉,而且往往发生在凌晨。
ai-server-operator 想填的就是这一段。README 第一句把定位写得很克制:把服务器告警变成可解释、需要审批的操作。站点文案更直白——Monitoring tells you what broke. AI Server Operator helps you understand and safely fix it.
先交代一件事,免得预期错位:这个仓库现在只有 9 个文件,没有 agent 实现。
.github/workflows/pages.yml 655
LICENSE 11343
NOTICE 48
README.md 1227
docs/product-standard.md 1510
site/index.html 4055
site/robots.txt 92
site/sitemap.xml 238
site/styles.css 2498
主语言显示 HTML,原因就是 site/index.html 是唯一有分量的源文件。README 的 Status 段落写得很清楚:实验室目前通过 Beszel 监控四台 Linux 服务器,仓库从「公开产品契约和安全模型」起步,remediation agent 是下一个里程碑。
所以这篇不去吹一个不存在的执行器。我更想拆的是:当一个会自动改生产机器的系统还没写一行执行代码时,先把什么钉死才有意义。这个仓库给的答案是两样东西——一份四层边界契约,一个零 JS 的静态站。
四层边界:一个产品拆成四个安全域
docs/product-standard.md 开头就是那张我反复回去看的表:
| Surface | Purpose | Authentication | Indexing |
|---|---|---|---|
| Public site | Explain, educate, convert | No | Yes |
| Documentation | Teach and answer questions | No | Yes |
| App console | Deliver the service | Required | No |
| API | Stable machine interface | Token/OAuth | No |
这张表真正值钱的不是四行分类,而是最后两列的组合关系:要登录的页面一律不索引,可索引的页面一律不含控制面。README 的 Product boundary 段落把它落到具体主机上:
www:营销、文档、博客、定价、搜索内容app:要认证的控制面api:带版本的机器接口status:公开的服务健康页
这个切分在实现里是真的分开了:页面上的「Open console」指向 https://monitor.ledgendaryanimal.top/,和放 index.html 的 Pages 域不是同一个主机。道理不难,难在坚持。审批型产品的信任不是来自「我们很安全」,而是来自「你能自己检查」。一旦为了省事先把控制台塞进 www 的子路径,robots.txt 的 Allow/Disallow 就开始和登录态打架,缓存里出现半截后台页只是时间问题——而这类事故一旦发生,删索引比防索引贵得多。
契约还顺手管了导航和 URL:
## Navigation contract
The public site always shows Product, Use cases, Docs, Open source, Pricing,
and **Open console**. The console keeps the same logo and provides an obvious
**Back to website** link. A persistent environment label distinguishes public
content from the authenticated console.
翻成一句话:公开站必须始终能走到那六个入口,控制台必须留一条回官网的路,并且任何时刻都要有一个环境标签说明你站在哪一面。
「常驻的环境标签」这条在实现里就是一行 <span>:
<header>
<a class="brand" href="/">AI Server Operator <span>PUBLIC SITE</span></a>
<nav>
<a href="#how">How it works</a>
<a href="#open-source">Open source</a>
<a href="#faq">FAQ</a>
<a class="button secondary" href="https://monitor.ledgendaryanimal.top/">Open console ↗</a>
</nav>
</header>
我喜欢这种约束的颗粒度:它不规定你用 React 还是 Django,只规定「任何时刻用户必须知道自己站在公开面还是控制面」。这是能写进 code review 的规则,不是能写进 PPT 的口号。
对照实际页面,差距也是真的:header 里现在是 How it works、Open source、FAQ、Open console,契约要求的 Product、Use cases、Docs、Pricing 还没落地;sitemap.xml 里也只有一条 URL,说明 /docs/ 这类页面尚不存在。契约先行的代价就是这个——文档会先于实现撒一堆待办。
审批单的字段,其实已经写在文案里
落地「需审批」时,第一个绕不过去的问题是:审批人到底在看什么?
站点 THE OPERATING LOOP 那四张卡片里,第三张给了一句话答案:
Show the exact command, impact, risk, and rollback path.
把这句话当需求读,一条 pending action 至少要带四个字段。我再拿 README 里 Community edition 的可检查清单对齐了一遍,得到这张对照:
| 审批要素 | 仓库原文 | 在数据模型里的角色 |
|---|---|---|
| command | Show the exact command | 待执行命令,逐字展示,不做摘要 |
| impact | impact | 影响面:动哪个服务、波及哪些请求 |
| risk | risk | 风险等级,决定是否要二次确认 |
| rollback | rollback path、rollback metadata | 回滚路径与回滚元数据,与 action 同生命周期 |
| timeout | timeouts | 执行上限,超时按失败处理而不是「可能成功」 |
| allowlist | command allowlists | 准入判断,卡在计划生成之后、执行之前 |
| audit | audit logs | 追加写、不可改,审批人/时间/结果全在里 |
这张表是我对仓库的解读,仓库里目前还没有对应的 schema 文件。README 给的是几句承诺——"approval required before every write action",加上 "command allowlists, timeouts, audit logs, and rollback metadata"——这些字段长什么样、用什么格式存,要等 remediation agent 那个里程碑。
但顺序值得强调:allowlist 校验必须卡在计划生成之后、执行之前。反过来的话,模型先生成一条 rm -rf,你在执行前才发现它不在白名单里,等于把一次危险的生成当成正常流程走完,只靠最后一层兜。审批界面也会退化成「展示一条注定被拒的命令」,人很快就学会闭眼点通过——这是审批流最典型的失效模式。正确的位置是:白名单在计划生成阶段就参与约束(能生成什么),审批在计划确定之后拦截(要不要执行),两层各管一段,不要合并成一层。
诊断这一段也有具体所指,站点原文是:
Diagnose — Separate real pressure from misleading numbers like Linux file cache.
这是整个产品里最容易做出差异、也最容易做错的一步。free 里 buff/cache 占掉几个 G、df 和 du 对不上、容器里看到的 /proc 其实是宿主机的——这些都会让一个只读阈值的系统给出错误结论,然后拿一个错误结论去驱动一次有审批的动作。审批只能保证「人同意了」,保证不了「判断是对的」。所以 explainable 在这里不是形容词,是硬需求:结论必须带证据链,否则审批人没有能力否决,那道门就是个装饰。
站点本身也是实现:零 JS 的单文件加一条 Pages 工作流
site/index.html 只有一个 <script>,类型是 application/ld+json:
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "AI Server Operator",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Linux",
"description": "Open-source, approval-gated AI operations for Linux servers.",
"offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
}
没有框架、没有构建、没有 hydration,styles.css 2.5KB,全部产物就是一张 HTML 加一张 CSS。这个选择跟契约先行是同一套逻辑:静态渲染的页面在 Core Web Vitals 上几乎没有可失败的地方,同时也最容易被搜索和 answer engine 完整读到——契约文档里 "fast static rendering" 和 "No authenticated console page is indexable" 这两条,靠一个不执行 JS 的静态站天然满足。
发布侧就是一条 GitHub Actions,site/** 一改就自动上线:
on:
push:
branches: [main]
paths:
- "site/**"
- ".github/workflows/pages.yml"
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: true
permissions 收敛到三个,id-token: write 是 Pages 用 OIDC 部署所必需,全程不需要任何 PAT。concurrency.group: pages 配 cancel-in-progress: true,保证连续两次 push 不会并发写同一个环境,后一次直接顶掉前一次——对静态站这是对的语义,因为它没有需要按序应用的状态。
踩到的坑
一、Live lab signal 是写死的数字。
hero 区那段看起来像实时数据的条:
<div class="signal">
<strong>Live lab signal</strong>
<span>4 servers connected</span>
<span>1 disk warning detected</span>
<span>0 actions without approval</span>
</div>
三个数字全是 HTML 里的字符串。现象是「实时」,原因是静态站没有后端可以拉。它和 README 里「四台服务器」这句是手工对齐的,某天实验室多接一台机器,这里就开始撒谎。这类文案的毒性在于它站在最显眼的位置,而读者没有任何办法验证。要么明确写成 snapshot 并标上时间,要么等 status 那个面起来之后从它取;在那之前,我更倾向于把 "Live" 这个词删掉。
二、两套 URL 口径同时存在。
product-standard.md 的 URL 契约写的是独立域名加子域:
https://product.example/
https://product.example/docs/
https://app.product.example/
https://api.product.example/v1/
https://status.product.example/
而站点里实际生效的是 GitHub Pages 的项目子路径,同一个地址在四处各写了一遍:index.html 的 <link rel="canonical">、<meta property="og:url">、robots.txt 的 Sitemap: 行、sitemap.xml 的 <loc>。现象是现在能跑,原因是先有 Pages 部署、后有域契约。代价是迁自定义域那天要同时改四处,漏一处就是 canonical 和 sitemap 不同源——搜索引擎看到两个 URL 指向同一份内容,权重被摊薄,而这个问题要几周才会在报表里显形。
三、paths 过滤让部署范围和内容范围对不上。
工作流只在 site/** 变化时触发,看起来合理,但契约文档躺在 docs/ 下:只改 product-standard.md、不动 site/,站点不会重建。目前没暴露问题,是因为文档和页面是手写的两份;一旦页面开始从契约生成(比如把那张四层边界表渲染成页面),docs/** 就必须进 paths,否则线上会长期停在和契约不一致的版本上,而且是静默的。
边界与代价
得把话说回来:这个仓库现在没有可执行的东西。审批门槛、命令白名单、超时、审计日志、回滚元数据,现阶段是 README 里的一份承诺加一个静态页上的说明,不是你能 docker compose up 起来的行为。"approval required before every write action" 在对应代码存在之前,只是一个设计约束。
这套做法换来的东西是边界清楚:模型供应商自带("bring your own model provider"),运维数据留在自己基础设施上,安全行为可检查——发布契约里明确写了 "core safety behavior remains inspectable",Apache-2.0 可读可改。
代价也很具体:
- 每次写操作都要一个人签字,夜间告警的处理时延由人的响应速度决定,不由系统决定。想要自动化率,就得在「哪些动作可以免审批」上分级,而分级本身就是一次风险决策。
- 自带模型意味着诊断质量取决于你接的那个模型。同一条告警换个模型可能给出完全不同的计划,可复现性得自己兜。
- 自托管意味着升级、备份、证书、审计日志保留策略全是你的事,没有厂商代管这一层。
小结
如果只记一句:在让 AI 碰生产机器之前,先把「谁能看见什么、谁能批准什么、批准时看到什么」写成可检查的契约。 这个仓库目前交付的就是这份契约和一个零 JS 的静态站,执行器还在路上;但它先把边界的形状摆了出来,后面写 agent 的人有地方挂。