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. Dont be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/CheckmateCheckmate 是一款完全开源、可自托管的可用性与基础设施监控应用前端与后端代码统一存放在同一仓库中。本指南以仓库内的简体中文 README 为主体结合 docker-compose.yaml、Helm 安装指南、自定义 CA 信任指南 以及服务端源码系统讲解 Checkmate 的安装部署、环境变量配置、Docker 监控、监控生命周期原理与性能表现帮助你快速上手并把监控系统真正跑起来。项目概览一个仓库前后端一体Checkmate 是一个开源、可自托管的监控工具通过精美的可视化效果实时追踪服务器硬件、可用性、响应时间以及事件。它会定期检查服务器或网站是否可访问、运行是否正常并针对被监控服务的可用性、停机时间和响应时间提供实时告警与报告。本仓库同时包含 Checkmate 的前端和后端代码。构建后的镜像将前端静态资源与后端服务打包为单个 all-in-one 镜像通过 docker/Dockerfile 分两个阶段构建先在前端阶段node:22-slimnpm 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。配套代理 CaptureCheckmate 还提供一个名为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 WindowsJSON 查询监控多语言支持阿拉伯语、简体中文、繁体中文台湾、捷克语、英语、芬兰语、法语、德语、日语、葡萄牙语巴西、俄语、西班牙语、泰语、土耳其语、乌克兰语和越南语对应仓库 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.yamlcurl -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_STRINGmongodb://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,rprocess.exit(r.statusCode200?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、KubernetesHelm 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)。服务端核心变量变量必填说明DB_CONNECTION_STRING是MongoDB 连接字符串例如mongodb://mongodb:27017/uptime_dbJWT_SECRET是用于签发认证令牌的密钥可用openssl rand -hex 32生成CLIENT_HOST是用户访问应用的 URL例如https://checkmate.example.com用于 CORS 以及通知和邮件中的链接。源码校验其为合法 URL见 envValidation.tsENCRYPTION_KEY否用于加密存储的 Docker TLS 客户端密钥静态加密用openssl rand -base64 32生成。支持逗号分隔多密钥第一个密钥负责加密其余密钥用于解密。API 与每个 worker 上必须保持一致。无停机轮换流程先在所有节点配置OLD_KEY,NEW_KEY再改为NEW_KEY,OLD_KEY等待 worker 重新加密所有行后移除OLD_KEY。源码会校验每个密钥必须是恰好 32 字节的 padded standard base64 且不允许重复见 envValidation.tsPORT否API 与 Web 客户端服务端口默认52345HEALTH_PORT否运行 job worker 的进程提供的/livez、/readyz、/metrics端点端口默认52346NODE_ENV否development、production或test默认development。development会禁用通用 API 限流器生产环境务必设置为productionLOG_LEVEL否服务端日志级别error、warn、info或debug默认debugTOKEN_TTL否签发的认证令牌有效期例如12h或7d默认99dQUEUE_MODE否primary默认同时运行 API、Web 客户端和作业调度器worker仅运行作业处理 worker不提供 APIQUEUE_PRIMARY_PROCESSES否true默认或false。控制primary节点是否也自行处理监控作业当所有检查由专用worker节点处理时设为false。在worker模式下该变量被忽略STATUS_PAGE_THEMES_ENABLED否true默认或false。为false时状态页忽略主题设置始终渲染默认主题Web 客户端运行时覆盖变量默认情况下 Web 客户端无需任何配置它通过同源/api/v1调用 API。对于默认设置不适用的场景例如 API 与页面来源不同服务端会在运行时将以下可选变量渲染进客户端源码见 envValidation.ts变量说明CLIENT_CONFIG_API_BASE_URL客户端调用 API 的完整基础 URL例如https://api.example.com/api/v1默认同源/api/v1CLIENT_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_*对应变量。源码会在检测到遗留变量时输出警告日志见 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 字段的两种形式Host示例说明本地 socketunix:///var/run/docker.sock也接受裸绝对路径如/var/run/docker.sock。用于监控运行 Checkmate 的同一台机器上的 daemon远程 daemontcp://docker.example.com:2376始终使用双向 TLS端口默认为2376。不支持 2375 端口的未加密 daemon监控本地 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 与 IP1. 创建 CACA 密钥设置口令签发完成后离线保管openssl genrsa -aes256 -out ca-key.pem 4096 openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -subj /CNdocker-ca -out ca.pem2. 创建服务器证书SAN 必须覆盖 Checkmate 访问 daemon 用到的所有名称或地址openssl genrsa -out server-key.pem 4096 openssl req -subj /CNdocker.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.cnf3. 为 Checkmate 创建客户端证书密钥不要加口令Checkmate 无法使用加密私钥openssl genrsa -out key.pem 4096 openssl req -subj /CNcheckmate -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.pem4. 让 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/dockerdsudo systemctl daemon-reload sudo systemctl restart docker防火墙仅向运行 Checkmate 的机器开放 2376 端口。5. 从 Checkmate 主机验证然后将ca.pem、cert.pem、key.pem粘贴到监控表单docker --tlsverify --tlscacertca.pem --tlscertcert.pem --tlskeykey.pem \ -Hdocker.example.com:2376 version监控生命周期一次检查如何变成一次告警README 用一个六步生命周期清晰描述了 Checkmate 的核心工作流服务端源码worker.check-evaluator.ts、worker.monitor-status-policy.ts实现了其中的关键判定逻辑执行检查监控项执行一次检查HTTP / Ping / 端口 / 通过 Capture 代理的硬件检查保存结果结果被保存成功/失败 响应时间评估结果近期的检查结果根据该监控项配置的状态变更阈值进行评估。监控项类型定义中的statusWindow、statusWindowSize、statusWindowThreshold等字段见 monitor.type.ts正是这一评估机制的配置载体状态迁移当达到状态变更阈值且当前状态与上一状态不同时监控项状态发生变化状态包括initializing、up、down、breached源码中还包含paused、maintenance见 monitor.type.ts事件流转状态发生变化时根据监控项当前状态创建或解决一个事件通知触发根据配置触发通知在 worker.monitor-status-policy.ts 中可以直观看到第 46 步的决策逻辑当状态未变化时不做任何动作监控项变为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. Dont be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/Checkmate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考