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 是一款开源、可自托管的监控工具用于实时追踪服务器硬件、Uptime、响应时间与告警事件并提供可视化界面。本指南以项目意大利语文档docs/translations/README.it.md为骨架结合仓库中的部署配置、环境变量校验与服务端源码系统讲解 Checkmate 的功能特性、安装部署、配置参数、监控器生命周期与底层实现原理帮助读者快速完成从部署到监控上手的全流程。项目概览Checkmate 能做什么Checkmate 是一个同时包含前端与后端的开源监控项目前端位于 client/ 目录后端位于 server/ 目录主要能力包括定期探测服务器或网站是否可达、是否处于最佳运行状态实时输出被监控服务的可用性、停机时间与响应时间报告在故障发生时即时触发告警与通知通过美观的图表对监控数据进行可视化呈现。除了核心探测能力Checkmate 还配套一个名为Capture的采集 Agent用于从远程服务器收集 CPU、内存、磁盘与温度等硬件指标。Capture 并非运行 Checkmate 的必需组件但启用后可以补充硬件维度的洞察。Capture 可在 Linux、Windows、Mac、Raspberry Pi 以及任何能运行 Go 的设备上执行适用于服务器基础设施监控场景。功能特性总览根据意大利语文档的「Funzionalità」章节Checkmate 具备以下核心特性完全开源、可自托管可部署在自有服务器或家用设备如 Raspberry Pi 4/5上多种监控类型Uptime、Docker、Ping、SSL、端口Port、游戏服务器Game server等监控页面速度监控Page Speed评估 Web 页面的加载性能基础设施监控覆盖内存、磁盘使用率、CPU 性能、网络等指标需要 Capture Agent 配合并支持磁盘挂载点选择的精细化监控事件一瞥Incidents at a glance快速掌握当前告警事件状态页面Status pages提供多个精心设计的主题多渠道通知支持 E-mail、Webhook、Discord、Slack、PagerDuty、Matrix、Microsoft Teams、Telegram、Pushover、TwilioSMS等计划维护Scheduled maintenance提前规划维护窗口避免误报JSON 查询监控对响应体进行 JSON 路径提取与断言多语言支持涵盖阿拉伯语、中文简/繁、捷克语、英语、芬兰语、法语、德语、日语、葡萄牙语巴西、俄语、西班牙语、泰语、土耳其语、乌克兰语、越南语等。以上监控能力在服务端源码中可以得到印证monitor.type.ts 中定义了MonitorTypes [http, ping, pagespeed, hardware, docker, port, game, grpc, websocket, dns, unknown]并支持equal、include、regex三种响应匹配方式对应 JSON 查询断言。通知渠道方面providers 目录 下可以看到discord.ts、email.ts、matrix.ts、ntfy.ts、pagerduty.ts、pushover.ts、rocketChat.ts、signalgrid.ts、slack.ts、teams.ts、telegram.ts、twilio.ts、webhook.ts等实现文件说明文档中的通知列表对应着实际可用的渠道实现。快速体验官方 Demo 与前置条件在自行部署之前可以先通过官方 Demo 直观体验 Checkmate 的最新构建版本其访问账号为demouserdemo.com密码为Demouser1!注意Demo 服务器会不定期更新若不可用可在项目 Discussions 频道反馈。自行部署的前置条件非常轻量仅需两条已安装Docker已安装Git安装部署参考 Compose 文件与多平台方案Checkmate 提供的最快捷启动方式是仓库根目录下的参考 Docker Compose 文件 docker/docker-compose.yaml。它定义了两个服务checkmate使用一体化镜像ghcr.io/bluewave-labs/checkmate:latest同时承载 API 与 Web 客户端mongodb独立的mongo:8.0数据库服务通过数据卷mongo-data持久化数据。所谓「一体化all-in-one」的含义是Checkmate 应用本身被打包进单个镜像但 MongoDB 并未内置在该镜像中仍是必需的依赖——参考 Compose 文件会自动为你启动 MongoDB在自定义部署场景下需要通过DB_CONNECTION_STRING指向外部 MongoDB 实例。镜像启动时通过健康检查探测http://localhost:52346/livez并与 MongoDB 的健康状态service_healthy建立依赖关系确保数据库就绪后才启动应用。stop_grace_period: 60s为优雅停机留出缓冲时间。安装命令如下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 文件外文档还列举了多种一键部署渠道Coolify、Elestio、KubernetesHelm、Sive Host南非、Cloudzy、PikaPods 等。其中 Kubernetes 部署方式在 charts/helm/checkmate/INSTALLATION.md 中有完整指南涵盖helm install checkmate ./charts/helm/checkmate、Ingress/TLS 配置支持 cert-manager、API 与 Worker 分层伸缩含 KEDA 自动扩缩容等高级主题。若需要监控服务器基础设施还需部署 Capture Agent其仓库中同样包含安装说明。环境变量配置详解Checkmate 镜像完全通过服务器容器上的环境变量进行配置。下表汇总了核心变量的要求、默认值与用途配置声明见 docker/docker-compose.yaml运行时校验逻辑见 server/src/config/envValidation.ts变量必填说明DB_CONNECTION_STRING是MongoDB 连接串例如mongodb://mongodb:27017/uptime_dbJWT_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→ 移除OLD_KEY」的顺序执行PORT否API 与 Web 客户端监听端口默认52345HEALTH_PORT否健康检查端口承载/livez、/readyz、/metrics端点默认52346NODE_ENV否development/production/test默认developmentdevelopment会关闭通用 API 限流真实部署应设为productionLOG_LEVEL否服务端日志级别error/warn/info/debug默认debugTOKEN_TTL否已签发认证令牌的有效期如12h、7d默认99dQUEUE_MODE否primary默认运行 API、Web 客户端与任务调度器worker仅运行任务处理 Worker不提供 APIQUEUE_PRIMARY_PROCESSES否true默认/falseprimary节点是否同时处理监控任务当所有检查由独立 Worker 处理时设为falseworker模式下忽略STATUS_PAGE_THEMES_ENABLED否true默认/false为false时状态页忽略主题设置始终渲染默认主题从源码看envValidation.ts 使用 zod 对上述变量做了严格校验JWT_SECRET与DB_CONNECTION_STRING均为必填min(1)CLIENT_HOST必须是合法 URLENCRYPTION_KEY的每个条目必须满足「填充标准 base64 的 32 字节」即openssl rand -base64 32的输出格式正则^[A-Za-z0-9/]{43}$且不允许重复条目。一旦校验失败服务会记录错误日志并process.exit(1)拒绝启动避免带病运行。Web 客户端默认无需配置它默认调用自身来源的/api/v1。当默认值不适用例如 API 与页面不在同一来源时服务端会通过以下可选变量在运行时把覆盖配置渲染进客户端变量说明CLIENT_CONFIG_API_BASE_URL客户端调用 API 的完整基础 URL默认同源/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_*变量。同时checkmate-client、checkmate-backend、checkmate-mongo等旧镜像已不再更新应切换到ghcr.io/bluewave-labs/checkmate并保留现有 MongoDB 服务与数据卷。自定义 CA 信任监控内网 HTTPS 端点如果目标 HTTPS 端点的证书由私有 CA如 Smallstep、内部 PKI签发Checkmate 默认会因证书校验失败而将其判定为 DOWN即使服务实际可达。解决此问题的完整指南见 docs/custom-ca-trust.md主要有两种思路Node 级信任最简单将自定义 CA 证书挂载进容器并通过NODE_EXTRA_CA_CERTS环境变量让 Node.js 信任它services: checkmate: image: ghcr.io/bluewave-labs/checkmate:latest restart: always ports: - 52345:52345 env_file: - server.env environment: NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem volumes: - ./certs:/certs:ro depends_on: - mongodbOS 级信任Debian 系镜像Checkmate 镜像基于node:22-slim默认未安装ca-certificates包。可派生 Dockerfile 安装证书并让 Node 使用系统证书库FROM ghcr.io/bluewave-labs/checkmate:latest USER root RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/* # 自定义 CA 证书必须以 .crt 结尾 COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/ RUN update-ca-certificates USER node # Node 默认使用内置 CA 库需显式切换为系统库 ENV NODE_OPTIONS--use-system-ca再通过 Compose override 文件参考 docker/dev/docker-compose.custom-ca-example.yaml构建启动docker compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml upSmallstep 用户可用step certificate inspect --format pem step-ca/root_ca.crt custom-ca.pem导出根证书再套用上述任一方案。注意安全要点只信任自己掌控的 CA确保证书为 PEM 格式.pem/.crt、容器挂载路径正确并在添加证书后重启容器。验证信任是否生效可进入容器执行docker exec -it 容器名 sh后检查/usr/local/share/ca-certificates/或cat /etc/ssl/certs/ca-certificates.crt | grep ...。Docker 监控守护进程连接与 TLS 加密作为特性列表中的重点监控类型Docker 监控在服务端由 DockerProvider.ts 实现。其核心逻辑是连接 Docker 守护进程以守护进程的 ping 响应决定监控器 up/down 状态同时记录每个容器的状态、健康度、CPU/内存占用、重启次数、端口与挂载信息启用「收集容器日志」后每次检查还会存储每个容器最近 200 行日志日志保留 7 天常量定义见 docker.type.ts。Docker 主机地址支持两种形式形式示例说明本地 socketunix:///var/run/docker.sock也接受纯绝对路径如/var/run/docker.sock用于监控与 Checkmate 同机运行的守护进程远程守护进程tcp://docker.example.com:2376始终使用双向 TLS端口默认2376不支持 2375 端口的未加密守护进程监控本地 socket参考 Compose 文件默认未挂载 socket需要自行添加卷并授予容器宿主机的docker组权限。先用stat -c %g /var/run/docker.sock查出组 ID然后services: checkmate: volumes: - /var/run/docker.sock:/var/run/docker.sock:ro group_add: - 989 # stat 输出的 gid监控远程守护进程将主机设为tcp://host:port并在监控器表单中填入与docker --tlsverify相同的 PEM 文件CA 证书签发守护进程服务器证书的 CA若开启「忽略 TLS/SSL 错误」则可不填跳过对守护进程身份的校验客户端证书守护进程用于认证 Checkmate 的证书客户端密钥对应的私钥必须未加密无口令。Checkmate 会校验其与证书匹配并用ENCRYPTION_KEY加密存储之后不再明文展示编辑时留空表示保留已存密钥。TLS Docker 监控器要求服务器设置ENCRYPTION_KEY见上文配置表未设置时保存会直接报错若密钥被移除或错误轮换相关检查将持续解密失败直至恢复。源码层面DockerProvider.ts 在发起 HTTPS 请求时会通过rejectUnauthorized: !monitor.ignoreTlsErrors控制是否校验守护进程身份并仅在提供dockerTlsKey时使用EncryptionService解密密钥——这正对应文档所述的密钥加密存储机制。若守护进程的证书由私有 CA 签发、且希望 Checkmate 整体都信任它参见 docs/custom-ca-trust.md仅针对 Docker 监控表单中的CA 证书字段就已足够。性能表现与资源占用得益于大量优化Checkmate 的内存占用非常低仅需极少的 CPU 与内存资源。项目文档记载在一个每分钟监控323 台服务器的 Node.js 实例上其内存占用保持在小规模水平同一服务器上 MongoDB 与 Redis 的内存占用分别约为398MB 与 15MB。此外项目宣称在1000 活跃监控器的压力测试下运行平稳未出现明显问题或性能瓶颈。以上均为项目 README 中记载的数据实际资源消耗会随监控器数量、检查频率与数据保留策略而不同建议以自身环境实测为准。监控器生命周期从探测到事件的全流程Checkmate 的监控器遵循一条清晰的生命周期流水线文档归纳为 6 个步骤执行检查监控器执行一次探测HTTP / ping / port或通过 Capture Agent 执行硬件检查存储结果结果被持久化成功/失败 响应时间阈值评估近期检查结果与监控器配置的状态变更阈值status change threshold进行比对状态变更若达到阈值且当前状态与先前状态不同监控器状态发生迁移例如initializing、up、down、breached事件流转状态变更时根据当前状态创建或解决一个事件incident通知触发根据配置触发相应的通知。这条流水线在服务端代码中有完整的实现证据状态枚举定义在 monitor.type.tsMonitorStatuses [up, down, paused, initializing, maintenance, breached]并包含statusWindow状态窗口位图、statusWindowSize、statusWindowThreshold等阈值字段状态→动作的决策逻辑集中在 worker.monitor-status-policy.ts 的MonitorStatusPolicy.evaluate()当状态未变化时不产生任何动作变为down时创建事件并发送「状态变更」通知硬件监控器变为breached时创建事件并发送「阈值越界」通知从down/breached恢复为up时解决事件并发送通知检查结果的数据结构定义在 types/network.ts其中StatusChangeResult携带thresholdBreachescpu/memory/disk/temp 布尔标志正是硬件阈值评估的输出载体。可见文档描述的「评估阈值 → 变更状态 → 流转事件 → 触发通知」在代码层面被拆解为监控器状态机与事件/通知反应器reactor形成完整闭环。技术栈与仓库结构根据文档的 Tech stack 章节Checkmate 采用如下技术栈React.js前端 UI 框架MUIMaterial UIReact 组件库Node.js服务端运行时MongoDB数据存储Recharts图表可视化库以及其他大量开源组件。这些在仓库结构中均有对应前端页面组件位于 client/src含 Components/design-elements 等设计体系、Features 状态管理、Hooks 业务逻辑服务端控制器/路由/校验位于 server/src/api领域模型与仓储位于 server/src/domain网络探测 Provider 位于 server/src/service/network后台任务与 Worker 位于 server/src/worker。监控数据的时间序列化、快照化处理则在 server/src/db/migration 中的迁移脚本里可见。更多文档、社区与贡献使用指南与更多文档可查阅 docs/ 目录其中包含自定义 CA 信任指南 docs/custom-ca-trust.md、自定义 CA 快速参考、基础设施磁盘选择、编码规范 与多语言翻译贡献指南等主 README 的英文原版见 README.md其他语言的翻译版本位于 docs/translations/例如简体中文 docs/translations/README.zh-CN.md问题与想法项目维护者推荐通过官方 Discord 频道交流首选GitHub Discussions 论坛也会定期查看欢迎提出任何问题、建议或功能想法发布通知可使用 Newreleases 这类免费服务追踪 Checkmate 的新版本发布参与贡献项目维护团队Alex 为 team lead另有 Gorkem、Aryaman、Mert、Karen 等成员乐于与各水平的贡献者协作。贡献流程为先阅读贡献者指南新人不妨从标记了good-first-issue的 issue 入手遇到疑似 bug 可提交 issue通过 Pull Request 提交新功能、体验优化或 bug 修复。根据 README 记载作为年轻项目Checkmate 已获得数千 Star 并吸引来自全球的 90 位贡献者其仓库也曾被 Google、Microsoft、Intel、Cisco、Tencent、ByteDance、Cloudflare 等公司的员工点亮。结语从本文可以清晰地看到Checkmate 的价值在于「上手简单、扩展深入」一条docker compose up命令即可获得完整的 Uptime 与事件监控能力而环境变量、自定义 CA、Docker TLS、Worker 分层伸缩等机制又为生产环境与复杂基础设施留足了演进空间。结合仓库源码读者可以在 docker/docker-compose.yaml 查看部署基线、在 server/src/config/envValidation.ts 理解配置校验、在 server/src/worker 与 server/src/domain 中追踪监控器从探测到事件通知的完整闭环从而真正把 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/Checkmate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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. Dont be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/CheckmateCheckmate 是一款开源、可自托管的监控工具用于实时追踪服务器硬件、Uptime、响应时间与告警事件并提供可视化界面。本指南以项目意大利语文档docs/translations/README.it.md为骨架结合仓库中的部署配置、环境变量校验与服务端源码系统讲解 Checkmate 的功能特性、安装部署、配置参数、监控器生命周期与底层实现原理帮助读者快速完成从部署到监控上手的全流程。项目概览Checkmate 能做什么Checkmate 是一个同时包含前端与后端的开源监控项目前端位于 client/ 目录后端位于 server/ 目录主要能力包括定期探测服务器或网站是否可达、是否处于最佳运行状态实时输出被监控服务的可用性、停机时间与响应时间报告在故障发生时即时触发告警与通知通过美观的图表对监控数据进行可视化呈现。除了核心探测能力Checkmate 还配套一个名为Capture的采集 Agent用于从远程服务器收集 CPU、内存、磁盘与温度等硬件指标。Capture 并非运行 Checkmate 的必需组件但启用后可以补充硬件维度的洞察。Capture 可在 Linux、Windows、Mac、Raspberry Pi 以及任何能运行 Go 的设备上执行适用于服务器基础设施监控场景。功能特性总览根据意大利语文档的「Funzionalità」章节Checkmate 具备以下核心特性完全开源、可自托管可部署在自有服务器或家用设备如 Raspberry Pi 4/5上多种监控类型Uptime、Docker、Ping、SSL、端口Port、游戏服务器Game server等监控页面速度监控Page Speed评估 Web 页面的加载性能基础设施监控覆盖内存、磁盘使用率、CPU 性能、网络等指标需要 Capture Agent 配合并支持磁盘挂载点选择的精细化监控事件一瞥Incidents at a glance快速掌握当前告警事件状态页面Status pages提供多个精心设计的主题多渠道通知支持 E-mail、Webhook、Discord、Slack、PagerDuty、Matrix、Microsoft Teams、Telegram、Pushover、TwilioSMS等计划维护Scheduled maintenance提前规划维护窗口避免误报JSON 查询监控对响应体进行 JSON 路径提取与断言多语言支持涵盖阿拉伯语、中文简/繁、捷克语、英语、芬兰语、法语、德语、日语、葡萄牙语巴西、俄语、西班牙语、泰语、土耳其语、乌克兰语、越南语等。以上监控能力在服务端源码中可以得到印证monitor.type.ts 中定义了MonitorTypes [http, ping, pagespeed, hardware, docker, port, game, grpc, websocket, dns, unknown]并支持equal、include、regex三种响应匹配方式对应 JSON 查询断言。通知渠道方面providers 目录 下可以看到discord.ts、email.ts、matrix.ts、ntfy.ts、pagerduty.ts、pushover.ts、rocketChat.ts、signalgrid.ts、slack.ts、teams.ts、telegram.ts、twilio.ts、webhook.ts等实现文件说明文档中的通知列表对应着实际可用的渠道实现。快速体验官方 Demo 与前置条件在自行部署之前可以先通过官方 Demo 直观体验 Checkmate 的最新构建版本其访问账号为demouserdemo.com密码为Demouser1!注意Demo 服务器会不定期更新若不可用可在项目 Discussions 频道反馈。自行部署的前置条件非常轻量仅需两条已安装Docker已安装Git安装部署参考 Compose 文件与多平台方案Checkmate 提供的最快捷启动方式是仓库根目录下的参考 Docker Compose 文件 docker/docker-compose.yaml。它定义了两个服务checkmate使用一体化镜像ghcr.io/bluewave-labs/checkmate:latest同时承载 API 与 Web 客户端mongodb独立的mongo:8.0数据库服务通过数据卷mongo-data持久化数据。所谓「一体化all-in-one」的含义是Checkmate 应用本身被打包进单个镜像但 MongoDB 并未内置在该镜像中仍是必需的依赖——参考 Compose 文件会自动为你启动 MongoDB在自定义部署场景下需要通过DB_CONNECTION_STRING指向外部 MongoDB 实例。镜像启动时通过健康检查探测http://localhost:52346/livez并与 MongoDB 的健康状态service_healthy建立依赖关系确保数据库就绪后才启动应用。stop_grace_period: 60s为优雅停机留出缓冲时间。安装命令如下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 文件外文档还列举了多种一键部署渠道Coolify、Elestio、KubernetesHelm、Sive Host南非、Cloudzy、PikaPods 等。其中 Kubernetes 部署方式在 charts/helm/checkmate/INSTALLATION.md 中有完整指南涵盖helm install checkmate ./charts/helm/checkmate、Ingress/TLS 配置支持 cert-manager、API 与 Worker 分层伸缩含 KEDA 自动扩缩容等高级主题。若需要监控服务器基础设施还需部署 Capture Agent其仓库中同样包含安装说明。环境变量配置详解Checkmate 镜像完全通过服务器容器上的环境变量进行配置。下表汇总了核心变量的要求、默认值与用途配置声明见 docker/docker-compose.yaml运行时校验逻辑见 server/src/config/envValidation.ts变量必填说明DB_CONNECTION_STRING是MongoDB 连接串例如mongodb://mongodb:27017/uptime_dbJWT_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→ 移除OLD_KEY」的顺序执行PORT否API 与 Web 客户端监听端口默认52345HEALTH_PORT否健康检查端口承载/livez、/readyz、/metrics端点默认52346NODE_ENV否development/production/test默认developmentdevelopment会关闭通用 API 限流真实部署应设为productionLOG_LEVEL否服务端日志级别error/warn/info/debug默认debugTOKEN_TTL否已签发认证令牌的有效期如12h、7d默认99dQUEUE_MODE否primary默认运行 API、Web 客户端与任务调度器worker仅运行任务处理 Worker不提供 APIQUEUE_PRIMARY_PROCESSES否true默认/falseprimary节点是否同时处理监控任务当所有检查由独立 Worker 处理时设为falseworker模式下忽略STATUS_PAGE_THEMES_ENABLED否true默认/false为false时状态页忽略主题设置始终渲染默认主题从源码看envValidation.ts 使用 zod 对上述变量做了严格校验JWT_SECRET与DB_CONNECTION_STRING均为必填min(1)CLIENT_HOST必须是合法 URLENCRYPTION_KEY的每个条目必须满足「填充标准 base64 的 32 字节」即openssl rand -base64 32的输出格式正则^[A-Za-z0-9/]{43}$且不允许重复条目。一旦校验失败服务会记录错误日志并process.exit(1)拒绝启动避免带病运行。Web 客户端默认无需配置它默认调用自身来源的/api/v1。当默认值不适用例如 API 与页面不在同一来源时服务端会通过以下可选变量在运行时把覆盖配置渲染进客户端变量说明CLIENT_CONFIG_API_BASE_URL客户端调用 API 的完整基础 URL默认同源/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_*变量。同时checkmate-client、checkmate-backend、checkmate-mongo等旧镜像已不再更新应切换到ghcr.io/bluewave-labs/checkmate并保留现有 MongoDB 服务与数据卷。自定义 CA 信任监控内网 HTTPS 端点如果目标 HTTPS 端点的证书由私有 CA如 Smallstep、内部 PKI签发Checkmate 默认会因证书校验失败而将其判定为 DOWN即使服务实际可达。解决此问题的完整指南见 docs/custom-ca-trust.md主要有两种思路Node 级信任最简单将自定义 CA 证书挂载进容器并通过NODE_EXTRA_CA_CERTS环境变量让 Node.js 信任它services: checkmate: image: ghcr.io/bluewave-labs/checkmate:latest restart: always ports: - 52345:52345 env_file: - server.env environment: NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem volumes: - ./certs:/certs:ro depends_on: - mongodbOS 级信任Debian 系镜像Checkmate 镜像基于node:22-slim默认未安装ca-certificates包。可派生 Dockerfile 安装证书并让 Node 使用系统证书库FROM ghcr.io/bluewave-labs/checkmate:latest USER root RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/* # 自定义 CA 证书必须以 .crt 结尾 COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/ RUN update-ca-certificates USER node # Node 默认使用内置 CA 库需显式切换为系统库 ENV NODE_OPTIONS--use-system-ca再通过 Compose override 文件参考 docker/dev/docker-compose.custom-ca-example.yaml构建启动docker compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml upSmallstep 用户可用step certificate inspect --format pem step-ca/root_ca.crt custom-ca.pem导出根证书再套用上述任一方案。注意安全要点只信任自己掌控的 CA确保证书为 PEM 格式.pem/.crt、容器挂载路径正确并在添加证书后重启容器。验证信任是否生效可进入容器执行docker exec -it 容器名 sh后检查/usr/local/share/ca-certificates/或cat /etc/ssl/certs/ca-certificates.crt | grep ...。Docker 监控守护进程连接与 TLS 加密作为特性列表中的重点监控类型Docker 监控在服务端由 DockerProvider.ts 实现。其核心逻辑是连接 Docker 守护进程以守护进程的 ping 响应决定监控器 up/down 状态同时记录每个容器的状态、健康度、CPU/内存占用、重启次数、端口与挂载信息启用「收集容器日志」后每次检查还会存储每个容器最近 200 行日志日志保留 7 天常量定义见 docker.type.ts。Docker 主机地址支持两种形式形式示例说明本地 socketunix:///var/run/docker.sock也接受纯绝对路径如/var/run/docker.sock用于监控与 Checkmate 同机运行的守护进程远程守护进程tcp://docker.example.com:2376始终使用双向 TLS端口默认2376不支持 2375 端口的未加密守护进程监控本地 socket参考 Compose 文件默认未挂载 socket需要自行添加卷并授予容器宿主机的docker组权限。先用stat -c %g /var/run/docker.sock查出组 ID然后services: checkmate: volumes: - /var/run/docker.sock:/var/run/docker.sock:ro group_add: - 989 # stat 输出的 gid监控远程守护进程将主机设为tcp://host:port并在监控器表单中填入与docker --tlsverify相同的 PEM 文件CA 证书签发守护进程服务器证书的 CA若开启「忽略 TLS/SSL 错误」则可不填跳过对守护进程身份的校验客户端证书守护进程用于认证 Checkmate 的证书客户端密钥对应的私钥必须未加密无口令。Checkmate 会校验其与证书匹配并用ENCRYPTION_KEY加密存储之后不再明文展示编辑时留空表示保留已存密钥。TLS Docker 监控器要求服务器设置ENCRYPTION_KEY见上文配置表未设置时保存会直接报错若密钥被移除或错误轮换相关检查将持续解密失败直至恢复。源码层面DockerProvider.ts 在发起 HTTPS 请求时会通过rejectUnauthorized: !monitor.ignoreTlsErrors控制是否校验守护进程身份并仅在提供dockerTlsKey时使用EncryptionService解密密钥——这正对应文档所述的密钥加密存储机制。若守护进程的证书由私有 CA 签发、且希望 Checkmate 整体都信任它参见 docs/custom-ca-trust.md仅针对 Docker 监控表单中的CA 证书字段就已足够。性能表现与资源占用得益于大量优化Checkmate 的内存占用非常低仅需极少的 CPU 与内存资源。项目文档记载在一个每分钟监控323 台服务器的 Node.js 实例上其内存占用保持在小规模水平同一服务器上 MongoDB 与 Redis 的内存占用分别约为398MB 与 15MB。此外项目宣称在1000 活跃监控器的压力测试下运行平稳未出现明显问题或性能瓶颈。以上均为项目 README 中记载的数据实际资源消耗会随监控器数量、检查频率与数据保留策略而不同建议以自身环境实测为准。监控器生命周期从探测到事件的全流程Checkmate 的监控器遵循一条清晰的生命周期流水线文档归纳为 6 个步骤执行检查监控器执行一次探测HTTP / ping / port或通过 Capture Agent 执行硬件检查存储结果结果被持久化成功/失败 响应时间阈值评估近期检查结果与监控器配置的状态变更阈值status change threshold进行比对状态变更若达到阈值且当前状态与先前状态不同监控器状态发生迁移例如initializing、up、down、breached事件流转状态变更时根据当前状态创建或解决一个事件incident通知触发根据配置触发相应的通知。这条流水线在服务端代码中有完整的实现证据状态枚举定义在 monitor.type.tsMonitorStatuses [up, down, paused, initializing, maintenance, breached]并包含statusWindow状态窗口位图、statusWindowSize、statusWindowThreshold等阈值字段状态→动作的决策逻辑集中在 worker.monitor-status-policy.ts 的MonitorStatusPolicy.evaluate()当状态未变化时不产生任何动作变为down时创建事件并发送「状态变更」通知硬件监控器变为breached时创建事件并发送「阈值越界」通知从down/breached恢复为up时解决事件并发送通知检查结果的数据结构定义在 types/network.ts其中StatusChangeResult携带thresholdBreachescpu/memory/disk/temp 布尔标志正是硬件阈值评估的输出载体。可见文档描述的「评估阈值 → 变更状态 → 流转事件 → 触发通知」在代码层面被拆解为监控器状态机与事件/通知反应器reactor形成完整闭环。技术栈与仓库结构根据文档的 Tech stack 章节Checkmate 采用如下技术栈React.js前端 UI 框架MUIMaterial UIReact 组件库Node.js服务端运行时MongoDB数据存储Recharts图表可视化库以及其他大量开源组件。这些在仓库结构中均有对应前端页面组件位于 client/src含 Components/design-elements 等设计体系、Features 状态管理、Hooks 业务逻辑服务端控制器/路由/校验位于 server/src/api领域模型与仓储位于 server/src/domain网络探测 Provider 位于 server/src/service/network后台任务与 Worker 位于 server/src/worker。监控数据的时间序列化、快照化处理则在 server/src/db/migration 中的迁移脚本里可见。更多文档、社区与贡献使用指南与更多文档可查阅 docs/ 目录其中包含自定义 CA 信任指南 docs/custom-ca-trust.md、自定义 CA 快速参考、基础设施磁盘选择、编码规范 与多语言翻译贡献指南等主 README 的英文原版见 README.md其他语言的翻译版本位于 docs/translations/例如简体中文 docs/translations/README.zh-CN.md问题与想法项目维护者推荐通过官方 Discord 频道交流首选GitHub Discussions 论坛也会定期查看欢迎提出任何问题、建议或功能想法发布通知可使用 Newreleases 这类免费服务追踪 Checkmate 的新版本发布参与贡献项目维护团队Alex 为 team lead另有 Gorkem、Aryaman、Mert、Karen 等成员乐于与各水平的贡献者协作。贡献流程为先阅读贡献者指南新人不妨从标记了good-first-issue的 issue 入手遇到疑似 bug 可提交 issue通过 Pull Request 提交新功能、体验优化或 bug 修复。根据 README 记载作为年轻项目Checkmate 已获得数千 Star 并吸引来自全球的 90 位贡献者其仓库也曾被 Google、Microsoft、Intel、Cisco、Tencent、ByteDance、Cloudflare 等公司的员工点亮。结语从本文可以清晰地看到Checkmate 的价值在于「上手简单、扩展深入」一条docker compose up命令即可获得完整的 Uptime 与事件监控能力而环境变量、自定义 CA、Docker TLS、Worker 分层伸缩等机制又为生产环境与复杂基础设施留足了演进空间。结合仓库源码读者可以在 docker/docker-compose.yaml 查看部署基线、在 server/src/config/envValidation.ts 理解配置校验、在 server/src/worker 与 server/src/domain 中追踪监控器从探测到事件通知的完整闭环从而真正把 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/Checkmate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考