上个月帮朋友的一个内部项目做数据库部署场景很典型一台腾讯云上的Ubuntu 24.04服务器需要用PostgreSQL存业务数据。本来想直接apt install postgresql省事但考虑到后面可能要复制环境、升级版本、甚至换服务器最后还是决定用Docker容器化部署。整套流程从系统初始化到参数调优、从踩坑到收尾大概是半天时间。这篇文章把过程完整记录下来包括每一步命令、参数选择的理由以及几个会让人卡半天的坑希望能给准备做同样部署的同学一个可靠的参考。1. 项目概述容器化部署PostgreSQL的核心思路1.1 为什么不直接用apt装PostgreSQL很多人会觉得奇怪Ubuntu的apt源里明明有postgresql包一条命令就能装好为什么非要绕一圈用Docker我最初也这么想但实际对比下来容器化的优势恰恰体现在后期运维上。第一个好处是环境隔离。PostgreSQL依赖的glibc、openssl等库版本不会和系统其他软件互相干扰Ubuntu 24.04自带的PostgreSQL版本通常偏旧而Docker官方镜像可以精确锁定你想要的版本。第二个好处是迁移便捷。裸机安装的数据库换台机器要重新配置数据目录、日志、权限容器化环境下只需要把数据卷和compose文件拷过去另一台机器上docker compose up -d就完成了迁移。当然容器化也有劣势比如性能上会有轻微损耗以及排障时多了一层容器隔离。但我在2C4G的机器上实测日常读写几乎感知不到差异。对绝大多数中小业务来说容器化带来的部署便利远远大于那点损耗这也是我最终选Docker的原因。1.2 适合哪些场景以及云服务器怎么选这套方案最适合的是业务初期、没有专职DBA、需要快速上线且可能频繁调整环境的团队。比如开发测试环境、中小型Web应用的后端数据库、数据分析项目的存储层。如果你的业务已经达到千万级日活数据库需要精细化调优建议直接上云数据库或者找专业DBA那不是我这里讨论的场景。选择PostgreSQL而不是MySQL是因为业务里有不少复杂查询和JSON字段PostgreSQL在这方面的能力更成熟。服务器配置方面我用的是腾讯云2核4G的标准型实例系统镜像选择Ubuntu 24.04 LTS系统盘50G额外挂了一块50G的数据盘。2C4G对中小业务够用但如果你读写频繁建议直接上4核8G。磁盘多说一句PostgreSQL的数据文件对磁盘IO非常敏感有条件的话数据盘选SSD。这次偷懒挂的是普通云硬盘后面导入数据时明显感觉到性能瓶颈。2. Ubuntu 24.04环境初始化与Docker安装2.1 登录服务器后的基础设置拿到腾讯云服务器后第一件事是SSH登录。如果你习惯用Windows可以直接用系统自带的ssh命令或者Termius、Tabby这类终端工具。登录之后我习惯先把系统更新一遍这个步骤在Ubuntu 24.04上是必须的sudo apt update sudo apt upgrade -y更新完顺手设置一下时区让系统时间对齐北京时间后面排查日志的时候你会感谢这个操作sudo timedatectl set-timezone Asia/Shanghai还有个容易被忽略的坑Ubuntu 24.04默认可能启用了UFWUncomplicated Firewall如果开着防火墙但没放行端口后面Docker映射出来的端口外部访问很可能被挡掉。建议先把SSH端口放行之后再按需放行其他端口sudo ufw allow 22/tcp sudo ufw enable这一步看个人偏好如果你习惯在腾讯云安全组里管理端口UFW也可以不启用。但你必须清楚端口策略到底在哪一层生效否则排查连不上数据库的问题会非常痛苦。2.2 用官方源安装DockerUbuntu的apt源里也带docker.io但版本比较旧而且不包含docker compose插件所以强烈建议用Docker官方仓库安装。在Ubuntu 24.04上安装Docker Engine的步骤如下# 安装依赖工具 sudo apt install -y ca-certificates curl gnupg # 创建keyrings目录并导入Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc # 添加Docker官方apt源注意noble对应Ubuntu 24.04 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ noble stable | sudo tee /etc/apt/sources.list.d/docker.list # 更新索引并安装 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里有个新手容易踩的坑Ubuntu 24.04的代号是noble源里写错成jammy22.04也能执行但装出来的可能是旧版本甚至找不到包。装完后检查一下源文件确认无误。安装完成后把当前用户加入docker组这样后面执行docker命令不需要每次sudo日常操作体验提升非常明显sudo usermod -aG docker $USER newgrp docker之后用docker version验证客户端和服务端版本两边都能正常输出就说明装好了。2.3 配置腾讯云内网镜像加速器Docker Hub在国内拉取镜像经常慢到怀疑人生甚至直接超时。腾讯云服务器有一个免费的内网镜像加速地址配置到Docker的daemon.json里拉镜像速度会有质的飞跃。创建/etc/docker/daemon.json{ registry-mirrors: [https://mirror.ccs.tencentyun.com] }保存后重启Dockersudo systemctl daemon-reload sudo systemctl restart docker顺手把Docker开机自启打开不然服务器重启后容器不会自动拉起来sudo systemctl enable docker这里多说一句镜像加速地址最好用你所在云厂商内网的如果你用的是其他云厂商的机器或者自建机房直接填这个地址不一定快得用各自云厂商的加速方案。另外安装包里docker-compose-plugin这个包很重要后面我们用的docker compose命令就靠它。3. 用Docker Compose编排PostgreSQL容器3.1 PostgreSQL镜像版本怎么选Docker Hub上的官方PostgreSQL镜像主要有两个tag系列postgres:16和postgres:16-alpine。alpine版本基于Alpine Linux构建镜像体积小很多内存占用也低对部署来说更轻量。但要注意alpine版本用的是musl libc而不是glibc个别扩展可能编译不了。我这次选的是postgres:16-alpine因为业务没有用到需要编译的自定义扩展选alpine可以把镜像从几百MB压缩到几十MB而且实测运行稳定。至于为什么选16而不是最新的17PostgreSQL 16在2023年9月发布到2024年已经经过多个小版本迭代稳定性和生态兼容性都更好。17虽然更新但对中小项目来说没必要追求前沿稳定第一。如果你有特殊需求比如必须用某个新特性那另说。3.2 编写docker-compose.yaml在服务器上规划一个项目目录比如/opt/postgres然后在里面放docker-compose.yaml。这是我最常用的一个基础版本services: postgres: image: postgres:16-alpine container_name: postgres16 restart: always environment: POSTGRES_USER: appuser POSTGRES_PASSWORD: YourStrongPassword POSTGRES_DB: appdb TZ: Asia/Shanghai ports: - 5432:5432 volumes: - ./data:/var/lib/postgresql/data - ./backup:/backup command: - postgres - -c - shared_buffers512MB - -c - effective_cache_size1536MB - -c - max_connections200 - -c - log_min_duration_statement1000 - -c - log_timezoneAsia/Shanghai几个关键点的说明POSTGRES_USER和POSTGRES_PASSWORD是容器首次启动时初始化数据库用的环境变量会创建一个超级用户和对应的数据库。POSTGRES_DB设置默认数据库名。密码一定要用强密码这里只是示例实际部署建议用至少20位的随机字符串。volumes里挂载了两个目录./data是PostgreSQL的数据目录必须挂载否则容器一删数据就全没了./backup是我习惯预留的备份目录方便在宿主机上直接操作备份文件。command部分传给postgres的是运行时参数这些参数会把镜像默认配置覆盖掉。示例里给的shared_buffers、effective_cache_size等值针对2C4G的机器具体怎么算我在第5节详细讲。3.3 数据持久化的底层逻辑很多第一次用Docker跑有状态服务的人都会踩一个大坑容器启动时正常读写一切看起来非常美好结果某天手一抖执行了docker rm或者升级镜像时没注意数据目录直接跟着容器一起没了。PostgreSQL容器化的关键就是数据持久化数据一定不能写在容器内部的可写层。Docker挂载数据卷有两种主流方式bind mount./data:/var/lib/postgresql/data和named volumepgdata:/var/lib/postgresql/data。bind mount的好处是数据直接存在宿主机指定目录你随时可以ls查看备份也方便named volume由Docker管理路径更隐蔽但在宿主机上直接操作文件不方便。我习惯用bind mount对数据库这种需要经常备份、排查的场景更友好。挂载目录的权限也值得提一下PostgreSQL镜像里的postgres用户UID是999如果你发现容器启动后报权限错误多半是宿主机目录权限不对。最简单的做法是sudo chown -R 999:999 /opt/postgres/data当然如果目录是新建的空目录让容器自己初始化时创建也可以但后续在宿主机上操作文件时还是要留意UID。4. 启动容器与校验连接4.1 启动与日志检查编排文件写完后第一次启动建议用up -d后台运行再配合日志观察状态cd /opt/postgres docker compose up -d docker compose logs -flogs -f看到类似下面的输出说明数据库初始化成功LOG: database system is ready to accept connections如果启动失败日志里通常会有明确原因常见的有端口被占用、挂载目录权限不对、密码环境变量不符合规范PostgreSQL要求密码不能为空等。排查顺序一般是从下往上逐行看日志先看最后几行再追到最初报错的位置。数据目录挂载这一点再说一遍如果./data目录已经存在且里面有数据PostgreSQL容器会直接复用如果目录为空容器会执行初始化流程然后创建超级用户和默认数据库用户名密码就是上面POSTGRES_USER和POSTGRES_PASSWORD里配的。这里有个隐藏细节如果数据目录已经初始化过了你再改POSTGRES_USER、POSTGRES_PASSWORD这些环境变量是不会生效的因为初始化只发生在第一次启动。这经常让一些同学困惑数据目录还在但密码怎么改都不对。4.2 在容器内验证psql连接容器正常起来后先用容器内的psql验证本地连接docker exec -it postgres16 psql -U appuser -d appdb能进入psql命令行就说明数据库本身没问题。顺手做几个最基本的检查SELECT version(); SHOW shared_buffers; SHOW max_connections;查看一下参数是否生效。如果你在宿主机上装了postgresql-client也可以直接从宿主机连接sudo apt install -y postgresql-client psql -h 127.0.0.1 -U appuser -d appdb4.3 远程连接与云安全组配置本地连接没问题很多人下一步就直接用Navicat、DBeaver等客户端从自己电脑上连。这时候最容易出问题。腾讯云服务器的端口放行有两层一层是系统内部防火墙如果有开UFW另一层是云平台的安全组。两个地方都得放行5432端口只放一个都不行。我这次就吃了这个亏UFW放行了但安全组只开了22端口结果从公网怎么都连不上排查了半天才发现问题。腾讯云控制台操作路径是云服务器实例详情 - 安全组 - 配置规则 - 入站规则 - 添加规则协议选TCP端口填5432来源按需填你的公网IP或者0.0.0.0/0不推荐全开。安全组规则修改后立即生效不需要重启机器。需要提醒的是如果数据库只给同一台机器上的应用用那根本不需要把5432端口暴露到公网只用容器网络访问就行。把数据库暴露到公网是风险最高的操作之一密码一旦泄露被暴力破解就是分分钟的事。如果业务确实需要远程访问建议来源填你的办公网IP而不是0.0.0.0/0再加一层防火墙白名单。5. PostgreSQL关键参数调优5.1 内存参数怎么算PostgreSQL安装完默认参数非常保守不太适合直接上生产这也是很多同学部署完发现性能不行的原因。调优的核心参数是shared_buffers和effective_cache_size。shared_buffers是PostgreSQL自己的共享缓存池业界通用建议设置为总内存的25%左右effective_cache_size是给查询计划器估算操作系统文件缓存用的一般设置为总内存的50%~75%。以我这台2核4G的机器为例shared_buffers4G x 25% 1G但考虑到操作系统本身也要内存而且Docker里可能不止跑PostgreSQL一个容器我实际设置的是512MB留出一部分余量。如果你确定这台机器只跑数据库可以大胆设到1G。effective_cache_size4G x 50% 2G我设置的是1536MB同样偏保守。max_connections默认100我改到200但如果应用是连接池模式几十个连接其实就够了连接数太高反而会占用更多共享内存。work_mem这个参数决定单个排序或哈希操作能用的内存默认4MB。注意它是“每次操作”分配的不是按会话分配的设置太高会导致内存爆掉。我一般保持默认除非确认某些查询频繁出现磁盘排序。修改这些参数除了在compose文件的command里传也可以进容器改postgresql.conf但容器一旦重建配置就丢了所以推荐在compose里统一管理配置这也是容器化的优势。参数生效后可以用SHOW命令确认。5.2 慢SQL日志与定位日常运维中慢SQL是最容易拖垮数据库的元凶。定位慢SQL的通用做法是开启慢查询日志。在compose的command里加一个参数- -c - log_min_duration_statement1000log_min_duration_statement1000表示执行时间超过1000毫秒1秒的语句会被记录到日志。之后查看日志docker compose logs postgres | grep duration或者直接进容器查看日志文件。日志里会看到类似这样的内容LOG: duration: 2345.123 ms statement: SELECT * FROM orders WHERE user_id 123;这时候就可以分析这条SQL是否缺少索引、是否做了全表扫描等。慢SQL日志是定位性能瓶颈的第一手资料建议从部署第一天就开启反正日志量也不大。5.3 时区、编码这些容易忽略的细节PostgreSQL因为时区问题导致日志时间和业务时间不一致这种问题通常不会立刻暴露但等你查日志的时候才发现很坑。Docker官方PostgreSQL镜像默认时区是UTC和北京时间相差8小时所以我在compose里设置了TZ: Asia/Shanghai环境变量和log_timezoneAsia/Shanghai参数。这样容器内的时间、日志时间和宿主机时间就能保持一致排查问题不用再手动换算时区。编码方面Docker官方镜像初始化数据库时会用UTF-8一般不需要额外处理。但如果你是从旧版本迁移过来的数据库数据里的编码格式可能不一致迁移验证时一定要检查特殊字符是否正常。6. 实战中的常见问题与排查心得6.1 外部连不上数据库按什么顺序排查这个问题我遇到过多次而且每次卡住的人都容易走弯路。如果你在服务器本机可以连接但从外部客户端连不上按下面顺序排查第一步检查端口是否监听。在服务器上执行ss -lntp | grep 5432如果只有127.0.0.1:5432而没有0.0.0.0:5432说明PostgreSQL只监听了回环地址。Docker的ports映射默认会监听0.0.0.0但如果手工指定过127.0.0.1:5432:5432外部当然连不上。第二步检查云安全组。登录腾讯云控制台确认入站规则放行了TCP 5432端口。第三步检查系统防火墙。如果你启用了UFW执行sudo ufw status确认5432端口已放行。第四步在外部机器上测试网络连通性。比如在你本地电脑执行telnet 服务器公网IP 5432如果连不通说明还有网络层问题如果通了但提示认证失败就进入下一个问题——认证。6.2 密码认证失败与特殊字符用psql连接时出现password authentication failed for user appuser先检查密码是不是真错了。这里有个很隐蔽的场景数据目录已经初始化过你修改compose里的POSTGRES_PASSWORD不会生效必须执行docker compose down然后删掉数据目录重新初始化或者用psql里的ALTER USER命令改密码。另一个常见问题是特殊字符被shell转义了。密码里如果包含$、、!等特殊字符用双引号包起来最稳妥比如docker exec -it postgres16 psql host127.0.0.1 userappuser passwordpss$word dbnameappdb或者用.pgpass文件。总之认证问题先分清是密码错了还是认证方式不对再针对性处理。6.3 容器重启后数据没了怎么办数据丢失通常是因为没挂数据卷或者挂载路径写错了。有时候手误把宿主机目录挂载到了容器里的/tmp或者多打了一个字符容器自然不知道数据该写到哪。遇到这种情况首先停止容器不要继续写入然后尝试数据恢复工具。但说实话容器内可写层一旦丢数据恢复成功率很低。最靠谱的办法是预防在compose文件里永远写清楚数据卷映射并且部署完成后马上验证一次。验证方法很粗暴往数据库里写一条测试数据然后docker compose down再docker compose up -d查一下数据还在不在。这一分钟的操作能避免后面好几个小时的痛苦。6.4 性能突然变差的排查思路容器化数据库性能变差先别急着怪Docker。我的排查顺序是先看宿主机资源top、free -h再看容器资源占用docker stats最后看数据库慢日志。很多时候是磁盘IO跑满了或者shared_buffers设小了导致频繁读写磁盘。PostgreSQL的pg_stat_statements视图可以看到最耗时SQL语句部署时建议加上这个扩展实际操作docker exec -it postgres16 psql -U appuser -d appdb -c CREATE EXTENSION IF NOT EXISTS pg_stat_statements;然后查询前几条最耗时的语句SELECT query, calls, total_exec_time, mean_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;这个视图的信息量非常大很多“数据库突然变卡”的问题靠它都能排除掉大部分原因。7. 备份、恢复与后续拓展7.1 定时备份方案数据库部署好之后备份是不能省的。最基础的备份方式是pg_dump逻辑备份它可以对某个库做一致性导出。我习惯把备份命令写成一个脚本再用cron定时执行。脚本大概长这样#!/bin/bash BACKUP_DIR/opt/postgres/backup DATE$(date %Y%m%d_%H%M%S) docker exec postgres16 pg_dump -U appuser -d appdb -F c -f /backup/appdb_$DATE.dump find $BACKUP_DIR -name *.dump -mtime 7 -delete这里-F c表示自定义格式/backup是容器内挂载的备份目录对应宿主机上的/opt/postgres/backup。find命令会自动清理7天前的备份文件避免磁盘被塞满。把脚本放到/etc/cron.daily/backup_postgres并赋予执行权限就能每天自动备份了。恢复的时候用pg_restore即可docker exec -i postgres16 pg_restore -U appuser -d appdb --clean /backup/appdb_xxxx.dump如果数据量不大直接用SQL格式的备份文件配合psql恢复也可以。备份这件事宁可多做不要少做我自己就经历过一次数据库文件损坏后靠备份恢复的紧急情况当时真是庆幸有自动备份。7.2 升级与迁移容器化的好处在版本升级时体现得很明显。假设要把PostgreSQL从16升级到17大致流程是先pg_dump导出数据然后改compose文件里的镜像版本重新docker compose up启动新容器最后导入数据。这个过程和裸机升级相比省去了很多环境层面的麻烦。但如果数据量很大pg_dump加pg_restore的时间会很长这时也可以考虑用pg_upgrade不过那是在容器内完成的复杂操作中小项目直接用逻辑备份迁移就够了。7.3 将容器化思维扩展到更多基础设施PostgreSQL容器化部署稳定跑起来之后你会发现这套思维可以复制到几乎所有中间件Redis、MySQL、MongoDB、Nginx、RabbitMQ都能通过类似的docker-compose编排跑起来。以后的服务器运维会越来越像“声明式管理”写好配置文件一次部署多处复用。这也是我觉得Docker很值得投入学习的地方——它不只是把某个软件跑起来那么简单更是一种把基础设施代码化的思维方式。回到开头说的那个项目这套PostgreSQL容器化方案上线到现在运行了一个多月除了中间一次磁盘告警之外没有出过问题。真要说心得最重要的是别在第一次部署时追求所谓最优参数先把服务跑通后面慢慢调。另一个是数据安全永远靠备份兜底没有备份的数据库就像没系安全带的驾驶。这套方案已经在帮我的项目稳定扛业务了希望分享出来的这些细节也能让你在自己的服务器上少折腾几个来回。
上个月帮朋友的一个内部项目做数据库部署场景很典型一台腾讯云上的Ubuntu 24.04服务器需要用PostgreSQL存业务数据。本来想直接apt install postgresql省事但考虑到后面可能要复制环境、升级版本、甚至换服务器最后还是决定用Docker容器化部署。整套流程从系统初始化到参数调优、从踩坑到收尾大概是半天时间。这篇文章把过程完整记录下来包括每一步命令、参数选择的理由以及几个会让人卡半天的坑希望能给准备做同样部署的同学一个可靠的参考。1. 项目概述容器化部署PostgreSQL的核心思路1.1 为什么不直接用apt装PostgreSQL很多人会觉得奇怪Ubuntu的apt源里明明有postgresql包一条命令就能装好为什么非要绕一圈用Docker我最初也这么想但实际对比下来容器化的优势恰恰体现在后期运维上。第一个好处是环境隔离。PostgreSQL依赖的glibc、openssl等库版本不会和系统其他软件互相干扰Ubuntu 24.04自带的PostgreSQL版本通常偏旧而Docker官方镜像可以精确锁定你想要的版本。第二个好处是迁移便捷。裸机安装的数据库换台机器要重新配置数据目录、日志、权限容器化环境下只需要把数据卷和compose文件拷过去另一台机器上docker compose up -d就完成了迁移。当然容器化也有劣势比如性能上会有轻微损耗以及排障时多了一层容器隔离。但我在2C4G的机器上实测日常读写几乎感知不到差异。对绝大多数中小业务来说容器化带来的部署便利远远大于那点损耗这也是我最终选Docker的原因。1.2 适合哪些场景以及云服务器怎么选这套方案最适合的是业务初期、没有专职DBA、需要快速上线且可能频繁调整环境的团队。比如开发测试环境、中小型Web应用的后端数据库、数据分析项目的存储层。如果你的业务已经达到千万级日活数据库需要精细化调优建议直接上云数据库或者找专业DBA那不是我这里讨论的场景。选择PostgreSQL而不是MySQL是因为业务里有不少复杂查询和JSON字段PostgreSQL在这方面的能力更成熟。服务器配置方面我用的是腾讯云2核4G的标准型实例系统镜像选择Ubuntu 24.04 LTS系统盘50G额外挂了一块50G的数据盘。2C4G对中小业务够用但如果你读写频繁建议直接上4核8G。磁盘多说一句PostgreSQL的数据文件对磁盘IO非常敏感有条件的话数据盘选SSD。这次偷懒挂的是普通云硬盘后面导入数据时明显感觉到性能瓶颈。2. Ubuntu 24.04环境初始化与Docker安装2.1 登录服务器后的基础设置拿到腾讯云服务器后第一件事是SSH登录。如果你习惯用Windows可以直接用系统自带的ssh命令或者Termius、Tabby这类终端工具。登录之后我习惯先把系统更新一遍这个步骤在Ubuntu 24.04上是必须的sudo apt update sudo apt upgrade -y更新完顺手设置一下时区让系统时间对齐北京时间后面排查日志的时候你会感谢这个操作sudo timedatectl set-timezone Asia/Shanghai还有个容易被忽略的坑Ubuntu 24.04默认可能启用了UFWUncomplicated Firewall如果开着防火墙但没放行端口后面Docker映射出来的端口外部访问很可能被挡掉。建议先把SSH端口放行之后再按需放行其他端口sudo ufw allow 22/tcp sudo ufw enable这一步看个人偏好如果你习惯在腾讯云安全组里管理端口UFW也可以不启用。但你必须清楚端口策略到底在哪一层生效否则排查连不上数据库的问题会非常痛苦。2.2 用官方源安装DockerUbuntu的apt源里也带docker.io但版本比较旧而且不包含docker compose插件所以强烈建议用Docker官方仓库安装。在Ubuntu 24.04上安装Docker Engine的步骤如下# 安装依赖工具 sudo apt install -y ca-certificates curl gnupg # 创建keyrings目录并导入Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc # 添加Docker官方apt源注意noble对应Ubuntu 24.04 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ noble stable | sudo tee /etc/apt/sources.list.d/docker.list # 更新索引并安装 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里有个新手容易踩的坑Ubuntu 24.04的代号是noble源里写错成jammy22.04也能执行但装出来的可能是旧版本甚至找不到包。装完后检查一下源文件确认无误。安装完成后把当前用户加入docker组这样后面执行docker命令不需要每次sudo日常操作体验提升非常明显sudo usermod -aG docker $USER newgrp docker之后用docker version验证客户端和服务端版本两边都能正常输出就说明装好了。2.3 配置腾讯云内网镜像加速器Docker Hub在国内拉取镜像经常慢到怀疑人生甚至直接超时。腾讯云服务器有一个免费的内网镜像加速地址配置到Docker的daemon.json里拉镜像速度会有质的飞跃。创建/etc/docker/daemon.json{ registry-mirrors: [https://mirror.ccs.tencentyun.com] }保存后重启Dockersudo systemctl daemon-reload sudo systemctl restart docker顺手把Docker开机自启打开不然服务器重启后容器不会自动拉起来sudo systemctl enable docker这里多说一句镜像加速地址最好用你所在云厂商内网的如果你用的是其他云厂商的机器或者自建机房直接填这个地址不一定快得用各自云厂商的加速方案。另外安装包里docker-compose-plugin这个包很重要后面我们用的docker compose命令就靠它。3. 用Docker Compose编排PostgreSQL容器3.1 PostgreSQL镜像版本怎么选Docker Hub上的官方PostgreSQL镜像主要有两个tag系列postgres:16和postgres:16-alpine。alpine版本基于Alpine Linux构建镜像体积小很多内存占用也低对部署来说更轻量。但要注意alpine版本用的是musl libc而不是glibc个别扩展可能编译不了。我这次选的是postgres:16-alpine因为业务没有用到需要编译的自定义扩展选alpine可以把镜像从几百MB压缩到几十MB而且实测运行稳定。至于为什么选16而不是最新的17PostgreSQL 16在2023年9月发布到2024年已经经过多个小版本迭代稳定性和生态兼容性都更好。17虽然更新但对中小项目来说没必要追求前沿稳定第一。如果你有特殊需求比如必须用某个新特性那另说。3.2 编写docker-compose.yaml在服务器上规划一个项目目录比如/opt/postgres然后在里面放docker-compose.yaml。这是我最常用的一个基础版本services: postgres: image: postgres:16-alpine container_name: postgres16 restart: always environment: POSTGRES_USER: appuser POSTGRES_PASSWORD: YourStrongPassword POSTGRES_DB: appdb TZ: Asia/Shanghai ports: - 5432:5432 volumes: - ./data:/var/lib/postgresql/data - ./backup:/backup command: - postgres - -c - shared_buffers512MB - -c - effective_cache_size1536MB - -c - max_connections200 - -c - log_min_duration_statement1000 - -c - log_timezoneAsia/Shanghai几个关键点的说明POSTGRES_USER和POSTGRES_PASSWORD是容器首次启动时初始化数据库用的环境变量会创建一个超级用户和对应的数据库。POSTGRES_DB设置默认数据库名。密码一定要用强密码这里只是示例实际部署建议用至少20位的随机字符串。volumes里挂载了两个目录./data是PostgreSQL的数据目录必须挂载否则容器一删数据就全没了./backup是我习惯预留的备份目录方便在宿主机上直接操作备份文件。command部分传给postgres的是运行时参数这些参数会把镜像默认配置覆盖掉。示例里给的shared_buffers、effective_cache_size等值针对2C4G的机器具体怎么算我在第5节详细讲。3.3 数据持久化的底层逻辑很多第一次用Docker跑有状态服务的人都会踩一个大坑容器启动时正常读写一切看起来非常美好结果某天手一抖执行了docker rm或者升级镜像时没注意数据目录直接跟着容器一起没了。PostgreSQL容器化的关键就是数据持久化数据一定不能写在容器内部的可写层。Docker挂载数据卷有两种主流方式bind mount./data:/var/lib/postgresql/data和named volumepgdata:/var/lib/postgresql/data。bind mount的好处是数据直接存在宿主机指定目录你随时可以ls查看备份也方便named volume由Docker管理路径更隐蔽但在宿主机上直接操作文件不方便。我习惯用bind mount对数据库这种需要经常备份、排查的场景更友好。挂载目录的权限也值得提一下PostgreSQL镜像里的postgres用户UID是999如果你发现容器启动后报权限错误多半是宿主机目录权限不对。最简单的做法是sudo chown -R 999:999 /opt/postgres/data当然如果目录是新建的空目录让容器自己初始化时创建也可以但后续在宿主机上操作文件时还是要留意UID。4. 启动容器与校验连接4.1 启动与日志检查编排文件写完后第一次启动建议用up -d后台运行再配合日志观察状态cd /opt/postgres docker compose up -d docker compose logs -flogs -f看到类似下面的输出说明数据库初始化成功LOG: database system is ready to accept connections如果启动失败日志里通常会有明确原因常见的有端口被占用、挂载目录权限不对、密码环境变量不符合规范PostgreSQL要求密码不能为空等。排查顺序一般是从下往上逐行看日志先看最后几行再追到最初报错的位置。数据目录挂载这一点再说一遍如果./data目录已经存在且里面有数据PostgreSQL容器会直接复用如果目录为空容器会执行初始化流程然后创建超级用户和默认数据库用户名密码就是上面POSTGRES_USER和POSTGRES_PASSWORD里配的。这里有个隐藏细节如果数据目录已经初始化过了你再改POSTGRES_USER、POSTGRES_PASSWORD这些环境变量是不会生效的因为初始化只发生在第一次启动。这经常让一些同学困惑数据目录还在但密码怎么改都不对。4.2 在容器内验证psql连接容器正常起来后先用容器内的psql验证本地连接docker exec -it postgres16 psql -U appuser -d appdb能进入psql命令行就说明数据库本身没问题。顺手做几个最基本的检查SELECT version(); SHOW shared_buffers; SHOW max_connections;查看一下参数是否生效。如果你在宿主机上装了postgresql-client也可以直接从宿主机连接sudo apt install -y postgresql-client psql -h 127.0.0.1 -U appuser -d appdb4.3 远程连接与云安全组配置本地连接没问题很多人下一步就直接用Navicat、DBeaver等客户端从自己电脑上连。这时候最容易出问题。腾讯云服务器的端口放行有两层一层是系统内部防火墙如果有开UFW另一层是云平台的安全组。两个地方都得放行5432端口只放一个都不行。我这次就吃了这个亏UFW放行了但安全组只开了22端口结果从公网怎么都连不上排查了半天才发现问题。腾讯云控制台操作路径是云服务器实例详情 - 安全组 - 配置规则 - 入站规则 - 添加规则协议选TCP端口填5432来源按需填你的公网IP或者0.0.0.0/0不推荐全开。安全组规则修改后立即生效不需要重启机器。需要提醒的是如果数据库只给同一台机器上的应用用那根本不需要把5432端口暴露到公网只用容器网络访问就行。把数据库暴露到公网是风险最高的操作之一密码一旦泄露被暴力破解就是分分钟的事。如果业务确实需要远程访问建议来源填你的办公网IP而不是0.0.0.0/0再加一层防火墙白名单。5. PostgreSQL关键参数调优5.1 内存参数怎么算PostgreSQL安装完默认参数非常保守不太适合直接上生产这也是很多同学部署完发现性能不行的原因。调优的核心参数是shared_buffers和effective_cache_size。shared_buffers是PostgreSQL自己的共享缓存池业界通用建议设置为总内存的25%左右effective_cache_size是给查询计划器估算操作系统文件缓存用的一般设置为总内存的50%~75%。以我这台2核4G的机器为例shared_buffers4G x 25% 1G但考虑到操作系统本身也要内存而且Docker里可能不止跑PostgreSQL一个容器我实际设置的是512MB留出一部分余量。如果你确定这台机器只跑数据库可以大胆设到1G。effective_cache_size4G x 50% 2G我设置的是1536MB同样偏保守。max_connections默认100我改到200但如果应用是连接池模式几十个连接其实就够了连接数太高反而会占用更多共享内存。work_mem这个参数决定单个排序或哈希操作能用的内存默认4MB。注意它是“每次操作”分配的不是按会话分配的设置太高会导致内存爆掉。我一般保持默认除非确认某些查询频繁出现磁盘排序。修改这些参数除了在compose文件的command里传也可以进容器改postgresql.conf但容器一旦重建配置就丢了所以推荐在compose里统一管理配置这也是容器化的优势。参数生效后可以用SHOW命令确认。5.2 慢SQL日志与定位日常运维中慢SQL是最容易拖垮数据库的元凶。定位慢SQL的通用做法是开启慢查询日志。在compose的command里加一个参数- -c - log_min_duration_statement1000log_min_duration_statement1000表示执行时间超过1000毫秒1秒的语句会被记录到日志。之后查看日志docker compose logs postgres | grep duration或者直接进容器查看日志文件。日志里会看到类似这样的内容LOG: duration: 2345.123 ms statement: SELECT * FROM orders WHERE user_id 123;这时候就可以分析这条SQL是否缺少索引、是否做了全表扫描等。慢SQL日志是定位性能瓶颈的第一手资料建议从部署第一天就开启反正日志量也不大。5.3 时区、编码这些容易忽略的细节PostgreSQL因为时区问题导致日志时间和业务时间不一致这种问题通常不会立刻暴露但等你查日志的时候才发现很坑。Docker官方PostgreSQL镜像默认时区是UTC和北京时间相差8小时所以我在compose里设置了TZ: Asia/Shanghai环境变量和log_timezoneAsia/Shanghai参数。这样容器内的时间、日志时间和宿主机时间就能保持一致排查问题不用再手动换算时区。编码方面Docker官方镜像初始化数据库时会用UTF-8一般不需要额外处理。但如果你是从旧版本迁移过来的数据库数据里的编码格式可能不一致迁移验证时一定要检查特殊字符是否正常。6. 实战中的常见问题与排查心得6.1 外部连不上数据库按什么顺序排查这个问题我遇到过多次而且每次卡住的人都容易走弯路。如果你在服务器本机可以连接但从外部客户端连不上按下面顺序排查第一步检查端口是否监听。在服务器上执行ss -lntp | grep 5432如果只有127.0.0.1:5432而没有0.0.0.0:5432说明PostgreSQL只监听了回环地址。Docker的ports映射默认会监听0.0.0.0但如果手工指定过127.0.0.1:5432:5432外部当然连不上。第二步检查云安全组。登录腾讯云控制台确认入站规则放行了TCP 5432端口。第三步检查系统防火墙。如果你启用了UFW执行sudo ufw status确认5432端口已放行。第四步在外部机器上测试网络连通性。比如在你本地电脑执行telnet 服务器公网IP 5432如果连不通说明还有网络层问题如果通了但提示认证失败就进入下一个问题——认证。6.2 密码认证失败与特殊字符用psql连接时出现password authentication failed for user appuser先检查密码是不是真错了。这里有个很隐蔽的场景数据目录已经初始化过你修改compose里的POSTGRES_PASSWORD不会生效必须执行docker compose down然后删掉数据目录重新初始化或者用psql里的ALTER USER命令改密码。另一个常见问题是特殊字符被shell转义了。密码里如果包含$、、!等特殊字符用双引号包起来最稳妥比如docker exec -it postgres16 psql host127.0.0.1 userappuser passwordpss$word dbnameappdb或者用.pgpass文件。总之认证问题先分清是密码错了还是认证方式不对再针对性处理。6.3 容器重启后数据没了怎么办数据丢失通常是因为没挂数据卷或者挂载路径写错了。有时候手误把宿主机目录挂载到了容器里的/tmp或者多打了一个字符容器自然不知道数据该写到哪。遇到这种情况首先停止容器不要继续写入然后尝试数据恢复工具。但说实话容器内可写层一旦丢数据恢复成功率很低。最靠谱的办法是预防在compose文件里永远写清楚数据卷映射并且部署完成后马上验证一次。验证方法很粗暴往数据库里写一条测试数据然后docker compose down再docker compose up -d查一下数据还在不在。这一分钟的操作能避免后面好几个小时的痛苦。6.4 性能突然变差的排查思路容器化数据库性能变差先别急着怪Docker。我的排查顺序是先看宿主机资源top、free -h再看容器资源占用docker stats最后看数据库慢日志。很多时候是磁盘IO跑满了或者shared_buffers设小了导致频繁读写磁盘。PostgreSQL的pg_stat_statements视图可以看到最耗时SQL语句部署时建议加上这个扩展实际操作docker exec -it postgres16 psql -U appuser -d appdb -c CREATE EXTENSION IF NOT EXISTS pg_stat_statements;然后查询前几条最耗时的语句SELECT query, calls, total_exec_time, mean_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;这个视图的信息量非常大很多“数据库突然变卡”的问题靠它都能排除掉大部分原因。7. 备份、恢复与后续拓展7.1 定时备份方案数据库部署好之后备份是不能省的。最基础的备份方式是pg_dump逻辑备份它可以对某个库做一致性导出。我习惯把备份命令写成一个脚本再用cron定时执行。脚本大概长这样#!/bin/bash BACKUP_DIR/opt/postgres/backup DATE$(date %Y%m%d_%H%M%S) docker exec postgres16 pg_dump -U appuser -d appdb -F c -f /backup/appdb_$DATE.dump find $BACKUP_DIR -name *.dump -mtime 7 -delete这里-F c表示自定义格式/backup是容器内挂载的备份目录对应宿主机上的/opt/postgres/backup。find命令会自动清理7天前的备份文件避免磁盘被塞满。把脚本放到/etc/cron.daily/backup_postgres并赋予执行权限就能每天自动备份了。恢复的时候用pg_restore即可docker exec -i postgres16 pg_restore -U appuser -d appdb --clean /backup/appdb_xxxx.dump如果数据量不大直接用SQL格式的备份文件配合psql恢复也可以。备份这件事宁可多做不要少做我自己就经历过一次数据库文件损坏后靠备份恢复的紧急情况当时真是庆幸有自动备份。7.2 升级与迁移容器化的好处在版本升级时体现得很明显。假设要把PostgreSQL从16升级到17大致流程是先pg_dump导出数据然后改compose文件里的镜像版本重新docker compose up启动新容器最后导入数据。这个过程和裸机升级相比省去了很多环境层面的麻烦。但如果数据量很大pg_dump加pg_restore的时间会很长这时也可以考虑用pg_upgrade不过那是在容器内完成的复杂操作中小项目直接用逻辑备份迁移就够了。7.3 将容器化思维扩展到更多基础设施PostgreSQL容器化部署稳定跑起来之后你会发现这套思维可以复制到几乎所有中间件Redis、MySQL、MongoDB、Nginx、RabbitMQ都能通过类似的docker-compose编排跑起来。以后的服务器运维会越来越像“声明式管理”写好配置文件一次部署多处复用。这也是我觉得Docker很值得投入学习的地方——它不只是把某个软件跑起来那么简单更是一种把基础设施代码化的思维方式。回到开头说的那个项目这套PostgreSQL容器化方案上线到现在运行了一个多月除了中间一次磁盘告警之外没有出过问题。真要说心得最重要的是别在第一次部署时追求所谓最优参数先把服务跑通后面慢慢调。另一个是数据安全永远靠备份兜底没有备份的数据库就像没系安全带的驾驶。这套方案已经在帮我的项目稳定扛业务了希望分享出来的这些细节也能让你在自己的服务器上少折腾几个来回。
