Ubuntu 24.04上Docker部署PostgreSQL完整实操记录-平芜编程栈

我在这台腾讯云服务器上用Docker部署PostgreSQL踩了不少坑，官方文档写得云里雾里，网上教程又大多针对旧版本系统，很多命令在Ubuntu 24.04上直接跑不通。折腾了一整天，总算把整套流程捋顺了，从零到生产可用，包括远程连接、权限配置、数据持久化这些关键环节，现在整理成这篇实操记录，希望对正在折腾的人有帮助。

说实话，Ubuntu 24.04刚推出来的时候，我还在犹豫要不要把服务器系统升级上去。毕竟作为长期支持版本，官方保证支持到2029年，安全性更新和软件源维护都有保障，最终决定拿这台腾讯云服务器当小白鼠。结果发现24.04相比22.04在几个底层库上变动挺大，直接导致我之前熟悉的那套部署流程全部要重新验证。特别是Docker的安装方式和PostgreSQL容器的兼容性，都有不少值得注意的细节。

1. 部署方案设计与核心思路

1.1 为什么选择Docker方式部署PostgreSQL

在云服务器上部署PostgreSQL，无非就三条路：apt直接安装、编译源码安装、Docker容器化部署。我个人的建议是，除非你有极度定制化的需求，否则优先选Docker，理由很实在。

apt源里的PostgreSQL版本通常滞后，Ubuntu 24.04官方源里默认的还是PostgreSQL 16，但PostgreSQL 17都已经发布一段时间了。如果你需要尝鲜或者生产环境有特定版本要求，apt这条路基本就走不通了。编译安装更折腾，依赖库、编译参数、后续维护全得自己操心，光是处理那一堆依赖关系就够写一篇文章了。

Docker部署的核心优势在于环境隔离和版本管理。我在这台腾讯云服务器上同时跑了多个项目，每个项目对数据库版本的要求可能都不一样，有的要PostgreSQL 15，有的要16，Docker可以让你在一台机器上完美共存，互不干扰。而且容器级别的资源限制、日志管理、启动策略，都比裸机部署要精细得多。

1.2 部署架构与关键决策

我这次部署采用单机单容器架构，目录规划如下：

PostgreSQL数据目录挂载到宿主机/data/postgresql，确保容器删除后数据不丢失
配置目录独立挂载，方便直接修改配置文件而不必进入容器
日志输出到宿主机/data/postgresql/logs，便于集中查看和日志采集

选择这个架构主要基于三点考虑。数据安全永远是第一位的，Docker容器本身是瞬态的，随时可能被删除重建，如果数据存放在容器内部，一旦误删容器，数据就彻底没了。其次是运维方便，直接在宿主机上用vim修改配置文件然后重启容器，比进入容器操作要顺手得多。最后是适配腾讯云的监控体系，后续如果要接入云监控或者日志服务，日志在宿主机上会好处理很多。

2. 服务器基础环境配置

2.1 系统初始设置

拿到一台全新的腾讯云服务器，第一步别急着装Docker，先把系统基础环境调理好。我习惯用如下顺序操作：

# 以root用户登录后，先更新软件源和系统 apt update && apt upgrade -y # 安装基础工具包 apt install -y wget curl vim git lrzsz net-tools # 设置时区为Asia/Shanghai timedatectl set-timezone Asia/Shanghai # 创建软件安装目录 mkdir -p /data/software /data/postgresql

时区设置这个细节很容易被忽略，但影响特别大。如果你不设置时区，默认的UTC时间，那么PostgreSQL的NOW()函数返回的时间会比北京时间慢8小时。这个时间偏差在开发和联调阶段会让你抓狂，特别是做日志分析、定时任务调试的时候。

2.2 Ubuntu 24.04的apt源优化

Ubuntu 24.04的apt源在国内访问有时候不太稳定，尤其在你执行apt update的时候，那个速度简直让人怀疑人生。腾讯云服务器可以很方便地使用内网镜像源，不仅快而且不消耗公网流量。

# 备份原始源文件 cp /etc/apt/sources.list /etc/apt/sources.list.bak # 直接替换为腾讯云镜像源 cat > /etc/apt/sources.list << 'EOF' deb http://mirrors.cloud.tencent.com/ubuntu/ noble main restricted universe multiverse deb http://mirrors.cloud.tencent.com/ubuntu/ noble-updates main restricted universe multiverse deb http://mirrors.cloud.tencent.com/ubuntu/ noble-backports main restricted universe multiverse deb http://mirrors.cloud.tencent.com/ubuntu/ noble-security main restricted universe multiverse EOF apt update

