配置数据库

关于如何配置关系型数据库的概述

本指南解释了如何配置 Keycloak 服务器以将数据存储在关系型数据库中。

支持的数据库

服务器内置了对不同数据库的支持。您可以通过查看 db 配置选项的预期值来查询可用的数据库。下表列出了支持的数据库及其经过测试的版本。

数据库 选项值 测试版本

MariaDB 服务器

mariadb

11.4

Microsoft SQL Server

mssql

2022

MySQL

mysql

8.4

Oracle 数据库

oracle

23.5

PostgreSQL

postgres

17

Amazon Aurora PostgreSQL

postgres

16.1

默认情况下，服务器使用 dev-file 数据库。这是服务器将用于持久化数据的默认数据库，仅用于开发用例。dev-file 数据库不适用于生产用例，并且在部署到生产环境之前必须替换。

安装数据库驱动程序

数据库驱动程序作为 Keycloak 的一部分发布，但 Oracle 数据库驱动程序除外。

如果您想连接到此数据库，请手动安装必要的缺失驱动程序，或者如果您想连接到已包含数据库驱动程序的其他数据库，请跳过此部分。

安装 Oracle 数据库驱动程序

要为 Keycloak 安装 Oracle 数据库驱动程序

  1. 从以下来源之一下载 ojdbc17 和 orai18n JAR 文件

    1. 压缩的 JDBC 驱动程序和 Companion Jars 版本 23.6.0.24.10，来自 Oracle 驱动程序下载页面。

    2. Maven Central，通过 ojdbc17 和 orai18n。

    3. 数据库供应商为特定使用的数据库推荐的安装介质。

  2. 当运行解压缩的分发包时：将 ojdbc17 和 orai18n JAR 文件放在 Keycloak 的 providers 文件夹中

  3. 当运行容器时：构建自定义 Keycloak 镜像，并将 JAR 文件添加到 providers 文件夹中。当为 Operator 构建自定义镜像时，这些镜像需要是优化的镜像，并设置了 Keycloak 的所有构建时选项。

    一个最小的 Containerfile，用于构建可与 Keycloak Operator 一起使用的镜像，并包含从 Maven Central 下载的 Oracle 数据库 JDBC 驱动程序，如下所示

    FROM quay.io/keycloak/keycloak:latest
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc17/23.6.0.24.10/ojdbc17-23.6.0.24.10.jar /opt/keycloak/providers/ojdbc17.jar
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.6.0.24.10/orai18n-23.6.0.24.10.jar /opt/keycloak/providers/orai18n.jar
# Setting the build parameter for the database:
ENV KC_DB=oracle
# Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Keycloak Operator, it needs to be optimized, which requires Keycloak's build step:
RUN /opt/keycloak/bin/kc.sh build

    有关如何构建优化镜像的详细信息，请参阅在容器中运行 Keycloak 指南。

然后继续配置数据库，如下一节所述。

配置数据库

对于每个支持的数据库，服务器都提供了一些预设的默认值，以简化数据库配置。您可以通过提供一些关键设置（例如数据库主机和凭据）来完成配置。

配置可以在 build 命令或 start 命令期间设置

  1. 使用 build 命令，后跟优化的 start 命令（推荐）

    首先，连接到数据库所需的最小设置可以在 conf/keycloak.conf 中指定

    # The database vendor.
db=postgres

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=change_me

# Sets the hostname of the default JDBC URL of the chosen vendor
db-url-host=keycloak-postgres

    然后，以下命令基于配置选项创建新的优化服务器镜像并启动服务器。

    bin/kc.[sh|bat] build
bin/kc.[sh|bat] start --optimized

  2. 仅使用 start 命令（不带 --optimized）

    bin/kc.[sh|bat] start --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me
上面的示例包括连接到数据库所需的最小设置，但它暴露了数据库密码，因此不推荐使用。至少对于密码，请使用上面显示的 conf/keycloak.conf、环境变量或密钥库。

