这是「Docker 好项目」系列的第 30 期。这个系列写到第 30 期,回头看第 1 期写的是 Uptime Kuma——一个点鼠标就能配好的监控面板。第 30 期又回到监控,但换了个路子:Uptime Kuma 是「你在网页上点出来的监控」,Gatus 是「你在 YAML 里写出来的监控」。这一期的理由很简单——服务器多了以后,监控配置本身也该进版本管理;而且 Gatus 有几个 Uptime Kuma 天然做不到的能力:条件式健康判断(不只看 200,还看响应体字段、响应时间、证书剩余天数)、给 README 插可实时更新的 SVG 状态徽章、以及把「网络断了」和「服务挂了」区分开。v5.37.0 于 2026-09-24 发布,Apache-2.0,纯 Go 编译成单二进制,12k stars。

顺便把边界说清楚:它不替代 Uptime Kuma,两者定位不同(第 1 期那篇讲的是一次配置 30 个站点的场景,Gatus 更适合「配置文件即监控定义」)。如果你只有两三个站要盯,Uptime Kuma 更省事;如果你要盯十几个服务、还要把状态码和证书写进文档,往下看。

Gatus 效果图

痛点开场

先说清 Gatus 到底是冲着什么问题来的。

作者在 README 里回答的第一个问题就是:「我有 Prometheus + Alertmanager,为什么还要 Gatus?」答案很直白:指标类监控依赖「有流量」。你的负载均衡器半夜挂了,Prometheus 不会报警——因为没有请求打到后端,错误率曲线是一条平线。等到早上有用户访问、开始报错,你的告警才响。这时候你不是在通知用户,而是在被用户通知。

具体到自托管场景,痛点大概是这几条:

  • 指标监控看不到「没人访问」的故障。第 1 期 Uptime Kuma 解决了「从外部主动探测」,但它是纯黑盒的:只看端口通不通、状态码对不对
  • 健康判断太浅。「返回 200」不等于「服务正常」。很多服务挂了之后会返回一个 200 的欢迎页或者 502 的 JSON,肉眼看得出来,但黑盒监控看不出来
  • 证书过期是个固定门票。Let's Encrypt 三个月一续,续期失败不会立刻炸,往往在你最不方便的时候炸。你要的不是「证书过期了」而是「还有 3 天就过期,赶紧看看」
  • 配置点不出版本历史。网页上点出来的监控,谁知道三个月前那个探测条件是谁改的、为什么改
  • 状态页要能给别人看。想在自己的 README 或文档里插一个实时状态徽章,或者给同事一个只看不改的状态页

Gatus 的答案是把监控定义彻底变成声明式 YAML:每个端点写 URL + 一组「条件」,条件里可以用 [STATUS]、[RESPONSE_TIME]、[BODY](支持 JSONPath)、[CERTIFICATE_EXPIRATION]、[DOMAIN_EXPIRATION] 这些占位符,条件全过才算健康。配置文件往 Git 里一丢,谁改的、改了什么都清清楚楚;而且容器支持热加载,改完文件不用重启。

Gatus 监控与告警的数据流

这张是仓库里的架构图:Watchdog 按 interval 主动去请求端点、按你写的 conditions 判定结果,失败的进 Alerting 走各家 Provider(ntfy / Slack / Discord / Telegram / PagerDuty……一共四十来种),结果持久化进 Storage(内存 / SQLite / Postgres),最后通过 Controllers 暴露给 UI。整条链路里唯一需要你写的东西就是 YAML。

能力边界