这里特别提醒一下，Ubuntu 24.04的代号是noble，不是之前的jammy，如果照抄22.04的命令会直接报错。我之前就吃过这个亏，复制了旧命令然后发现一堆404错误，排查了半天才发现是源地址的问题。

3. Docker引擎安装与加速配置

3.1 Docker安装的几种方式

Ubuntu 24.04上安装Docker，官方推荐用apt仓库安装，我也建议正常情况都走这条路。虽然我见过有人直接用snap install docker，省事儿是省事儿，但后续管理权限、自定义配置会比较麻烦，而且在Ubuntu 24.04上snap版Docker偶尔会有奇怪的兼容性问题，不建议在服务器环境使用。

# 安装依赖包 apt install -y apt-transport-https ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置Docker apt仓库 echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker引擎 apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

需要提醒的是，我们在服务器上直接运行了docker命令但没用sudo，这样操作起来最顺手。但Docker和系统安全息息相关，在当前的安全环境下，确保你完全清楚自己在做什么再这么配置。

# 将当前用户加入docker组，免sudo执行docker命令 usermod -aG docker $USER newgrp docker # 设置Docker开机自启 systemctl enable docker systemctl start docker # 验证安装 docker --version docker compose version

3.2 配置镜像加速器

Docker镜像拉取速度在国内一直是个痛点，尤其是从Docker Hub直接拉取PostgreSQL官方镜像，那个速度简直折磨人。腾讯云服务器可以配置使用腾讯云的Docker镜像加速器，速度快很多。

mkdir -p /etc/docker cat > /etc/docker/daemon.json << 'EOF' { "registry-mirrors": ["https://mirror.ccs.tencentyun.com"] } EOF systemctl daemon-reload systemctl restart docker

腾讯云这个镜像加速地址，只对腾讯云服务器内网有效，如果你用的是其他厂商的服务器或者本地虚拟机，这个地址是访问不了的。如果你用阿里云服务器，可以换用阿里云的加速器；如果是在本地环境，我试过配置几个公共加速器，效果都不太稳定，最后干脆把代理环境配好直接拉取。

3.3 验证Docker环境

什么都配置好之后，强烈建议先拉一个小镜像测试一下，别一上来就拉PostgreSQL。踩过的坑，用hello-world先确认Docker全家桶工作正常，然后再拉取PostgreSQL镜像，这样万一出问题，至少能隔离开来是Docker自身问题还是PostgreSQL镜像问题。

docker pull hello-world docker run --rm hello-world # 看到Hello from Docker!提示，说明Docker环境正常

4. PostgreSQL容器镜像选择与部署

4.1 镜像版本选择策略

Docker Hub上的PostgreSQL官方镜像，版本非常多，从9.x到17.x都有。很多人习惯直接docker pull postgres:latest，这样省事，但生产环境我强烈不建议这么做，这是给自己埋雷。你怎么知道你下次启动容器时的latest变成了什么版本呢？

我的建议是明确指定大版本号。比如当前要部署的目标环境，PostgreSQL 16是最稳定的长期支持版本，就和Ubuntu 24.04搭配得很默契。需要说明的是，PostgreSQL的小版本升级不需要重新初始化数据目录，直接拉取新的小版本镜像重新启动容器即可。

# 拉取PostgreSQL 16.x版本镜像 docker pull postgres:16 # 查看本地已有镜像 docker images

4.2 使用docker-compose编排部署

docker run虽然简单直观，但每次要写一长串参数，而且不好维护。我更推荐用docker-compose，尤其当你需要多容器编排的时候，比如数据库加应用容器，compose文件的优势立刻就体现出来了。

在/data/postgresql目录下创建docker-compose.yml文件：

services: postgresql: image: postgres:16 container_name: postgresql restart: always environment: POSTGRES_USER: myadmin POSTGRES_PASSWORD: 'YourStrongPassw0rd!' POSTGRES_DB: myapp TZ: 'Asia/Shanghai' PGTZ: 'Asia/Shanghai' ports: - "5432:5432" volumes: - /data/postgresql/data:/var/lib/postgresql/data - /data/postgresql/logs:/var/log/postgresql shm_size: 256mb healthcheck: test: ["CMD-SHELL", "pg_isready -U myadmin -d myapp"] interval: 10s timeout: 5s retries: 5