默认模式是 keycloak，但您可以使用 db-schema 配置选项更改它。

也可以在 导入和导出 Realm 或 管理员引导和恢复 时配置数据库

bin/kc.[sh|bat] import --help
bin/kc.[sh|bat] export --help
bin/kc.[sh|bat] bootstrap-admin --help

有关更多信息，请参阅 配置 Keycloak。

覆盖默认连接设置

服务器使用 JDBC 作为底层技术与数据库通信。如果默认连接设置不足，您可以使用 db-url 配置选项指定 JDBC URL。

以下是 PostgreSQL 数据库的示例命令。

bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase

请注意，当调用包含特殊 shell 字符（例如 ;）的命令时，您需要转义字符，因此您可能希望在配置文件中设置它。

覆盖默认 JDBC 驱动程序

服务器根据您选择的数据库使用默认的 JDBC 驱动程序。

要设置不同的驱动程序，您可以将 db-driver 设置为 JDBC 驱动程序的完全限定类名

bin/kc.[sh|bat] start --db postgres --db-driver=my.Driver

无论您设置什么驱动程序，默认驱动程序始终在运行时可用。

仅在您真正需要时才设置此属性。例如，当利用特定云数据库服务的 JDBC 驱动程序包装器的功能时。

配置数据库的 Unicode 支持

所有字段的 Unicode 支持取决于数据库是否允许 VARCHAR 和 CHAR 字段使用 Unicode 字符集。

  • 如果可以设置这些字段，则 Unicode 很可能可以工作，通常会以字段长度为代价。

  • 如果数据库仅在 NVARCHAR 和 NCHAR 字段中支持 Unicode，则所有文本字段的 Unicode 支持不太可能工作，因为服务器模式广泛使用 VARCHAR 和 CHAR 字段。

数据库模式仅为以下特殊字段提供 Unicode 字符串支持

  • Realm：显示名称、HTML 显示名称、本地化文本（键和值）

  • 联合提供程序：显示名称

  • 用户：用户名、名字、姓氏、属性名称和值

  • 组：名称、属性名称和值

  • 角色：名称

  • 对象的描述

否则，字符仅限于数据库编码中包含的字符，通常是 8 位。但是，对于某些数据库系统，您可以启用 Unicode 字符的 UTF-8 编码，并在所有文本字段中使用完整的 Unicode 字符集。对于给定的数据库，这种选择可能会导致最大字符串长度比 8 位编码支持的最大字符串长度更短。

配置 Oracle 数据库的 Unicode 支持

如果 Oracle 数据库在创建时在 VARCHAR 和 CHAR 字段中启用了 Unicode 支持，则该数据库支持 Unicode 字符。例如，您将 AL32UTF8 配置为数据库字符集。在这种情况下，JDBC 驱动程序不需要特殊设置。

如果数据库在创建时未启用 Unicode 支持，则需要配置 JDBC 驱动程序以支持特殊字段中的 Unicode 字符。您可以配置两个属性。请注意，您可以将这些属性配置为系统属性或连接属性。

  1. 将 oracle.jdbc.defaultNChar 设置为 true。

  2. 可选地，将 oracle.jdbc.convertNcharLiterals 设置为 true。

    有关这些属性和任何性能影响的详细信息，请参阅 Oracle JDBC 驱动程序配置文档。

Microsoft SQL Server 数据库的 Unicode 支持

对于 Microsoft SQL Server 数据库，Unicode 字符仅在特殊字段中受支持。数据库不需要特殊设置。

应将 JDBC 驱动程序的 sendStringParametersAsUnicode 属性设置为 false，以显着提高性能。如果没有此参数，Microsoft SQL Server 可能无法使用索引。

配置 MySQL 数据库的 Unicode 支持

如果 MySQL 数据库在使用 CREATE DATABASE 命令创建时在 VARCHAR 和 CHAR 字段中启用了 Unicode 支持，则该数据库支持 Unicode 字符。

