JBoss Keycloak Docker容器无法启动，访问返回ERR_EMPTY_RESPONSE

AI 小北

2026-7-11

解决Docker Compose部署JBoss Keycloak启动后立即停止的问题

1. 检查容器资源限制

Keycloak启动需要足够内存，默认Docker资源限制可能导致OOM退出：

在docker-compose.yml中给Keycloak容器分配内存：

keycloak:
  image: jboss/keycloak:15.0.2 # 替换为你使用的版本
  environment:
    - DB_VENDOR=POSTGRES
    - DB_ADDR=postgres
    - DB_DATABASE=keycloak
    - DB_USER=keycloak
    - DB_PASSWORD=password
    - KEYCLOAK_USER=admin
    - KEYCLOAK_PASSWORD=admin
  deploy:
    resources:
      limits:
        memory: 2G
      reservations:
        memory: 1G
  depends_on:
    - postgres

或直接指定JVM参数：

environment:
  - JAVA_OPTS=-Xmx1024m -Xms512m

2. 验证数据库连接配置

即使数据库可通信，也可能因权限、版本或结构问题导致Keycloak初始化失败：

确保PostgreSQL用户keycloak拥有keycloak数据库的全部权限（含建表、序列操作）。
确认PostgreSQL版本与Keycloak兼容（JBoss Keycloak 15+建议PostgreSQL 10+）。
清空并重建keycloak数据库，避免残留损坏的表结构。

3. 查看完整启动日志

表面日志可能遗漏关键错误，执行以下命令获取完整日志：

docker logs -f <keycloak_container_id>

重点排查关键词：ERROR（数据库连接、权限问题）、OutOfMemoryError（内存不足）、Failed to start（启动失败具体原因）。

4. 检查端口与网络配置

确认端口映射未被占用：
```
ports:
  - "8080:8080"
```
用netstat -tulpn | grep 8080检查端口占用，若冲突可修改映射为8081:8080。

添加数据库就绪等待逻辑：depends_on仅保证启动顺序，需用脚本等待数据库完全可用：

keycloak:
  image: jboss/keycloak:15.0.2
  command: ["/wait-for-it.sh", "postgres:5432", "--", "/opt/jboss/tools/docker-entrypoint.sh"]
  volumes:
    - ./wait-for-it.sh:/wait-for-it.sh
  # 其他配置...