🇺🇸 English | 🇸🇦 العربية | 🇪🇸 Català | 🇨🇿 Čeština | 🇩🇪 Deutsch | 🇪🇸 Español | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇧🇷 Português (Brasil) | 🇷🇺 Русский | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇨🇳 简体中文 | 🇹🇼 繁體中文

Checkmate

一个开源的在线状态与基础设施监控应用

此仓库包含 Checkmate 的前端与后端。Checkmate 是一款开源、可自托管的监控工具，用于实时追踪服务器硬件、在线状态、响应时间和故障事件，并提供美观的可视化。Checkmate 会定期检查服务器/网站是否可访问并运行良好，实时提供所监控服务的可用性、宕机时长和响应时间的告警与报告。

Checkmate 还提供一个名为 Capture 的采集代理，用于从远程服务器获取数据。虽然运行 Checkmate 不需要 Capture，但它可以提供有关服务器 CPU、内存、磁盘和温度状态的额外洞察。Capture 可以运行在 Linux、Windows、Mac、Raspberry Pi 或任何能够运行 Go 的设备上。

Checkmate 已在 1000 多个活动监控器下经过压力测试，未出现明显问题或性能瓶颈。

📚 目录

• 📦 演示
• 🔗 用户指南
• 🛠️ 安装
• 🚀 性能
• 💚 问题与建议
• 🧩 功能特性
• 🏗️ 截图
• 🏗️ 技术栈
• 🔗 相关链接
• 🤝 贡献

演示

你可以在线查看 Checkmate 的最新构建效果。

用户名是 demouser@demo.com，密码是 Demouser1!（请注意，我们会不定期更新演示服务器，如果你无法访问，请在 Discussions 频道提醒我们。）

用户指南

使用说明可在这里查看。

前置条件

• 已安装 Docker
• 已安装 Git

安装

最快启动 Checkmate 的方式是使用参考 Docker Compose 文件。该文件会启动两个服务：一体化 Checkmate 应用镜像（ghcr.io/bluewave-labs/checkmate）以及独立的 MongoDB 服务。

“all-in-one” 的含义： Checkmate 应用被打包在单个镜像中；MongoDB 并未内嵌在该镜像中，仍是必需组件。参考 Compose 文件会为你启动 MongoDB。对于自定义部署，请配置 DB_CONNECTION_STRING 以使用外部 MongoDB 实例。

curl -O https://raw.githubusercontent.com/bluewave-labs/checkmate/master/docker/docker-compose.yaml
JWT_SECRET="$(openssl rand -hex 32)" docker compose up -d

然后打开 http://localhost:52345。如果该应用通过另一个源（域名或局域网 IP）访问，请相应设置 CLIENT_HOST。若要自行构建镜像，请在检出目录中运行 docker build -f docker/Dockerfile -t checkmate .。如需使用 TLS，可在 52345 端口前部署任意反向代理（Caddy、Traefik、nginx）。

此外，也可以使用 Repocloud、Pikapods、Coolify、Elestio、Easypanel、K8s、Sive Host 或 Cloudzy 等一键部署选项。请注意，Helm chart 尚未迁移到一体化镜像：它仍然部署传统的 checkmate-client、checkmate-backend 和 checkmate-mongo 镜像，并且固定在 v3.8.1。

配置

该镜像完全通过服务器容器上的环境变量进行配置：

