在自动化部署里我见过最多的一类“玄学故障”就是脚本明明等到 PostgreSQL 进程起来了、端口也通了紧接着的连接请求却摔在FATAL: the database system is starting up或者更气人的直接Connection refused。问题不在于 PostgreSQL 没启动而在于我们把“进程存在”当成了“数据库就绪”。这篇实践笔记想讲清楚的只有一件事如何正确实现题面上的Check Wait For PostgreSQL To Become Ready让你的 shell 脚本、CI 服务、容器探针不再靠猜。适合正在写部署脚本、配 CI/CD、调容器化编排的同学参考。1. “启动成功”和“就绪”之间隔着一整个恢复流程1.1 postmaster 启动时到底在忙什么先回到最基础的层面。你执行pg_ctl start或者systemctl start postgresql之后前台那个进程确切地说是 postmaster并不是把共享内存准备好、端口一开就交差。它要走完一串序列读postgresql.conf、创建共享内存和信号量、拉起 logger、stats collector、walwriter、checkpointer 这些辅助进程然后才进入接受连接请求的阶段。这一步在数据目录正常关闭后再次启动时很快就过去了可一旦数据库是异常退出、或者你正在拉起一个 standby 节点那么接下来还有 WAL 重放recovery的过程。主库崩溃重启时要把 checkpoint 之后产生的 WAL 逐条重放才能把数据恢复到崩溃前的一致状态这个阶段叫 crash recovery。standby 节点更特殊它可能长期处于持续应用 WAL 的恢复模式。这两类场景里都有一个共同特征端口可能已经能建立 TCP 连接了但你真发一条SELECT过去后端会直接拒绝——典型报错就是FATAL: the database system is starting up在备库上则是FATAL: the database system is in recovery mode。所以“进程还活着”只说明 postmaster 撑过了初始化不代表存储层面已经达到可查询、可写入的一致性状态。就绪检查的本质就是在等这个“可查询”的门槛跨过去。1.2 端口穿透与认证系统就绪是两码事第二个容易混淆的点是监听端口不等于“就绪”信号它只是网络层接受连接的口子。PostgreSQL 在启动早期就会绑定并监听端口因为 accept 连接这件事本身不依赖 WAL 重放完成但连接进来之后后端进程要完成身份认证、加载配置、初始化事务环境这些能力是逐步准备好的。我见过一个非常典型的场景用 docker-compose 起 PostgreSQL健康检查只写了nc -z 127.0.0.1 5432检测到端口通就认为 ok紧接着应用启动第一次建连接池时全是FATAL: sorry, too many clients already或者the database system is starting up。端口通、进程活、数据库可查询这三个状态在时间线上跨度比很多人想象的大越是在并发连接场景里越要等最后一个。pg_ctl start -w虽然是个等待动作但它的内部实现其实是循环读postmaster.pid里的状态只要 postmaster 对外宣称“启动完成”就返回。这个“启动完成”仍然不等于“可执行事务”。所以从 wait 语义上看自己的检查脚本必须比pg_ctl -w再多走一步。1.3 等哪些指标才算等到了“就绪”我自己习惯把就绪状态分成四级从轻到重TCP 能握手说明端口被监听网络路径通。能发起连接并完成认证说明认证系统可用pg_hba.conf里的规则真的生效了。能执行最小查询SELECT 1说明后端进程能分配、事务系统可用、数据库元数据可访问。业务相关特殊检查比如主从切换场景里等它退出 recovery、可以正常写入或者反过来等它进入可读的 hot standby。这四级不是每次都全要但至少覆盖到第三级才称得上“Ready”。2. 就绪检查的两条路线pg_isready 很轻但别把轻当万能2.1 pg_isready 的真实行为一次握手就结束pg_isready是 PostgreSQL 自带的小工具源码里就是个很朴素的做法尝试建立一条到目标库的 TCP或者 Unix socket连接成功就返回然后立刻断开。它不真正做认证也不发送任何 SQL。所以它返回码 0表示“TCP 层面能够连上这个端口”仅此而已。返回码的含义值得记一下返回码含义0服务可以接受连接端口可达握手成功1服务器拒绝了连接进程活着但处于启动中/不接受新连接2无法连接服务器端口不通、进程没起来、网络问题3服务器不存在一般很少遇到多半是参数解析问题注意 0 和 1 的区别很重要。重启过程中PostgreSQL 会开始监听端口同时对进入的连接直接返回拒绝这时pg_isready返回 1 而不是 2。所以等待脚本里可以把 2 当成“还没起来”把 1 当成“正在起来”两种情况都继续循环即可但不要误以为 1 是致命错误。另外pg_isready的-t参数只控制单次连接的握手超时时间并不是整个等待循环的时长。这个细节很多人第一次写脚本时会搞混。2.2 连接探测的正确姿势用 psql 执行最小查询既然pg_isready不做认证等待脚本里更可靠的第二道保险就是用psql实际执行一条最小查询。最轻量的就是SELECT 1它要求后端进程完整度过认证和事务启动流程能返回结果就说明整个查询管道是通的。许多部署文档都只教你用pg_isready这没问题但一旦你的场景里有强制认证——比如用了 scram-sha-256、需要通过密码连接——就建议补上psql探测。两条命令组合的语义是先证明网络层的服务在再用一次真实会话证明认证和查询都可用。单独任何一条都有盲区。如果要更贴近业务可以在探测里加入SELECT pg_is_in_recovery()用来判断备库是否还在重放 WAL。如果脚本的目的是主备切换后的“数据库可写”那就等它返回f再动手。再加一步最小事务测试BEGIN; SELECT 1; ROLLBACK不写入任何脏数据却能证明当前节点可以打开事务。3. 一个可复用的等待脚本参数、边界条件和日志陷阱3.1 脚本主体不是简单 while 循环下面这版脚本是我在多个部署场景里反复用过的核心逻辑不花哨但把几个容易翻车的边界都处理了#!/usr/bin/env bash set -Eeuo pipefail PGHOST${PGHOST:-127.0.0.1} PGPORT${PGPORT:-5432} PGUSER${PGUSER:-postgres} PGDATABASE${PGDATABASE:-postgres} PGPASSWORD${PGPASSWORD:-} PG_READY_TIMEOUT${PG_READY_TIMEOUT:-60} PG_READY_INTERVAL${PG_READY_INTERVAL:-2} PG_LOG_FILE${PG_LOG_FILE:-} need_tcp_hit0 if ! command -v pg_isready /dev/null 21; then echo [wait-pg] pg_isready not found, fallback to psql only need_tcp_hit1 fi start_ts$(date %s) while true; do ok1 if [ $need_tcp_hit -eq 0 ]; then if pg_isready -h $PGHOST -p $PGPORT -U $PGUSER -d $PGDATABASE -t 2 /dev/null 21; then : else ok0 fi fi if [ $ok -eq 1 ]; then if PGPASSWORD$PGPASSWORD psql -h $PGHOST -p $PGPORT -U $PGUSER -d $PGDATABASE -v ON_ERROR_STOP0 -Atqc SELECT 1 /dev/null 21; then : else ok0 fi fi if [ $ok -eq 1 ]; then echo [wait-pg] database is ready exit 0 fi now_ts$(date %s) elapsed$((now_ts - start_ts)) if [ $elapsed -ge $PG_READY_TIMEOUT ]; then echo [wait-pg] timeout after ${PG_READY_TIMEOUT}s, database not ready 2 if [ -n $PG_LOG_FILE ] [ -f $PG_LOG_FILE ]; then tail -n 50 $PG_LOG_FILE 2 || true fi exit 1 fi printf [wait-pg] not ready yet, elapsed %ss, wait %ss\n $elapsed $PG_READY_INTERVAL sleep $PG_READY_INTERVAL done有几个地方需要解释设计意图。PGPASSWORD直接走环境变量注入是为了避免在命令行里出现明文密码被进程列表看到如果生产环境不方便用环境变量也可以改用PGPASSFILE指向~/.pgpass。PG_READY_INTERVAL独立成变量则是因为sleep 1的密集轮询表面上“反应快”实际会在日志里刷出一大堆无意义行日志系统如果又接入采集成本很冤枉我一般设 2 到 3 秒。3.2 超时与失败处理别把两秒当成两分钟捕获超时后的表现和正常循环一样重要。脚本在超时退出时会把PG_LOG_FILE最后 50 行打出来。这个设计来自我线上遇到的真实案例脚本傻等了 5 分钟没就绪最后只看到一行 timeout根本不知道背后是权限问题还是磁盘问题。把日志尾巴带上排查路径会短很多。另一个细节是set -Eeuo pipefail与pg_isready的互动。pg_isready返回非 0 时会触发 errexit所以循环里必须在 if 条件内调用或者用|| true包住。psql同理这就是为什么两处检查我都写在 if 的判断表达式里而不是先执行再查$?。还有一点如果脚本是给 CI 用的建议把PG_READY_TIMEOUT设成 90 秒而不是 30 秒。CI 宿主机第一次拉镜像、第一次初始化数据目录耗时往往比本机长得多。我见过一堆 CI 偶发失败都是超时设得太激进数据库最后其实起来了脚本却先放弃了。3.3 一个隐藏的坑Unix socket 与 -h 参数很多人在容器里敲pg_isready不带-h默认会走/var/run/postgresql下的 Unix socket。容器镜像里这个目录的权限有时候不属于 postgres 用户于是明明数据库已经准备好了检查工具却报权限不足。统一带上-h 127.0.0.1或者你自己的真实地址走 TCP 路径能避开一堆 socket 权限问题。反过来如果数据库本身只监听了 Unix socketlisten_addresses脚本里硬连127.0.0.1会一直失败。这种场景要么改配置暴露 TCP要么就让脚本走 socket。先确认数据库的listen_addresses和port设置再决定探测地址属于部署前的基本功课。4. 容器、CI/CD 和 Kubernetes 里的就绪检查实践4.1 Docker healthcheck 的正确写法官方 postgres 镜像里同时带pg_isready和psql所以 healthcheck 很方便。关键是不要只写nc或者bash /dev/tcp这类端口探测端口通了镜像里的数据库进程未必已经准备好接受连接。FROM postgres:16-alpine HEALTHCHECK --interval5s --timeout3s --start-period10s --retries12 \ CMD pg_isready -U postgres -d postgres -h 127.0.0.1 -p 5432 || exit 1--start-period是给容器里 PostgreSQL 做 initdb、跑/docker-entrypoint-initdb.d下初始化脚本的预留时间这个窗口里即使健康检查不通过也不算 unhealthy。interval和timeout设多少取决于数据目录是否在新卷上、是否要恢复 WAL新机器上第一次启动可能要 20 秒以上start-period 我建议直接给到 30 秒宁可保守也不要让编排系统过早杀掉容器。如果自定义镜像里没有pg_isready但又有完整的 psql 客户端这样写HEALTHCHECK --interval5s --timeout3s --start-period10s --retries12 \ CMD [/bin/sh, -c, psql -U postgres -h 127.0.0.1 -tc \SELECT 1\ /dev/null 21 || exit 1]4.2 CI 里等数据库服务的三种姿势GitHub Actions 里用 services 启动 PostgreSQL 时可以直接配置 healthservices: postgres: image: postgres:16-alpine env: POSTGRES_PASSWORD: test POSTGRES_DB: app ports: - 5432:5432 options: - --health-cmdpg_isready -U postgres -d app --health-interval2s --health-timeout3s --health-retries30有 health 后job 会在服务变为 healthy 之后才开始跑省掉脚本里漫长的 sleep。GitLab CI 的 services 也有类似机制通过health_check关键字配置。但有些自建 Runner 版本比较老health_check配置不完全可靠这时最稳的办法还是 job 脚本里先跑等待命令也就是第三章那个脚本把超时时间放开输出日志的关键行。我个人非常反对在 CI 里写sleep 30这种“完全靠猜”的等待。数据库启动时间在不同 runner 上差异极大空载机器上可能 8 秒就绪负载高的共享 runner 上要 60 秒。固定值 sleep 要么太短导致偶发失败要么太长浪费流水线时间用带超时的轮询脚本才可控。4.3 Kubernetes 探针的分工startupProbe 与 readinessProbe在 K8s 里判断一个 PostgreSQL Pod 是否“就绪”不应该只依赖资源层面。常见做法是在 Deployment 里同时配置startupProbe和readinessProbe前者给慢启动留窗口后者负责持续性健康检查。ports: - containerPort: 5432 startupProbe: exec: command: [/bin/sh, -c, pg_isready -U postgres -d postgres -h 127.0.0.1] failureThreshold: 24 periodSeconds: 5 timeoutSeconds: 3 readinessProbe: exec: command: [/bin/sh, -c, psql -U postgres -d postgres -h 127.0.0.1 -Atqc SELECT 1 /dev/null 21] initialDelaySeconds: 5 periodSeconds: 10 timeoutSeconds: 3 failureThreshold: 3两个探针都放在同一个 PostgreSQL 容器里用的是镜像自带的pg_isready和psql是最省事的方式。startupProbe的failureThreshold乘以periodSeconds决定了最大启动容忍时间比如 24 * 5 120 秒足够覆盖大部分慢启动场景而且不会影响后续就绪检查。readinessProbe用psql做真实查询语义上比端口握手可靠得多。如果要给 sidecar 模式或像 Patroni 这类高可用集群做探针建议把探针命令换成指向 Patroni 的 REST API或者直接查pg_is_in_recovery()再加一个只读事务测试不然主备切换过程中会出现误判。5. 排查“等了很久还没就绪”的几条实用路径5.1 端口能连但认证失败hba 规则与加密插件等待脚本在循环里卡住最常见的原因不是数据库起得慢而是认证环节失败。PostgreSQL 从 trust 到 scram-sha-256 的演进中很多部署用官方镜像时 root 用户和 postgres 用户的连接路径不一样pg_hba.conf里同一行规则可能同时命中 host 和 local顺序错了就会先命中拒绝规则。排查时不要漫无目的地试密码直接用psql带对应参数连一次看返回的具体 FATAL 行。是password authentication failed for user还是no pg_hba.conf entry for host后者通常是连接来源 IP 没匹配到任何规则需要检查pg_hba.conf里 host 行的网段写法。如果数据库要对外提供服务我建议显式写规则不要靠默认的127.0.0.1/32猜。5.2 IPv6 与 localhost 的解析陷阱机器上localhost可能同时解析到::1而 PostgreSQL 默认listen_addresses如果是*IPv6 也能监听但如果你只写了127.0.0.1脚本里-h localhost会优先尝试::1连接自然被拒。这个现象在 macOS 和部分 Linux 上特别明显。最省心的做法是探测脚本统一用明确 IP比如-h 127.0.0.1不要依赖系统/etc/hosts的解析结果。如果双栈环境下数据库监听在[::1]那就反过来用-h ::1或者配置listen_addresses包含具体地址。5.3 数据目录的问题磁盘满、所有者不对、权限不一致PostgreSQL 启动早期就要在数据目录里写postmaster.pid、打开 WAL 文件。如果磁盘空间满启动进程可能一直卡在写 WAL 阶段进程看着在、端口也半掩半掩就是永远到不了就绪。这时等待脚本再增加超时也没用必须处理存储。还有一种是数据目录被 root 创建然后以 postgres 用户启动报permission denied后进程反复重启。系统日志里会留下FATAL: data directory ... has invalid permissions之类的信息。遇到这种情况先chown -R postgres:postgres数据目录再让等待脚本继续。磁盘满这个问题在容器里尤其隐蔽因为镜像层和卷的空间判断往往不能用直觉所以要养成保留 tail 输出的习惯日志尾巴里通常直接写着disk is full或者No space left on device。5.4 首次初始化与资源限制下的慢启动首次启动是最慢的要 initdb、生成 PG_VERSION、创建系统表还要执行镜像或初始化脚本里预置的 SQL。这个过程在低配机器上可能花几十秒。如果容器的 CPU limit 给得很低或者宿主机 IO 负载高启动时间还会放大。因此在编排器里给 PostgreSQL 留足够的 startup 容忍时间比把探针 interval 调到 1 秒更有价值。资源限制还有个容易被忽视的副作用如果shared_buffers设得比实际可用内存还大启动时内存分配就可能触发 OOM进程反复被杀脚本看起来就是“永远未就绪”。这时候该做的不是延长等待而是减小shared_buffers或者给容器提高内存限制。查一下 dmesg 或容器事件里有没有 OOM Kill 的记录比盯着连接超时快得多。我个人这几年下来最大的体会是“等待就绪”看起来是个小工具函数但它背后是一整套对 PostgreSQL 启动语义的理解。你愿意在这个环节花时间设计好超时、双保险认证和日志捕获后续的自动化编排就会省心很多。如果你的部署环境还涉及流复制、Patroni 这类高可用组件强烈建议把pg_is_in_recovery()的探测也纳入等待条件那会是另一个更长的故事了。
