Docker部署Keycloak连接本地SQL Server数据库问题求助

排查步骤与解决方案 #

1. 确认本地SQL Server的基础配置 #

• 启用TCP/IP协议：打开SQL Server配置管理器，找到「SQL Server网络配置」→「MSSQLSERVER的协议」，启用TCP/IP；双击TCP/IP，在「IP地址」选项卡中，确保IPAll的TCP端口为1433，且各IP地址的「已启用」设为「是」。
• 开放防火墙端口：在系统防火墙中添加入站规则，允许1433端口的TCP连接；也可临时关闭防火墙，验证是否是防火墙阻断了连接。
• 验证账号权限：确保使用的数据库账号（xxx）允许远程连接，且已映射到Keycloak数据库，拥有读写或db_owner权限。

2. 调整Docker网络配置 #

• Linux环境适配：Docker Desktop for Linux默认不支持host.docker.internal，需在docker-compose中添加extra_hosts：

  services:
    keycloak:
      image: quay.io/keycloak/keycloak:latest
      environment:
        KC_DB: mssql
        KC_DB_URL: jdbc:sqlserver://host.docker.internal:1433;databaseName=Keycloak;encrypt=false;trustServerCertificate=true;loginTimeout=30
        KC_DB_USERNAME: xxx
        KC_DB_PASSWORD: yyy
        KEYCLOAK_ADMIN: admin
        KEYCLOAK_ADMIN_PASSWORD: admin
      ports:
        - "4000:8080"
      extra_hosts:
        - "host.docker.internal:host-gateway"
      command:
        - start-dev
      restart: always
  

• 使用宿主机实际IP：直接替换host.docker.internal为本机局域网IP（如192.168.1.100），规避域名解析问题：

  KC_DB_URL: jdbc:sqlserver://192.168.1.100:1433;databaseName=Keycloak;encrypt=false;trustServerCertificate=true;loginTimeout=30
  

• network_mode: host注意事项：使用该模式时，容器共享宿主机网络，连接字符串需用localhost或127.0.0.1，但必须确保SQL Server监听0.0.0.0（允许所有IP访问），而非仅localhost。

3. 测试容器与SQL Server的连通性 #

进入Keycloak容器，验证端口连通性：

# 进入容器
docker exec -it <你的Keycloak容器ID> bash

# 安装telnet（容器无此工具时执行）
microdnf install telnet

# 测试1433端口
telnet host.docker.internal 1433

若连接失败，说明存在网络层面障碍（防火墙、SQL Server未监听端口等）；若连接成功，再排查SQL Server账号与数据库权限问题。

4. 调整连接字符串参数 #

若SQL Server强制加密，需修改参数为encrypt=true，并保留trustServerCertificate=true（仅测试环境使用，生产环境建议配置合法证书）：

KC_DB_URL: jdbc:sqlserver://host.docker.internal:1433;databaseName=Keycloak;encrypt=true;trustServerCertificate=true;loginTimeout=30

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