PostgreSQL数据库部署安装流程文档说明本文档以 Docker 方式快速部署 PostgreSQL 15.4。为兼顾可读性教程中直接使用了示例账号postgres/ 密码postgres便于初学者照做。生产环境请务必修改默认密码并收紧访问权限详见下文「安全提醒」。目录一、配置需求二、大概流程简述三、验证环节四、具体流程docker-compose 工程化部署五、常用管理命令六、验证连接七、备份与恢复八、监控与告警九、故障排查十、升级与回滚附录 A安全加固清单附录 B配置参数速查表一、配置需求1. 系统要求一台装了 Docker 的服务器该服务器能与本地win电脑ping通操作系统Ubuntu 22.04推荐2. 资源需求PostgreSQL 15.4 镜像Docker官方仓库国内的能用来拉取镜像的docker镜像源3. 预备配置参数参数值端口5432用户名postgres密码postgres默认数据库postgres二、大概流程简述拉取官方 PostgreSQL 镜像编写docker-compose.yml部署文件启动容器含数据持久化、健康检查、资源限制、日志轮转配置远程访问与认证验证数据库连接三、验证环节1. 验证 Docker 环境# 检查 Docker 是否安装sudodocker--version如图所示结果显示类似Docker version 24.03.1, build xxxx就说明已安装。# 检查 Docker 服务是否运行sudosystemctl statusdocker如图所示结果看到active (running)就正常。退出查看ctrlc2. 验证镜像源是否能进行拉取镜像# 拉取测试镜像sudodockerpull hello-world失败结果如图所示成功结果如图所示能正常运行就说明镜像源没问题。如果拉取失败配置国内 Docker 镜像加速器创建文件sudomkdir-p/etc/dockersudo vim /etc/docker/daemon.json配置加速镜清空文件内容写入以下 JSON注意格式开始编写按i{registry-mirrors:[https://docker.m.daocloud.io,https://docker.1ms.run,https://docker.anyhub.us.kg],dns:[223.5.5.5,114.114.114.114]}退出编写保存退出esc:wq应用配置sudosystemctl daemon-reload重启dockersudosystemctl restartdocker配置成功后重新执行上面的拉取命令测试即可。四、具体流程docker-compose 工程化部署 本节使用docker-compose将部署配置文件化做到「一份配置处处可起」便于维护、复现与升级。账号密码仍沿用postgres / postgres仅教程示例生产请修改。1. 拉取 PostgreSQL 镜像sudodockerpull postgres:15.42. 准备部署目录sudomkdir-p/opt/postgresql/composecd/opt/postgresql/compose3. 创建数据持久化目录并授权# 创建数据目录sudomkdir-p/opt/postgresql/data# 授权给容器内的 postgres 用户UID/GID 均为 999sudochown-R999:999 /opt/postgresql/data说明999:999是官方 postgres 镜像内部运行账户的 UID:GID授权后容器才有权写入数据目录。4. 编写docker-compose.yml在/opt/postgresql/compose/目录下创建docker-compose.yml# /opt/postgresql/compose/docker-compose.ymlservices:postgres:image:postgres:15.4container_name:postgres_dbrestart:unless-stopped# 宕机自动拉起手动停止则不拉起# 教程沿用默认账号密码生产环境请改为强密码建议通过 .env 注入environment:POSTGRES_USER:postgresPOSTGRES_PASSWORD:postgresPOSTGRES_DB:postgresTZ:Asia/Shanghaiports:-5432:5432# 对外暴露端口如仅需本机访问改为 127.0.0.1:5432:5432volumes:-/opt/postgresql/data:/var/lib/postgresql/data# 数据持久化# 资源限制避免单个容器拖垮宿主机deploy:resources:limits:cpus:2.0memory:2G# 健康检查容器假活时能被发现healthcheck:test:[CMD-SHELL,pg_isready -U postgres]interval:30stimeout:5sretries:3start_period:30s# 日志轮转防止日志撑满磁盘logging:driver:json-fileoptions:max-size:10mmax-file:35. 启动服务# 后台启动老版本的启动命令sudo docker-compose up -d#老版本不支持 docker compose空格分隔这个子命令。sudodockercompose up-d# 查看状态等待片刻后 STATUS 应显示 healthysudodockercomposeps# 查看实时日志sudodockercompose logs-fpostgres6. 验证数据库连接sudodockerexec-itpostgres_db psql-Upostgres进入 psql 后可执行\l查看数据库列表\q退出。7. 配置远程访问容器首次启动时会在数据目录生成默认的postgresql.conf与pg_hba.conf。修改它们以允许远程连接# 1) 让 PostgreSQL 监听所有网卡sudodockerexec-itpostgres_dbbash-csed -i\s/^#listen_addresses localhost/listen_addresses */\/var/lib/postgresql/data/postgresql.conf# 2) 放行远程访问示例放行 192.168.1.0/24 网段sudodockerexec-itpostgres_dbbash-cecho\host all all 192.168.1.0/24 md5\ /var/lib/postgresql/data/pg_hba.conf# 3) 重启容器使配置生效sudodockercompose restart⚠️安全提醒务必阅读上面的pg_hba.conf规则请按实际网段收紧不要在生产环境使用0.0.0.0/0 md5允许任意 IP 登录风险极大。默认密码postgres为公开示例生产环境必须修改进入 psql 后执行ALTER USER postgres PASSWORD 你的强密码;若数据库需要暴露到公网强烈建议启用 SSL 加密并通过防火墙/安全组限制 5432 端口来源 IP。应用代码中不要硬编码密码推荐使用环境变量或配置中心。五、常用管理命令以下命令均在/opt/postgresql/compose/目录docker-compose.yml所在目录下执行。# 查看容器状态sudodockercomposeps# 查看实时日志sudodockercompose logs-fpostgres# 停止服务保留数据sudodockercompose stop# 启动服务sudodockercompose start# 重启服务修改配置后使其生效sudodockercompose restart# 进入容器内的 psqlsudodockerexec-itpostgres_db psql-Upostgres# 进入容器 shell 排查sudodockerexec-itpostgres_dbbash# 停止并删除容器数据目录 /opt/postgresql/data 保留不会丢数据sudodockercompose down# 修改 compose 文件后重新生效sudodockercompose up-d六、验证连接1. 服务器本地验证# 进入容器内部连接数据库sudodockerexec-itpostgres_db psql-Upostgres成功结果如图所示2. Windows 本地连接使用 Python 测试连接进入虚拟环境安装 psycopg2 库pipinstallpsycopg2-binary成功结果如图所示创建测试脚本# test01.pyimportpsycopg2try:connpsycopg2.connect(host192.168.1.128,port5432,databasepostgres,userpostgres,passwordpostgres)print(连接成功)cursorconn.cursor()cursor.execute(SELECT version();)print(PostgreSQL 版本:,cursor.fetchone())cursor.close()conn.close()exceptExceptionase:print(连接失败:,e)⚠️注意请将代码中的192.168.1.128替换为您自己的服务器 IP 地址。成功结果如图所示运行脚本python test01.py七、备份与恢复数据库最重要的运维能力就是「能恢复」。没有备份等于裸奔。1. 手动备份逻辑备份# 备份单个数据库sudodockerexecpostgres_db pg_dump-Upostgres postgresbackup_$(date%F).sql# 备份所有数据库与角色推荐sudodockerexecpostgres_db pg_dumpall-Upostgresfull_backup_$(date%F).sql# 备份并压缩节省空间sudodockerexecpostgres_db pg_dumpall-Upostgres|gzipfull_backup_$(date%F).sql.gz2. 定时备份crontab在宿主机执行crontab -e添加# 每天凌晨 2:30 全量备份保留最近 14 天 30 2 * * * docker exec postgres_db pg_dumpall -U postgres | gzip /opt/postgresql/backup/full_$(date %F).sql.gz find /opt/postgresql/backup -name full_*.sql.gz -mtime 14 -delete3. 恢复# 恢复全量备份gunzip-cfull_backup_2026-06-26.sql.gz|sudodockerexec-ipostgres_db psql-Upostgres# 恢复单库catbackup_2026-06-26.sql|sudodockerexec-ipostgres_db psql-Upostgres-dpostgres⚠️注意恢复前请先停止写入业务避免数据冲突重要数据建议先在测试库演练恢复流程。八、监控与告警容器跑起来不等于健康需要持续监控。1. 容器层面# 实时资源占用sudodockerstats postgres_db# 健康状态compose 方式下已配置 healthchecksudodockerinspect--format{{.State.Health.Status}}postgres_db2. 数据库层面轻量方案进入 psql 后执行-- 当前连接数SELECTcount(*)FROMpg_stat_activity;-- 长事务运行超过 5 分钟SELECTpid,now()-query_startASduration,queryFROMpg_stat_activityWHEREstateactiveANDnow()-query_startinterval5 minutes;-- 数据库大小SELECTpg_size_pretty(pg_database_size(postgres));3. 专业监控可选进阶接入postgres_exporter Prometheus Grafana可图形化监控连接数、缓存命中率、复制延迟等并配置告警邮件/钉钉/飞书。九、故障排查现象可能原因解决方案容器启动后立即退出数据目录权限不对 / 端口被占sudo docker compose logs postgres查看日志确认chown 999:999ss -tlnp | grep 5432检查端口docker pull超时镜像源失效修改/etc/docker/daemon.json更换可用镜像源sudo systemctl restart docker后重试远程连接被拒绝pg_hba.conf未放行 / 未监听进入容器检查cat /var/lib/postgresql/data/pg_hba.conf确认listen_addresses *sudo docker compose restartpassword authentication failed密码错误 / 用户名错误用sudo docker exec -it postgres_db psql -U postgres本地登录验证数据目录初始化失败目录非空且不是 PG 数据目录清空目录后重试⚠️ 会丢数据先备份容器健康检查 unhealthy数据库未就绪或资源不足sudo docker compose logs、sudo docker stats排查适当调大start_period磁盘写满日志/备份未轮转清理旧备份确认 compose 中已配置logging轮转常用排查命令汇总# 看容器日志最近 200 行sudodockercompose logs--tail200postgres# 进入容器排查sudodockerexec-itpostgres_dbbash# 查看端口监听ss-tlnp|grep5432# 查看磁盘空间df-h十、升级与回滚1. 升级前必做# 1) 完整备份务必sudodockerexecpostgres_db pg_dumpall-Upostgrespre_upgrade_$(date%F).sql# 2) 停止并删除旧容器数据目录保留cd/opt/postgresql/composesudodockercompose down2. 升级修改 compose 中的镜像版本修改docker-compose.yml中的image: postgres:15.4为新版本如postgres:16.2然后sudodockercompose up-d⚠️跨大版本升级如 15 → 16不能直接挂载旧数据目录必须使用pg_upgrade迁移数据否则容器会启动失败。小版本升级15.4 → 15.5可直接升级。3. 回滚若升级后异常cd/opt/postgresql/compose# 1) 将 docker-compose.yml 的 image 改回旧版本如 postgres:15.4# 2) 重新启动数据目录未被新版本改写时可直接回退sudodockercompose up-d# 若数据目录已被改写则从 pre_upgrade_*.sql 恢复gunzip-cpre_upgrade_2026-06-26.sql|sudodockerexec-ipostgres_db psql-Upostgres附录 A安全加固清单生产环境上线前逐项确认修改默认密码ALTER USER postgres PASSWORD 强密码;禁用postgres/postgres收紧 pg_hba.conf用具体网段如192.168.1.0/24 scram-sha-256替代0.0.0.0/0认证方式优先scram-sha-256而非md5启用 SSL/TLSpostgresql.conf设置ssl on挂载证书客户端强制 SSL 连接网络隔离5432 端口不直接暴露公网通过防火墙/安全组限制来源 IP最小权限账号应用使用专用账号仅授予对应库的增删改查权限不要用 superuser凭证管理密码通过环境变量/密钥管理服务注入禁止硬编码进代码或镜像定期备份开启定时备份并演练恢复备份文件异地存储日志审计开启连接日志定期审计异常登录版本补丁关注 PostgreSQL 安全公告及时升级小版本附录 B配置参数速查表类别参数本文档取值说明连接端口5432默认端口连接用户名postgres教程默认生产请修改连接密码postgres教程默认生产必须修改连接默认库postgres初始化数据库持久化数据目录宿主机/opt/postgresql/data绑定挂载路径持久化数据目录容器内/var/lib/postgresql/dataPG 标准路径持久化数据卷属主999:999容器内 postgres 用户的 UID:GID部署compose 目录/opt/postgresql/composedocker-compose.yml 所在目录镜像版本postgres:15.4官方镜像容器名称postgres_db本文档统一命名重启策略unless-stopped宕机自动拉起手动停止不拉起时区TZAsia/Shanghai在 compose 中设置维护建议本文档内嵌了大量截图导致文件体积较大。建议后续将图片迁移至docs/images/目录并以相对路径引用便于 Git 版本管理与团队协作。