关于这个compose文件，有几个点值得展开说明。restart: always非常重要，有了这个配置，Docker守护进程启动时会自动拉起PostgreSQL容器，同时如果容器因为异常退出，也会自动重启。之前我在测试环境就是忘了写这个，服务器重启后数据库没起来，排查了半天才发现是这个问题。

POSTGRES_USER和POSTGRES_PASSWORD这两个环境变量，是PostgreSQL官方镜像的“首次启动”配置。也就是说，只有在数据目录为空的时候，镜像的entrypoint脚本才会去读取这些变量，创建用户和数据库。如果数据目录已经有数据了，这些环境变量会被忽略。明白这个机制后，你就知道为什么有时候改了密码环境变量但不起作用——因为你的数据目录已经初始化过了。

PGTZ这个环境变量容易被忽略，它控制的是PostgreSQL会话内部的时区。虽然我在宿主机层面设置了TZ，但PostgreSQL的默认时区行为有时候不按常理出牌，显式设置PGTZ能确保数据库层面的时间计算也是正确的北京时间。

4.3 启动容器并验证

cd /data/postgresql docker compose up -d # 查看容器状态 docker ps # 查看容器日志 docker logs -f postgresql

等日志稳定输出之后，可以进一步验证数据库连通性：

# 进入容器内部执行SQL docker exec -it postgresql psql -U myadmin -d myapp # 执行一些基础验证SQL SELECT version(); SELECT now(); SHOW timezone;

正常情况下，version()应该显示PostgreSQL 16.x，now()应该是北京时间，timezone应该是Asia/Shanghai。到这里，单机部署的核心环节就已经完成了。

5. 远程连接配置与安全加固

5.1 修改监听地址与认证方式

PostgreSQL默认只监听localhost，也就是只允许本机连接。要远程连接，必须修改两个地方：监听地址和认证方式。

PostgreSQL 16基于安全考虑，镜像里的postgresql.conf默认配置将listen_addresses设置成了localhost。Docker容器内部其实很特殊，因为容器有自己的网络命名空间，即使设置监听*，也只暴露在容器的网络栈中，通过端口映射才能从宿主机访问。所以这里可以放心修改。

# 进入容器并修改配置 docker exec -it postgresql bash # 在容器内执行 sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/" /var/lib/postgresql/data/postgresql.conf # 退出容器，重启使其生效 exit docker restart postgresql

同时要修改客户端认证配置pg_hba.conf，添加允许远程连接的规则：

# 编辑pg_hba.conf，在文件末尾追加 echo "host all all 0.0.0.0/0 scram-sha-256" >> /data/postgresql/data/pg_hba.conf # 重启容器 docker restart postgresql

关于认证方式，PostgreSQL 16的默认密码加密方式是scram-sha-256，这一点比旧版本的md5要安全得多。修改配置时务必保留默认的scram-sha-256，不要因为看着md5眼熟就改回md5。

5.2 腾讯云安全组与防火墙配置

腾讯云服务器有两层网络防线：安全组是云平台层面的虚拟防火墙，ufw是系统层面的防火墙，两层都要放行5432端口。

先看系统层面的防火墙：

ufw allow 5432/tcp ufw status

再登录腾讯云控制台，找到这台服务器实例，确认安全组入站规则中放行了TCP 5432端口。这一步最容易卡住，系统防火墙放行了，但云平台安全组没开，就是连不上。很多人排查半天，最后发现是安全组的事，这个坑我踩过不止一次。

5.3 安全加固经验

数据库端口暴露到公网，安全压力是巨大的。如果你只是自己用，或者团队内部使用，有更好的方案。

最稳妥的做法是修改默认端口。把宿主机映射端口从5432改成非常规端口，比如54321，虽然这种做法挡不住有耐心的攻击者，但能过滤掉绝大多数自动化扫描脚本，因为他们默认只会扫5432端口。

其次，密码必须足够复杂。我见过太多数据库弱口令被爆破的案例，有些人设置密码喜欢用公司名加生日，这种密码在字典库里基本是一击即中。建议用至少16位，包含大小写字母、数字、特殊字符的随机密码，用密码管理器生成并保存。