能干什么(以下基于 v5.37.0 源码与官方 README 逐项核实)

  • 多协议主动探测:HTTP/HTTPS、tcp://、icmp://(ping)、DNS 查询(v5.37.0 起支持 TXT 记录)、SSH、STARTTLS、WebSocket、gRPC、TLS 证书检查、域名到期检查
  • 条件式健康判断:这是它跟 Uptime Kuma 最大的差别。举几个真实用法——
  • [STATUS] == 200:状态码
  • [BODY].status == UP:响应体里 JSONPath 取字段断言(比「状态码是 200」深一层)
  • [BODY] == pat(*<h1>Example Domain</h1>*):响应体里必须出现某段内容(用来防「网关返回 200 但内容是错误页」)
  • [RESPONSE_TIME] < 300:响应时间阈值
  • [CERTIFICATE_EXPIRATION] > 72h:证书还剩多少小时
  • [DOMAIN_EXPIRATION] > 720h:域名还有多久到期
  • has([BODY].errors) == false / len([BODY].data) < 5:has、len、pat、any 四个函数
  • 多级阈值抑制抖动:failure-threshold: 3 表示连续失败 3 次才告警,success-threshold 表示连续成功几次才算恢复,send-on-resolved 表示恢复时再发一条。「抖一下就发消息」这种噪音能压下去
  • 维护窗口:maintenance 里配时间和时长(可以指定只在周几生效),窗口内不告警;还能按端点单独配 maintenance-windows
  • 外部端点(push 模式):external-endpoints 允许别的东西主动把状态推给 Gatus(带上 Bearer token)。适合「Gatus 访问不到的内网机器」反向报活。还带 heartbeat:多久没收到推送就自动判定为故障——这个思路和「定时任务没跑」类监控完全吻合
  • 测试套件(Suites,ALPHA):多个请求串起来跑,前一个请求的返回值能存进上下文供后面用([CONTEXT].token),能测「登录 → 拿数据 → 退出」这种多步流程
  • 状态徽章:/api/v1/endpoints/{key}/uptimes/7d/badge.svg 直接出 SVG,可以插进 README、文档、甚至别的网页。还有 Shields.io 格式、健康状态徽章、响应时间徽章
  • Prometheus 指标:metrics: true 后在 /metrics 暴露,能接进现成的 Grafana
  • 配置热加载:改配置文件不用重启容器(但挂载的是文件本身时可能检测不到,要挂目录,见踩坑)
  • 登录保护:HTTP Basic(密码用 bcrypt 哈希)或 OIDC
  • 界面:暗色为主,支持 ui: 段自定义标题、描述、按钮、Logo、自定义 CSS

不干什么

  • 不点鼠标配置。它的哲学就是配置文件即真相。想「打开网页加一条监控」的人会不适应——这是设计选择,不是缺功能
  • 不做多用户。没有账号体系、没有角色权限,就是一扇门(Basic / OIDC)+ 一个面板
  • 不是告警路由中心。它能往四十来个渠道发消息,但「什么时候发给谁、升级策略」这种复杂编排得靠第 19 期 n8n 或者 Alertmanager 兜
  • 不做日志采集、不做 APM、不看服务器 CPU 内存(那是第 27 期 Beszel 的活)
  • 不自动发现服务。你得自己把每个端点写进 YAML(好处是不会有意外惊喜)
  • 状态页不等于对外公告系统。它有个干净的仪表盘,但没有「发布事件说明、订阅邮件通知」那套事故沟通流程(那是 Uptime Kuma 的强项)

部署前准备

项 说明
镜像 ghcr.io/twin/gatus(官方 README 首选)或 twinproduction/gatus(Docker Hub 同名仓库)。两边是同一份多架构镜像
tag 规则 只有 stable、latest 和完整版本号三种。实测 tag 列表 57 个,v5、v5.37 这类滚动 tag 都不存在;:stable 当前与 :v5.37.0 指向同一个 digest(sha256:9dc46f66…),而 :latest 是另一个 digest(2026-10-07 构建)。本期钉 v5.37.0——stable 会跟着最新 release 走,出问题时你连回滚到哪个版本都说不清
平台 linux/amd64、linux/arm64、linux/arm/v7(树莓派 32 位也能跑,这点比不少 Go 项目友好)
基础镜像 scratch——镜像里只有一个 /gatus 二进制 + CA 证书 + 一份示例 config/config.yaml。没有 shell、没有 curl,docker exec 进去什么都干不了,排障只能看日志
端口 容器内 8080(不是 PORT 环境变量决定的,是 web.port 配置项,默认 8080;Dockerfile 里的 ENV PORT=8080 只是 EXPOSE 用的声明,Go 代码里根本没读它——别指望改这个环境变量换端口)
配置路径 默认读容器的 config/config.yaml(相对工作目录 /,即 /config/config.yaml),读不到再找 config/config.yml。可用 GATUS_CONFIG_PATH 覆盖,如果指向一个目录,目录下所有 *.yaml / *.yml 会被深度合并(endpoints 数组是追加,alerting.slack.webhook-url 这种标量只能出现在一个文件里)
数据卷 镜像没有声明任何 VOLUME,卷要自己挂。要持久化就把 storage.type 设成 sqlite、storage.path 指到挂载点(比如 /data/data.db),再挂 /data
权限 容器以 root 运行;ICMP(ping)探测从 v5.31.0 起不需要额外 capabilities,非特权 ping 即可(官方 README 明确写了)
资源 极小。Go 单二进制,几十 MB 内存量级,256MB 都富裕
注意 官方文档里那句 docker run -p 8080:8080 --name gatus ghcr.io/twin/gatus:stable 是能跑起来的,因为镜像自带示例配置,监控的是 twin.sh 和 example.org。看着它跑起来了别以为配好了——那是别人的站点

