Paperless-AI项目中使用自签名证书的解决方案

在部署Paperless-AI项目与Paperless-NGX实例集成时，当Paperless-NGX使用自签名证书时，可能会遇到证书验证失败的问题。本文将深入分析问题原因并提供两种有效的解决方案。

问题背景

Node.js应用在验证HTTPS连接时会严格检查服务器证书的有效性。当Paperless-NGX使用自签名证书时，默认情况下Node.js会拒绝连接，并抛出"unable to get local issuer certificate"错误。这是因为自签名证书不在Node.js信任的根证书列表中。

问题分析

通常，在Linux系统中可以通过更新ca-certificates来添加自定义CA证书：

1. 将根CA证书放入/usr/local/share/ca-certificates/
2. 执行update-ca-certificates命令

然而，Node.js并不使用系统的CA证书存储，而是维护自己的证书列表。因此，即使系统已正确配置，Node.js应用仍可能无法验证自签名证书。

解决方案

方案一：禁用证书验证（开发环境适用）

在docker-compose.yml中添加以下环境变量配置：

environment:
  - "NODE_TLS_REJECT_UNAUTHORIZED=0"

这种方法会完全禁用Node.js的TLS证书验证，虽然能解决问题，但会降低安全性，仅建议在开发或测试环境中使用。

方案二：添加自定义CA证书（生产环境推荐）

如果有自签名证书的根CA证书，可以通过以下方式让Node.js信任它：

environment:
  - "NODE_EXTRA_CA_CERTS=/path/to/custom-ca.crt"

这种方法更为安全，因为它只添加了对特定CA的信任，而不是完全禁用证书验证。

技术原理

Node.js使用自己的TLS实现，与系统证书存储分离。NODE_EXTRA_CA_CERTS环境变量允许开发者指定额外的CA证书文件，这些证书将被添加到Node.js内置的证书列表中。而NODE_TLS_REJECT_UNAUTHORIZED则控制是否强制执行证书验证。

最佳实践建议

1. 生产环境应始终使用方案二，维护适当的安全级别
2. 确保证书文件路径在容器内可访问
3. 考虑使用Docker卷将CA证书挂载到容器中
4. 定期更新和维护自定义CA证书

通过以上方法，可以安全可靠地在Paperless-AI项目中集成使用自签名证书的Paperless-NGX实例。