設定資料庫

關於如何設定關聯式資料庫的概述

本指南說明如何設定 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. 從 Oracle 驅動程式下載頁面取得的壓縮 JDBC 驅動程式和隨附 JAR 檔案版本 23.5.0.24.07。

    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 支援

對於 Microsoft SQL Server 資料庫，僅針對特殊欄位支援 Unicode 字元。資料庫不需要特殊設定。

應將 JDBC 驅動程式的 `sendStringParametersAsUnicode` 屬性設定為 `false` 以顯著提高效能。如果沒有此參數，Microsoft SQL Server 可能無法使用索引。

設定 MySQL 資料庫的 Unicode 支援

如果在使用 CREATE DATABASE 命令時使用 VARCHAR 和 CHAR 欄位中的 Unicode 支援建立資料庫，則 MySQL 資料庫支援 Unicode 字元。

請注意，由於 utf8 字元集的儲存需求不同，因此不支援 utf8mb4 字元集。如需詳細資訊，請參閱 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 驅動程式提供額外的功能，例如在多可用區設定中寫入器執行個體變更時傳輸資料庫連線。此驅動程式不屬於發行版本的一部分，必須先安裝才能使用。

若要安裝此驅動程式，請套用以下步驟

  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 映像檔 指南，以瞭解如何使用 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 復原。

設定 JPA 提供者組態選項以用於 migrationStrategy

要設定 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

資料庫供應商。

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 (預設)
在此頁面
編輯本指南