3255 字
16 分钟
监控与可观测性:Gatus 把状态页写进一个 YAML 文件

先吵一架:状态页的配置,该点鼠标还是该进 Git#

做拨测监控有两条路线。一条是 Uptime Kuma 那样的图形界面派:开个网页,点几下鼠标,加一个监控项,存进数据库,舒服直观;另一条是配置即代码派:所有监控项写在一个文本文件里,改配置就是改文件,文件进 Git,谁改了什么、什么时候改的,一条 blame 全看得清清楚楚。

这两条路线没有谁碾压谁,但当你的服务从三五个涨到二三十个,当你想把同一套拨测复制到第二台机器,当某天凌晨你想弄明白「这个监控项是谁上周改掉的」——图形界面派就开始吃力了:配置躺在数据库里,看不见、比不了、搬不走。

Gatus 就是配置即代码派的代表作:一个 config.yaml 声明全部端点、判定条件和告警渠道,首页就是一张现成的状态页,轻量、透明、可版本管理。这篇把它讲透:怎么部署、条件怎么写、告警怎么配、历史怎么留住。

项目地址:https://github.com/TwiN/gatus

Gatus 是什么:一份 YAML 就是一整套拨测#

Gatus 是开源的自动化拨测与状态页工具。它的工作方式一句话说清:你在一个 config.yaml 里声明要测的端点,它按你设的间隔去请求这些端点,用你写的条件判断健康与否,把结果画在首页状态页上,异常时按你配的渠道发告警。

它和同系列里讲过的 Blackbox Exporter 是亲戚关系:都属于主动拨测。但 Blackbox 是 Prometheus 体系里的探针组件,数据要进 Prometheus 才能看;Gatus 是自带存储、自带状态页、自带告警的一体机,部署完打开网页就能用。两者怎么选,简单说:已经在用 Prometheus 全家桶就用 Blackbox,只想快速要一张状态页加告警,就用 Gatus。

和 Uptime Kuma 的差异更值得展开,放在文末有完整的对比表,这里先给结论:Kuma 胜在功能全、界面友好;Gatus 胜在配置透明、轻量、天然适合 Git 管理。

部署:一个容器,一份配置#

Gatus 的官方镜像是 twinproduction/gatus,服务端口 8080。部署只需要两样东西:一个 docker-compose.yml 和一个 config.yaml,两者放在同一目录:

services:
gatus:
image: twinproduction/gatus:latest
container_name: gatus
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./config:/config
- ./data:/data

注意 volumes 的挂载点:Gatus 默认从 /config 目录读取 config.yaml,数据文件我们指定写到 /data,这两个路径在下面的配置里要对上。

目录建好、文件就位之后,启动和验证就三条命令:

Terminal window
docker compose up -d
docker compose logs -f gatus
curl -s http://localhost:8080/health

日志里能看到每个端点被逐个加载、第一次拨测的结果;/health 返回正常,就说明服务本身活着。之后改 config.yaml 不需要重建镜像,重启容器即可重新加载配置——这也是配置即代码的日常体验:改文件、重启、生效,整个过程可以写进一个 Git 提交里。

config.yaml 全解剖:三个端点一次讲清#

下面这份配置包含三类最典型的端点:一个网站首页、一个 API 接口、一个专门盯证书过期的检查。先看全貌,再逐段拆解:

storage:
type: sqlite
path: /data/data.db
endpoints:
- name: 博客首页
group: 对外服务
url: "https://blog.example.com"
interval: 60s
conditions:
- "[STATUS] == 200"
- "[RESPONSE_TIME] < 1000"
alerts:
- type: telegram
failure-threshold: 3
success-threshold: 2
description: "博客首页异常"
- name: 业务 API
group: 对外服务
url: "https://api.example.com/health"
interval: 60s
conditions:
- "[STATUS] == 200"
- "[BODY].status == ok"
alerts:
- type: telegram
failure-threshold: 3
success-threshold: 2
- name: 证书过期检查
group: 基础设施
url: "https://blog.example.com"
interval: 5m
conditions:
- "[CERTIFICATE_EXPIRATION] > 48h"
alerting:
telegram:
authorization-key: "你的 Bot Token"
to: "你的 Chat ID"

端点四要素:name、group、url、interval#

