Keycloak (PostgreSQL构建版) 镜像文档

镜像概述

本镜像基于Keycloak构建，专为PostgreSQL数据库环境优化，提供开源身份和访问管理（IAM）解决方案。Keycloak是一款功能全面的身份服务，支持单点登录（SSO）、用户认证、授权管理、OAuth 2.0/OpenID Connect等标准协议，本镜像预配置PostgreSQL支持，简化与PostgreSQL数据库的集成流程，适用于需要可靠身份管理且采用PostgreSQL作为后端数据库的场景。

核心功能与特性

Keycloak核心功能

• 身份认证：支持用户名/密码、多因素认证（MFA）、社交登录等多种认证方式。
• 授权管理：基于角色（RBAC）、属性（ABAC）的细粒度权限控制，支持资源和范围管理。
• 标准协议支持：兼容OAuth 2.0、OpenID Connect、SAML 2.0等国际安全协议。
• 用户联邦：支持与LDAP、Active Directory等用户存储系统集成，统一用户管理。
• 单点登录（SSO）：实现多应用间无缝身份切换，提升用户体验与安全性。

本镜像特有特性

• PostgreSQL优化：预配置PostgreSQL JDBC驱动，优化数据库连接池参数，确保与PostgreSQL高效协同。
• 简化部署：通过环境变量快速配置数据库连接信息，无需手动修改配置文件。
• 兼容性保障：针对PostgreSQL主流版本（12+）进行兼容性测试，确保稳定运行。

使用场景与适用范围

典型使用场景

• 企业内部系统：为ERP、CRM、OA等企业应用提供统一身份认证与权限管理。
• Web应用集成：为Java、Node.js、Python等各类Web应用提供SSO和授权服务。
• API安全防护：作为OAuth 2.0/OpenID Connect授权服务器，保护REST API接口。
• 多租户环境：通过Realm隔离实现多租户身份管理，满足SaaS平台需求。

适用范围

• 采用PostgreSQL作为数据库的企业级应用。
• 需要符合OAuth 2.0/OpenID Connect标准的身份服务场景。
• 追求开源、可定制化身份管理解决方案的团队或组织。

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 已部署PostgreSQL数据库（12+），并创建用于Keycloak的数据库及用户（需授予足够权限）。

基本部署（Docker Run）

通过docker run命令快速启动容器，需指定PostgreSQL连接信息及管理员账号：

docker run -d \
  --name keycloak-postgres \
  -p 8080:8080 \  # HTTP端口（生产环境建议搭配HTTPS代理）
  -e DB_VENDOR=postgres \  # 强制使用PostgreSQL驱动
  -e DB_ADDR=postgres-host \  # PostgreSQL服务器地址（如容器名或IP）
  -e DB_PORT=5432 \  # PostgreSQL端口（默认5432，可省略）
  -e DB_DATABASE=keycloak \  # Keycloak数据库名
  -e DB_USER=keycloak_user \  # 数据库用户名
  -e DB_PASSWORD=keycloak_pass \  # 数据库密码
  -e KEYCLOAK_USER=admin \  # Keycloak管理员用户名
  -e KEYCLOAK_PASSWORD=admin_pass \  # Keycloak管理员密码
  keycloak-postgres:latest  # 替换为实际镜像标签

启动后，访问http://<主机IP>:8080即可打开Keycloak管理控制台，使用KEYCLOAK_USER和KEYCLOAK_PASSWORD登录。

Docker Compose部署

通过docker-compose同时部署Keycloak和PostgreSQL（适合测试或开发环境）：

创建docker-compose.yml文件：

version: '3.8'

services:
  postgres:
    image: postgres:14-alpine
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak_user
      POSTGRES_PASSWORD: keycloak_pass
    volumes:
      - postgres-data:/var/lib/postgresql/data  # 持久化数据库数据
    restart: unless-stopped

  keycloak:
    image: keycloak-postgres:latest
    container_name: keycloak-postgres
    depends_on:
      - postgres  # 等待PostgreSQL启动后再启动
    environment:
      DB_VENDOR: postgres
      DB_ADDR: postgres  # 关联PostgreSQL容器名（内部DNS解析）
      DB_PORT: 5432
      DB_DATABASE: keycloak
      DB_USER: keycloak_user
      DB_PASSWORD: keycloak_pass
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin_pass
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  postgres-data:  # 定义数据卷，持久化PostgreSQL数据

执行部署命令：

docker-compose up -d

核心配置参数

生产环境注意事项

1. 启用HTTPS：通过KEYCLOAK_HTTPS_PORT并挂载SSL证书（如Let's Encrypt），或使用反向代理（Nginx/Traefik）终止HTTPS。
2. 数据持久化：通过-v挂载Keycloak配置目录（如/opt/jboss/keycloak/standalone/data），避免容器重启后数据丢失。
3. 数据库备份：定期备份PostgreSQL数据库，防止数据损坏或丢失。
4. 安全加固：
   • 使用强密码（管理员及数据库用户）。
   • 限制数据库用户权限（最小权限原则）。
   • 禁止直接暴露8080端口到公网，通过防火墙或代理控制访问。