psycopg3 的 connectionpool 在 uwsgi 多工作进程部署下，因进程间共享连接对象导致 ssl 状态错乱，引发空闲连接批量失效、pooltimeout 异常；根本解法是启用 `lazy-apps=true` 让每个 worker 独立初始化连接池。
在使用 psycopg3 的 ConnectionPool 时，开发者常期望连接池能长期稳定维持预设的最小连接数（如 min_size=5），尤其在低流量场景下保持连接活跃。然而，实际运行中却频繁出现「空闲一小时后所有连接瞬间消失」「pool_available 归零」「后续请求触发 PoolTimeout」等现象——而单连接模式（psycopg.connect()）却可稳定运行数日。问题根源并非 psycopg3 池逻辑缺陷，而是部署环境与连接生命周期管理的错配。
关键线索来自 PostgreSQL 服务端日志：
2025-02-09 10:46:46.488 CET [297518] user@db LOG: SSL error: decryption failed or bad record mac 2025-02-09 10:46:46.489 CET [297518] user@db LOG: could not receive data from client: Connection reset by peer
该 SSL error: decryption failed or bad record mac 是典型 TLS 会话状态不一致标志——意味着客户端（此处为 Python 进程）尝试复用一个已被其他上下文篡改或失效的加密通道。结合 uwsgi 的默认行为即可定位症结：
✅ 根本原因：uwsgi 默认的 preload 模式
uwsgi 启动时默认先加载应用（--module）、初始化全局变量（含 ConnectionPool 实例），再 fork 出多个 worker 进程。此时所有 worker 共享同一组底层 socket 文件描述符和 OpenSSL SSL_CTX 对象。当某 worker 关闭连接、重用连接或触发 SSL renegotiation 时，其操作会污染其他 worker 所持连接的 TLS 状态，导致空闲连接在首次复用时因密钥/nonce/序列号不匹配而被 PostgreSQL 拒绝，最终全部断开。
❌ 错误尝试（无效）：
- 调整 max_idle 或 min_size/max_size 参数 → 仅改变数量，不解决状态共享；
- 自定义 check=ConnectionPool.check_connection → 无法修复已损坏的 SSL 握手状态；
- 缩短 timeout → 加剧超时感知，但未触及本质。
✅ 正确解法：启用 lazy-apps = true
在 uwsgi 配置中显式启用懒加载，确保每个 worker 进程独立执行应用初始化：
# uwsgi.ini [uwsgi] module = main:app master = trueprocesses = 4 lazy-apps = true # ← 关键！禁止 preload，让每个 worker 自行 import & init # 其他配置...
processes = 4
lazy-apps = true # ← 关键！禁止 preload，让每个 worker 自行 import & init
# 其他配置...启用后，每个 worker 启动时都会独立执行 init_pool()，创建专属的 ConnectionPool 和底层 TCP+SSL 连接，彻底避免跨进程连接共享。此时连接池行为回归预期：
- min_size=5 的连接由各 worker 独立维护；
- 空闲连接受操作系统 TCP keepalive 及 PostgreSQL tcp_keepalives_* 参数保护；
- 即使长时间无请求，连接亦可持续存活（需确保 DB 端未主动 kill idle 连接）。
? 补充建议（增强健壮性）：
-
服务端保活配置（PostgreSQL postgresql.conf）：
tcp_keepalives_idle = 60 # 60秒无数据后发送keepalive tcp_keepalives_interval = 10 # 每10秒重试一次 tcp_keepalives_count = 6 # 连续6次失败才断开
-
客户端连接字符串显式启用 keepalive（psycopg3 v3.1.11+）：
cnx_str = ( f"host={DB_HOST} port={DB_PORT} dbname={DB_NAME} " f"user={DB_USERNAME} password={DB_USERPWD} " "keepalives=1 keepalives_idle=60 keepalives_interval=10 keepalives_count=6" ) self.pool = ConnectionPool(conninfo=cnx_str, min_size=min_cnx, open=True) - 避免在 __init__ 中过早初始化池：确保 init_pool() 在 worker 上下文中调用（lazy-apps 已保障），而非模块导入时。
总结：psycopg3 连接池本身设计合理，但其连接对象（含 SSL 状态）不具备跨进程安全性。在 uwsgi、gunicorn（preload 模式）等多进程 WSGI 服务器中，必须通过 lazy-apps=true 或 --reload-on-rss 等机制，确保连接池生命周期与 worker 进程严格对齐。这是生产环境正确使用连接池的必要前提。
