PostgreSQL 启动故障排查记录
- 2026-11-20 19:37:00
- 丁国栋
- AI生成 13
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 兼容问题的临时规避。长期可以考虑:
- 使用包含兼容版
gosu的镜像,并固定镜像版本或摘要。 - 自行构建 PostgreSQL 镜像,替换
gosu版本。 - 使用
setpriv等方式替代入口脚本中的gosu用户切换。 - 不建议将
privileged: true作为 Postgres 服务的长期配置。 - 如需长期保留
MAC_OVERRIDE或apparmor=unconfined,应在升级宿主 Docker、内核或数据库镜像后重新验证是否仍需要该配置。
还没有评论,来做第一个吧!