使用Docker Compose部署Keycloak时数据库连接失败排查求助
2026-7-2
排查Keycloak无法连接PostgreSQL数据库的问题
针对你提供的docker-compose.yml配置，从以下几个常见方向排查问题：
1. 数据库启动未就绪导致连接失败
depends_on仅保证容器启动顺序，不确保PostgreSQL服务完全初始化完成。Keycloak启动时，数据库可能还没完成启动流程，导致连接超时。
解决方式：
- 给Keycloak添加启动延迟，修改
command配置：command: - /bin/sh - -c - "sleep 10 && start-dev" - 或者使用等待工具（如
wait-for-it），待PostgreSQL端口就绪后再启动Keycloak（需自定义Keycloak镜像或在容器内安装工具）。
2. 验证Docker网络连通性
Docker Compose默认创建专属网络，服务名可直接作为域名访问，但需确认连通性：
- 单独启动数据库容器：
docker-compose up -d database - 进入Keycloak容器：
docker-compose run --rm auth /bin/bash - 在容器内执行
ping database，检查域名解析是否正常 - 尝试用psql连接：
psql -h database -U keycloak -d keycloak，输入密码password，确认是否能成功连接
若ping不通，检查Docker网络配置；若psql连接失败，排查数据库用户权限或初始化问题。
3. 检查PostgreSQL数据卷权限
你配置的/home/keycloak/postgres-data数据卷，宿主机目录权限可能不匹配PostgreSQL容器内的postgres用户（UID 999），导致数据库无法读写数据。
解决方式：
- 修改宿主机目录权限：
chown -R 999:999 /home/keycloak/postgres-data - 若目录已损坏，可删除数据卷重新初始化（注意会丢失数据）：
docker-compose down -v && docker-compose up -d database
4. 查看容器日志定位具体错误
通过日志获取更精准的报错信息：
- 查看Keycloak日志：
docker-compose logs auth，搜索Failed to obtain JDBC Connection等关键词 - 查看PostgreSQL日志：
docker-compose logs database，检查是否有密码认证失败、数据库不存在等初始化错误
5. 确认环境参数一致性
虽然你的配置中数据库与Keycloak的环境参数（用户名、密码、数据库名）已匹配，但可再次验证容器启动时的环境变量是否正确加载：
- 查看Keycloak容器环境变量：
docker-compose exec auth env | grep DB_ - 查看PostgreSQL容器环境变量：
docker-compose exec database env | grep POSTGRES_
内容的提问来源于stack exchange，提问作者Unik6065
相关产品推荐
相关产品推荐
