Checkmate 中文完全指南：自托管开源可用性与基础设施监控平台的部署、配置与运行原理

Checkmate 中文完全指南：自托管开源可用性与基础设施监控平台的部署、配置与运行原理

【免费下载链接】CheckmateCheckmate is an open-source, self-hosted tool designed to track and monitor server hardware, uptime, response times, and incidents in real-time with beautiful visualizations. Don't be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/Checkmate

Checkmate 是一款完全开源、可自托管的可用性与基础设施监控应用，前端与后端代码统一存放在同一仓库中。本指南以仓库内的简体中文 README 为主体，结合 docker-compose.yaml、Helm 安装指南、自定义 CA 信任指南 以及服务端源码，系统讲解 Checkmate 的安装部署、环境变量配置、Docker 监控、监控生命周期原理与性能表现，帮助你快速上手并把监控系统真正跑起来。

项目概览：一个仓库，前后端一体

Checkmate 是一个开源、可自托管的监控工具，通过精美的可视化效果实时追踪服务器硬件、可用性、响应时间以及事件。它会定期检查服务器或网站是否可访问、运行是否正常，并针对被监控服务的可用性、停机时间和响应时间提供实时告警与报告。

本仓库同时包含 Checkmate 的前端和后端代码。构建后的镜像将前端静态资源与后端服务打包为单个 "all-in-one" 镜像，通过 docker/Dockerfile 分两个阶段构建：先在前端阶段（node:22-slim+npm ci && npm run build）产出纯 JS 静态资源，再在后端阶段将client/dist复制为服务器的public目录，由 Node.js 后端同时对外提供 Web 页面与 API 服务。

技术栈

根据 README 的技术栈章节，Checkmate 采用以下核心组件：

• React.js：前端 UI 框架
• MUI (Material-UI)：React 组件库
• Node.js：后端运行时
• MongoDB：数据存储
• Recharts：可视化图表库

除此之外还依赖大量其他开源组件。前端源码位于 client/src，后端源码位于 server/src。

配套代理 Capture

Checkmate 还提供一个名为Capture的代理程序，用于从远程服务器拉取数据。Capture 并不是运行 Checkmate 所必需的，但它能提供服务器CPU、内存、磁盘和温度的额外信息（对应基础设施监控与硬件监控能力）。Capture 可在 Linux、Windows、Mac、Raspberry Pi 或任何能运行 Go 的设备上运行。

核心功能一览

Checkmate 的功能覆盖从可用性探测到告警触达的完整链路，主要包括：

• 完全开源，可部署到自己的服务器或家用设备（如 Raspberry Pi 4/5）
• 多种监控选项：可用性（HTTP）、Docker、Ping、SSL、端口、游戏服务器等。从 monitor.type.ts 的源码定义可以看到，Checkmate 支持http、ping、pagespeed、hardware、docker、port、game、grpc、websocket、dns等监控类型
• 页面速度监控（PageSpeed，支持桌面/移动两种策略，见 monitor.type.ts）
• 基础设施监控（内存、磁盘使用情况、CPU 性能、网络等）——需要 Capture 代理，并支持通过挂载点选择实现的选择性磁盘监控
• 一目了然的事件视图（Incidents）
• 多套精美主题的状态页（Status Pages）
• 多渠道通知：邮件、Webhook、Discord、Slack、PagerDuty、Matrix、Microsoft Teams、Telegram、Pushover、Twilio (SMS) 等
• 计划维护（Maintenance Windows）
• JSON 查询监控
• 多语言支持：阿拉伯语、简体中文、繁体中文（台湾）、捷克语、英语、芬兰语、法语、德语、日语、葡萄牙语（巴西）、俄语、西班牙语、泰语、土耳其语、乌克兰语和越南语（对应仓库 client/src/locales 下的 19 个语言文件）

前置要求与安装部署

前置要求

• 已安装Docker
• 已安装Git

快速启动：参考 Docker Compose 文件

仓库根目录提供了开箱即用的参考 Docker Compose 文件，它启动两个服务：all-in-one 的 Checkmate 应用镜像（ghcr.io/bluewave-labs/checkmate:latest）和独立的 MongoDB 服务（mongo:8.0）。

"all-in-one" 的含义：Checkmate 应用被封装在单个镜像中，但 MongoDB 并未内嵌于该镜像，仍是必需依赖。参考 Compose 文件会为你自动启动 MongoDB；自定义部署时，通过DB_CONNECTION_STRING环境变量接入外部 MongoDB 实例即可。

启动方式（也可使用仓库内的 docker/docker-compose.yaml）：

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）即可。

参考 Compose 文件结构