请注意，由于 utf8 字符集的存储要求不同，因此不支持 utf8mb4 字符集。有关详细信息，请参阅 MySQL 文档。在这种情况下，非特殊字段的长度限制不适用，因为列的创建是为了容纳字符数，而不是字节数。如果数据库默认字符集不允许 Unicode 存储，则只有特殊字段允许存储 Unicode 值。

  1. 启动 MySQL 服务器。

  2. 在 JDBC 驱动程序设置下，找到JDBC 连接设置。

  3. 添加此连接属性：characterEncoding=UTF-8

配置 PostgreSQL 数据库的 Unicode 支持

当 PostgreSQL 数据库字符集为 UTF8 时，PostgreSQL 数据库支持 Unicode。Unicode 字符可以在任何字段中使用，而不会减少非特殊字段的字段长度。JDBC 驱动程序不需要特殊设置。字符集在创建 PostgreSQL 数据库时确定。

  1. 通过输入以下 SQL 命令来检查 PostgreSQL 集群的默认字符集。

    show server_encoding;

  2. 如果默认字符集不是 UTF 8，请使用诸如以下命令创建以 UTF8 作为默认字符集的数据库

    create database keycloak with encoding 'UTF8';

为 Amazon Aurora PostgreSQL 准备

当使用 Amazon Aurora PostgreSQL 时，Amazon Web Services JDBC Driver 提供了额外的功能，例如在 Multi-AZ 设置中写入器实例更改时传输数据库连接。此驱动程序不包含在发行版中，需要先安装才能使用。

要安装此驱动程序，请应用以下步骤

  1. 当运行解压缩的分发包时：从 Amazon Web Services JDBC Driver 发布页面 下载 JAR 文件，并将其放在 Keycloak 的 providers 文件夹中。

  2. 当运行容器时：构建自定义 Keycloak 镜像，并将 JAR 文件添加到 providers 文件夹中。

    一个最小的 Containerfile，用于构建可与 Keycloak Operator 一起使用的镜像，如下所示

    FROM quay.io/keycloak/keycloak:latest
ADD --chmod=0666 https://github.com/awslabs/aws-advanced-jdbc-wrapper/releases/download/2.3.1/aws-advanced-jdbc-wrapper-2.3.1.jar /opt/keycloak/providers/aws-advanced-jdbc-wrapper.jar

    有关如何构建优化镜像的详细信息，请参阅在容器中运行 Keycloak 指南，以及 使用自定义 Keycloak 镜像 指南，了解如何使用 Keycloak Operator 运行优化和非优化镜像。

  3. 配置 Keycloak 以使用以下参数运行

    db-url

    将 aws-wrapper 插入到常规 PostgreSQL JDBC URL 中，从而生成类似 jdbc:aws-wrapper:postgresql://... 的 URL。

    db-driver

    设置为 software.amazon.jdbc.Driver 以使用 AWS JDBC 包装器。

为 MySQL 服务器准备

从 MySQL 8.0.30 开始，MySQL 支持为任何在创建时没有显式主键的 InnoDB 表生成隐式主键（更多信息请参见 此处）。如果启用此功能，数据库模式初始化和迁移将失败，并显示错误消息 Multiple primary key defined (1068)。然后，您需要在安装或升级 Keycloak 之前，通过在 MySQL 服务器配置中将参数 sql_generate_invisible_primary_key 设置为 OFF 来禁用它。

在集群配置中更改数据库锁定超时

由于集群节点可以并发启动，因此它们需要额外的时间来执行数据库操作。例如，启动的服务器实例可能会执行一些数据库迁移、导入或首次初始化。当集群节点并发启动时，数据库锁可防止启动操作相互冲突。

此锁的最大超时时间为 900 秒。如果节点等待此锁的时间超过超时时间，则启动失败。更改默认值的需求不太可能出现，但您可以通过输入以下命令来更改它

bin/kc.[sh|bat] start --spi-dblock-jpa-lock-wait-timeout 900

使用支持 XA 事务的数据库供应商

