Keycloak Docker容器部署文档
概述
本文档描述了如何使用Docker Compose在开发环境中部署Keycloak身份认证和访问管理系统。该部署方案包含MySQL数据库和Keycloak服务两个容器,通过Docker网络进行通信。
架构说明
┌─────────────────┐ ┌─────────────────┐
│ Keycloak │ │ MySQL │
│ Container │◄───┤ Container │
│ Port: 8080 │ │ Port: 3306 │
└─────────────────┘ └─────────────────┘
│ │
└───────────────────────┘
keycloak-network
docker-compose.yml 配置
version: '3.8'
services:
# MySQL容器
mysql:
container_name: mysql
image: mysql:8.4
command: [
"--character-set-server=utf8mb4",
"--collation-server=utf8mb4_unicode_ci",
"--lower-case-table-names=1"
]
ports:
- "3306:3306"
restart: always # 可选, 跟随docker的启动而启动
volumes:
- ./db-init:/docker-entrypoint-initdb.d
- ./data:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: 123456
MYSQL_DATABASE: keycloak
TZ: Asia/Shanghai
networks:
- keycloak-network
restart: unless-stopped # 自动重启,但排除手动停止的情况(最常用)
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
timeout: 20s
retries: 10
# Keycloak容器
keycloak:
container_name: keycloak
image: quay.io/keycloak/keycloak:26.2.5-0
depends_on:
mysql:
condition: service_healthy
environment:
# 管理员账号密码
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: admin
# 数据库配置
KC_DB: mysql
KC_DB_USERNAME: root
KC_DB_PASSWORD: 123456 # 修正:应与MySQL密码一致
# 使用容器内部端口3306,而不是主机映射端口
KC_DB_URL: jdbc:mysql://mysql:3306/keycloak?useSSL=false&allowPublicKeyRetrieval=true
# Quarkus配置
KC_TRANSACTION_XA_ENABLED: "false"
# 生产环境配置
KC_HOSTNAME_STRICT: "false"
KC_HOSTNAME_STRICT_HTTPS: "false"
KC_HTTP_ENABLED: "true"
ports:
- "8080:8080" # HTTP端口
networks:
- keycloak-network
volumes:
# 确保这些目录存在
- ./keycloak/conf:/opt/keycloak/conf
- ./keycloak/themes:/opt/keycloak/themes
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
command:
- start-dev
- --hostname-strict=false # hostname-strict = false
- --http-enabled=true
networks:
keycloak-network:
driver: bridge
服务组件
1. MySQL数据库服务
MySQL作为Keycloak的数据存储后端,负责存储用户、角色、权限等相关数据。
容器配置
镜像版本:
mysql:8.4
容器名称:
mysql
端口映射:
3306:3306
(主机端口3306映射到容器端口3306)
环境变量配置
MYSQL_ROOT_PASSWORD
123456
MySQL root用户密码
MYSQL_DATABASE
keycloak
自动创建的数据库名称
TZ
Asia/Shanghai
时区设置
启动参数说明
--character-set-server=utf8mb4 # 设置字符集为utf8mb4
--collation-server=utf8mb4_unicode_ci # 设置排序规则
--lower-case-table-names=1 # 表名小写存储和比较
数据持久化
数据目录:
./data:/var/lib/mysql
- MySQL数据文件持久化初始化脚本:
./db-init:/docker-entrypoint-initdb.d
- 数据库初始化SQL脚本
初始化脚本详细说明
MySQL 自带的机制,在 ./db-init 目录中放置的所有 .sql 文件都会在首次启动时按顺序自动执行。
⚠️ 仅在首次启动时执行
# 首次启动 - 会执行初始化脚本
docker-compose up -d
# 后续启动 - 不会再执行初始化脚本
docker-compose restart
如何重新执行初始化
# 1. 停止容器
docker-compose down
# 2. 删除数据卷(重要:会丢失所有数据)
rm -rf ./data/*
# 3. 重新启动
docker-compose up -d
健康检查
检查命令:
mysqladmin ping -h localhost
超时时间: 20秒
重试次数: 10次
2. Keycloak身份认证服务
Keycloak提供完整的身份认证和访问管理解决方案。
容器配置
镜像版本:
quay.io/keycloak/keycloak:26.2.5-0
容器名称:
keycloak
端口映射:
8080:8080
依赖服务: 等待MySQL容器健康检查通过后启动
管理员配置
旧的方式已经弃用
KEYCLOAK_ADMIN
admin
管理员用户名
KEYCLOAK_ADMIN_PASSWORD
admin
管理员密码
新的方式,支持环境变量、命令行配置
KC_BOOTSTRAP_ADMIN_USERNAME
admin
管理员用户名
KC_BOOTSTRAP_ADMIN_PASSWORD
admin
管理员密码
参考:
数据库连接配置
KC_DB
mysql
数据库类型
KC_DB_USERNAME
root
数据库用户名
KC_DB_PASSWORD
123456
数据库密码
KC_DB_URL
jdbc:mysql://mysql:3306/keycloak?useSSL=false&allowPublicKeyRetrieval=true
数据库连接URL
重要说明:
数据库URL中使用容器名
mysql
和内部端口3306
禁用SSL连接 (
useSSL=false
)允许公钥检索 (
allowPublicKeyRetrieval=true
)
运行时配置
KC_TRANSACTION_XA_ENABLED
false
禁用XA事务
KC_HOSTNAME_STRICT
false
禁用严格主机名检查
KC_HOSTNAME_STRICT_HTTPS
false
禁用严格HTTPS检查
KC_HTTP_ENABLED
true
启用HTTP协议
启动命令参数
start-dev # 开发模式启动
--hostname-strict=false # 禁用主机名严格检查
--http-enabled=true # 启用HTTP协议
数据卷映射
配置目录:
./keycloak/conf:/opt/keycloak/conf
- Keycloak配置文件主题目录:
./keycloak/themes:/opt/keycloak/themes
- 自定义主题文件时间同步:
/etc/localtime:/etc/localtime:ro
- 与主机时间同步
网络配置
keycloak-network
驱动类型: bridge
作用: 为MySQL和Keycloak容器提供内部网络通信
部署前准备
1. 创建必要的目录结构
mkdir -p keycloak/conf
mkdir -p keycloak/themes
mkdir -p db-init
mkdir -p data
2. 设置目录权限
chmod -R 755 keycloak/
chmod -R 755 db-init/
chmod -R 755 data/
3. 准备初始化脚本(可选)
在db-init
目录中放置SQL初始化脚本,容器启动时会自动执行。
部署步骤
1. 启动服务
docker-compose up -d
2. 查看服务状态
docker-compose ps
docker-compose logs -f keycloak
3. 验证部署
Keycloak管理控制台: http://localhost:8080
管理员登录: 用户名
admin
,密码admin
MySQL连接: 主机
localhost
,端口3307
配置参数详解
MySQL参数优化建议
字符集配置
--character-set-server=utf8mb4
--collation-server=utf8mb4_unicode_ci
确保支持完整的Unicode字符集,包括emoji等特殊字符。
表名配置
--lower-case-table-names=1
在Linux系统中强制表名小写,避免大小写敏感问题。
Keycloak开发模式说明
开发模式 (start-dev
) 特点:
自动启用HTTP协议
禁用生产环境安全检查
支持热重载配置
简化部署流程
⚠️ 警告: 开发模式仅适用于开发和测试环境,生产环境必须使用HTTPS和严格的安全配置。
故障排除
常见问题
1. 数据库连接失败
检查MySQL容器是否正常启动
验证数据库连接参数是否正确
确认网络连通性
2. Keycloak启动失败
查看容器日志:
docker-compose logs keycloak
检查数据库健康状态
验证环境变量配置
3. 端口冲突
修改端口映射配置
检查主机端口是否被占用
日志查看
# 查看所有服务日志
docker-compose logs
# 查看特定服务日志
docker-compose logs mysql
docker-compose logs keycloak
# 实时跟踪日志
docker-compose logs -f
生产环境注意事项
安全配置
修改默认管理员密码
启用HTTPS协议
配置严格的主机名检查
数据库优化
配置数据库连接池
设置适当的缓存参数
定期备份数据
监控和日志
配置日志收集
设置健康检查监控
配置告警机制
资源限制
设置容器内存和CPU限制
配置存储容量监控
版本信息
Keycloak版本: 26.2.5-0
MySQL版本: 8.4
Docker Compose版本: 3.8
Last updated
Was this helpful?