生产环境启动Keycloak报错求助：未提供HTTPS密钥材料

错误提示明确指出生产模式下未提供HTTPS密钥材料，核心问题是Keycloak 17+版本（Quarkus重构后）使用KC_前缀的环境变量，而非旧版的KEYCLOAK_，同时需确保证书文件可被容器内进程读取。

具体修复步骤 #

1. 修正HTTPS相关环境变量名称 #

将docker-compose中KEYCLOAK_HTTPS_*开头的变量替换为KC_HTTPS_*，这是Quarkus版Keycloak的标准配置前缀：

• KEYCLOAK_HTTPS_CERTIFICATE_FILE → KC_HTTPS_CERTIFICATE_FILE
• KEYCLOAK_HTTPS_CERTIFICATE_KEY_FILE → KC_HTTPS_CERTIFICATE_KEY_FILE

2. 替换JVM参数环境变量 #

KEYCLOAK_EXTRA_ARGS已被新版本弃用，改用KC_OPTS传递JVM参数：

• KEYCLOAK_EXTRA_ARGS: "-Dkeycloak.profile.feature.scripts=enabled" → KC_OPTS: "-Dkeycloak.profile.feature.scripts=enabled"

3. 确保证书文件权限正常 #

容器内运行Keycloak的用户是keycloak（UID 1000），需保证本地证书文件具备可读权限：

chmod 644 ./etc/letsencrypt/live/auth.mycompany.com/fullchain.pem
chmod 644 ./etc/letsencrypt/live/auth.mycompany.com/privkey.pem

如果服务器开启了SELinux，挂载卷时需添加:z标签以修复上下文权限：

volumes:
  - ./etc/letsencrypt/live/auth.mycompany.com/fullchain.pem:/opt/keycloak/certs/fullchain.pem:z
  - ./etc/letsencrypt/live/auth.mycompany.com/privkey.pem:/opt/keycloak/certs/privkey.pem:z

修改后的完整docker-compose配置片段 #

keycloak:
  image: quay.io/keycloak/keycloak:22.0.5
  command:
    - start --transaction-xa-enabled=false
  environment:
    KC_DB_URL: jdbc:postgresql://db:5432/keycloak
    KC_DB_URL_HOST: db
    KC_DB: postgres
    KC_DB_USERNAME: postgres
    KC_DB_PASSWORD: postgres
    KC_HEALTH_ENABLED: "true"
    KC_METRICS_ENABLED: "true"
    KC_HOSTNAME: auth.mycompany.com
    KEYCLOAK_ADMIN: admin
    KEYCLOAK_ADMIN_PASSWORD: admin
    KEYCLOAK_JDBC_PARAMS: sslmode=enable&connectTimeout=40000
    KC_OPTS: "-Dkeycloak.profile.feature.scripts=enabled"
    KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/certs/fullchain.pem
    KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/certs/privkey.pem
  ports:
    - 8443:8443
  depends_on:
    - db
  volumes:
    - ./etc/letsencrypt/live/auth.mycompany.com/fullchain.pem:/opt/keycloak/certs/fullchain.pem:z
    - ./etc/letsencrypt/live/auth.mycompany.com/privkey.pem:/opt/keycloak/certs/privkey.pem:z
  networks:
    - local-keycloak

验证要点 #

• 确认本地证书路径正确，文件未损坏
• 启动容器后查看日志，若仍有权限错误，可临时添加user: root指令测试（生产环境不建议长期使用），排查是否为权限问题

内容的提问来源于stack exchange，提问作者Pranav