每个端点先有四个基本字段:name 是显示在状态页上的名字;group 是分组,状态页会按组归类展示,服务多了不分组就是一场灾难;url 是拨测目标;interval 是拨测间隔,网站和 API 用 60s 比较常见,证书这类慢变量用 5m 甚至更长就够了,不要给所有端点无脑上 10s 的高频拨测,那是在给被测服务和自己同时上压力。

条件语法:方括号占位符加比较运算#

conditions 是一个数组,端点健康要求数组里的条件全部成立,有一条不成立就判失败。可用的占位符主要有:

  • [STATUS]:HTTP 状态码,最常用,如 [STATUS] == 200
  • [RESPONSE_TIME]:响应时间,单位毫秒,如 [RESPONSE_TIME] < 1000
  • [CERTIFICATE_EXPIRATION]:证书剩余有效期,如 [CERTIFICATE_EXPIRATION] > 48h,提前两天预警
  • [DNS_RCODE]:DNS 解析返回码,如 [DNS_RCODE] == NOERROR,适合盯域名解析是否正常
  • [BODY]:响应体内容,可以做字符串包含匹配,也能像示例里那样取 JSON 字段 [BODY].status == ok,让健康检查不止看状态码、还看业务自报状态

除了条件,端点还支持自定义 headers,比如给 API 带上鉴权头或特定的 User-Agent,需要测「带头才能访问」的接口时用得上。

证书之外,DNS 也是值得单独盯的一项:域名解析被改错、DNS 服务商出故障时,网站本身明明好端端的,用户却打不开。给关键域名加一个专门的 DNS 端点,成本只有几行:

- name: 域名解析检查
group: 基础设施
url: "8.8.8.8"
interval: 5m
dns:
query-name: "blog.example.com"
query-type: "A"
conditions:
- "[DNS_RCODE] == NOERROR"

这类「慢变量端点」的共同点是间隔可以放长、条件可以单纯,它们的价值不在实时,而在于出事时你能第一时间分清是服务挂了、证书过期了,还是解析没了。

告警:阈值防抖是精髓#

alerting 段在全局统一声明渠道的凭据——示例里是 Telegram,Gatus 还支持 Slack、Discord、邮件、PagerDuty,以及一个 custom 类型,本质就是 Webhook,能往任意 HTTP 接口 POST,方便接自建的通知网关;本站的告警体系怎么统一收口,可以参考 Alertmanager 告警链 那篇的思路。

端点里引用告警时,最重要的两个参数是 failure-threshold 和 success-threshold:前者是连续失败几次才真正发告警,后者是连续成功几次才发恢复通知。示例里设 3 和 2,意思是抖动一两次不吭声、确认挂了才喊、确认活了才报平安。这两个阈值是 Gatus 告警好用的关键:没有防抖的拨测告警,迟早被你自己静音。

WARNING

两个坑一次说清。第一,storage 不配 sqlite 时,Gatus 默认把历史放在内存里,容器一重启,可用率和响应时间历史全部清零——这不是 bug,是默认行为,想留住历史必须像示例这样显式配 sqlite 并把数据目录挂出来持久化。第二,Gatus 的首页状态页默认不需要登录,把状态页直接公开到公网,等于把你的服务清单、域名和可用率双手送给所有人,对外暴露前请务必套一层反向代理加访问控制,或者只在内网开放。

状态页与接口:给人看的和给机器看的#

部署完成后访问 8080 端口,首页就是状态页:每个端点一行,按 group 分组,显示当前状态、可用率百分比和响应时间历史曲线。一眼扫过去全绿才安心,有红的一行点进去能看到每次拨测的明细。

给机器用的部分有两个:一是 /api/v1/endpoints/statuses 接口,返回全部端点的结构化状态数据,可以被其他系统消费,比如汇总多台机器的状态、接到自己的面板里;二是徽章(badge)能力,能生成某个端点的可用率或响应时间徽章图片,嵌在 README 或文档里很顺手。多机部署时怎么把各节点的状态收拢成一个总览,舰队总览 那篇有完整的组织方法。

和 Uptime Kuma 正面对比#

