Keycloak 22.0.5 Docker生产部署SSL证书错误排查求助

问题背景 #

• 已完成操作：创建Docker网络keycloak-network、部署MySQL容器kc_mysql、编写Dockerfile构建自定义镜像mykeycloak
• 启动配置：挂载Let's Encrypt证书目录/etc/letsencrypt/live/abc.xyz.com到容器/etc/x509/https，配置SSL证书路径环境变量
• 错误现象：容器启动后报错ERROR: /etc/x509/https/fullchain.pem及Key material not provided to setup HTTPS，无法进入生产模式
• 权限排查：主机上root、user1、user2均可读取证书，但容器运行用户为UID 1000（对应用户user2），构建/运行容器的是user1（UID 1001）；Dockerfile中添加USER root或USER 1001未改变容器运行用户；开发模式下不使用证书可正常启动

核心原因分析 #

1. 软链接解析失败：Let's Encrypt的live目录下的证书文件是软链接，指向/etc/letsencrypt/archive/下的实际证书文件。直接挂载live目录到容器后，容器内无法解析软链接对应的主机路径，导致Keycloak无法读取真实证书内容。
2. 容器用户权限限制：Keycloak官方镜像默认以UID 1000的非root用户运行，即使挂载了目录，若主机上实际证书文件的权限未开放给容器内的UID 1000用户，也会出现读取失败；Dockerfile中的USER指令无效，是因为官方镜像的ENTRYPOINT/CMD逻辑可能覆盖了用户设置。

解决方案 #

方案1：挂载证书归档目录（推荐） #

直接挂载Let's Encrypt存储实际证书的归档目录，避免软链接问题：

1. 修改容器启动命令的挂载路径及证书路径：

docker run -v /var/lib/docker/volumes/keycloak:/opt/keycloak/conf \
  -v /etc/letsencrypt/archive/abc.xyz.com:/etc/x509/https \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/privkey1.pem \
  -e KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/fullchain1.pem \
  --name mykeycloak -p 8443:8443 -d --net keycloak-network \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  mykeycloak start --optimized

注意：privkey1.pem和fullchain1.pem中的数字需根据实际归档目录下的文件编号调整（首次生成是1，续签后会递增）

方案2：调整主机证书权限 #

开放主机上证书及目录的权限，确保容器内UID 1000用户可读取：

1. 给归档目录下的证书文件添加其他用户可读权限：

sudo chmod o+r /etc/letsencrypt/archive/abc.xyz.com/*.pem

2. 给证书目录链添加执行权限（允许用户进入目录）：

sudo chmod o+x /etc/letsencrypt /etc/letsencrypt/archive /etc/letsencrypt/archive/abc.xyz.com

3. 保持原启动命令不变，重新启动容器。

方案3：构建镜像时嵌入证书（适合固定证书场景） #

若证书不会频繁续签，可直接将证书复制到镜像内，避免挂载权限问题：

1. 修改Dockerfile，在最终镜像阶段添加证书复制逻辑：

# Use the builder image to build with the necessary configurations
FROM quay.io/keycloak/keycloak:latest as builder

ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_FEATURES=token-exchange
ENV KC_DB=mysql

WORKDIR /opt/keycloak
RUN /opt/keycloak/bin/kc.sh build --cache=ispn

# Final image
FROM quay.io/keycloak/keycloak:latest

COPY --from=builder /opt/keycloak/ /opt/keycloak/
# 复制证书到镜像内
COPY /etc/letsencrypt/live/abc.xyz.com/fullchain.pem /opt/keycloak/conf/
COPY /etc/letsencrypt/live/abc.xyz.com/privkey.pem /opt/keycloak/conf/

ENV KC_DB=mysql
ENV KC_DB_URL=jdbc:mysql://kc_mysql:3306/keycloak
ENV KC_DB_USERNAME=yyyy
ENV KC_DB_PASSWORD=xxxx
ENV KC_HOSTNAME=abc.xyz.com
# 调整证书路径为镜像内路径
ENV KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/conf/privkey.pem
ENV KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/conf/fullchain.pem

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

2. 重新构建镜像并启动：

docker build . -t mykeycloak
docker run -v /var/lib/docker/volumes/keycloak:/opt/keycloak/conf \
  --name mykeycloak -p 8443:8443 -d --net keycloak-network \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  mykeycloak start --optimized

方案4：临时以root用户运行容器（仅测试用） #

若需快速验证，可临时以root用户启动容器绕过权限限制（生产环境不推荐）：

docker run -v /var/lib/docker/volumes/keycloak:/opt/keycloak/conf \
  -v /etc/letsencrypt/live/abc.xyz.com:/etc/x509/https \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/privkey.pem \
  -e KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/fullchain.pem \
  --user root \
  --name mykeycloak -p 8443:8443 -d --net keycloak-network \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  mykeycloak start --optimized

验证步骤 #

1. 启动容器后查看日志，确认无SSL相关错误：

docker logs mykeycloak

2. 访问https://abc.xyz.com:8443验证Keycloak是否正常加载。

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