PostgreSQL 启动故障排查记录

2026-11-20 19:37:00
丁国栋
AI生成 14
摘要:PostgreSQL 启动故障排查记录

PostgreSQL 启动故障排查记录

1. 问题现象

启动项目后,postgres 容器显示为运行状态,但始终无法通过健康检查:

Up (unhealthy)
/var/run/postgresql:5432 - no response

同时观察到:

  • PostgreSQL 端口 5432 没有响应。
  • postgres 容器没有输出 PostgreSQL 启动日志。
  • db-init 服务无法开始执行。
  • zai 应用服务因依赖数据库健康状态而无法启动。
  • ./postgres_data 目录为空,数据库尚未完成初始化。

2. 初步排查

Compose 使用的数据库镜像为:

image: hub.zentao.net/third-party/pgvector/pgvector:pg16

检查容器进程后发现,容器中只有一个 gosu 进程持续占用接近 100% 的 CPU:

USER   STAT   %CPU   COMMAND
root   Rsl    99.9   gosu postgres /usr/local/bin/docker-entrypoint.sh postgres

镜像中的 gosu 版本为:

1.19 (go1.24.6 on linux/amd64)

由于 gosu 没有正常退出并把控制权交给 docker-entrypoint.sh,所以:

  • PostgreSQL 入口脚本从未真正执行。
  • PostgreSQL 没有启动并监听 5432。
  • 容器日志中不会出现 PostgreSQL 初始化或启动信息。
  • postgres_data 不会生成数据库文件。

3. 隔离验证

为排除数据库目录、密码、端口和 Compose 配置的影响,进行了以下隔离测试。

3.1 使用同一镜像单独执行 gosu

docker run --rm --network none \
  --entrypoint gosu \
  hub.zentao.net/third-party/pgvector/pgvector:pg16 \
  nobody id

结果:命令超时,说明故障与当前项目的数据目录和数据库配置无关。

3.2 验证用户切换工具

容器内使用 setpriv 和 su 切换到 postgres 用户均正常:

setpriv --reuid=999 --regid=999 --clear-groups id
su postgres -s /bin/sh -c id

说明 Linux 用户切换和文件权限本身正常,问题集中在 gosu。

3.3 关闭 seccomp

docker run --rm --network none \
  --security-opt seccomp=unconfined \
  --entrypoint gosu \
  hub.zentao.net/third-party/pgvector/pgvector:pg16 \
  nobody id

结果:仍然超时,说明原因不是 Docker seccomp。

3.4 关闭 AppArmor

docker run --rm --network none \
  --security-opt apparmor=unconfined \
  --entrypoint gosu \
  hub.zentao.net/third-party/pgvector/pgvector:pg16 \
  nobody id

结果:命令立即成功。

3.5 增加 MAC_OVERRIDE 能力

docker run --rm --network none \
  --cap-add MAC_OVERRIDE \
  --entrypoint gosu \
  hub.zentao.net/third-party/pgvector/pgvector:pg16 \
  nobody id

结果:命令立即成功。

3.6 使用 privileged

docker run --rm --network none \
  --privileged \
  --entrypoint gosu \
  hub.zentao.net/third-party/pgvector/pgvector:pg16 \
  nobody id

结果:命令成功,但 privileged 权限范围过大,不适合作为长期修复方案。

4. 根因

当前宿主启用了 AppArmor,Docker 容器默认使用 docker-default 配置。

镜像中的 gosu 1.19 在该 AppArmor 配置下会进入忙循环,无法完成用户切换,最终导致 PostgreSQL 入口脚本永远没有执行。

因此,问题本质是:

宿主 Docker AppArmor 默认配置
        +
镜像中的 gosu 1.19
        ↓
gosu 100% CPU 忙循环
        ↓
docker-entrypoint.sh 未执行
        ↓
PostgreSQL 未初始化、5432 无响应

这不是 PostgreSQL 用户名、密码、端口、数据目录或 Compose 依赖声明错误导致的。

5. 修复方案对比

5.1 cap_add: MAC_OVERRIDE

配置方式:

cap_add:
  - MAC_OVERRIDE

MAC_OVERRIDE 是 Linux capability,对应 CAP_MAC_OVERRIDE。它允许持有该能力的进程绕过 AppArmor、SELinux 等强制访问控制检查。

特点:

  • AppArmor 策略仍然加载。
  • 持有该能力的 root 进程可以绕过 MAC 检查。
  • PostgreSQL 切换为 postgres 用户后,该能力通常会随权限降级而失去。
  • 影响面相对较小。
  • 不影响 seccomp、cgroup、namespace 或普通文件权限。

适用场景:需要临时规避特定 AppArmor 兼容问题,同时尽量缩小权限变化。

5.2 security_opt: apparmor=unconfined

配置方式:

security_opt:
  - apparmor=unconfined

该配置会使容器不加载 AppArmor 策略。

特点:

  • 容器内的所有进程都不再受 AppArmor 限制。
  • 包括 gosu、PostgreSQL 以及之后通过 docker exec 启动的进程。
  • 不改变 Linux capabilities、seccomp、cgroup 和 namespace 配置。
  • 不等同于 privileged: true。
  • 权限影响面比单独增加 MAC_OVERRIDE 更大。

适用场景:需要彻底排除 AppArmor 兼容问题,或临时诊断安全策略相关故障。

5.3 两种方案对比

对比项 cap_add: MAC_OVERRIDE security_opt: apparmor=unconfined
作用对象 持有该能力的进程 容器内所有进程
AppArmor 策略 保留 完全关闭
权限范围 较窄 较宽
是否影响 seccomp 否 否
是否等同 privileged 否 否
是否影响普通文件权限 否 否
适用场景 局部绕过 MAC 限制 完整关闭 AppArmor

6. 当前采用的修复

当前在 docker-compose.yaml 的 postgres 服务中采用了权限范围较小的方案:

services:
  postgres:
    image: hub.zentao.net/third-party/pgvector/pgvector:pg16
    container_name: postgres
    cap_add:
      - MAC_OVERRIDE

重新创建容器:

docker compose up -d --force-recreate postgres
docker compose up -d

7. 修复后的验证结果

修复后服务状态如下:

postgres         Up (healthy)
db-init          Exited (0)
zai              Up

数据库验证结果:

/var/run/postgresql:5432 - accepting connections
zai_base|0.8.7

说明:

  • PostgreSQL 已完成初始化并接受连接。
  • zai_base 数据库存在。
  • vector 扩展已安装,版本为 0.8.7。
  • db-init 正常执行并退出。
  • zai 应用数据库迁移全部完成,HTTP 服务正常监听 8000 端口。

8. 长期建议

当前配置是对 gosu 1.19 与宿主 AppArmor 兼容问题的临时规避。长期可以考虑:

  1. 使用包含兼容版 gosu 的镜像,并固定镜像版本或摘要。
  2. 自行构建 PostgreSQL 镜像,替换 gosu 版本。
  3. 使用 setpriv 等方式替代入口脚本中的 gosu 用户切换。
  4. 不建议将 privileged: true 作为 Postgres 服务的长期配置。
  5. 如需长期保留 MAC_OVERRIDE 或 apparmor=unconfined,应在升级宿主 Docker、内核或数据库镜像后重新验证是否仍需要该配置。

还没有评论,来做第一个吧!

称呼
邮箱
博客分类