维度GatusUptime Kuma
配置方式单个 config.yaml,进 Git 管理网页 GUI 操作,存数据库
配置可审查性强,diff 与 blame 一目了然弱,变更无版本记录
复制到新机器拷贝文件即可导出导入或重搭数据库
判定条件表达式语法,状态码/响应时间/证书/DNS/响应体组合判断以状态码和关键词匹配为主
状态页自带,按分组展示可用率与历史自带,功能更丰富,可多状态页
通知渠道Telegram、Slack、Discord、Webhook 等主流渠道渠道数量更多,冷门渠道也覆盖
资源占用很轻,单容器内存占用小相对更重
上手门槛要会写 YAML点鼠标即可,零门槛

选型一句话:个人少量服务、喜欢图形界面选 Kuma;服务上了规模、想把监控配置当代码管,选 Gatus。两者并不互斥,完全可以 Kuma 管内网杂项、Gatus 管对外服务的状态页,各取所长。

把配置管进 Git:这才是它真正的用法#

既然配置只是一个文件,就别浪费这个形态。推荐的日常姿势是:把 config.yaml 连同 docker-compose.yml 一起放进一个私有 Git 仓库,改监控项走和改代码一样的流程——本地编辑、提交、推送、到服务器上拉取重启。好处是立竿见影的:谁在什么时候加了一个端点、谁把某个间隔从 60s 改成了 5m,git log 里全有;新机器要复刻整套拨测,clone 仓库、填上凭据、up 一下就完事;改坏了想回滚,一条 git revert 就回到上一版。

唯一要留心的是凭据:config.yaml 里写着 Telegram Bot Token 这类敏感信息,仓库必须是私有的;更稳妥的做法是把凭据抽到环境变量里,配置文件只留占位,仓库里再放一份不带真实值的示例文件。这样配置可以放心地版本管理,秘密则留在服务器本地,两不耽误。

排障小节#

条件写错了不报错,只判失败。 这是新手最容易被坑的一点:conditions 里的表达式写错语法、占位符拼错,Gatus 不会在启动时拦住你,而是每次拨测都判定为失败,状态页一片红。排查顺序是先看容器日志确认配置已加载,再把条件删到只剩 [STATUS] == 200 这一条最基础的,确认端点能转绿,然后逐条把条件加回去,加一条测一条。尤其注意 [BODY] 的 JSON 路径写法和字符串比较要不要带引号,这是错得最多的地方。

时区对不上,历史曲线看着别扭。 Gatus 容器默认时区通常是 UTC,状态页上的时间点和你本地时间差着时区,半夜的故障看起来像发生在下午。解决办法是在 compose 里给容器加环境变量 TZ=Asia/Shanghai,让日志和展示都回到本地时区。

间隔与保留期的关系没算清。 历史能留多久,取决于拨测间隔和存储里的数据量:60s 间隔的端点一天产生 1440 条记录,端点多了之后 sqlite 文件会稳步长大。不是故障,但要心里有数,磁盘告警别漏了 Gatus 自己的数据目录。

容器里测宿主机上的服务,地址别写 localhost。 Gatus 在容器里运行时,config.yaml 里写 http://localhost:某端口 指的是容器自己,不是宿主机。测同机其他服务时,Linux 上可以在 compose 里给服务加 extra_hosts: ["host.docker.internal:host-gateway"],然后 url 写 http://host.docker.internal:端口;或者干脆测这些服务对外暴露的域名地址,顺带把反向代理这一层也测进去了。

Telegram 告警发不出。 先分清是渠道配置问题还是没触发:把某个端点的 failure-threshold 临时改成 1,再把 url 改成一个必然失败的地址,重启后一分钟内应该收到告警;收不到,就专心查 Bot Token 与 Chat ID——最常见的是机器人没和你说过话、或群 ID 填错。

小结#

Gatus 的价值不在功能多,而在姿态对:监控配置从数据库里的黑盒变成 Git 里的明文,审查、复制、回滚、迁移全部顺理成章。一份 config.yaml 同时搞定拨测、状态页和告警,sqlite 把历史留住,阈值防抖把告警噪音压下去。如果你已经受够了在网页后台里逐个点监控项,或者正想把手里的监控配置纳入版本管理,Gatus 是目前这个路线里最值得先试的一个。

监控与可观测性:Gatus 把状态页写进一个 YAML 文件
https://www.anexns.cloudns.org/posts/monitoring-gatus/
作者
Anexns
发布于
2026-11-16
许可协议
CC BY-NC-SA 4.0