Docker部署Keycloak连接SQL Server启动失败问题求助

问题描述 #

使用Keycloak 18.0.0 Docker镜像连接SQL Server，已创建keycloak数据库，Dockerfile配置如下：

FROM quay.io/keycloak/keycloak:18.0.0 

ENV KEYCLOAK_ADMIN=admin
ENV KEYCLOAK_ADMIN_PASSWORD=admin


ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start", "--hostname-strict=false", "--auto-build", "--proxy=edge", "--db=mssql", "--db-url-host=***", "--db-username=***", "--db-password=***"]

构建运行后，数据库自动创建表，但Keycloak启动后崩溃，先出现以下错误：

违反唯一键约束'UK_CLI_SCOPE'，无法在对象'dbo.CLIENT_SCOPE'中插入重复键

修复该错误后仍报错，最终错误：

无法在开发/生产模式下启动服务器

错误原因与解决方案 #

1. 唯一键约束冲突（UK_CLI_SCOPE） #

• 原因：数据库残留了之前启动失败时的脏数据，或是手动操作过CLIENT_SCOPE表，导致初始化时插入重复的客户端范围记录。
• 解决：清空keycloak数据库的所有表，或直接删除数据库重建，确保初始化环境干净后再启动容器。

2. 无法在开发/生产模式启动 #

Keycloak 18+版本严格区分开发模式（start-dev）和生产模式（start），你的配置用了start命令但缺少生产模式必要配置：

• 生产模式必须设置加密密钥：Keycloak需要加密敏感数据（如用户密码、会话信息），生产模式下必须显式配置加密密钥，否则无法启动。
• 生产模式不建议依赖--auto-build实时初始化：应先执行build命令完成数据库初始化和配置构建，再启动服务，避免重复初始化引发冲突。
• 主机名配置问题：虽设置了--hostname-strict=false，但生产模式下建议明确指定--hostname，否则可能触发模式校验失败。

Dockerfile缺失的配置 #

你的Dockerfile需要补充以下关键配置：

1. 生产模式加密密钥：通过环境变量KC_ENCRYPTION_KEY或启动参数--encryption-key设置，密钥需至少32位字符。
2. 启用HTTP（可选）：生产模式默认只开启HTTPS，若需HTTP访问需添加KC_HTTP_ENABLED=true。
3. 拆分构建与启动流程：先执行build完成数据库初始化，再启动服务，避免重复初始化导致冲突。

修正后的Dockerfile示例：

FROM quay.io/keycloak/keycloak:18.0.0 

# 管理员账号配置
ENV KEYCLOAK_ADMIN=admin
ENV KEYCLOAK_ADMIN_PASSWORD=admin

# 数据库配置
ENV KC_DB=mssql
ENV KC_DB_URL_HOST=***
ENV KC_DB_USERNAME=***
ENV KC_DB_PASSWORD=***

# 服务配置
ENV KC_HOSTNAME_STRICT=false
ENV KC_PROXY=edge
ENV KC_HTTP_ENABLED=true
# 生产模式必填：替换为安全的加密密钥（至少32位）
ENV KC_ENCRYPTION_KEY=your-32-character-or-longer-secure-key-here

# 先执行build完成数据库初始化，再启动服务
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
CMD ["start"]

Keycloak对SQL Server的支持 #

Keycloak 18.0.0官方明确支持SQL Server作为后端数据库，镜像已内置SQL Server驱动，只要数据库配置正确即可正常使用。

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