docker run 一行版

mkdir -p /opt/gatus/config /opt/gatus/data

cat > /opt/gatus/config/config.yaml <<'EOF'
storage:
  type: sqlite
  path: /data/data.db

endpoints:
  - name: my-blog
    group: web
    url: "https://www.xlee.chat/"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
      - "[CERTIFICATE_EXPIRATION] > 168h"
EOF

docker run -d \
  --name gatus \
  --restart unless-stopped \
  -p 8080:8080 \
  -e GATUS_CONFIG_PATH=/config/config.yaml \
  -e GATUS_LOG_LEVEL=INFO \
  -v /opt/gatus/config:/config \
  -v /opt/gatus/data:/data \
  ghcr.io/twin/gatus:v5.37.0

几个选择的原因:

  • 挂目录而不是挂单个文件。-v /opt/gatus/config:/config 是目录挂载,改完 config.yaml 容器能自动感知并热加载;如果写成 -v /opt/gatus/config/config.yaml:/config/config.yaml(bind 单个文件),官方 issue #151 记着这种情况热加载检测不到,你得手动重启
  • GATUS_CONFIG_PATH=/config/config.yaml 显式写出来。默认值是 config/config.yaml,在容器里就是 /config/config.yaml,效果一样——但显式写能避免「我明明改了文件怎么不生效」这类自我怀疑
  • /data 单独一个目录放 SQLite。配置和数据分开挂,备份策略不一样(配置进 Git,数据靠定时备份)
  • ICMP 探测不用加 --cap-add NET_RAW。v5.31.0 起走非特权 ping 了,老教程里的 --cap-add=NET_RAW --cap-add=NET_ICMP 现在不需要(加了也不报错,只是多余)

国内拉 GHCR 慢的话可以挂镜像加速前缀,但别改掉镜像名本身,否则以后升级对不上。

docker-compose 推荐版

SQLite 版(单机、日常用,本期推荐):

