为什么选择 Keycloak？

特性 Keycloak
开箱即用 OAuth2/OIDC/SAML 全支持
单点登录 原生支持 SSO
社交登录 微信/GitHub/Google 等开箱即用
用户管理 完整的管理控制台
企业认可度 Red Hat 出品，大量企业使用

本文聚焦 Docker 环境下的 Keycloak 部署与日常运维。

一、快速部署

1. 准备数据库

Keycloak支持多种数据库，下面以MySQL数据库举例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
-- 1. 创建数据库（指定字符集为 utf8mb4，以支持 Emoji 等特殊字符）
CREATE DATABASE IF NOT EXISTS keycloak
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;


-- 2. 创建用户（如果用户已存在，会先删除再重建，请确保数据安全）
DROP USER IF EXISTS 'keycloak'@'%';
CREATE USER 'keycloak'@'%' IDENTIFIED BY 'your strong password';

-- 3. 授予该用户对 keycloak 数据库的所有权限（包含建表、删表、增删改查）
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'%';

-- 4. 刷新权限，使设置立即生效
FLUSH PRIVILEGES;

2. Docker Compose 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: unless-stopped
    command: start
    environment:
      KC_DB: mysql
      KC_DB_URL: jdbc:mysql://xxxx:3306/keycloak?characterEncoding=UTF-8
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: "前面创建的数据库密码"
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: "keycloak登录密码"
      # 允许 Keycloak 监听 HTTP
      KC_HTTP_ENABLED: "true"
      KC_HTTP_PORT: 8080
      # 信任代理传递的 X-Forwarded-* 头
      KC_PROXY_HEADERS: xforwarded
      # 根据您的实际访问地址调整（如果通过 Nginx + HTTPS，改为 https://域名:8080）
      KC_HOSTNAME: http://<IP或域名>:8080
      # 关闭域名严格检查（适用于反向代理）
      KC_HOSTNAME_STRICT: "false"
    ports:
      - "8080:8080"
    volumes:
      - keycloak_data:/opt/keycloak/data
    
volumes:
  keycloak_data:
    name: keycloak_data

3. 启动服务

1
docker compose up -d

首次启动后访问 http://服务器IP:8090 即可看到 Keycloak 欢迎页面。

二、服务端配置

1. 反向代理配置

生产环境建议使用 Nginx/Caddy 作为反向代理，启用 HTTPS：

Nginx 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
server {
    listen 443 ssl;
    server_name sso.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://<IP或域名>:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. 数据库选择

数据库 适用场景 备注
PostgreSQL 生产环境首选 性能稳定，官方推荐
MySQL 已有 MySQL 环境 需要额外配置
H2 开发测试 不推荐生产使用

三、常见问题

Q1: 访问管理控制台提示 “HTTPS required”

原因： 生产模式强制要求 HTTPS
解决：
配置反向代理启用 HTTPS或添加环境变量：

1
2
KC_HTTP_ENABLED: "true"
KC_HOSTNAME_STRICT: "false"

Q2: 登录后跳转失败

原因： 客户端回调地址配置错误
解决：

  1. 检查 Client 的 Valid redirect URIs
  2. 确保 Root URL 配置正确
  3. 检查 Web origins 是否包含应用域名

Q3: 忘记管理员密码

解决： 重置管理员密码

1
docker exec -it keycloak /opt/keycloak/bin/kc.sh bootstrap-admin-user

Q4: 社交登录配置失败

原因： 回调地址未在第三方平台配置
解决：
在微信/GitHub 等平台的回调地址中添加：

1
https://sso.yourdomain.com/realms/{realm}/broker/{provider}/endpoint

四、安全建议

建议 说明
启用 HTTPS 生产环境必须启用，可使用 Let’s Encrypt 免费证书
强密码策略 在 Realm Settings 中配置密码复杂度要求
定期更新镜像 docker pull quay.io/keycloak/keycloak:latest
保护管理员账号 使用强密码，启用双因素认证
限制管理端口 仅内网访问管理控制台，或配置 IP 白名单
定期审计日志 检查异常登录尝试
备份加密 备份文件包含敏感数据，传输和存储时加密

Keycloak 功能强大，配置相对复杂，但掌握这些基础运维技能，足以应对大多数企业认证场景。