Bitnami Keycloak Config CLI 镜像文档

镜像概述和主要用途

Keycloak Config CLI 是一个 Keycloak 扩展工具，用于将 JSON 或 YAML 格式的配置导入到 Keycloak 服务器中，且无需重启服务器。Bitnami 提供的该镜像封装了 Keycloak Config CLI，具备轻量级、安全加固和易于部署的特点，适用于 Keycloak 配置的自动化管理场景。

核心功能和特性

Keycloak Config CLI 核心功能

• 支持 JSON/YAML 格式的 Keycloak 配置文件导入
• 无需重启 Keycloak 服务器即可应用配置变更
• 支持配置增量更新和全量覆盖策略
• 与 Keycloak 管理员 API 无缝集成

Bitnami 镜像特性

• 非 root 用户运行，增强容器安全性
• 基于轻量级操作系统（Photon Linux），减少攻击面
• 包含安全加固措施，符合生产环境最佳实践
• 提供 SBOM（软件物料清单）和漏洞扫描报告
• 支持 FIPS 模式配置（适用于安全合规场景）

使用场景和适用范围

• Keycloak 配置自动化：替代手动配置，通过代码化方式管理 Keycloak realms、客户端、角色等资源
• CI/CD 集成：在持续集成/部署流程中自动导入配置，确保环境一致性
• 多环境配置同步：在开发、测试和生产环境间同步 Keycloak 配置
• 批量配置管理：处理大规模或复杂的 Keycloak 配置场景
• 安全合规部署：通过 FIPS 模式满足金融、政务等行业的安全合规要求

使用方法和配置说明

获取镜像

推荐从 Docker Hub 拉取官方预构建镜像：

# 拉取最新版
docker pull bitnami/keycloak-config-cli:latest

# 拉取特定版本（需注意：2025年8月28日后，历史版本迁移至 bitnamilegacy 仓库）
docker pull bitnamilegacy/keycloak-config-cli:[版本号]

基本使用

最小化 Docker Run 示例

docker run --rm \
  --name keycloak-config-cli \
  -e KEYCLOAK_URL=[***] \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin-password \
  -v /path/to/configs:/configs \
  bitnami/keycloak-config-cli:latest \
  --config-files /configs

参数说明：

• KEYCLOAK_URL：Keycloak 服务器基础 URL
• KEYCLOAK_USER：Keycloak 管理员用户名
• KEYCLOAK_PASSWORD：Keycloak 管理员密码
• -v /path/to/configs:/configs：挂载本地配置文件目录到容器内
• --config-files /configs：指定配置文件路径（支持通配符，如 /configs/*.json）

详细配置

核心环境变量

FIPS 模式配置

Bitnami 安全镜像支持 FIPS 140-2 合规模式，通过以下环境变量启用：

Docker Compose 示例

version: '3.8'

services:
  keycloak:
    image: bitnami/keycloak:latest
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin-password
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"]
      interval: 10s
      timeout: 5s
      retries: 5

  config-cli:
    image: bitnami/keycloak-config-cli:latest
    depends_on:
      keycloak:
        condition: service_healthy
    environment:
      - KEYCLOAK_URL=[***]
      - KEYCLOAK_USER=admin
      - KEYCLOAK_PASSWORD=admin-password
      - IMPORT_STRATEGY=OVERWRITE
      - LOG_LEVEL=INFO
    volumes:
      - ./keycloak-configs:/configs
    command: --config-files /configs/*.json

高级配置

Keycloak Config CLI 支持丰富的命令行参数和配置选项，完整列表请参考 官方文档。常用高级参数包括：

• --fail-on-warnings：警告视为错误并退出
• --dry-run：仅验证配置，不实际执行导入
• --cache-ttl：API 响应缓存时间（秒）
• --http-proxy：设置 HTTP 代理

支持的标签

Bitnami 镜像采用以下标签策略：

• latest：最新稳定版，持续更新
• [主版本].[次版本].[补丁]：特定版本（2025年8月28日后迁移至 bitnamilegacy 仓库）
• [主版本].[次版本]：滚动更新的次要版本系列

注意：2025年8月28日后，非最新版标签将从 bitnami 仓库迁移至 bitnamilegacy 仓库，且不再接收更新。

重要通知：Bitnami 镜像目录变更

自2025年8月28日起，Bitnami 将调整其公共镜像目录策略，推出 Bitnami Secure Images 计划，主要变更包括：

• 社区用户首次可访问安全优化版容器镜像
• 逐步弃用非加固的 Debian 基础镜像，免费 tier 仅提供有限的加固镜像（仅 latest 标签，用于开发目的）
• 所有现有镜像（包括历史版本标签）将在两周内迁移至 bitnamilegacy 仓库，不再更新
• 生产环境建议采用 Bitnami Secure Images，提供加固容器、CVE 透明度（VEX/KEV）、SBOM 和企业支持

详细信息请参见 Bitnami Secure Images 公告。

为什么使用 Bitnami 安全镜像

• 安全加固：基于最小化 Photon Linux，减少攻击面，符合行业安全最佳实践
• 漏洞透明度：提供 VEX/KEV 合规报告、EPSS 风险评分和 CVE 修复时间线
• 供应链安全：SLSA-3 合规构建流程，提供签名验证、SBOM 和病毒扫描报告
• 一致性：与 Bitnami 虚拟机/云镜像使用相同的组件和配置策略，易于跨环境迁移
• 企业支持：生产环境可获取长期支持、安全更新和技术服务

非 root 容器说明

该镜像默认以非 root 用户（1001）运行，增强容器安全性。非 root 容器的优势包括：

• 限制容器内权限，降低漏洞利用风险
• 符合 Kubernetes 等编排平台的安全上下文要求
• 遵循最小权限原则，减少攻击面

如需调整用户权限，可通过 --user 参数或 Kubernetes SecurityContext 配置。

变更记录

• 2024年1月16日：移除 docker-compose.yaml 文件（该文件仅用于内部测试）

贡献与反馈

• 代码贡献：通过 bitnami/containers 仓库提交 PR
• 问题反馈：在 GitHub Issues 提交问题，建议包含环境信息、复现步骤和日志

许可证

Copyright © 2025 Broadcom. 本软件采用 Apache License 2.0 许可证。

商标声明：本软件由 Bitnami 打包，相关商标归各自公司所有，使用不暗示任何关联或背书。