配置数据库

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

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

支持的数据库

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

数据库 选项值 测试版本

MariaDB 服务器

mariadb

10.11

Microsoft SQL Server

mssql

2022

MySQL

mysql

8.0

Oracle 数据库

oracle

19.3

PostgreSQL

postgres

16

Amazon Aurora PostgreSQL

postgres

16.1

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

安装数据库驱动程序

除 Oracle 数据库驱动程序外，数据库驱动程序作为 Keycloak 的一部分提供。

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

安装 Oracle 数据库驱动程序

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

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

    1. 压缩的 JDBC 驱动程序和配套 JAR 文件 版本 23.5.0.24.07 来自 Oracle 驱动程序下载页面。

    2. 通过 ojdbc11 和 orai18n 的 Maven Central。

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

  2. 在运行解压缩的发布版时：将 ojdbc11 和 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/ojdbc11/23.5.0.24.07/ojdbc11-23.5.0.24.07.jar /opt/keycloak/providers/ojdbc11.jar
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.5.0.24.07/orai18n-23.5.0.24.07.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 指南。

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

配置数据库

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

  1. 启动服务器并设置基本选项以配置数据库

    bin/kc.[sh|bat] start --db postgres --db-url-host mypostgres --db-username myuser --db-password change_me

    此命令包括连接到数据库所需的最小设置。

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

如果您想使用特定数据库（H2 除外），请不要对 start 命令使用 --optimized 标志。在启动服务器实例之前执行构建阶段是必要的。您可以通过在没有 --optimized 标志的情况下启动实例或在优化启动之前执行 build 命令来实现。有关更多信息，请参阅 配置 Keycloak。

覆盖默认连接设置

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

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

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

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

覆盖默认 JDBC 驱动程序

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

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

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 字符串支持

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

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

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

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

  • 角色：名称

  • 对象的描述

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

配置 Oracle 数据库的 Unicode 支持

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

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

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

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

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

Microsoft SQL Server 数据库的 Unicode 支持

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

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

配置 MySQL 数据库的 Unicode 支持

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

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

  1. 启动 MySQL 服务器。

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

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

配置 PostgreSQL 数据库的 Unicode 支持

当数据库字符集为 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 驱动程序 提供了额外的功能，例如在多 AZ 设置中写入器实例发生变化时传输数据库连接。此驱动程序不是分发的一部分，需要在使用之前安装。

要安装此驱动程序，请执行以下步骤

  1. 在运行解压缩的发布版时：从 Amazon Web Services JDBC 驱动程序发布页面 下载 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 Operator 运行优化和非优化映像的 使用自定义 Keycloak 映像 指南。

  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 恢复，除非该路径存在稳定存储。

设置 JPA 提供程序配置选项以进行迁移策略

要设置 JPA 迁移策略（手动/更新/验证），您应该按如下方式设置 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

数据库供应商。

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（默认）
在本页上
编辑本指南