Uptime-Kuma 监控远程 Docker 主机时的 TLS 证书配置指南

问题背景

在使用 Uptime-Kuma 监控远程 Docker 主机时，许多用户会遇到 TLS 证书验证失败的问题。特别是当使用 acme.sh 工具通过 Let's Encrypt 生成的证书时，虽然通过 curl 命令测试连接正常，但在 Uptime-Kuma 界面中测试连接时却会出现 "unable to get issuer certificate" 的错误。

问题根源分析

这个问题的根本原因在于 acme.sh 生成的证书链不完整。具体来说：

1. acme.sh 默认生成的 ca.pem 文件只包含中间证书，不包含根证书 ISRG Root X1
2. curl 命令会自动使用系统中存储的根证书进行验证，因此可以正常工作
3. Uptime-Kuma 内部使用的 axios 库不会自动加载系统根证书，需要完整的证书链才能验证

解决方案

完整证书链生成方法

正确的做法是手动合并中间证书和根证书：

# 下载 Let's Encrypt 的根证书
curl -sS https://letsencrypt.org/certs/isrgrootx1.pem -o isrgrootx1.pem

# 合并证书链（fullchain.cer 包含服务器证书和中间证书）
cat fullchain.cer isrgrootx1.pem > ca.pem

证书文件说明

需要准备三个关键文件：

1. cert.pem - 服务器证书（可直接使用 acme.sh 生成的 fullchain.cer）
2. key.pem - 私钥文件
3. ca.pem - 完整的证书链（必须包含根证书）

Uptime-Kuma 配置建议

在 Uptime-Kuma 的 Docker 容器中，建议将证书文件存放在 /app/data/docker-tls/主机名/ 目录下，包含以下三个文件：

• ca.pem (完整证书链)
• cert.pem (服务器证书)
• key.pem (私钥)

验证方法

配置完成后，可以通过以下方式验证：

1. 在容器内使用 curl 测试（不指定 --cacert 参数）：

curl --cert ./cert.pem --key ./key.pem https://主机名:2376/version

2. 在 Uptime-Kuma 网页界面测试连接

技术原理深入

Let's Encrypt 的证书链采用三级结构：

1. 终端实体证书（服务器证书）
2. 中间证书（Let's Encrypt E5）
3. 根证书（ISRG Root X1）

完整的证书验证需要能够追溯整个信任链。acme.sh 默认生成的 ca.cer 只包含中间证书，缺少根证书，导致 axios 无法完成完整的证书验证过程。

相比之下，curl 会检查系统的证书存储（通常是 /etc/ssl/certs），其中已经预置了 ISRG Root X1 根证书，因此可以自动补全证书链完成验证。

最佳实践建议

1. 定期更新证书：Let's Encrypt 证书有效期90天，建议设置自动续期
2. 证书文件权限：确保 key.pem 文件权限为600，避免私钥泄露
3. 备份策略：妥善备份证书和私钥，防止数据丢失
4. 监控证书过期：在 Uptime-Kuma 中设置对证书过期的监控

通过以上配置，Uptime-Kuma 就能够正确验证远程 Docker 主机的 TLS 证书，实现对远程 Docker 环境的稳定监控。