Keycloak：开源身份与访问管理服务部署与使用指南

一、项目官方信息

Keycloak 是一个开源的身份与访问管理（Identity and Access Management）平台。官方 README 的定位是：用最少的精力为应用添加认证、为服务提供保护，你无需再自己处理存储用户、认证用户这些事情。它提供用户联合（user federation）、强认证、用户管理、细粒度授权等能力，是一个 CNCF 项目。

简单说，Keycloak 把“登录、注册、单点登录、OAuth2 / OIDC 授权、社会登录”这套能力统一收进一个服务里，你的各个业务系统只要对接 Keycloak 即可，不用各自重复造轮子。

二、官方图片

上面是 Keycloak 官方 Logo。官方 README 以文字说明为主，启动入口在 Release 与官网下载页，登录控制台后即可看到 Realm 管理、客户端、用户等图形化界面。

三、环境要求

根据官方 README，Keycloak 有两种官方运行方式：下载发行版直接运行，或使用官方 Docker 镜像。

• 发行版方式：需要 Java 17 及以上运行环境（Keycloak 基于 Quarkus，自带运行时，发行版已打包好，无需额外安装 JDK 也可直接运行）。
• Docker 方式：需要 Docker 引擎 20+；官方镜像托管在 Quay.io：quay.io/keycloak/keycloak。
• 端口：开发模式（start-dev）默认监听 HTTP 8080；生产模式启用 HTTPS 时默认 8443。
• 资源建议：内存 1GB 以上起步；生产环境建议外接 PostgreSQL 等数据库，而非使用默认的嵌入式 H2。
• 域名与证书：生产模式必须绑定域名并使用合法 HTTPS 证书（--http-enabled=false）。

四、完整部署步骤

方式 A：Docker 快速体验（开发模式）

官方 README 给出的最简启动命令是：

docker run quay.io/keycloak/keycloak start-dev

为了能登录管理控制台，通常带上管理员账号密码与端口映射：

docker run -d --name keycloak-dev \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=changeit \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:latest \
  start-dev

说明：

• KEYCLOAK_ADMIN 与 KEYCLOAK_ADMIN_PASSWORD 是首个启动时创建的初始管理员账号。
• start-dev 是开发模式：开启 HTTP、宽松安全策略，方便本地调试，官方明确不建议用于生产。
• 启动后访问 http://服务器IP:8080，/ 是账号控制台，/admin 是管理控制台。

方式 B：发行版直接运行

官方 README 原文：从官网下载发行包，解压后运行：

bin/kc.[sh|bat] start-dev

Linux/macOS 用 bin/kc.sh，Windows 用 bin/kc.bat。等价的生产启动命令为：

bin/kc.sh start-dev        # 开发模式，HTTP 8080
bin/kc.sh start --help     # 查看全部生产参数

方式 C：Docker Compose 生产部署（HTTPS + 外接数据库）

生产环境应使用 start 命令而非 start-dev，关闭明文 HTTP、绑定域名并挂载证书。下面给出一份可直接落地的 Compose 示例（含 PostgreSQL）：

docker-compose.yml：

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: unless-stopped
    command: >
      start
      --hostname=auth.example.com
      --http-enabled=false
      --https-certificate-file=/etc/x509/https/tls.crt
      --https-certificate-key-file=/etc/x509/https/tls.key
      --db=postgres
      --db-url-host=postgres
      --db-username=keycloak
      --db-password=changeit
      --proxy=edge
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=请改成强密码
      - TZ=Asia/Shanghai
    ports:
      - "8443:8443"
    volumes:
      - ./certs:/etc/x509/https:ro
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    container_name: keycloak-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=changeit
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

启动：

docker compose up -d
docker compose logs -f keycloak

参数说明：

• --hostname=auth.example.com：绑定对外域名，生产必填。
• --http-enabled=false：关闭明文 HTTP，只走 HTTPS（8443）。
• --https-certificate-file / --https-certificate-key-file：挂载 TLS 证书与私钥。
• --db=postgres 等：外接 PostgreSQL，替代默认嵌入式 H2，生产推荐。
• --proxy=edge：当 Keycloak 位于反向代理（edge）之后时使用。

验证部署

# 开发模式
curl -I http://localhost:8080
# 生产模式
curl -I https://auth.example.com:8443

浏览器打开 https://auth.example.com/admin，用 KEYCLOAK_ADMIN 与密码登录，看到管理控制台即部署成功。

五、使用方法

• 创建 Realm：默认自带 master 主 Realm，不要直接在上面建业务。在左上角下拉新建一个业务 Realm（如 myrealm），后续应用都在该 Realm 下配置。
• 创建 Client（客户端）：在 Realm 里 Clients → Create client，选择 OIDC 协议，配置回调地址（Valid redirect URIs），它就是你的应用接入点。
• 创建用户：Users → Add user，填写用户名、邮箱，再在 Credentials 标签设置密码。用户可自己在账号控制台（/）改密码、绑定二次验证。
• 对接应用：应用通过 OIDC 标准流程（Authorization Code）重定向到 Keycloak 登录页，登录成功后带回授权码换取 Token；Keycloak 官方为 Java、Node.js 等提供适配器（README 列出了 keycloak-server、keycloak-client、keycloak-quickstarts、keycloak-nodejs-connect 等子项目）。
• 社会登录：在 Realm 身份提供（Identity Providers）里可配置 Google、GitHub、OIDC、SAML 等外部 IdP。
• 用户联合：可对接已有 LDAP / Active Directory 作为用户源，这就是 README 所说的 user federation。

六、常见问题 FAQ

1. start-dev 启动后能直接用于公网吗？ 不能。start-dev 是开发模式，开启 HTTP、安全策略宽松，且使用嵌入式 H2。生产必须用 start 命令、--http-enabled=false、绑定域名与证书，并外接数据库。

2. 忘记管理员密码怎么办？ 管理员账号来自首次启动时的 KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD 环境变量。可在容器启动日志里确认，或重新设置这两个变量后重启（注意不要误删已有 Realm 数据）。

3. 访问 /admin 一直跳回登录页 / 提示 invalid token？ 常见于生产模式未正确配置 --hostname，或反向代理与实际域名不一致导致回调地址不匹配。检查 --hostname 与代理 --proxy=edge 配置。

4. 生产模式一定要外接数据库吗？ 官方推荐生产用 PostgreSQL / MySQL 等外部数据库，默认 H2 是嵌入式文件库，不适合多实例与生产持久化。

5. Docker 镜像为什么是 quay.io 而不是 Docker Hub？ 官方 README 明确给出的镜像是 quay.io/keycloak/keycloak，请以此为准，不要用第三方 Docker Hub 镜像。

6. 启动报证书 / HTTPS 相关错误？ 生产模式 --http-enabled=false 时必须同时提供合法证书与私钥，并把证书文件正确挂载进容器路径，再核对 --https-certificate-file 路径。

七、跳转链接

• GitHub 仓库：https://github.com/keycloak/keycloak
• 官方文档：https://www.keycloak.org/documentation.html
• 下载：https://www.keycloak.org/downloads.html