deploy.stack/dbSer/postgres/readme.md

PostgreSQL 部署配置

基于 Docker Compose 的 PostgreSQL 数据库部署方案，提供生产环境和测试环境两套配置。

目录结构

postgres/
├── env.cfg            # 环境变量配置（镜像版本、密码、认证方式）
├── prod.stack.yml     # 生产环境部署配置
├── test.stack.yml     # 测试环境部署配置
└── readme.md          # 本文件

环境变量说明 (env.cfg)

变量名	说明	示例值
IMAGE_TAG	测试环境使用的 PostgreSQL 镜像（≤16 版本）	postgres:16.10
IMAGE_TAG_V15	PostgreSQL 15 镜像标签	postgres:15.14
IMAGE_TAG_V17	PostgreSQL 17 镜像标签	postgres:17.6
IMAGE_TAG_V18	生产环境使用的 PostgreSQL 18 镜像标签	postgres:18.0
POSTGRES_PASSWORD	数据库超级用户密码	AGC4eGx2aq8rSiZXBP
POSTGRES_HOST_AUTH_METHOD	主机认证方式	scram-sha-256

⚠️ 安全提示：部署前请务必修改 POSTGRES_PASSWORD 为你自己的强密码，不要使用默认密码。

环境差异对比

配置项	生产环境 (prod.stack.yml)	测试环境 (test.stack.yml)
项目名称	prod-dbs	test-dbs
容器名称	prod-postgres	test-postgres
镜像版本	IMAGE_TAG_V18（PostgreSQL 18）	IMAGE_TAG（PostgreSQL 16）
共享内存	256mb	128mb
数据卷路径	/var/lib/postgresql（≥17 版本）	/var/lib/postgresql/data（≤16 版本）

📌 注意：PostgreSQL ≥17 版本的数据目录变更为 /var/lib/postgresql，≤16 版本为 /var/lib/postgresql/data，请根据版本正确挂载。

部署前准备

创建数据卷目录：

mkdir -pv /data/volumes/postgres/data

部署命令

拉取镜像

生产环境：

docker compose --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/prod.stack.yml pull

测试环境：

docker compose --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/test.stack.yml pull

启动服务

生产环境：

docker compose -p prod-dbs --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/prod.stack.yml up -d

测试环境：

docker compose -p test-dbs --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/test.stack.yml up -d

连接信息

参数	值
主机	localhost 或服务器 IP
端口	5432
用户名	postgres
密码	env.cfg 中 POSTGRES_PASSWORD 的值
认证方式	scram-sha-256

连接示例：

psql -h localhost -p 5432 -U postgres

数据持久化

数据库数据挂载在宿主机 /data/volumes/postgres/data 目录下，容器重建后数据不会丢失。

常用管理命令

# 查看运行状态
docker compose -p prod-dbs ps

# 查看日志
docker compose -p prod-dbs logs -f postgres

# 停止服务
docker compose -p prod-dbs down

# 重启服务
docker compose -p prod-dbs restart

版本升级注意事项

• 从 PostgreSQL ≤16 升级到 ≥17 时，数据目录路径发生变化，需要迁移数据
• 升级前请务必备份数据：pg_dumpall -U postgres > backup.sql
• 不支持跨大版本直接替换数据目录，需使用 pg_upgrade 或逻辑备份恢复