监控配置总在 UI 与 Git 之间漂移？用 Overcheck 把可用性检查做成可审计的声明式资源
可用性监控的第一阶段通常很简单：在界面里填一个 URL、选一个告警渠道，服务挂掉时收到通知即可。问题会在团队和服务数量增长后出现：谁在什么时候改过超时阈值？新环境如何复制同一组检查？某个监控为什么在页面里存在、仓库里却没有定义？如果监控规则只有 UI 里的状态，运维配置就很难像代码一样被 review、回滚和复现。
Overcheck 是一个仍处于 Early 阶段的自托管可用性监控项目，采用 AGPL-3.0 许可证。它的重点不是宣称替代所有成熟监控平台，而是把三件事组合在一起：团队角色、可写的 REST API，以及由 CLI 执行的 YAML 同步。它支持 HTTP(S)、TCP、ping 和关键字检查，也可通过 Slack、邮件或 webhook 发出告警；数据后端是 PostgreSQL。
对于已经把基础设施定义放进 Git 的团队，值得关注的并非“又多一个状态页”，而是监控对象能否成为一组有明确所有权的资源：同一份 YAML 可先做 dry-run，再提交到版本库，最后由部署流程应用到目标实例。
先区分「声明」和「观察结果」
监控系统里有两类数据，不能混为一谈。第一类是声明：要检查哪个地址、多久检查一次、慢到什么程度算降级、失败后通知谁。这些数据适合进入 Git，因为它们需要审查与变更记录。第二类是观察结果：每一次检查的耗时、失败历史与事故时间线。它们会持续增长，通常应该留在监控服务的数据存储中，而不是塞进仓库。
Overcheck 的 YAML 管理的是前者。overcheck apply 读取文件后，会从 API 获取现有 monitor 与 alert channel，并按 name 对齐资源：文件里有、服务端没有的资源会创建；同名但字段不同的资源会更新；服务端存在而文件不再定义的资源会删除。由于它是 reconciliation，而不是简单的“批量新增”，重跑相同的文件不会继续制造重复资源。
这也带来一个重要边界：改名不是原地重命名。文档明确说明，YAML 中的 name 是匹配键；改名会被视为“创建新资源，再删除旧资源”。因此，名称应使用稳定的业务语义，例如 payments-api-health，而不是包含临时环境编号或本次事故代号的字符串。
用最小 YAML 表达检查目标与降级阈值
项目的快速启动方式是克隆仓库后运行 Docker Compose：
git clone https://github.com/overcheck/overcheck && cd overcheck docker compose up -d
服务启动后可从 http://localhost:3000 创建管理员帐号。若要把定义纳入版本控制，则安装 CLI，并使用 API key 连接目标实例：
npm install -g @overcheck/cli
export OVERCHECK_URL="https://monitor.example.com"
export OVERCHECK_API_KEY="${OVERCHECK_API_KEY}"
下面的例子同时定义站点 HTTP 检查、带响应体断言的 API 检查，以及一个 Slack 告警通道。它使用的是文档中定义的实际字段，而不是从产品描述推测出来的配置结构：
monitors:
- name: marketing-site
type: http
httpUrl: https://example.com
intervalSeconds: 60
degradedAfterMs: 800
alertChannels: [oncall-slack]
- name: api-health
type: keyword
httpUrl: https://api.example.com/health
httpBodyContains: '"status":"ok"'
intervalSeconds: 30
retries: 1
alertChannels: [oncall-slack]
alertChannels:
- name: oncall-slack
type: slack
config:
webhookUrl: "${SLACK_WEBHOOK_URL}"
这里最容易被忽略的是 degradedAfterMs。它不是故障超时，而是响应超过阈值后将检查标记为 degraded 的界线。对外可访问的 API 来说，“仍返回 200、但已经慢到 800ms”与“完全不可用”是两种不同信号；前者更适合作为容量、依赖服务或缓存退化的早期告警。检查间隔 intervalSeconds 的最小值为 10 秒，不能以更短间隔绕过系统限制。
不要把 webhook URL 或 API key 写进 Git。上例使用环境变量只是为了说明字段位置；CI 中应通过该平台的 secret 机制注入。提交前也要确认 YAML 中没有从管理界面复制来的真实凭据。
先 dry-run，再让 CI 负责应用
直接应用前先获得变更计划：
overcheck apply -f monitors.yaml --dry-run overcheck apply -f monitors.yaml
--dry-run 的价值在于提前暴露 reconcile 的副作用，尤其是删除：当某个资源不在 YAML 中时，apply 会将它视为应删除的资源。如果团队同时允许 UI 手工创建临时检查，就必须先约定边界。一个简单做法是将“长期、由服务负责人维护的检查”全部声明在仓库中；一次性排障检查则使用单独的实例、单独的命名空间约定，或在排障结束后显式清理。否则，下一次部署可能删除了某位同事刚在 UI 中添加的紧急检查。
从已有 UI 状态起步时，可以反向导出：
overcheck export -o monitors.yaml
导出文件不是天然可靠的基线。应先删除不应长期保存的临时检查，审查名称、URL、间隔与告警路由，再把它作为受保护目录下的配置提交。之后让 PR 审查回答具体问题：这个 endpoint 是否应由这个团队值班？阈值是否与服务 SLO 相符？新增的 webhook 是否指向正确的告警入口？这些问题比“页面上能不能点出一个监控”更容易留下可追溯的答案。
处理配置所有权，而不是盲信「UI 也是 API 客户端」
Overcheck 的 dashboard 写操作使用同一套 REST API，这有利于脚本和 UI 看到同一份服务端状态，但不自动解决多人并发修改。管理员、编辑者和查看者三类角色可以限制谁能变更资源，却不能替团队规定“Git 是不是最终权威来源”。
建议把资源分为两层。第一层是 Git 管理的基线，CI 只对该集合运行 apply；第二层是短期诊断资源，不允许与基线重名，也不由这条 CI 作业回收。若暂时不需要双轨，最简单的策略反而是更严格：所有长期 monitor 与 alert channel 都必须出现在 YAML 中，UI 只用于查看、生成 API key 或处理不在 apply/export 覆盖范围内的状态页资源。
这项限制不是猜测。当前项目文档明确写明，状态页的品牌、监控分组和事故尚未由 apply/export 管理，仍需通过 API 或状态页路由操作。因此不能宣称“一份 YAML 管理整个监控系统”；它当前管理的是 monitor 和 alert channel。将这类能力边界写入运行手册，能避免自动化脚本给人制造错误的控制感。
在 CI 中可以把同步拆成明确的两个 job。PR job 只安装 CLI、注入只读或受限的 API key，并执行 overcheck apply -f monitors.yaml --dry-run，把计划输出附在构建日志中；受保护分支上的部署 job 才允许执行真正的 apply。不要让任意 fork 提交拿到能修改监控实例的 key，也不要在测试阶段用生产告警 webhook 发送探测通知。若需要验证配置语法而不触碰共享实例，可以在临时的自托管实例中运行同一份 YAML；这样能同时检查字段、资源名称唯一性与告警通道引用，而不会把预发布操作混进值班系统。
另外，reconcile 的“删除未声明资源”语义意味着 Git 仓库的变更保护尤为重要。对 monitors.yaml 启用 CODEOWNERS、要求服务负责人审批，并将 apply 的提交 SHA 记录在部署日志中。发生误删时，维护者便能先定位到哪一次定义变更造成差异，再通过 Git 回滚并重新 apply；这比从 UI 记忆里恢复一组 URL、阈值和通知目标可靠得多。
留意高频检查的存储成本与失败模式
监控不是零成本的 ping。Overcheck 通过 CHECK_RETENTION_DAYS 保存检查历史，默认值为 90 天。检查结果的存储量会随 monitor 数量、检查频率和保留天数近似线性增长。把几十个 endpoint 都设为 10 秒间隔，和每分钟检查一次的 PostgreSQL 体量完全不同；部署前应根据磁盘预算与排障窗口选择间隔和保留期，而不是只追求更密集的数据点。
另一个失败模式是把 keyword 检查当成完整的业务验收。它只能验证 HTTP 响应体是否包含指定子串，适合健康端点或少量固定标记；它不能证明订单创建、权限校验、异步队列等关键路径都正确。对真正重要的用户旅程，应保留应用级合成测试，并将监控定义为“快速发现服务不可达、响应退化或健康契约失效”的一层，而不是端到端质量的替代品。
Overcheck 适合希望把团队监控从纯 UI 操作过渡到 API 与 YAML 协同管理的场景，尤其是已有 Docker、PostgreSQL 和 Git 驱动部署流程的团队。它很新，README 也明确标注 Early；在关键生产环境采用前，应自行验证备份、升级、告警投递、权限模型和故障恢复。把监控配置当成可审计资源并不消除值班责任，但它能让“谁在监控什么、为什么这样监控”从不可见的页面状态，变成团队可以 review 的工程决策。