搬瓦工 VPS Keycloak 单点登录身份管理教程

Keycloak 是由 Red Hat 维护的开源身份和访问管理（IAM）平台，提供开箱即用的单点登录（SSO）、用户联合、身份代理和社交登录功能。它支持 OpenID Connect（OIDC）、OAuth 2.0 和 SAML 2.0 协议，可以作为所有应用的统一认证中心。本文将详细介绍如何在搬瓦工 VPS 上部署 Keycloak 并配置多应用的单点登录。

一、系统要求

内存：至少 1GB，推荐 2GB 以上（Keycloak 基于 Java，内存消耗较大）。
磁盘：至少 5GB 可用空间。
前置条件：已安装 Docker 和 Docker Compose。
域名：建议配置独立域名（如 auth.example.com）并申请 SSL 证书。

二、Docker Compose 部署

2.1 创建项目目录和配置

mkdir -p /opt/keycloak
cat > /opt/keycloak/docker-compose.yml <<'EOF'
version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: keycloak-db
    restart: always
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: KeycloakDBPass2026
    volumes:
      - pg_data:/var/lib/postgresql/data
    networks:
      - keycloak-net

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: always
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: KeycloakDBPass2026
      KC_HOSTNAME: auth.example.com
      KC_PROXY: edge
      KC_HTTP_ENABLED: "true"
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: AdminPass2026
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - keycloak-net

volumes:
  pg_data:

networks:
  keycloak-net:
EOF

2.2 启动服务

cd /opt/keycloak
docker compose up -d

# 查看启动日志
docker logs -f keycloak

三、配置 Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

nginx -t && systemctl reload nginx

四、初始配置

4.1 登录管理控制台

访问 https://auth.example.com，使用 admin 账户登录管理控制台。

4.2 创建 Realm

Realm 是 Keycloak 中的租户隔离单元。不建议在 master realm 中创建业务用户，应创建新的 Realm。在管理控制台左上角点击 master 下拉菜单，选择 Create Realm，输入名称如 myrealm。

4.3 创建客户端（Client）

每个需要接入 SSO 的应用都需要注册为一个客户端。在新创建的 Realm 下，进入 Clients 页面，点击 Create client：

Client ID：my-webapp
Client Protocol：openid-connect
Root URL：https://app.example.com
Valid Redirect URIs：https://app.example.com/*
Web Origins：https://app.example.com

4.4 创建用户

在 Users 页面点击 Add user，填写用户信息后，在 Credentials 标签页设置初始密码。

五、OIDC 集成示例

5.1 获取 OIDC 配置端点

# OIDC 发现端点
curl https://auth.example.com/realms/myrealm/.well-known/openid-configuration

5.2 与 OAuth2 Proxy 集成

配合 OAuth2 Proxy 使用 Keycloak 作为认证源：

OAUTH2_PROXY_PROVIDER=oidc
OAUTH2_PROXY_OIDC_ISSUER_URL=https://auth.example.com/realms/myrealm
OAUTH2_PROXY_CLIENT_ID=oauth2-proxy
OAUTH2_PROXY_CLIENT_SECRET=your_client_secret
OAUTH2_PROXY_EMAIL_DOMAINS=*
OAUTH2_PROXY_SCOPE="openid email profile"

六、用户联合（Federation）

6.1 集成 LDAP

如果已部署 LDAP 目录服务，可以在 Keycloak 中配置 LDAP Federation，实现用户数据同步。在 Realm Settings > User Federation 中添加 LDAP Provider，配置连接信息和同步策略。

6.2 社交登录

Keycloak 支持 GitHub、Google、微信等社交登录。在 Identity Providers 中添加对应提供商，填入 Client ID 和 Secret 即可。

七、安全加固

# 配置密码策略
# 在 Realm Settings > Authentication > Password Policy 中添加：
# - Minimum Length: 12
# - Uppercase Characters: 1
# - Lowercase Characters: 1
# - Digits: 1
# - Special Characters: 1
# - Not Username
# - Password History: 5

# 配置暴力破解防护
# 在 Realm Settings > Security Defenses > Brute Force Detection 中启用：
# - Max Login Failures: 5
# - Wait Increment: 60 seconds
# - Max Wait: 900 seconds

八、备份与恢复

# 导出 Realm 配置
docker exec keycloak /opt/keycloak/bin/kc.sh export \
  --dir /opt/keycloak/data/export \
  --realm myrealm

# 备份 PostgreSQL 数据库
docker exec keycloak-db pg_dump -U keycloak keycloak > /opt/keycloak/backup.sql

# 恢复数据库
docker exec -i keycloak-db psql -U keycloak keycloak < /opt/keycloak/backup.sql

九、性能优化

配置 JVM 内存参数：KC_JAVA_OPTS="-Xms512m -Xmx1024m"
启用数据库连接池，合理设置连接数量。
对于生产环境，建议使用外部 PostgreSQL 而非容器内数据库。
配置会话超时策略，清理过期会话以释放内存。

总结

Keycloak 是功能最完整的开源 SSO 解决方案，通过一套平台即可管理所有应用的用户认证。在搬瓦工 VPS 上部署 Keycloak 建议至少使用 2GB 内存方案。配合 OAuth2 Proxy 和 Authelia 可以为所有 Web 应用建立完整的身份安全体系。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，通过 bwh81.net 进入官网购买。