如果是纯内网使用或者个人开发环境，更建议配合腾讯云安全组设置IP白名单，只允许特定IP访问5432端口。比如你的办公网固定IP，或者你家里的宽带IP，这样安全等级立刻提升好几个档次。我在生产环境一般就是数据库不直接暴露公网，而是通过跳板机转发访问，虽然多了一步操作，但安全性完全不是一个量级。

6. 数据持久化与备份策略

6.1 数据持久化验证

刚部署完数据库，很多人会有疑问：万一容器挂了怎么办？重启后数据还在吗？要验证数据持久化是否配置正确，最直接的办法就是实际测试一下。

# 创建测试数据 docker exec -it postgresql psql -U myadmin -d myapp -c "CREATE TABLE test(id serial primary key, name text);" docker exec -it postgresql psql -U myadmin -d myapp -c "INSERT INTO test(name) VALUES('持久化测试');" # 强制删除容器（模拟灾难场景） docker compose down docker compose up -d # 验证数据是否还在 docker exec -it postgresql psql -U myadmin -d myapp -c "SELECT * FROM test;"

如果你能看到之前插入的数据，说明数据持久化没问题。这里的关键就在volume挂载配置，/data/postgresql/data映射到了容器内部的/var/lib/postgresql/data，这个目录在镜像的Dockerfile中被声明为VOLUME，所有数据文件都在这里。

多数情况下，如果忘记了配置数据目录挂载，容器一删，数据库就彻底没了，连恢复的机会都没有。那种数据丢失的感觉，经历过的人都懂，比被老板骂一顿还难受。

6.2 定时备份方案

数据持久化只是第一步，定期备份才是数据安全的终极防线。我喜欢用crontab加pg_dump的方式，简单可靠，不需要额外装复杂的备份工具。

# 创建备份脚本 cat > /data/postgresql/backup.sh << 'EOF' #!/bin/bash BACKUP_DIR="/data/backup/postgresql" BACKUP_FILE="$BACKUP_DIR/myapp_$(date +%Y%m%d_%H%M%S).sql" KEEP_DAYS=7 mkdir -p $BACKUP_DIR # 使用docker exec执行pg_dump docker exec postgresql pg_dump -U myadmin -d myapp > $BACKUP_FILE # 压缩备份文件 gzip $BACKUP_FILE # 清理7天前的备份 find $BACKUP_DIR -name "*.sql.gz" -mtime +$KEEP_DAYS -exec rm {} \; # 输出备份结果 echo "Backup completed at $(date)" >> /data/postgresql/backup.log EOF chmod +x /data/postgresql/backup.sh # 配置每天凌晨2点执行备份 echo "0 2 * * * /data/postgresql/backup.sh" | crontab -

这个备份方案的思路是：每天凌晨2点用pg_dump导出完整的SQL文件，压缩后保留7天，既保证了可以恢复到任意一天的数据状态，又不会让磁盘被备份文件塞满。如果你的数据库特别大，可以考虑用pg_basebackup做物理备份，或者用WAL-G做持续归档，但绝大多数中小项目用逻辑备份就够了。

生产环境的话建议把备份文件再同步一份到腾讯云COS对象存储，异地容灾级别。这个可以通过腾讯云自带的coscmd工具轻松实现，加几行命令就行。注意，安全第一，备份密码文件或环境变量不要硬编码在脚本里，避免泄露。

提示：腾讯云存储等云服务都可以配合这些备份策略，但要注意访问密钥的权限控制。尽量减少密钥泄露的风险，只授予必要的读写权限，不要用主账号密钥。

7. 常见故障排查与优化实践

7.1 容器启动失败

症状：执行docker compose up -d后，容器状态是Exited，或者一直在Restarting。

排查方法：

# 查看容器日志，这是最直接的线索 docker logs postgresql

常见的错误就是端口被占用。你之前用apt装过PostgreSQL，宿主机5432端口已经被占用了，容器内的PostgreSQL无法绑定这个端口。解决方式是先停掉并卸载宿主机自带的PostgreSQL，或者修改宿主机的映射端口。

另一个常见问题是数据目录权限不匹配。容器内的PostgreSQL是以postgres用户（UID 999）运行的，挂载到宿主机后，如果宿主机上的/data/postgresql/data目录所属用户不是UID 999，容器就报权限错误，无法写入数据文件。我遇到过这种情况，排查了很久才发现是权限问题，后面学乖了，直接在创建数据目录的时候就把属主设置为UID 999：