变量	是否必填	说明
DB_CONNECTION_STRING	是	MongoDB 连接字符串，例如 mongodb://mongodb:27017/uptime_db
JWT_SECRET	是	用于签发身份验证令牌的密钥；可使用 openssl rand -hex 32 生成
CLIENT_HOST	是	用户访问该应用的 URL，例如 https://checkmate.example.com；用于 CORS 以及通知和邮件中的链接
ENCRYPTION_KEY	否	用于加密静态存储的 Docker TLS 客户端密钥；可使用 openssl rand -base64 32 生成。支持逗号分隔的列表：第一个密钥用于加密，所有密钥都可用于解密。API 和每个 worker 上的该值必须保持一致。若要在不停机的情况下轮换密钥，请先在所有位置部署 OLD_KEY,NEW_KEY，然后在所有位置改为 NEW_KEY,OLD_KEY，等待 worker 重新加密所有记录后，再移除 OLD_KEY。
PORT	否	API 和 Web 客户端提供服务的端口（默认 52345）
HEALTH_PORT	否	用于 /livez、/readyz 和 /metrics 端点的端口，由运行 job worker 的任意进程提供服务（默认 52346）
NODE_ENV	否	development、production 或 test（默认 development）。development 会禁用通用 API 速率限制器；正式部署时请设置为 production
LOG_LEVEL	否	服务器日志级别：error、warn、info 或 debug（默认 debug）
TOKEN_TTL	否	签发的身份验证令牌有效期，例如 12h 或 7d（默认 99d）
QUEUE_MODE	否	primary（默认）运行 API、Web 客户端和任务调度器；worker 仅运行任务处理 worker，不提供 API
QUEUE_PRIMARY_PROCESSES	否	true（默认）或 false。控制 primary 节点是否同时自行处理监控任务；当专用的 worker 节点负责所有检查时，请设置为 false。在 worker 模式下会被忽略
STATUS_PAGE_THEMES_ENABLED	否	true（默认）或 false。当设置为 false 时，状态页将忽略主题设置，并始终渲染默认主题

Web 客户端默认无需任何配置：它会调用其来源相同的 API（/api/v1）。对于默认设置不适用的场景——例如 API 通过不同于页面的源访问——服务器会在运行时通过以下可选变量将覆盖配置渲染到客户端中：

变量	说明
CLIENT_CONFIG_API_BASE_URL	客户端调用 API 的完整基础 URL，例如 https://api.example.com/api/v1；默认为同源 /api/v1
CLIENT_CONFIG_CLIENT_HOST	客户端构建绝对链接时使用的源（邀请、状态页）；默认为浏览器当前源
CLIENT_CONFIG_LOG_LEVEL	浏览器控制台日志级别：error、warn、info 或 debug（默认 error）

从旧版镜像升级？ UPTIME_APP_* 变量（UPTIME_APP_API_BASE_URL、UPTIME_APP_CLIENT_HOST、UPTIME_APP_LOG_LEVEL）已不再读取。在大多数部署环境中无需替代配置——同源默认值即可满足需求；如果你之前将客户端指向了另一个源，请使用上述 CLIENT_CONFIG_* 对应变量。checkmate-client、checkmate-backend、checkmate-mongo 和 checkmate-backend-mono-multiarch 镜像已不再更新——请切换到 ghcr.io/bluewave-labs/checkmate，并保留现有的 MongoDB 服务与数据卷。

完整安装说明请参阅 Checkmate 文档门户。

或者，你也可以使用 Coolify、Elestio、K8s（传统镜像，固定在 v3.8.1）、Sive Host（南非）、Cloudzy 或 Pikapods 快速部署一个 Checkmate 实例。如果你希望监控服务器基础设施，则需要 Capture 代理。Capture 仓库中也包含安装说明。

使用自定义 CA

如果需要监控使用私有证书颁发机构（如 Smallstep）签发证书的内部 HTTPS 端点，请参考我们的自定义 CA 信任指南，以了解 Docker 配置选项。

Docker 监控器

Docker 监控器会报告主机上正在运行的每个容器。它可以直连 Docker 守护进程，也可以从 Capture 代理读取容器指标。直连监控器使用守护进程的 ping 响应来判断可用性，并记录容器状态、健康状态、CPU 和内存使用率、重启次数、已发布端口以及挂载。启用 收集容器日志 后，每次直连检查还会额外保存每个容器最新的 200 行日志；日志保留 7 天。

Docker 主机 字段支持以下三种形式：

主机	示例	说明
本地套接字	unix:///var/run/docker.sock	也接受不带协议的绝对路径，例如 /var/run/docker.sock。当监控 Checkmate 所在主机上的 Docker 守护进程时，请使用该值。
远程守护进程	tcp://docker.example.com:2376	始终使用双向 TLS；端口默认为 2376。不支持位于 2375 端口上的未加密守护进程。
Capture 代理	https://capture.example.com/api/v1/metrics/docker	填写以 /metrics/docker 结尾的完整端点及其授权密钥。Checkmate 会请求 all=true，因此已停止的容器也会被包含在内。

