Paperless-ngx 2.15.x版本PostgreSQL SSL连接问题分析与解决方案

问题背景

Paperless-ngx是一个开源的文档管理系统，在2.15.0版本升级后，部分用户在使用SSL连接PostgreSQL数据库时遇到了连接失败的问题。错误信息显示系统无法访问/root/.postgresql/postgresql.crt证书文件，导致数据库连接被拒绝。

问题现象

当用户配置PostgreSQL强制使用SSL连接（通过hostssl配置）并设置PAPERLESS_DBSSLMODE=require时，系统会抛出以下错误：

django.db.utils.OperationalError: connection failed: connection to server at "176.177.19.6", port 5432 failed: could not open certificate file "/root/.postgresql/postgresql.crt": Permission denied

值得注意的是，这个问题仅在2.15.0及更高版本中出现，2.14.7及之前版本工作正常。

根本原因分析

经过深入调查，发现问题的根源在于s6-overlay工具的行为变化以及PostgreSQL客户端库(libpq)的证书查找机制：

1. 证书查找机制：PostgreSQL客户端库默认会在用户主目录下的.postgresql目录中查找证书文件。对于root用户，这个路径是/root/.postgresql/postgresql.crt。

2. s6-setuidgid行为：在2.15.0版本中，Paperless-ngx开始使用s6-setuidgid来以非root用户(paperless)身份运行迁移脚本。然而，s6-setuidgid不会自动更新$HOME环境变量，导致即使切换了用户，仍然尝试访问root用户的主目录。

3. 权限问题：当以paperless用户身份运行时，它没有权限访问/root目录，因此当libpq尝试检查证书文件时会失败。

解决方案

目前有以下几种可行的解决方案：

方案一：显式设置HOME环境变量（推荐）

在docker-compose.yml中为webserver服务添加环境变量：

environment:
  HOME: /usr/src/paperless

方案二：以非root用户运行容器

修改docker-compose.yml，指定用户ID运行：

services:
  webserver:
    user: "1000:1000"

方案三：等待官方修复

开发团队已经注意到这个问题，并正在准备修复方案。可以关注后续版本更新。

技术细节补充

1. PostgreSQL SSL连接机制：当使用SSL连接时，PostgreSQL客户端会按照以下顺序查找证书：

   • 用户主目录下的.postgresql目录
   • 系统默认的证书存储位置
   • 如果都不存在，对于有效的CA签名证书(如Let's Encrypt)，通常会使用系统证书存储

2. s6-overlay特性：s6-overlay是一个轻量级的init系统，它的s6-setuidgid工具设计上只改变用户ID和组ID，不修改环境变量，这与传统的su或sudo命令行为不同。

3. 安全影响：以非root用户运行容器是一个更安全的做法，符合最小权限原则，这也是Docker安全最佳实践之一。

总结

Paperless-ngx 2.15.x版本的PostgreSQL SSL连接问题主要是由于用户切换时环境变量处理不一致导致的。通过理解PostgreSQL的证书查找机制和s6-overlay的工作方式，用户可以采取多种解决方案来恢复系统功能。建议用户根据自身环境选择最适合的解决方案，同时关注官方后续的修复更新。

这个问题也提醒我们，在容器化环境中，用户切换和环境变量处理是需要特别注意的细节，特别是在涉及文件系统权限和安全连接的场景下。