mkdir -p /data/postgresql/data chown -R 999:999 /data/postgresql/data

7.2 认证失败与密码修改

症状：在本机用psql连接提示password authentication failed for user "myadmin"。

可能的原因：

首次启动创建用户时环境变量设置错误，导致密码不是你想设的那个
pg_hba.conf里配置的认证方式和实际用的密码加密方式不匹配
数据目录在创建用户之前就已经初始化过了，环境变量根本没生效

针对最麻烦的情况，就是环境变量没生效但数据目录已经初始化。这时候需要手动修改密码：

# 进入容器 docker exec -it postgresql psql -U myadmin -d myapp # 执行SQL修改密码 ALTER USER myadmin WITH PASSWORD 'NewStrongPassword';

注意，如果你的pg_hba.conf里配的是scram-sha-256，这个密码切换没问题，因为新密码会自动用当前配置的加密方式存储。

7.3 远程连接超时或拒绝连接

症状：从本地电脑用pgAdmin或psql连接腾讯云服务器上的PostgreSQL，提示超时或者connection refused。

排查顺序（按可能性从高到低排列）：

腾讯云安全组是否放行了5432端口
系统防火墙ufw是否放行
PostgreSQL是否监听了*或0.0.0.0
pg_hba.conf是否允许你的IP网段访问
网络是否通，可以先telnet 服务器IP 5432试试

这里想说的是，排查问题不要靠猜，要按照网络连通性的层次从外往内排查：先确认端口通不通，再确认监听地址，最后看认证配置。我见过很多同事一上来就修改PostgreSQL配置，结果问题其实出在安全组。

7.4 性能优化基础配置

PostgreSQL容器默认配置偏保守，大致适合小内存的虚拟机环境。如果你的腾讯云服务器内存有4GB或更多，建议调整几个核心参数。

# 修改postgresql.conf shared_buffers = 1GB effective_cache_size = 3GB maintenance_work_mem = 256MB work_mem = 16MB max_connections = 200

这几个参数的含义，用大白话解释一下。shared_buffers是PostgreSQL在内存里缓存数据的缓冲区大小，通常设置为物理内存的1/4；effective_cache_size是对操作系统文件缓存的一个估计值，影响查询规划器的决策，通常设置为物理内存的50%~75%；work_mem是单个查询排序、哈希操作能用的内存，不要设置太大，否则高并发场景下内存直接爆掉；max_connections控制最大连接数，默认100对于小项目够用，但如果你用连接池，可以适当调大。

如果不确定，建议先保持默认配置，观察实际负载再调整。机器性能问题要具体分析，不要一上来就改参数，很多时候压垮数据库的是慢查询而不是配置不够好。

8. 部署验证与上线检查清单

8.1 功能验证清单

在正式使用之前，可以从下面几个维度全面验证数据库的可用性：

数据库连接是否正常，本机和远程分别测试
数据是否持久化，删除容器重建后数据不丢
服务是否自动重启，宿主机重启后容器自动拉起
备份流程是否正常，能完整导出并恢复
日志是否正常输出，并且有合理的轮转策略

8.2 最佳实践总结

这次在腾讯云上部署PostgreSQL，有几个特别想分享的心得。

不要在生产环境使用latest标签的镜像，锁定大版本号是对未来自己的负责。前后端协作时，环境不一致的锅甩起来很累，锁定版本后大家起码有一个共同基线。

密码管理要安全，数据库密码不要写在明文的配置文件或环境变量里。我见过很多公司PostgreSQL密码直接写在.env文件里传到Git仓库的，那种泄漏风险比黑客攻击还大。可以考虑用Docker secret或者外部密钥管理服务来保存敏感配置。

关于数据目录，强烈建议不要和数据库容器放在同一块系统盘上。腾讯云服务器可以单独挂载数据盘，把/data挂到独立的数据盘上，这样即使系统盘故障，数据也还在。这个我在生产环境吃过亏，系统盘崩溃重装系统后，数据盘直接挂载到新系统就能恢复数据，省去了很多麻烦。

最后特别提醒一下，不要在容器里额外安装软件，比如用apt装vim、net-tools之类的工具。容器应该是不可变基础设施，想改配置就修改挂载到宿主机的配置文件然后重启，想装工具就在宿主机上装。保持容器的纯净，既有利于镜像复用，也方便后续升级迁移。

Ubuntu 24.04上Docker部署PostgreSQL完整实操记录