ActualBudget项目中使用自签名证书时的Docker健康检查问题解决方案

问题背景

在使用ActualBudget项目的Docker部署时，当配置了自签名证书后，系统内置的健康检查脚本会出现故障。具体表现为Node.js的fetch请求因自签名证书不被信任而失败，导致Docker容器被标记为不健康状态。

技术原理分析

这个问题源于Node.js的安全机制。默认情况下，Node.js会对HTTPS请求执行严格的证书验证，包括：

1. 证书是否由受信任的CA签发
2. 证书中的主机名是否与请求的域名匹配
3. 证书是否在有效期内

当使用自签名证书时，由于证书不是由公共CA签发，Node.js会拒绝建立安全连接，抛出"self-signed certificate"错误。

解决方案

方法一：配置Node.js信任自签名证书

通过设置NODE_EXTRA_CA_CERTS环境变量，可以指定Node.js额外信任的CA证书：

NODE_EXTRA_CA_CERTS=/path/to/your/ca.crt node src/scripts/health-check.js

关键点：

1. 需要将自签名证书或CA证书放置在容器内可访问的位置
2. 证书文件路径需要正确映射到容器中
3. 建议将证书放在容器标准证书目录如/usr/local/share/ca-certificates/

方法二：修改健康检查脚本

另一种方案是修改健康检查脚本，使其跳过证书验证：

const https = require('https');
const agent = new https.Agent({
  rejectUnauthorized: false
});

fetch('https://localhost:8003/health', { agent })
  .then(response => {
    if (!response.ok) process.exit(1);
    process.exit(0);
  })
  .catch(() => process.exit(1));

注意：这种方法会降低安全性，仅建议在开发环境使用。

最佳实践建议

1. 证书配置：确保自签名证书包含正确的SAN(Subject Alternative Name)，特别是包含localhost
2. 容器部署：在Dockerfile中添加证书安装步骤
3. 环境隔离：生产环境建议使用正规CA签发的证书
4. 健康检查优化：可以考虑增加重试机制和超时设置

实施步骤

1. 生成包含localhost的自签名证书
2. 创建Dockerfile添加证书：

   COPY ca.crt /usr/local/share/ca-certificates/
   RUN update-ca-certificates
   

3. 修改docker-compose.yml配置健康检查：

   healthcheck:
     test: ["CMD", "NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/ca.crt", "node", "src/scripts/health-check.js"]
     interval: 30s
     timeout: 10s
     retries: 3
   

总结

在ActualBudget项目中使用自签名证书时，通过正确配置Node.js的证书信任机制，可以解决Docker健康检查失败的问题。建议优先采用添加证书到信任链的方案，既保证安全性又确保系统监控功能正常工作。对于生产环境，还是推荐使用正规CA签发的证书以避免此类问题。