默认情况下，Keycloak 使用非 XA 事务和适当的数据库驱动程序。

如果您希望使用您的驱动程序提供的 XA 事务支持，请输入以下命令

bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=true

Keycloak 会自动为您的供应商选择合适的 JDBC 驱动程序。

某些供应商（例如 Azure SQL 和 MariaDB Galera）不支持或依赖 XA 事务机制。

XA 恢复默认情况下已启用，并将使用文件系统位置 KEYCLOAK_HOME/data/transaction-logs 来存储事务日志。

除非在该路径下有稳定的存储可用，否则在容器化环境中启用 XA 事务并不能完全支持 XA 恢复。

为 migrationStrategy 设置 JPA 提供程序配置选项

要设置 JPA migrationStrategy（manual/update/validate），您应该按如下方式设置 JPA 提供程序

为 connections-jpa SPI 的 quarkus 提供程序设置 migration-strategy
bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

如果您还想获取用于数据库初始化的 SQL 文件，则必须添加此额外的 SPI initializeEmpty (true/false)

为 connections-jpa SPI 的 quarkus 提供程序设置 initialize-empty
bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-initialize-empty=false

以相同的方式，migrationExport 指向特定的文件和位置

为 connections-jpa SPI 的 quarkus 提供程序设置 migration-export
bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

有关更多信息，请查看 迁移数据库 文档。

相关选项

值

db

数据库供应商。

在生产模式下，dev-file 的默认值已弃用，您应该显式指定数据库。

CLI: --db
Env: KC_DB

dev-file (默认), dev-mem, mariadb, mssql, mysql, oracle, postgres

db-driver

JDBC 驱动程序的完全限定类名。

如果未设置，则会根据所选数据库设置默认驱动程序。

CLI: --db-driver
Env: KC_DB_DRIVER

db-password

数据库用户的密码。

CLI: --db-password
Env: KC_DB_PASSWORD

db-pool-initial-size

连接池的初始大小。

CLI: --db-pool-initial-size
Env: KC_DB_POOL_INITIAL_SIZE

db-pool-max-size

连接池的最大大小。

CLI: --db-pool-max-size
Env: KC_DB_POOL_MAX_SIZE

100 (默认)

db-pool-min-size

连接池的最小大小。

CLI: --db-pool-min-size
Env: KC_DB_POOL_MIN_SIZE

db-schema

要使用的数据库模式。

CLI: --db-schema
Env: KC_DB_SCHEMA

db-url

完整的数据库 JDBC URL。

如果未提供，则会根据所选数据库供应商设置默认 URL。例如，如果使用 postgres，则默认 JDBC URL 将为 jdbc:postgresql://127.0.0.1/keycloak。

CLI: --db-url
Env: KC_DB_URL

db-url-database

设置所选供应商的默认 JDBC URL 的数据库名称。

如果设置了 db-url 选项，则忽略此选项。

CLI: --db-url-database
Env: KC_DB_URL_DATABASE

db-url-host

设置所选供应商的默认 JDBC URL 的主机名。

如果设置了 db-url 选项，则忽略此选项。

CLI: --db-url-host
Env: KC_DB_URL_HOST

db-url-port

设置所选供应商的默认 JDBC URL 的端口。

如果设置了 db-url 选项，则忽略此选项。

CLI: --db-url-port
Env: KC_DB_URL_PORT

db-url-properties

设置所选供应商的默认 JDBC URL 的属性。

确保根据数据库供应商期望的格式设置属性，并在该属性值的开头附加正确的字符。如果设置了 db-url 选项，则忽略此选项。

CLI: --db-url-properties
Env: KC_DB_URL_PROPERTIES

db-username

数据库用户的用户名。

CLI: --db-username
Env: KC_DB_USERNAME

transaction-xa-enabled

如果设置为 true，将使用 XA 数据源。

CLI: --transaction-xa-enabled
Env: KC_TRANSACTION_XA_ENABLED

true, false (默认)
在此页上
编辑本指南