services:
  gatus:
    image: ghcr.io/twin/gatus:v5.37.0
    container_name: gatus
    restart: unless-stopped
    ports:
      # 只绑回环,外部访问走反向代理;不需要反代就去掉 127.0.0.1: 前缀
      - "127.0.0.1:8080:8080"
    volumes:
      - ./config:/config
      - ./data:/data
    environment:
      GATUS_CONFIG_PATH: /config/config.yaml
      GATUS_LOG_LEVEL: INFO
    healthcheck:
      test: ["CMD", "/gatus", "health", "--url", "http://localhost:8080"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 20s

Postgres 版(多实例共用一个库,或者历史数据想留得比 SQLite 更久):

services:
  gatus:
    image: ghcr.io/twin/gatus:v5.37.0
    container_name: gatus
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./config:/config
    environment:
      GATUS_CONFIG_PATH: /config/config.yaml
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17
    container_name: gatus-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: gatus
      POSTGRES_USER: gatus
      POSTGRES_PASSWORD: 换成强密码
    volumes:
      - gatus-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gatus -d gatus"]
      interval: 30s
      timeout: 5s
      retries: 5

volumes:
  gatus-pgdata:

Postgres 版的配置里那一行连接串要写对(这是 Gatus 少见的「配置里塞连接串」的地方):

storage:
  type: postgres
  path: "postgres://gatus:换成强密码@postgres:5432/gatus?sslmode=disable"

depends_on 配 service_healthy 是关键——不配的话 Gatus 可能在 Postgres 还没 ready 时就冲上去连,容器直接 panic 退出(它启动阶段连不上库是致命错误,不是降级)。

healthcheck 里那个 /gatus health --url ... 值得解释一下:因为镜像是 scratch、没有 curl 和 wget,官方只能让二进制自己带一个 health 子命令去请求自己的 /health 端点。这是这个项目的镜像形态倒逼出来的用法,不是常规套路。

配置项逐项解释

顶级配置(只列会在生产里真正调的):

参数 默认值 为什么这么写
endpoints 必填 要监控的端点列表,见下表
storage.type memory 三选一:memory / sqlite / postgres。默认内存,重启即归零,历史全没了——所以只要你在乎「昨天的可用率是多少」,就必须改成 sqlite 或 postgres
storage.path "" sqlite 时是数据库文件路径(如 /data/data.db),postgres 时是完整连接串(不是路径!)。type: memory 时这个字段必须留空,填了会报错
storage.caching false 只在 sqlite / postgres 下生效。写穿缓存,端点特别多(上百)时开,能明显降低仪表盘加载耗时
storage.maximum-number-of-results 100 每个端点保留多少条历史结果。SQLite 长期跑想省空间就调小,想看更长的历史曲线就调大
storage.maximum-number-of-events 50 每个端点保留多少条事件(状态变化记录)
metrics false 开了在 /metrics 出 Prometheus 指标。注意 /metrics 是不受 security 保护的(源码里挂在鉴权中间件之前),要收敛就在反代层限制来源 IP
concurrency 3 同时执行的健康检查数。端点多了(几十个)可以调到 10~20;填 0 表示不限制。调太高会让 [RESPONSE_TIME] 失真(资源竞争导致耗时虚高)
skip-invalid-config-update false 配置写错时 Gatus 默认直接退出。设 true 会保留旧配置继续跑——但官方自己建议别开,因为下次重启会直接起不来。保持 false,改配置前先本地校验 YAML
alerting {} 告警渠道配置,见「告警/通知配置」一节
security.basic {} Basic 认证。端点(endpoints[].ui.hide-*)之外,只有 API 受保护,静态资源和首页不受——要拦页面得靠反代
maintenance {} 全局维护窗口
connectivity.checker.target 无 强烈建议配。写个 1.1.1.1:53,Gatus 会定期确认自己还有外网;一旦自己断网,所有端点检查自动跳过,避免「机房断了,四十个端点一起报警」
ui.title / ui.header / ui.dashboard-heading 见源码默认值 页面标题和顶部文案,改成自己认得出来的名字
ui.dark-mode true 默认暗色。想给别人看一个浅色状态页就设 false
ui.buttons [] 顶部加按钮(名称 + 链接),比如「回首页」「看文档」

端点级配置(endpoints[]):

参数 默认值 为什么这么写
name 必填 显示名,也是 URL key 的来源
group "" 分组名,仪表盘上按组折叠展示。给「web」「internal」「db」这类分组,端点一多就靠它保持可读
url 必填 HTTP 填完整 URL;tcp://host:port、icmp://host、DNS 探测填 DNS 服务器地址
method GET 需要 POST 才健康的服务(少见)才改
conditions [] 条件全部满足才算健康,一条不过就标记为故障。条件写空的话只要请求发出去不出错就算通,几乎是没意义的配置,别偷懒
interval 60s 检查间隔。作者的用法建议:复杂的健康检查用 5m,用来触发告警的关键检查用 30s。太密没意义还涨噪音
headers {} 需要鉴权的端点在这里塞 Authorization,配合下面 ui.hide-url 用
body "" 请求体,支持 [RANDOM_STRING_N]、[ENDPOINT_NAME] 这些占位符,做写操作探测时用
graphql false 开了会把 body 包成 {"query":"..."},调 GraphQL 接口时省事
alerts [] 该端点挂哪些告警渠道。即使配了 default-alert,这里也至少要写 - type: ntfy,不写就是不发
client.insecure false 跳过证书校验。自签名证书的内网服务需要它,但能改就用可信任证书,别长期开
client.timeout 10s 请求超时,见「默认超时」
client.network ip ICMP 走 ip / ip4 / ip6,双栈机器上观察异常时可以显式指定
ui.hide-url false URL 里带 token 时必须打开
ui.hide-conditions false 隐藏判定条件,公开状态页时用(不想暴露内部业务字段名)
ui.hide-errors false 隐藏错误详情,同上
ui.badge.response-time [50, 200, 300, 500, 750] 响应时间徽章的配色阈值(毫秒),按自己服务的正常水线调整
maintenance-windows [] 单端点维护窗口,比如备份脚本每天凌晨跑的时候别告警
extra-labels {} 加进 Prometheus 指标的额外标签,方便 Grafana 里按环境分组
always-run / store 套件专用 只在 Suites 里用

security.basic 的两个字段:

参数 值 说明
username 用户名 明文
password-bcrypt-base64 Base64(bcrypt hash) 不是明文密码,也不是裸的 bcrypt 串,是「bcrypt 哈希再做一次 base64」。生成方法见下节,这是最容易配错的一项

1Panel 面板怎么搞

好消息:1Panel 应用商店收录了 Gatus(对照官方 appstore 仓库核过,官网也有 1panel.pro/apps/gatus 的介绍页)。两条路:

路线 A:应用商店一键装

  1. 「应用商店」搜 Gatus → 安装
  2. 填参数:宿主端口、数据/配置目录
  3. 装完第一件事是去看它的 config.yaml 被放在哪——商店模板里的默认配置监控的是示例站点,你不改成自己的,它就一直是「监控别人的站点」
  4. 商店装的应用通常是绑定挂载配置目录,改完配置生效一般不用重启(热加载),不生效就重启容器

路线 B:容器 → 编排自建(推荐)

商店模板你不好控制版本 tag 和 security 配置,所以更推荐自己贴 compose:

  1. 容器 → 编排 → 创建编排:名称填 gatus,把上面 SQLite 版 compose 贴进去,注意把 ./config、./data 换成 1Panel 里的绝对路径(比如 /opt/1panel/apps/gatus/config)
  2. 先在宿主上把 config/config.yaml 建好再启动,否则容器会读镜像自带的示例配置,成功启动但监控的是 twin.sh——这个坑很隐蔽
  3. 端口冲突先改宿主端口:8080 被占了就改 ports 左边,容器内的 8080 别动(要动得同时改配置里的 web.port)
  4. 防火墙放行:1Panel「主机 → 防火墙」放行宿主端口;华为云 ECS 还要单独去云控制台安全组放行——这一步最容易漏。不过更推荐只绑 127.0.0.1,对外走反代,一个端口都不开
  5. 反向代理(推荐):1Panel「网站 → 反向代理」建一条指向 127.0.0.1:8080,然后在「证书」页签申请 Let's Encrypt
  6. 公开状态页的取舍:如果这个页面要给同事或不认识的人看,两个原则——一是在配置里给敏感端点加 ui.hide-url / ui.hide-conditions / ui.hide-errors(仪表盘要拿到数据才能渲染,加密页面和监控数据本身是矛盾的);二是反代层限制来源 IP,尤其别把 /metrics 暴露出去

首次访问

浏览器打开 http://服务器IP:8080,没有登录步骤(除非你配了 security)。默认进来就是一个暗色的 Health Dashboard。

第一次打开你会看到几个预设端点——front-end、back-end、monitoring、nas,指向 twin.sh 和 example.org。这说明你的配置没被读到,容器用的是镜像里那份示例 config/config.yaml。检查顺序:

# 1. 容器里的配置路径对不对
docker exec gatus ls -l /config   # scratch 镜像没 shell,这条会失败,改用下面方式

# 2. 直接看日志,启动时会打印实际读到的配置文件路径
docker logs gatus | grep -i "Reading configuration"
# 期望看到:[config.LoadConfiguration] Reading configuration from configFile=/config/config.yaml

那个 docker exec 的注释不是玩笑:scratch 镜像里没有 ls、没有 sh,任何 docker exec gatus <命令> 都会报 executable file not found。排障手段只有 docker logs、docker inspect 和宿主侧的文件操作。

配置读对了之后,仪表盘上就是你自己的端点了。每个端点是一张卡片:名称、分组、URL、健康徽章(Healthy / Unhealthy)、一排细长的历史结果条(绿=成功、红=失败、灰=无数据),鼠标悬停能看到那次检查的时间戳、响应时间和每条条件的判定结果。顶部有搜索框、Filter 和 Sort。「No Group」是没写 group 的端点。

Gatus 端点分组视图

点单个卡片进入端点详情页,那里有更长的历史、响应时间图表,以及这个端点所有可用徽章的地址——想往 README 里插徽章的话,直接从这里复制。

最小可用配置

目标:五分钟内让 Gatus 开始监控你自己的服务,并且历史能存住。

# /opt/gatus/config/config.yaml
storage:
  type: sqlite
  path: /data/data.db
  maximum-number-of-results: 200

connectivity:
  checker:
    target: 1.1.1.1:53
    interval: 60s

ui:
  title: "Status | 我的服务"
  header: "Status"
  dashboard-heading: "服务健康总览"
  dashboard-subheading: "每 5 分钟主动探测一次"
  default-sort-by: group

endpoints:
  # 1. 自己的网站,看状态码 + 证书剩余时间
  - name: blog
    group: web
    url: "https://www.xlee.chat/"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1500"
      - "[CERTIFICATE_EXPIRATION] > 168h"   # 剩一周以上才算健康

  # 2. 有健康检查接口的服务,直接断言接口返回
  - name: halo-api
    group: web
    url: "https://www.xlee.chat/actuator/health"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == UP"

  # 3. 内网服务,只关心端口通不通
  - name: nas-ssh
    group: internal
    url: "tcp://192.168.31.193:22"
    interval: 1m
    conditions:
      - "[CONNECTED] == true"

  # 4. 域名到期,一天查一次就够
  - name: domain-xlee-chat
    group: infra
    url: "https://www.xlee.chat/"
    interval: 24h
    conditions:
      - "[DOMAIN_EXPIRATION] > 720h"        # 剩 30 天以上

这几条覆盖了日常最实用的四种模式:状态码 + 响应时间(网站)、响应体字段(有 API 的服务)、纯连通性(内网设备)、到期类(域名/证书)。

配完看日志确认没有 not valid 之类的报错,刷新页面就能看到四张卡片。注意 [BODY].status == UP 这类条件写错了不会在启动时报错,只会让那个端点一直显示 Unhealthy——加完端点第一次要去详情页看一眼条件判定,别配完就不管。

告警/通知配置

Gatus 支持四十来种告警渠道。自托管场景里最顺手的两个:ntfy(第 13 期那个,手机上装个 App 就能收)和 通用 webhook(接 n8n、接企业微信机器人、接任何东西)。

推荐写法:default-alert + 端点里只写类型

alerting:
  ntfy:
    topic: "gatus-alerts"
    url: "https://ntfy.example.com"     # 自建 ntfy 的地址;用公共 ntfy.sh 就删掉这行
    token: "tk_你的访问令牌"             # 自建实例开了鉴权才需要
    priority: 3
    click: "https://status.example.com" # 手机点通知跳到状态页
    default-alert:
      enabled: true
      failure-threshold: 3      # 连续失败 3 次才发(5m 间隔 = 15 分钟)
      success-threshold: 2      # 连续成功 2 次才算恢复
      send-on-resolved: true    # 恢复时补一条,不然你不知道什么时候好的
      description: "健康检查失败"
    overrides:                  # 按分组覆盖:内网设备用另一个 topic
      - group: "internal"
        topic: "gatus-internal"
        priority: 2

  # 通用 webhook:接 n8n / 企业微信机器人 / 自己的脚本
  custom:
    url: "https://n8n.example.com/webhook/gatus"
    method: "POST"

endpoints:
  - name: blog
    group: web
    url: "https://www.xlee.chat/"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: ntfy          # 用了 default-alert,这里仍然必须写 type

三个必须记住的点:

  1. default-alert 不会自动生效。它只是「预置参数」,端点 alerts 里还是要写 - type: ntfy。官方 README 对这点有明确警告
  2. failure-threshold 要跟 interval 一起算。5m 间隔配 threshold: 3 意味着故障 15 分钟后才叫你;30s 间隔配 3 意味着 1 分半。想「快但别抖」就把关键端点的 interval 压到 30s,阈值留 2~3
  3. send-on-resolved: true 建议都打开。不然告警只有「坏了」没有「好了」,你半夜收到消息之后还得自己爬起来确认

配完怎么验证?把某个端点的 URL 改成一定访问不到的地址(比如 https://127.0.0.1:9/),interval 临时调到 30s,等阈值到点收通知;收到之后改回来,等 send-on-resolved 的恢复消息。别指望「配完就信」——告警没验证过等于没配,这是所有监控系统的通病。

排查用 GATUS_LOG_LEVEL=DEBUG,日志里会打印 configuredProviders=[...] 和 ignoredProviders=[...],能直接看出哪个 Provider 没被识别(配置写错时它会被静默忽略,只是不工作,不报错)。

反向代理与 HTTPS

Gatus 是普通 HTTP 服务,没有 WebSocket 之类的特殊要求,反代配置很标准。以第 2 期 Nginx Proxy Manager 为例:Proxy Host 转发到 127.0.0.1:8080,SSL 页签申请 Let's Encrypt 证书并打开 Force SSL。

原生 nginx 配置:

server {
    listen 443 ssl;
    server_name status.example.com;
    # ssl_certificate / ssl_certificate_key 略

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # /metrics 不经过 Gatus 的鉴权,在反代层关掉或限 IP
    location = /metrics {
        allow 192.168.31.0/24;
        deny all;
        proxy_pass http://127.0.0.1:8080/metrics;
    }
}

注意 Gatus 的鉴权覆盖范围:security.basic 只保护 /api/v1/... 下的受保护路由,首页 HTML 和静态资源是不拦的。也就是说,光配了 Basic 不等于「整个面板要登录才能看」——想真正做到「打开就要密码」,最省事的办法是在反代层做 Basic 认证(NPM 里叫 Access List,nginx 里用 auth_basic + htpasswd 文件),让它挡在 Gatus 前面。

# 反代层做 Basic 认证(NPM 的 Access List 就是这个原理)
htpasswd -c /etc/nginx/.htpasswd_status admin

另外两个反代侧的注意点:

  • 不要开 proxy_buffering off。Gatus 的响应时间探测是服务端行为,跟反代无关,但仪表盘会轮询 API 拉状态,关掉缓冲只是白白增加后端压力
  • 想公开状态页但不想被人乱扫:在反代层对 /api/v1/endpoints/statuses 限速即可,不要直接把端口开在公网

如果只在家用、不上公网,那就直接 http://192.168.x.x:8080,不必折腾证书。

踩坑清单

  1. 以为改了 PORT 环境变量就能换端口——不行。Go 代码里根本没读 PORT,端口只认配置里的 web.port(默认 8080)。Dockerfile 里的 ENV PORT=8080 只配 EXPOSE 用
  2. 容器起来了,仪表盘显示的是 twin.sh 和 example.org——你的配置没被读到,容器在用镜像自带的示例 config/config.yaml。用 docker logs 里的 Reading configuration from configFile=... 确认实际读的路径
  3. docker exec gatus sh 报找不到可执行文件——镜像是 scratch,里面只有一个二进制。排障只能看日志、查 docker inspect、在宿主侧改文件
  4. 挂了单个配置文件,改完不生效——热加载在 bind mount 单文件时可能检测不到(官方 issue #151)。挂目录而不是挂文件
  5. 改了配置容器直接退出——skip-invalid-config-update 默认 false,配置写错时它选择退出而不是带病运行。改配置前先用 yamllint 或者随便找个在线 YAML 校验过一遍。别为了「容错」把它设成 true,官方自己也建议保持默认
  6. Basic 认证配了但页面还是能直接打开——security.basic 只保护 API 路由,首页和静态资源不受保护。要「打开就要密码」得在反代层做 Basic
  7. password-bcrypt-base64 填了密码明文/bcrypt 串就是登不进去——它要的是 base64(bcrypt(password))。用 htpasswd -bnBC 9 "" '你的密码' | tr -d ':\n' 生成 bcrypt 串,再 base64 一次。官方示例里的成本参数是 10,文档建议 9(Basic 认证每次请求都要验一遍密码,成本越高越慢)
  8. storage.type 用了 sqlite 但没写 path——启动直接报错 sql storage requires a non-empty path。反过来,type: memory 时写了 path 也会报 memory storage does not support persistence
  9. Postgres 版的 path 写成了文件路径——type: postgres 时 path 要填完整连接串 postgres://user:pass@host:5432/db?sslmode=disable,不是目录
  10. 重启后历史数据全丢——默认 storage.type: memory,不持久化。要留历史就切 sqlite/postgres
  11. ICMP 探测加了 --cap-add NET_RAW 还是不通——先看客户端配置;v5.31.0 起非特权 ping 已经够用,加 capabilities 是多余的。真不通时按官方指引看 pro-bing 的 Linux 说明(net.ipv4.ping_group_range 之类的内核参数)
  12. /metrics 被公网扫到——metrics: true 时它挂在鉴权中间件之前,不受 security 保护。要么反代限 IP,要么只绑回环
  13. 告警配了但从来没收到过——两个高频原因:端点 alerts 里忘了写 - type: ntfy(default-alert 不会自动挂载);或者 Provider 名写错被静默忽略(用 GATUS_LOG_LEVEL=DEBUG 看 ignoredProviders)
  14. [BODY] 条件对非 JSON 响应报错/一直 Unhealthy——[BODY].xxx 是 JSONPath,响应体不是 JSON 就用 [BODY] == pat(*关键字*) 这种模式匹配
  15. 机房断网导致四十个端点一起报警——没配 connectivity.checker。配上 target: 1.1.1.1:53,自己断网时自动跳过所有检查
  16. 端点太多时响应时间数字很奇怪——concurrency 调太高会让 [RESPONSE_TIME] 因资源竞争虚高。官方建议复杂度高的检查间隔给 5m,告警用的简单检查才给 30s
  17. ipconfig 改了 interval 但没看到变化——interval 小于「上一次检查耗时」时,实际执行间隔会被拉长(官方文档专门说了这点)。别给复杂检查配 5s
  18. 维护窗口没生效——maintenance.timezone 默认是 UTC。想按北京时间每天凌晨 2 点静默,要写 timezone: "Asia/Shanghai" 和 start: "02:00",不然会在北京时间上午 10 点开始静默
  19. 外部端点(push 模式)收不到数据 401——Authorization: Bearer <token> 里的 token 是配置里 external-endpoints[].token 的值,且推送路径的 key 是 <组名>_<端点名>,空格、/、_、.、#、+、& 都会被替换成 -
  20. 把 ui: 配了一堆结果没看到变化——浏览器 localStorage 里会缓存 UI 偏好,换浏览器或清一下本地存储再看

备份

Gatus 要备的东西不多,就两样:配置文件和存储数据。

配置进 Git(最重要的一条)

cd /opt/gatus
git init
git add config/config.yaml
git commit -m "gatus: 初始监控配置"

这是 Gatus 相对点击式监控最大的价值:谁在什么时候加了哪个端点、为什么把阈值从 3 改成 5,全在 commit 历史里。可以配合一个 systemd timer / cron,每天把改动自动 commit 一次。

SQLite 数据(历史与可用率)

# 建议在容器停止时打包,SQLite 正在写时直接 cp 可能拿到不一致的快照
docker stop gatus
tar czf /backup/gatus-data_$(date +%F).tar.gz -C /opt/gatus/data .
docker start gatus

不停容器的话,用 SQLite 官方的在线备份方式更安全:

# 容器里没有 sqlite3,得在宿主上操作(宿主装了 sqlite3 才行)
sqlite3 /opt/gatus/data/data.db ".backup '/backup/gatus-data_$(date +%F).db'"

Postgres 版:用 pg_dump 就行,容器里就有现成的工具:

docker exec gatus-postgres pg_dump -U gatus -d gatus \
  | gzip > /backup/gatus_$(date +%F).sql.gz

要不要备「数据」这件事,取决于你怎么用 Gatus:如果你只是拿它做即时告警(坏了就发消息),历史数据丢了影响不大——配置在 Git 里,重建容器十分钟的事,data.db 不备也行。如果你想在 Grafana 里看三个月的可用率曲线,那 SQLite/Postgres 的数据就必须认真备。

不管哪种方案,备份文件别只留在同一台机器上——接第 21 期 Kopia 同步到对象存储,才叫备份。

小结

适合谁:手上管着十几个以上服务、习惯把配置写进 Git 的人;需要「不只看 200,还要断言响应体字段」的深度健康检查的人;想在 README 或文档里插实时状态徽章的人;证书/域名到期这类「固定日期炸弹」想统一盯的人;服务器上跑着好几种架构(amd64 + ARM)需要同一份配置的人。已经有 Uptime Kuma 但觉得「点出来的配置没法管」的人,是本期最典型的读者。

不适合谁:就盯两三个站点、偶尔看看的人(Uptime Kuma 点两下更快,别为了 YAML 而 YAML);需要多人协作、分角色权限的团队(没有账号体系);需要复杂告警路由和升级策略的(那是 Alertmanager 的领域);想监控服务器 CPU/内存/磁盘的(那是第 27 期 Beszel);需要对外发布事故公告和邮件订阅的(Uptime Kuma 的状态页更完整)。

跟第 1 期 Uptime Kuma 的关系,一句话讲清:Uptime Kuma 是「一个人肉点出来的监控面板」,Gatus 是「一份能进 Git 的监控配置」。前者上手快、界面友好、状态页功能全;后者判定条件更深、配置可版本化、徽章能嵌进文档、镜像小到几十 MB。真正的最优解是两个都装:Gatus 做深度探测和对外徽章,Uptime Kuma 做那道「机房整体挂了」之外的兜底与状态页——它们监控同一个服务并不冲突,视角不同而已。

项目地址

  • GitHub:https://github.com/TwiN/gatus(Apache-2.0,12k stars,最新 release v5.37.0,2026-09-24 发布,约两周一个版本)
  • 官方文档:README 本身就是最完整的文档,配置项、条件语法、四十多个告警渠道的接入方式全在里面,.examples/ 目录有 SQLite / Postgres / Grafana 三套现成 compose
  • 镜像:ghcr.io/twin/gatus:v5.37.0(Docker Hub 同名镜像 twinproduction/gatus:v5.37.0)
  • 1Panel:应用商店已收录,也可走「容器 → 编排」贴 compose 自建(推荐,便于钉版本)
  • 配套:第 13 期 ntfy(手机推送)、第 19 期 n8n(告警转微信/钉钉)、第 2 期 Nginx Proxy Manager(反代 + HTTPS)、第 27 期 Beszel(资源层监控,与 Gatus 互补)