Docker PostgreSQL 16 部署要点（Ubuntu 22）

一、镜像相关

镜像：postgres:16
国内服务器必须配置 Docker 加速器，否则拉取超时
Docker 镜像、容器存储位置：默认 /var/lib/docker

二、挂载卷（重点）

只挂载数据目录即可，配置文件已内置在数据目录中，不需要额外挂载 conf 文件。

宿主机路径	容器内路径
`/home/ubuntu/docker/postgres/data`	`/var/lib/postgresql/data`

该目录包含：全部业务数据、索引、WAL 日志、PG 账号权限系统表、postgresql.conf、pg_hba.conf。

删除容器后，宿主机目录不变，数据与配置全部保留。

⚠️ 权限大坑（必做）

容器内部 postgres 进程 UID 固定为 999 ，宿主机无此用户名，Linux 只识别数字 UID。

挂载数据卷，pg进程（UID为999的用户）要操作宿主机目录，必须要重新分配数据目录权限

bash 复制代码

sudo mkdir -p /home/ubuntu/docker/postgres/data
sudo chown -R 999:999 /home/ubuntu/docker/postgres/data
sudo chmod 700 /home/ubuntu/docker/postgres/data

chown -R 999:999：让容器内 PG 进程拥有目录读写权限
chmod 700：仅属主可访问，PG 强制要求；700 挡不住 root 用户

❌ 禁止在宿主机直接编辑挂载目录内的 conf 文件

用 sudo vim 保存后文件属主变成 root，UID=999 的 PG 进程读取失败，容器反复重启。

✅ 修改配置正确方式：进入容器内部编辑

bash 复制代码

docker exec -it pg16 bash
vim /var/lib/postgresql/data/postgresql.conf
vim /var/lib/postgresql/data/pg_hba.conf

三、初始化账号密码逻辑

环境变量	说明
`POSTGRES_USER`	超级用户名，省略默认 `postgres`，建议显式写明
`POSTGRES_PASSWORD`	超级用户密码，必填，不能为空

⚠️ 仅宿主机数据目录为空（首次启动）时，环境变量才生效！

如果目录已存在旧数据，修改 run 命令的环境变量完全无效，账号密码存储在 PG 系统表中。修改密码需进入 psql 执行 ALTER USER。

安全规范：业务程序不要直接使用 postgres 超级账号，启动成功后新建业务用户与业务库。

四、日志说明

Docker 版 PG 默认日志输出到容器标准输出，用 docker logs pg16 查看，不落地磁盘文件，无需挂载日志目录
需要磁盘日志需修改 postgresql.conf 开启，再额外挂载日志目录，普通业务不推荐

五、网络安全（云服务器必看）

端口映射：-p 5432:5432
云服务器安全组严禁开放 5432 到 0.0.0.0/0，限制为自己本机公网 IP，防止爆破
更安全的做法：-p 127.0.0.1:5432:5432，仅本机可连，外部完全不可达

六、完整容器创建命令

bash 复制代码

sudo docker run -d \
  --name pg16 \
  -p 5432:5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD="替换为你的强密码" \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/docker/postgres/data:/var/lib/postgresql/data \
  --restart always \
  postgres:16

七、启动后校验

bash 复制代码

# 查看容器运行状态
docker ps

# 查看启动日志，出现 "database system is ready to accept connections" 代表成功
docker logs pg16

# 进入 psql 交互终端测试
docker exec -it pg16 psql -U postgres

八、备份提醒

数据库运行时不要直接拷贝宿主机 data 目录，会造成数据损坏。

逻辑备份使用 pg_dump：

bash 复制代码

# 备份
docker exec pg16 pg_dump -U postgres 库名 > backup.sql

# 恢复
cat backup.sql | docker exec -i pg16 psql -U postgres -d 库名

九、创建业务用户 & 数据库

在 psql 内执行：

sql 复制代码

CREATE USER business_user WITH PASSWORD '业务密码';
CREATE DATABASE business_db OWNER business_user;
GRANT ALL PRIVILEGES ON DATABASE business_db TO business_user;

十、故障排查要点

现象	原因	解决
容器反复重启	目录权限问题，文件属主变成 root	`chown -R 999:999` 修复权限
改了环境变量密码不生效	数据目录非空，环境变量仅首次生效	进入 psql 执行 `ALTER USER`
容器启动报权限错误	宿主机目录权限不是 700	`chmod 700` 修复

修改数据库参数两种方式：

容器内改 conf → 重启容器
run 命令追加 -c 参数：docker run ... postgres:16 -c max_connections=200