基于 Capture 的监控器会将 Capture 提供的容器状态、健康状态、CPU、内存、启动时间和已暴露端口归一化为相同的 Docker 页面。Capture 当前不提供重启次数、挂载、已发布的主机端口绑定或容器日志，因此这些值将显示为不可用。Capture 还会将健康检查仍处于启动阶段的容器报告为健康，因此 starting 健康状态只会出现在直连监控器中；已停止的容器不会携带 CPU 或内存指标。

监控本地套接字。 参考 Compose 文件未挂载该套接字，因此需要添加挂载，并授权容器使用主机的 docker 用户组。该镜像以非特权用户身份运行，否则将无法读取该套接字。使用 stat -c %g /var/run/docker.sock 查找用户组 ID，然后：

services:
  checkmate:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    group_add:
      - "989"   # the gid printed by stat

监控远程守护进程。 将主机设置为 tcp://host:port，并在监控表单的 TLS 凭据 部分填入你传给 docker --tlsverify 的相同 PEM 文件：

• CA 证书：签发守护进程服务器证书的 CA。除非开启 忽略 TLS/SSL 错误，否则必填；该选项会跳过对守护进程身份的验证。
• 客户端证书：守护进程用于验证 Checkmate 身份的证书。
• 客户端密钥：与证书匹配的私钥，未加密（无密码短语）。Checkmate 会校验它与证书是否匹配，使用 ENCRYPTION_KEY 加密，并且之后不会再显示。编辑时留空该字段可保留已存储的密钥。

使用 TLS 的 Docker 监控要求服务器上设置 ENCRYPTION_KEY（参见配置）。若未设置就保存，会失败并显示相应错误提示。若该密钥被删除或轮换错误，受影响的检查会在密钥恢复前持续出现解密错误。

如果守护进程的证书由某个私有 CA 签发，并且你还希望 Checkmate 的其他部分也信任该 CA，请参见自定义 CA 信任指南；仅对 Docker 监控而言，CA 证书 字段即可。

使用 TLS 保护 Docker 守护进程

Docker 守护进程默认未启用 TLS。在 Docker 主机上按照以下步骤，为 Checkmate 生成 CA、服务器证书和客户端证书。这是根据 Docker 官方指南 整理的流程。请将 docker.example.com 和 203.0.113.10 替换为你的守护进程 DNS 名称和 IP 地址。

1. 创建 CA。 CA 密钥会设置密码短语；证书签发后，请将其离线保存。

openssl genrsa -aes256 -out ca-key.pem 4096
openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -subj "/CN=docker-ca" -out ca.pem

2. 创建服务器证书。 Subject Alternative Names 必须包含 Checkmate 用于连接 daemon 的所有名称或地址。

openssl genrsa -out server-key.pem 4096
openssl req -subj "/CN=docker.example.com" -sha256 -new -key server-key.pem -out server.csr
cat > server-ext.cnf <<EOF
subjectAltName = DNS:docker.example.com,IP:203.0.113.10
extendedKeyUsage = serverAuth
EOF
openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out server-cert.pem -extfile server-ext.cnf

3. 为 Checkmate 创建客户端证书。 请勿为该密钥添加密码短语；Checkmate 无法使用加密私钥。

openssl genrsa -out key.pem 4096
openssl req -subj "/CN=checkmate" -new -key key.pem -out client.csr
echo "extendedKeyUsage = clientAuth" > client-ext.cnf
openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out cert.pem -extfile client-ext.cnf
rm client.csr server.csr server-ext.cnf client-ext.cnf
chmod 0400 ca-key.pem key.pem server-key.pem
chmod 0444 ca.pem server-cert.pem cert.pem

4. 为守护进程指定证书。 将 ca.pem、server-cert.pem 和 server-key.pem 移至 /etc/docker/certs/，并配置 /etc/docker/daemon.json：

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],
  "tls": true,
  "tlsverify": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem"
}

在 systemd 单元已传递 -H fd:// 的发行版（Debian、Ubuntu 及衍生版）上，当两处都设置了 hosts 时，daemon 会拒绝启动。请使用 override 从单元中移除该标志，然后重启：

sudo systemctl edit docker.service

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

sudo systemctl daemon-reload && sudo systemctl restart docker

仅将主机防火墙上的 2376 端口开放给运行 Checkmate 的机器。

5. 在 Checkmate 主机上验证，然后将 ca.pem、cert.pem 和 key.pem 粘贴到监控表单中：

docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \
  -H=docker.example.com:2376 version

更多文档，请参见 docs 目录。

性能

得益于全面优化，Checkmate 的内存占用极低，仅需极少的内存与 CPU 资源。以下是在服务器上运行的 Node.js 实例的内存使用情况，该实例每分钟监控 323 台服务器：

在监控相同数量服务器的情况下，同一台服务器上 MongoDB 的内存占用（398Mb）如下：

问题与建议

如有任何问题、建议或意见，你可以选择以下任一方式：

• Discord 频道（推荐）
• GitHub 讨论区（我们会时不时查看）

欢迎随时提出问题或分享你的想法，我们很期待听到你的声音！

功能

• 完全开源，可部署在你的服务器或家用设备上（例如 Raspberry Pi 4 或 5）
• 多种监控方式：HTTP（含 SSL 证书到期检查）、Ping、端口、DNS、Docker、gRPC、WebSocket、游戏服务器
• 页面速度监控
• 基础设施监控（内存、磁盘使用量、CPU 性能、网络等） - 需要 Capture 代理
  • 支持按挂载点选择磁盘监控
• 故障事件一目了然
• 提供 5 款精美主题的状态页
• 支持电子邮件、Webhooks、Discord、Slack、PagerDuty、Matrix、Rocket.Chat、Microsoft Teams、Telegram、Pushover、ntfy、SignalGrid、Twilio（短信）通知
• 计划内维护
• JSON 查询监控
• 多语言支持：阿拉伯语、加泰罗尼亚语、简体中文、繁体中文（台湾）、捷克语、英语、芬兰语、法语、德语、意大利语、日语、波兰语、葡萄牙语（巴西）、俄语、西班牙语、泰语、土耳其语、乌克兰语和越南语

监控器生命周期

1. 监控器会执行一次检测（HTTP / ping / 端口 / 通过 Capture 代理的硬件）
2. 检测结果会被存储（成功/失败 + 响应时间）
3. 最近的检测结果会对照监控器中配置的状态变更阈值进行评估
4. 如果满足监控器的状态变更阈值，且当前状态与上一状态不同，则监控器的状态会发生变化（例如：initializing、up、down、breached）
5. 状态发生变化时：会根据监控器的当前状态创建或解决事件
6. 将根据配置触发通知

截图

技术栈

• ReactJs
• MUI（React 框架）
• Node.js
• MongoDB
• Recharts
• 还有众多其他开源组件！

相关链接

• 如果你愿意支持我们，请考虑点个 ⭐ 并点击“watch”。
• 对路线图/功能集有任何问题或建议？请查看我们的 Discord 频道 或 Discussions 论坛。
• 希望在有新版本发布时收到提醒？请使用 Newreleases，这是一个用于跟踪发布的免费服务。
• 观看 Checkmate 的安装与使用视频

贡献

我们是 Alex（团队负责人）、Gorkem、Aryaman、Malena 和 Mert，致力于帮助个人和企业监控其基础设施和服务器。

我们始终以与不同层级的贡献者建立紧密联系为荣。尽管 Checkmate 仍是一个年轻的项目，但它已经收获了近 1.1 万 star，并吸引了来自全球各地的 150 多名贡献者。

我们的仓库获得了来自 Google, Microsoft, Intel, Cisco, Tencent, Electronic Arts, ByteDance, JP Morgan Chase, Deloitte, Accenture, Foxconn, Broadcom, China Telecom, Barclays, Capgemini, Wipro, Cloudflare, Dassault Systèmes and NEC 员工的 star，因此不要犹豫——加入进来，与我们一起贡献和学习吧！

你可以通过以下方式做出贡献：

0. 给这个仓库 star 😃
1. 查看 贡献者指南。鼓励初次贡献者查看 good-first-issue 标签。
2. 如果你希望深入了解架构，请阅读 Checkmate 的详细结构。
3. 如果你认为遇到了 bug，请提交 issue。
4. 如果你是新人，请查看 good-first-issue 相关问题。
5. 发起 pull request，以添加新功能、提升使用体验或修复 bug。
6. 在 CodeCanvas 上查看 Checkmate 代码库的交互式导览 这里。若要完善现有数据流模拟或创建新的模拟，请按照快速教程 这里。