阿列克谢·阿列尼科夫:生产环境中的 Docker PostgreSQL:卷、共享内存、连接池与备份

阿列克谢·阿列尼科夫:生产环境中的 Docker PostgreSQL:卷、共享内存、连接池与备份

💡 原文英文,约2200词,阅读约需8分钟。
📝

内容提要

本文介绍生产环境用Docker运行PostgreSQL的要点。PG18+将PGDATA挂载点改为/var/lib/postgresql,旧卷需先导出再恢复。默认配置有五大隐患:/dev/shm仅64MB致共享内存报错,应设shm_size≥1GB;10秒SIGKILL会中断检查点,应设stop_grace_period为60秒;健康检查须指定用户和库;连接过多需用PgBouncer事务池;卷权限须为999:999。另需固定镜像版本、启用数据校验和、限制端口暴露,并用pg_dump或WAL归档做异地备份。

🔎

延伸解读

PG18 卷路径变更:升级前必须规划

PostgreSQL 18 将 PGDATA 默认路径改为 /var/lib/postgresql 下的版本子目录,官方镜像的 VOLUME 目标也随之改变。这意味着直接复用 PG17 的旧卷启动 PG18 容器会失败。文章给出的安全升级流程是:先用 pg_dumpall 从旧容器导出,停止服务但保留旧卷,再用新卷启动 PG18 并恢复。旧卷在验证前不要删除,可作为回滚手段。

默认 Docker 配置的五个生产隐患

文章指出默认配置与 PostgreSQL 的运行方式存在多处冲突:/dev/shm 仅 64MB 会导致并行查询因共享内存不足而报错;10 秒 SIGKILL 超时可能中断检查点,引发启动时的 WAL 崩溃恢复;健康检查不指定用户和库会产生误报;缺少连接池时突发连接可能触发 OOM;卷权限需匹配 999:999。这些都不是 Docker 本身的问题,而是默认值未针对数据库调整。

连接池与内存参数需按主机规模调整

PostgreSQL 为每个连接分配独立进程,内存开销随连接数上升。文章建议用 PgBouncer 事务池吸收突发连接,并将 Postgres 的 max_connections 控制在合理范围。同时给出了 2GB 到 32GB 主机的参数对照表,强调 shared_buffers 不应占满内存,需为操作系统页缓存留出空间。这些参数需随主机规格成比例调整,而非照搬示例。

备份策略:避免直接打包运行中的卷

文章警告,对运行中的 PGDATA 执行 tar 或 rsync 会捕获不一致的页面,产生无法恢复的备份。对于约 30–50GB 以下的数据库,可用 pg_dump -Fc 做逻辑备份并加密传输到异地存储;更大或对 RPO 要求高的场景,应使用 WAL 归档配合 PITR。无论哪种方式,都应定期在临时容器中实际恢复验证,未经验证的备份不可靠。

❓

Q&A

PostgreSQL 18 的 Docker 镜像为什么不能直接挂载旧版 PG17 的数据卷?

PostgreSQL 18+ 将 PGDATA 移到了版本化子目录(如 /var/lib/postgresql/18/docker),官方 VOLUME 目标改为 /var/lib/postgresql,以便未来 pg_upgrade --link 能干净地升级大版本。如果直接把 PG17 的卷挂到 PG18 镜像上,容器会跳过初始化或立即退出。正确做法是先用 pg_dumpall 从 PG17 导出,再恢复到挂载在 /var/lib/postgresql 的新卷上。

Docker 里跑 PostgreSQL 时 /dev/shm 只有 64MB 会出什么问题?该怎么设置?

Docker 默认将 /dev/shm 限制为 64MB,而 PostgreSQL 的并行查询 worker 和动态共享内存段需要更多空间,负载高时会报错“could not resize shared memory segment ... No space left on device”。应在 Compose 中显式设置 shm_size: 1gb(小实例至少 1GB,shared_buffers 超过 2GB 时用 2GB–4GB),然后重建容器。

docker compose down 时 PostgreSQL 为什么可能被强制杀死并导致启动变慢?

Docker 默认在发送 SIGTERM 后只等 10 秒就发 SIGKILL。如果 PostgreSQL 在检查点期间有大量脏缓冲区要刷盘,10 秒不够,进程会在刷盘中途被杀,下次启动被迫进行缓慢的 WAL 崩溃恢复。应设置 stop_grace_period: 60s(写密集实例可设 120s),让 Postgres 收到 SIGTERM 后完成快速关闭和检查点。

Docker 中 PostgreSQL 的健康检查为什么用 pg_isready 会误报?正确的写法是什么?

只写 test: ["CMD-SHELL", "pg_isready"] 会检查默认用户(root)和默认数据库,可能在 initdb 重启期间、实际数据库和角色尚未创建时就短暂通过。应始终指定用户和目标数据库,例如 test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"],并配合 interval、timeout、retries 和 start_period 使用。

PostgreSQL 在 Docker 里连接数一多就 OOM,怎么解决?

PostgreSQL 为每个客户端连接 fork 一个独立 OS 后端进程(约 5–10MB 内存外加 work_mem),突发几百个连接容易触发容器内 OOM kill。应在 Postgres 前部署 PgBouncer,使用 transaction 池模式,把 Postgres 的 max_connections 保持在合理范围(如 100–150),由 PgBouncer 承接 500+ 客户端连接。PgBouncer 1.21+ 在事务模式下原生支持协议级预处理语句,Prisma、SQLAlchemy、pgx 等 ORM 无需特殊处理。

在 Docker 中备份 PostgreSQL 时为什么不能直接 tar 正在运行的数据卷?推荐哪些备份方式?

对运行中的 PostgreSQL 用 tar 或 rsync 复制原始 PGDATA 文件会捕获撕裂页,产生无法恢复的备份。推荐两种方式:数据库小于约 30–50GB 时,用 pg_dump -Fc 做逻辑压缩转储,加密后传到 S3 兼容存储(如 Cloudflare R2);更大数据库或低 RPO 要求时,用 pgBackRest 或 WAL-G 做持续 WAL 归档和 PITR。每月还应使用临时容器实际验证备份可恢复。

生产环境用 Docker 跑 PostgreSQL 需要固定镜像版本吗?端口和卷权限有什么要求?

需要固定精确镜像版本(如 postgres:18.1-bookworm),不要用 :latest。端口方面不要将 5432 暴露在 0.0.0.0,PgBouncer 应绑定到 127.0.0.1:6432 或内部网络。卷方面 Linux 生产主机优先用本地 NVMe SSD 上的 Docker 命名卷,或属主为 UID/GID 999:999 的专用主机路径,切勿将 PGDATA 放在 SMB/CIFS 网络共享上。

🏷️

标签

➡️

继续阅读