跳到主要内容 Docker 部署 PostgreSQL 数据库教程 | 极客日志
SQL
Docker 部署 PostgreSQL 数据库教程 本文介绍如何使用 Docker 部署 PostgreSQL 数据库。涵盖环境准备、镜像拉取、容器启动(含数据持久化)、生产环境安全配置(网络隔离、密码管理)、备份策略及常见问题排查。重点强调生产环境需锁定版本、限制访问权限并定期备份,提供从测试到企业级部署的完整方案。
蓝绿部署 发布于 2026/3/29 更新于 2026/4/13 1 浏览PostgreSQL 是一款开源免费的高级关系型数据库管理系统,始于 1986 年,由全球开发者社区持续维护迭代,兼具悠久历史与前沿特性。它严格遵循 ACID 事务原则,确保数据读写的一致性与可靠性,同时突破传统关系型数据库局限,支持多模型存储——既能兼容标准 SQL,又可高效处理 JSON、数组、地理空间(GIS)等复杂数据类型。
其核心优势在于极强的扩展性:可通过自定义函数、存储过程及丰富插件(如 PostGIS 用于地理信息分析)拓展功能,适配从中小型应用到企业级海量数据场景(如电商交易、日志分析、科学计算)。此外,它采用多版本并发控制(MVCC)优化高并发读写性能,内置数据加密、访问控制等安全机制,是平衡功能深度、稳定性与运维友好性的主流开源数据库优选。
🧰 准备工作
Linux Docker & Docker Compose 安装 建议使用系统包管理器或官方脚本安装 Docker 和 Docker Compose。
apt-get update && apt-get install -y docker.io docker-compose-plugin
1、查看 PostgreSQL 镜像详情 可在 Docker Hub 中找到 PostgreSQL 镜像页面。
在镜像页面中,你会看到多种拉取方式,下面逐一说明如何下载与部署(生产环境务必使用明确版本号,禁止直接使用 latest )。
2、下载 PostgreSQL 镜像
2.1 版本选择说明 镜像标签 适用场景 风险提示 postgres:latest 测试/学习 版本不固定,大版本升级可能导致数据不可用 postgres:16 生产环境推荐 稳定版本,兼容当前主流应用,升级需按官方流程 postgres:15 生产环境备选 长期支持版本,适合需要稳定性的 legacy 系统
2.2 拉取镜像
docker pull library/postgres:16
2.3 拉取后改名(保持与官方镜像命名一致)
docker pull library/postgres:16 \
&& docker tag library/postgres:16 library/postgres:16 \
&& docker rmi library/postgres:16
docker pull:拉取镜像
docker tag:重命名镜像引用方式
docker rmi:删除临时标签,避免重复占用空间
2.4 官方直连方式(网络支持时使用) 若网络可直连 Docker Hub,或已配置加速器,可直接:
docker pull postgres:latest
docker pull postgres:16
2.5 查看镜像是否拉取成功 REPOSITORY TAG IMAGE ID CREATED SIZE
postgres 16 5 d2f9e78c6f1 2 weeks ago 374 MB
3、部署 PostgreSQL 以下示例按「测试 → 准生产 → 企业级」分类,生产环境请优先选择 3.2 或 3.3 方案,并补充安全配置。
3.1 快速部署(✅ 测试/学习专用,禁止生产使用) docker run -d --name pg-test \
-e POSTGRES_PASSWORD=StrongTestPass123! \
-p 5432:5432 \
library/postgres:latest
--name pg-test:容器名称
-e POSTGRES_PASSWORD=StrongTestPass123!:设置 postgres 超级用户密码(必填,测试也建议用强密码)
-p 5432:5432:将宿主机端口映射到容器 5432 端口
docker exec -it pg-test psql -U postgres
3.2 挂载数据目录(⚠️ 准生产方案,需补充安全配置) 该方式解决了数据持久化问题,是生产环境的基础形态。必须补充版本锁定、密码管理、网络隔离、资源限制等安全措施后,方可用于真实生产环境 。
第一步:创建宿主机目录并配置权限 PostgreSQL 容器内部使用 UID 999、GID 999 的 postgres 用户运行进程,宿主机目录需授权该用户可读写:
mkdir -p /data/postgres/{data,logs}
chown -R 999:999 /data/postgres
chmod -R 700 /data/postgres
第二步:启动容器并挂载目录(生产推荐 16 版本) docker run -d --name pg-web \
-e POSTGRES_PASSWORD=ComplexProdPass_2024! \
-e POSTGRES_USER=appuser \
-e POSTGRES_DB=appdb \
-e TZ=Asia/Shanghai \
-p 127.0.0.1:5432:5432 \
--restart always \
--memory 2G \
--cpus 1 \
-v /data/postgres/data:/var/lib/postgresql/data \
library/postgres:16
目录说明(官方镜像标准路径) 宿主机目录 容器目录 说明 是否必选 /data/postgres/data /var/lib/postgresql/data 核心数据目录(含配置文件) 是 /data/postgres/logs /var/log/postgresql 日志目录(需手动配置) 否
⚠️ 重要说明:官方 PostgreSQL 镜像的配置文件(postgresql.conf、pg_hba.conf)默认存储在 $PGDATA(即 /var/lib/postgresql/data)目录下,而非 /etc/postgresql(该路径为 Debian 系统原生安装路径,容器镜像不适用);日志默认输出到 stdout,推荐通过 Docker 日志驱动收集(如 json-file、loki),而非直接挂载文件目录。
3.3 docker-compose 部署(🏭 企业级参考方案,需根据业务调整) 统一管理配置与容器,支持一键启动、集群扩展,适合生产环境规模化部署。
第一步:编写 docker-compose.yml(生产级配置) version: '3.8'
services:
postgres:
image: library/postgres:16
container_name: pg-service
restart: always
environment:
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: ${DB_NAME}
TZ: Asia/Shanghai
PGDATA: /var/lib/postgresql/data
ports:
- "127.0.0.1:5432:5432"
volumes:
- ./data:/var/lib/postgresql/data
deploy:
resources:
limits:
cpus: '2'
memory: 4G
healthcheck:
test: ["CMD-SHELL" , "pg_isready -U ${DB_USER} -d ${DB_NAME}" ]
interval: 10s
timeout: 5s
retries: 3
networks:
- app-network
networks:
app-network:
driver: bridge
第二步:创建 .env 文件(密码管理,避免明文暴露) 在 docker-compose.yml 同级目录创建 .env 文件:
DB_USER=appadmin
DB_PASSWORD=StrongProdPass@2024#
DB_NAME=businessdb
第三步:启动服务
mkdir -p ./data && chown -R 999:999 ./data && chmod 700 ./data
docker compose up -d
docker compose ps
初始化脚本:若需启动时自动执行 SQL(如创建表、授权),可在 ./init-scripts 目录下放置 .sql 或 .sh 文件,容器启动时会自动执行;
配置修改:直接编辑 ./data/postgresql.conf 和 ./data/pg_hba.conf,修改后需重启容器生效;
网络隔离:通过自定义网络 app-network 隔离数据库服务,仅允许同网络内的应用访问。
4、结果验证
查看容器状态
docker ps | grep postgres
docker compose ps
应看到容器状态为 Up(健康检查通过会显示 healthy)。
进入 PostgreSQL 命令行
docker exec -it pg-web psql -U appuser -d appdb
docker compose exec postgres psql -U ${DB_USER} -d ${DB_NAME}
创建测试表验证功能 CREATE TABLE test(id SERIAL PRIMARY KEY , name TEXT, create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP );
INSERT INTO test(name) VALUES ('Hello PostgreSQL!' );
SELECT * FROM test;
id | name | create_time
1 | Hello PostgreSQL! | 2024 -05 -20 10 :00 :00 + 08 (1 row )
5、生产环境关键配置补充(🏭 必看)
5.1 远程访问配置(⚠️ 严格限制访问范围) 默认配置仅允许本地访问,若需跨服务器访问(如应用与数据库分离),需修改配置文件,禁止直接开放 0.0.0.0/0 :
第一步:修改 postgresql.conf
cd /data/postgres/data
sed -i 's/^listen_addresses = .*/listen_addresses = ' *'/' postgresql.conf
第二步:修改 pg_hba.conf(限定内网网段)
vi /data/postgres/data/pg_hba.conf
echo "host all all 172.18.0.0/16 md5" >> pg_hba.conf
🚫 高危警告:
禁止添加 host all all 0.0.0.0/0 md5(全网开放),若需公网访问,必须通过 VPN、反向代理或云数据库网关,同时启用 SSL 加密。
第三步:重启容器 docker restart pg-web
docker compose restart postgres
5.2 密码安全优化
docker exec -it pg-web psql -U postgres ALTER USER appuser WITH PASSWORD 'NewStrongPass2024!' ;
生产环境推荐使用 Docker Secrets 或云厂商密钥管理服务(如 AWS Secrets Manager),避免 .env 文件泄露。
5.3 日志配置(容器化最佳实践) 推荐使用 Docker 日志驱动收集日志,而非文件挂载:
docker run -d --name pg-web \
--log-driver json-file \
--log-opt max-size=10m \
--log-opt max-file=3 \
library/postgres:16
如需输出日志到文件,需修改 postgresql.conf:
ALTER SYSTEM SET logging_collector = on;
ALTER SYSTEM SET log_directory = '/var/log/postgresql' ;
ALTER SYSTEM SET log_filename = 'postgresql-%Y-%m-%d.log' ;
ALTER SYSTEM SET log_rotation_age = '1d' ;
ALTER SYSTEM SET log_rotation_size = '100MB' ;
SELECT pg_reload_conf();
5.4 备份策略(生产必备)
手动备份示例:
docker exec pg-web pg_dump -U appuser -d appdb -F c -f /var/lib/postgresql/data/backup_$(date +%Y%m%d).dump
docker cp pg-web:/var/lib/postgresql/data/backup_20240520.dump /data/backups/
定时备份(使用 crontab):
crontab -e
0 2 * * * docker exec pg-web pg_dump -U appuser -d appdb -F c -f /var/lib/postgresql/data/backup_$(date +%Y%m%d).dump && docker cp pg-web:/var/lib/postgresql/data/backup_$(date +%Y%m%d).dump /data/backups/ && find /data/backups/ -name "backup_*.dump" -mtime +7 -delete
6、常见问题排查
6.1 容器启动失败(日志显示权限错误) 原因 :宿主机数据目录权限不足,容器内 postgres 用户(UID 999)无法读写。
解决 :
chown -R 999:999 /data/postgres
chmod -R 700 /data/postgres
6.2 无法连接数据库(应用或客户端报错)
netstat -tulpn | grep 5432
firewall-cmd --add-port=5432/tcp --permanent && firewall-cmd --reload
检查 pg_hba.conf 配置:确保客户端 IP 在授权网段内;
查看容器日志排查:
docker logs pg-web
docker compose logs postgres
6.3 数据库时区不正确 ALTER SYSTEM SET timezone = 'Asia/Shanghai' ;
SELECT pg_reload_conf();
6.4 大版本升级(如 15 → 16) ⚠️ 重要提醒:PostgreSQL 大版本升级不可直接替换镜像版本 ,数据目录不兼容,需通过 pg_dump 备份 + 恢复 或 pg_upgrade 工具迁移。
docker exec pg-v15 pg_dumpall -U postgres -f /data/backup/all_dump.sql
docker stop pg-v15 && docker rm pg-v15
docker run -d --name pg-v16 -e POSTGRES_PASSWORD=xxx -v /data/postgres-v16:/var/lib/postgresql/data library/postgres:16
docker cp /data/backup/all_dump.sql pg-v16:/tmp/
docker exec pg-v16 psql -U postgres -f /tmp/all_dump.sql
6.5 日志文件过大 解决 :启用日志轮转(参考 5.3 日志配置),或使用 logrotate 管理宿主机日志文件:
vi /etc/logrotate.d/postgres
/data/postgres/logs/*.log {
daily
rotate 7
compress
missingok
notifempty
create 0600 999 999
}
7、可选优化(提升专业度与安全性)
7.1 为什么不推荐 root 用户跑数据库?
权限过大:容器内 root 用户可操作宿主机资源,存在安全风险;
数据安全:意外操作(如 rm -rf)可能直接删除宿主机数据;
符合最小权限原则:PostgreSQL 官方镜像默认使用非 root 用户,降低攻击面。
7.2 Docker Volume vs Bind Mount(数据挂载选择) 挂载方式 优点 缺点 适用场景 Bind Mount(宿主机目录) 直接访问文件,备份方便 权限配置复杂,跨平台兼容差 生产环境(可控服务器) Docker Volume 权限自动管理,跨平台兼容 文件路径隐藏,需通过 docker volume 命令管理 测试/集群环境
7.3 PostgreSQL 在容器中与 K8s 的差异
容器部署:适合中小规模应用,配置简单,运维成本低;
K8s 部署:适合大规模、高可用场景,支持自动扩缩容、滚动更新、StatefulSet 持久化,但需额外配置 PV/PVC、ConfigMap、Secret 等资源。
结尾 至此,你已掌握 PostgreSQL Docker 从测试到准生产的完整部署流程,包括镜像版本选择、数据持久化、安全配置、备份策略与问题排查。
初学者:使用「3.1 快速部署」验证功能,熟悉 PostgreSQL 基础操作;
中小团队:基于「3.2 挂载数据目录」或「3.3 docker-compose 部署」,补充权限控制、网络隔离、定时备份,即可满足大部分生产需求;
企业级场景:需进一步探索主从复制、读写分离、SSL 加密、监控告警(如 Prometheus + Grafana)等进阶功能,结合业务需求优化配置。
始终牢记:生产环境无小事 ,版本锁定、权限最小化、数据备份、网络隔离是数据库安全的四大基石,切勿直接将测试配置用于真实业务场景。
微信扫一扫,关注极客日志 微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
相关免费在线工具 SQL 美化和格式化 在线格式化和美化您的 SQL 查询(它支持各种 SQL 方言)。 在线工具,SQL 美化和格式化在线工具,online
SQL 转 CSV/JSON/XML 解析 INSERT 等受限 SQL,导出为 CSV、JSON、XML、YAML、HTML 表格(见页内语法说明)。 在线工具,SQL 转 CSV/JSON/XML在线工具,online
CSV 工具包 CSV 与 JSON/XML/HTML/TSV/SQL 等互转,单页多 Tab。 在线工具,CSV 工具包在线工具,online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
Markdown 转 HTML 将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online