services: checkmate: image: ghcr.io/bluewave-labs/checkmate:latest pull_policy: always restart: always ports: - "52345:52345" environment: - DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db - CLIENT_HOST=${CLIENT_HOST:-http://localhost:52345} - JWT_SECRET=${JWT_SECRET:?set JWT_SECRET in your environment} - ENCRYPTION_KEY=${ENCRYPTION_KEY:-} stop_grace_period: 60s healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"] interval: 15s timeout: 3s start_period: 60s start_interval: 2s retries: 3 depends_on: mongodb: condition: service_healthy mongodb: image: mongo:8.0 restart: always command: ["mongod", "--quiet", "--bind_ip_all"] volumes: - mongo-data:/data/db healthcheck: test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"] interval: 5s timeout: 30s start_period: 0s start_interval: 1s retries: 30 volumes: mongo-data:

可以看到参考 Compose 对 Checkmate 容器做了健康检查（探测 worker 健康端口的/livez），并设置了stop_grace_period: 60s保证优雅停机；MongoDB 容器则通过mongoshping 命令做健康检查，Checkmate 容器等待 MongoDB 健康后才启动。

一键部署与托管平台

你也可以使用以下平台快速启动 Checkmate 实例：Coolify、Elestio、Kubernetes（Helm Chart）、Sive Host（南非）、Cloudzy、PikaPods。如需监控服务器基础设施，需要安装 Capture 代理，其仓库中包含安装说明。

Kubernetes 部署的完整步骤见 charts/helm/checkmate/INSTALLATION.md：先克隆仓库并编辑values.yaml（设置client.ingress.host、api.ingress.host、api.protocol及 secrets 下的所有change_me值），然后执行：

helm install checkmate ./charts/helm/checkmate

用kubectl get pods/kubectl get svc验证所有 Pod 处于Running且Ready状态后，即可通过配置的 Ingress 域名访问。

使用自定义 CA

如果你需要使用私有 CA（例如 Smallstep）签发的证书来监控内部 HTTPS 端点，请查看 自定义 CA 信任指南。该指南提供了两种 Docker 配置方案：

• Node 级信任：将 CA 证书以卷挂载进容器，并设置NODE_EXTRA_CA_CERTS环境变量指向证书文件
• OS 级信任（Debian 系）：基于官方镜像派生新镜像，安装ca-certificates包并把.crt证书放入/usr/local/share/ca-certificates/，执行update-ca-certificates，再以NODE_OPTIONS="--use-system-ca"启动 Node

需要注意，Checkmate 镜像基于node:22-slim，默认不携带ca-certificates包，OS 级方案必须显式安装该包；且只有以--use-system-ca启动时 Node 才会读取系统证书库。对于大多数场景，NODE_EXTRA_CA_CERTS的 Compose 方案更简单。

更多文档可参见 docs 目录。

环境变量配置详解

镜像完全通过服务端容器上的环境变量进行配置。这份配置的校验逻辑可以在 envValidation.ts 中看到——所有变量都经过 Zod schema 校验，任何必填项缺失或格式错误都会在启动时打印错误并退出进程（process.exit(1)）。

服务端核心变量

Web 客户端运行时覆盖变量

默认情况下 Web 客户端无需任何配置：它通过同源/api/v1调用 API。对于默认设置不适用的场景（例如 API 与页面来源不同），服务端会在运行时将以下可选变量渲染进客户端（源码见 envValidation.ts）：

从旧镜像升级的注意点

旧的UPTIME_APP_*变量（UPTIME_APP_API_BASE_URL、UPTIME_APP_CLIENT_HOST、UPTIME_APP_LOG_LEVEL）不再被读取。大多数场景无需替换——同源默认值已覆盖；如果你曾将客户端指向其他来源，请改用上面的CLIENT_CONFIG_*对应变量。源码会在检测到遗留变量时输出警告日志（见 envValidation.ts）。

checkmate-client、checkmate-backend、checkmate-mongo、checkmate-backend-mono-multiarch镜像已不再更新——请切换到ghcr.io/bluewave-labs/checkmate，保留现有 MongoDB 服务和数据卷。

Docker 监控深入

Docker 监控项连接 Docker daemon，并报告其运行的每个容器状态。daemon 的 ping 响应决定监控项是 up 还是 down，其延迟即为响应时间。每次检查还会记录每个容器的状态、健康、CPU 与内存使用、重启次数、已发布端口和挂载点。启用收集容器日志后，每次检查还会额外存储每个容器最新的 200 行日志；日志保留 7 天（对应 DockerProvider.ts 中monitor.dockerLogsEnabled分支触发日志采集的逻辑）。

Docker host 字段的两种形式

监控本地 socket

参考 Compose 文件没有挂载Docker socket，因此需要手动添加并授予容器宿主机的docker组权限。镜像以非特权用户运行，否则无法读取 socket。先用stat -c %g /var/run/docker.sock查出组 ID，然后在 Compose 中配置：

services: checkmate: volumes: - /var/run/docker.sock:/var/run/docker.sock:ro group_add: - "989" # stat 命令输出的 gid

监控远程 daemon

将 Host 设置为tcp://host:port，并在监控表单的TLS 凭据部分填写与docker --tlsverify一致的 PEM 文件：

• CA 证书：为 daemon 服务器证书签名的 CA。除非开启忽略 TLS/SSL 错误（跳过 daemon 身份校验），否则必填
• 客户端证书：daemon 用于认证 Checkmate 的证书
• 客户端密钥：匹配的私钥，必须未加密（无口令）。Checkmate 会校验其与证书匹配，用ENCRYPTION_KEY加密保存后不再显示。编辑时留空即可保留已存密钥

TLS Docker 监控项要求服务端已设置ENCRYPTION_KEY（见上文环境变量表）。未设置时保存会直接报错。如果密钥被移除或轮换错误，受影响的检查会持续报解密错误，直到恢复密钥。

如果 daemon 的证书由私有 CA 签发，且你希望 Checkmate 的其他功能也信任该 CA，请参考 自定义 CA 信任指南；仅针对 Docker 监控项，填写CA 证书字段就足够了。

用 TLS 保护 Docker daemon（操作要点）

Docker daemon 默认不启用 TLS。若需保护远程 daemon，可按以下流程在 Docker 主机上生成 CA、服务器证书和 Checkmate 客户端证书（来自 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. 创建服务器证书（SAN 必须覆盖 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. 让 daemon 使用证书。将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" }

在 Debian、Ubuntu 等 systemd 单元已传-H fd://的发行版上，两处都设置hosts会导致 daemon 拒绝启动。用 override 移除该标志并重启：

sudo systemctl edit docker.service

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

sudo systemctl daemon-reload && sudo systemctl restart docker

防火墙仅向运行 Checkmate 的机器开放 2376 端口。

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

监控生命周期：一次检查如何变成一次告警

README 用一个六步生命周期清晰描述了 Checkmate 的核心工作流，服务端源码（worker.check-evaluator.ts、worker.monitor-status-policy.ts）实现了其中的关键判定逻辑：

1. 执行检查：监控项执行一次检查（HTTP / Ping / 端口 / 通过 Capture 代理的硬件检查）
2. 保存结果：结果被保存（成功/失败 + 响应时间）
3. 评估结果：近期的检查结果根据该监控项配置的状态变更阈值进行评估。监控项类型定义中的statusWindow、statusWindowSize、statusWindowThreshold等字段（见 monitor.type.ts）正是这一评估机制的配置载体
4. 状态迁移：当达到状态变更阈值且当前状态与上一状态不同时，监控项状态发生变化，状态包括initializing、up、down、breached（源码中还包含paused、maintenance，见 monitor.type.ts）
5. 事件流转：状态发生变化时，根据监控项当前状态创建或解决一个事件
6. 通知触发：根据配置触发通知

在 worker.monitor-status-policy.ts 中可以直观看到第 4～6 步的决策逻辑：当状态未变化时不做任何动作；监控项变为down时创建事件并发送通知；变为breached（硬件监控超出阈值）时同样创建事件并发送通知；从down/breached恢复为up时则解决事件并发送状态变更通知。

性能

得益于大量优化，Checkmate 在运行时占用的内存非常少，对内存和 CPU 资源的需求极低。根据 README 的性能章节，项目已声称在1000+ 个活跃监控项的环境下完成压力测试，未出现任何明显问题或性能瓶颈；下方示例是一个每分钟监控 323 台服务器的 Node.js 实例，其内存占用保持在极低水平，同一服务器、相同监控数量下 MongoDB 与 Redis 的内存占用分别约为 398MB 与 15MB。

此外，若希望将调度与处理分离以获得水平扩展能力，可参考 charts/helm/checkmate/INSTALLATION.md 中的 worker 层说明：默认单 Pod 既调度又处理作业；通过worker.enabled: true可拆分出无入站流量的专用 worker 层，并结合 KEDAScaledObject按 MongoDB 中的待处理检查积压量在minReplicaCount与maxReplicaCount之间自动伸缩（默认关闭，需集群安装 KEDA 算子）。需要注意terminationGracePeriodSeconds（默认 30s）必须大于服务端排空超时（25s），否则 worker 可能在排空过程中被 SIGKILL 导致丢失进行中的检查。

参与贡献

Checkmate 团队鼓励各层次开发者参与贡献，方式包括：阅读贡献者指南（新手建议从good-first-issue标签入手）、遇到 bug 提交 issue、通过 Pull Request 添加新功能、改进体验或修复 bug。仓库根目录还提供了 CLAUDE.md、CODE_OF_CONDUCT.md 与 Checkmate.CodeCanvas 等协作与交互式代码演示资源。

如果你有任何问题、建议或意见，可以通过项目的 Discord 频道（推荐）或 GitHub Discussions 论坛反馈。

【免费下载链接】CheckmateCheckmate is an open-source, self-hosted tool designed to track and monitor server hardware, uptime, response times, and incidents in real-time with beautiful visualizations. Don't be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/Checkmate