Checkmate 自定义 CA 信任配置指南：让私有证书签发的 HTTPS 端点不再误报 DOWN

Checkmate 自定义 CA 信任配置指南让私有证书签发的 HTTPS 端点不再误报 DOWN【免费下载链接】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私有 CA如 Smallstep、内部 PKI签发的 HTTPS 端点在 Checkmate 的 Docker 部署中常常因证书校验失败而显示为 DOWN即使服务本身完全可达。本文基于仓库中的 Custom CA Trust Guide 与配套示例配置系统讲解在 Docker 环境下为 Checkmate 配置自定义 CA 信任的两种方案Node 级NODE_EXTRA_CA_CERTS与 OS 级update-ca-certificates并附 Smallstep 根证书导出、完整验证流程与安全注意事项帮助你无需关闭 SSL 校验即可监控内部 HTTPS 服务。背景为什么私有 CA 会导致监控误报 DOWNCertificate AuthorityCA证书颁发机构是负责签发和管理数字证书的实体。公开 CA如 Lets Encrypt、DigiCert的根证书被绝大多数操作系统和运行时默认信任而私有或内部 CA如 Smallstep 签发的证书、企业内部 PKI 体系签发的证书并不在默认信任列表中需要显式配置信任。Checkmate 的监控探针在执行 HTTPS 检查时会基于 Node.js 内置的 CA 信任存储对服务端证书做完整校验详见下文源码分析。当被监控的 HTTPS 端点使用的是私有 CA 签发的证书时校验会因未知 CAunknown CA而失败于是该端点会被标记为 DOWN即便该服务实际可正常访问监控数据与告警依然是错误的。这正是自定义 CA 信任配置要解决的问题在不关闭 SSL 校验的前提下让 Checkmate 信任你的私有 CA。从源码层面看Checkmate 的 HTTP 检查默认走严格证书校验。HttpProvider.ts 中为 HTTPS 请求维护了两个共享连接池 agentthis.httpsAgent new HttpsAgent({ ...agentOptions, rejectUnauthorized: true }); this.httpsAgentInsecure new HttpsAgent({ ...agentOptions, rejectUnauthorized: false });httpsAgentrejectUnauthorized: true用于正常检查严格验证证书链httpsAgentInsecurerejectUnauthorized: false仅在监控项开启Ignore TLS/SSL errors时使用。也就是说默认情况下任何不被 Node 信任存储认可的 CA 都会导致检查失败。虽然逐个监控项开启忽略 TLS 错误也是一种做法httpProvider.test.ts 中有对应测试但那等于放弃证书校验存在安全风险。自定义 CA 信任提供的是信任特定 CA但保持完整校验的折中方案。方案一Node 级信任推荐最简单Node.js 提供了NODE_EXTRA_CA_CERTS环境变量启动时Node 会读取该变量指向的 PEM 证书文件并将其追加到默认的 CA 信任链中不会覆盖内置信任存储。这是最轻量的做法无需重新构建镜像。1. Docker Compose 配置在checkmate服务上添加证书卷挂载与环境变量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: - mongodb要点说明NODE_EXTRA_CA_CERTS指向容器内证书文件的绝对路径即/certs/custom-ca.pem卷挂载./certs:/certs:ro将宿主机的certs目录以只读方式挂载进容器避免容器内被篡改env_file: server.env用于注入 Checkmate 自身的环境变量如ENCRYPTION_KEY等与 CA 信任配置互不影响depends_on保证 MongoDB 先就绪参考 docker/dev/docker-compose.yaml 中mongodb服务的service_healthy健康检查。2. 目录结构在 Docker Compose 项目根目录下创建certs目录并放入你的 CA 证书PEM 格式docker/dev/ ├── docker-compose.yaml ├── certs/ │ └── custom-ca.pem └── ...仓库中已经预留了 docker/dev/certs/ 目录用于放置证书文件。3. 使用仓库自带的示例 override 文件仓库在 docker/dev/docker-compose.custom-ca-example.yaml 中提供了一份开箱即用的示例 overrideservices: checkmate: environment: NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem volumes: - ./certs:/certs:ro启动方式Compose 会自动合并基础文件与 override 文件docker compose -f docker-compose.yaml -f docker-compose.custom-ca-example.yaml up -d该示例文件头部注释明确标注了 Dev/Test only: Not required in production即它演示的是最小信任配置生产环境请按需调整如将证书打入镜像或使用密钥管理系统。方案二OS 级信任Debian 基础镜像 自定义 Dockerfile当需要整个容器层面都信任该 CA例如其他依赖系统 CA 存储的程序也要用时可以基于官方镜像派生一个自定义镜像把 CA 安装到操作系统信任存储中。1. 自定义 Dockerfile创建checkmate-custom-ca.DockerfileFROM ghcr.io/bluewave-labs/checkmate:latest USER root RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/* # Copy your custom CA certificate (must have a .crt extension) COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/ # Update CA certificates RUN update-ca-certificates USER node # Node uses its bundled CA store by default; make it read the system store ENV NODE_OPTIONS--use-system-ca关键点官方镜像默认以node用户运行安装系统包需要先切换到USER root装完再切回USER node与 docker/Dockerfile 中USER node的做法一致放入/usr/local/share/ca-certificates/的证书扩展名必须是.crtPEM 格式否则update-ca-certificates不会处理它必须显式RUN update-ca-certificates才会重新生成/etc/ssl/certs/ca-certificates.crt捆绑文件Node.js 默认使用自带的 CA 存储即使系统层已信任该 CA也需要NODE_OPTIONS--use-system-ca让 Node 改读系统存储Checkmate 的 Node 进程才会真正受益。2. Docker Compose override构建自定义镜像创建docker-compose.custom-ca.yamlservices: checkmate: build: context: . dockerfile: checkmate-custom-ca.Dockerfile restart: always ports: - 52345:52345 env_file: - server.env depends_on: - mongodb运行docker compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml up基础镜像注意事项Checkmate 官方镜像是基于node:22-slim的 Debian 系镜像见 docker/Dockerfile 与 docker/Dockerfile 中两个 stage 的FROM node:22-slim。该精简镜像默认不安装ca-certificates包所以在执行update-ca-certificates之前必须先apt-get install -y ca-certificates见上文 Dockerfile。汇总三条关键约束ca-certificates包需自行安装slim 镜像不自带/usr/local/share/ca-certificates/下的证书必须是.crt扩展名Node 只有在启动参数带--use-system-ca时才会读取系统信任存储。对大多数场景而言方案一的NODE_EXTRA_CA_CERTS组合方式更简单无需重建镜像。Smallstep CA 证书导出如果内部 CA 使用的是 Smallstep注仅作背景说明不提供外部链接可按如下方式导出根 CA 证书# 导出根 CA 证书 step certificate inspect --format pem step-ca/root_ca.crt custom-ca.pem # 或者使用已配置的 CA URL step certificate inspect --format pem $(step path)/certs/root_ca.crt custom-ca.pem使用导出的证书将导出的custom-ca.pem复制到你的docker/dev/certs/目录选择上文方案一或方案二中的任一种进行配置重启 Checkmate server 容器使其生效。完整实战示例基线失败 → 自定义 CA 成功下面以 Smallstep CA 为例演示一套完整的验证闭环确认自定义 CA 信任是否真的生效。基线测试预期失败1. 不带自定义 CA 信任启动 Checkmatecd docker/dev docker-compose up -d2. 测试到内部 HTTPS 端点的连接# 预期报 TLS 错误unknown CA docker-compose exec server node -e const https require(https); https.get(https://your-internal-site.com, res { console.log(STATUS:, res.statusCode); }).on(error, e { console.error(ERR:, e.message); }); 预期结果TLS 错误self-signed certificate/unable to verify the first certificate/ unknown CA。自定义 CA 测试预期成功1. 导出 Smallstep 根 CAstep certificate inspect --format pem step-ca/root_ca.crt docker/dev/certs/smallstep-root-ca.pem2. 更新 docker-compose.yaml加入自定义 CA 信任services: server: environment: NODE_EXTRA_CA_CERTS: /certs/smallstep-root-ca.pem volumes: - ./certs:/certs:ro3. 重启并应用自定义 CA 配置docker-compose down docker-compose -f docker-compose.yaml -f docker-compose.custom-ca-example.yaml up -d4. 再次测试同一连接# 这次应成功 docker-compose exec server node -e const https require(https); https.get(https://your-internal-site.com, res { console.log(STATUS:, res.statusCode); }).on(error, e { console.error(ERR:, e.message); }); 预期结果HTTP 200 OK。验证要点基线TLS 失败证明默认行为未知 CA 导致拒绝符合预期自定义 CATLS 成功证明自定义 CA 信任配置已生效两组测试必须同时通过才能确认功能配置正确。至此Checkmate server 会信任由 Smallstep CA 签发的证书可以放心监控内部 HTTPS 端点而无需关闭 SSL 校验。安全注意事项⚠️重要安全警告只信任你控制或明确信任的 CA。信任不可信 CA 会破坏监控系统的安全边界。私有 CA只信任来自你所在组织 PKI 基础设施的 CA自签名证书优先考虑搭建正规的 CA 基础设施而不是直接信任自签名证书证书有效性确保 CA 证书未过期且合法访问控制生产环境中限制对 CA 证书文件的访问。配套的快速参考文档 Custom CA Quick Reference 还给出了额外安全实践使用只读卷挂载./certs:/certs:ro、不要把证书提交进版本控制、绝不要信任不受控的 CA。故障排查验证 CA 是否已被容器信任# 进入运行中的容器 docker exec -it container_name sh # 检查 CA 是否在信任存储中 ls -la /usr/local/share/ca-certificates/ cat /etc/ssl/certs/ca-certificates.crt | grep -A 5 -B 5 YOUR_CA_NAME第二条命令适用于 OS 级方案Node 级方案可直接检查挂载文件docker exec -it container ls -la /certs/常见问题权限拒绝Permission denied确保 CA 证书文件具有正确的读权限证书格式优先使用 PEM 格式.pem、.crt以获得最佳兼容性容器重启新增 CA 证书后务必重启容器环境变量与镜像层只有在启动时才生效路径问题核对卷挂载中证书路径是否与NODE_EXTRA_CA_CERTS指向的容器内路径一致日志佐证查看容器日志辅助定位docker compose logs server连接测试可用wget --ca-certificate/certs/custom-ca.pem https://your-internal-site.com在容器内显式指定 CA 测试连通性。更多参考Custom CA Quick Reference快速上手版含环境变量速查与文件结构图docker/dev/docker-compose.custom-ca-example.yamlNode 级信任的现成示例 overridedocker/Dockerfile官方镜像构建过程确认node:22-slim基础镜像与USER node运行方式README.mdREADME 中关于自定义 CA 场景与 Docker 监控TLS 凭据、Docker host 形式的背景说明。【免费下载链接】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），仅供参考