匯入和匯出 Realm

關於如何匯入和匯出 realm 的概述

在本指南中，您將了解使用 JSON 檔案匯入和匯出 realm 的不同方法。

匯出和匯入到單個檔案可能會產生大型檔案，因此如果您的資料庫包含超過 500 個使用者，請匯出到目錄而不是單個檔案。使用目錄效能更好，因為目錄提供者會為每個「頁面」（一個使用者檔案）使用單獨的交易。每個檔案和每個交易的預設使用者數量為五十。將此數字增加到更大的數量會導致執行時間呈指數級增加。

在使用 kc.[sh|bat] import | export 命令之前，需要停止所有 Keycloak 節點。這可確保產生的操作不會與並行請求產生一致性問題。它還確保從與伺服器實例相同的機器執行匯入或匯出命令不會導致連接埠或其他衝突。

提供資料庫連線參數的選項

當使用下面的 export 和 import 命令時，Keycloak 需要知道如何連線到儲存有關 realm、客戶端、使用者和其他實體的資訊的資料庫。如設定 Keycloak中所述，該資訊可以作為命令列參數、環境變數或設定檔提供。對每個命令使用 --help 命令列選項，以查看可用的選項。

某些配置選項是建置時配置選項。預設情況下，如果 Keycloak 檢測到建置時參數的變更，它會自動為 export 和 import 命令重新建置。

如果您已按照設定 Keycloak中所述使用 build 命令建置了 Keycloak 的最佳化版本，請使用命令列選項 --optimized 讓 Keycloak 跳過建置檢查以縮短啟動時間。執行此操作時，請從命令列中刪除建置時選項，並僅保留執行時選項。

如果您不使用 --optimized，請記住 import 或 export 命令會隱式地為您建立或更新最佳化的映像 - 如果您從與伺服器實例相同的機器執行命令，這可能會影響您下次啟動伺服器。

將 Realm 匯出到目錄

要匯出 realm，您可以使用 export 命令。當調用此命令時，您的 Keycloak 伺服器實例不得啟動。

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

要將 realm 匯出到目錄，您可以使用 --dir <dir> 選項。

bin/kc.[sh|bat] export --dir <dir>

當將 realm 匯出到目錄時，伺服器將為每個正在匯出的 realm 建立單獨的檔案。

設定如何匯出使用者

您還可以透過設定 --users <strategy> 選項來設定如何匯出使用者。此選項的可用值為

different_files

使用者會匯出到不同的 json 檔案中，具體取決於 --users-per-file 設定的每個檔案的最大使用者數量。這是預設值。

skip

跳過匯出使用者。

realm_file

使用者將匯出到與 realm 設定相同的檔案中。對於名為「foo」的 realm，這將是「foo-realm.json」，其中包含 realm 資料和使用者。

same_file

所有使用者都會匯出到一個明確的檔案中。因此，您將為一個 realm 獲得兩個 json 檔案，一個包含 realm 資料，另一個包含使用者。

如果您使用 different_files 策略匯出使用者，您可以透過設定 --users-per-file 選項來設定每個檔案的使用者數量。預設值為 50。

bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100

將 Realm 匯出到檔案

要將 realm 匯出到檔案，您可以使用 --file <file> 選項。

bin/kc.[sh|bat] export --file <file>

當將 realm 匯出到檔案時，伺服器將使用同一個檔案來儲存所有正在匯出的 realm 的設定。

匯出特定 realm

如果您沒有指定要匯出的特定 realm，則會匯出所有 realm。要匯出單個 realm，您可以使用 --realm 選項，如下所示

bin/kc.[sh|bat] export [--dir|--file] <path> --realm my-realm

從目錄匯入 Realm

要匯入 realm，您可以使用 import 命令。當調用此命令時，您的 Keycloak 伺服器實例不得啟動。

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

將 realm 匯出到目錄後，您可以使用 --dir <dir> 選項將 realm 匯回伺服器，如下所示

bin/kc.[sh|bat] import --dir <dir>

當使用 import 命令匯入 realm 時，您可以設定是否應跳過現有的 realm，或者是否應使用新的設定覆寫它們。為此，您可以設定 --override 選項，如下所示

bin/kc.[sh|bat] import --dir <dir> --override false

預設情況下，--override 選項設定為 true，以便始終使用新的設定覆寫 realm。

從檔案匯入 Realm

要匯入先前匯出到單個檔案中的 realm，您可以使用 --file <file> 選項，如下所示

bin/kc.[sh|bat] import --file <file>

在 Realm 設定檔案中使用環境變數

您可以使用佔位符來解析任何 realm 設定的環境變數中的值。

使用佔位符的 Realm 設定
{
    "realm": "${MY_REALM_NAME}",
    "enabled": true,
    ...
}

在上面的範例中，設定為 MY_REALM_NAME 環境變數的值將用於設定 realm 屬性。

啟動期間匯入 Realm

您還可以在伺服器啟動時使用 --import-realm 選項匯入 realm。

bin/kc.[sh|bat] start --import-realm

當您設定 --import-realm 選項時，伺服器將嘗試從 data/import 目錄匯入任何 realm 設定檔。此目錄僅會讀取使用 .json 副檔名的常規檔案，子目錄會被忽略。

對於 Keycloak 容器，匯入目錄是 /opt/keycloak/data/import

如果伺服器中已存在 realm，則會跳過匯入操作。此行為背後的主要原因是避免重新建立 realm，並可能在伺服器重新啟動之間遺失狀態。

要重新建立 realm，您應該在啟動伺服器之前明確執行 import 命令。

使用管理控制台匯入和匯出

您還可以使用管理控制台匯入和匯出 realm。此功能與先前章節中描述的其他 CLI 選項不同，因為管理控制台僅提供 _部分_ 匯出 realm 的功能。在這種情況下，可以匯出目前的 realm 設定以及一些資源，例如客戶端、角色和群組。無法使用此方法匯出該 realm 的使用者。

當使用管理控制台匯出時，realm 和選定的資源始終會匯出到名為 realm-export.json 的檔案。此外，所有敏感值（例如密碼和客戶端密鑰）都會使用 * 符號遮罩。

要使用管理控制台匯出 realm，請執行以下步驟

  1. 選擇一個 realm。

  2. 在選單中按一下 [Realm 設定]。

  3. 指向 realm 設定螢幕右上角的 [動作] 選單，然後選擇 [部分匯出]。

    將顯示資源清單以及 realm 設定。

  4. 選擇您要匯出的資源。

  5. 按一下 [匯出]。

從管理控制台匯出的 realm 不適用於備份或伺服器之間傳輸資料。只有 CLI 匯出才適用於備份或伺服器之間傳輸資料。
如果 realm 包含許多群組、角色和客戶端，則此操作可能會導致伺服器在一段時間內無法回應使用者請求。請謹慎使用此功能，尤其是在生產系統上。

以類似的方式，您可以匯入先前匯出的 realm。請執行以下步驟

  1. 在選單中按一下 [Realm 設定]。

  2. 指向 realm 設定螢幕右上角的 [動作] 選單，然後選擇 [部分匯入]。

    將顯示一個提示，您可以在其中選擇要匯入的檔案。根據此檔案，您會看到可以匯入的資源以及 realm 設定。

  3. 按一下 [匯入]。

您還可以控制如果匯入的資源已存在，Keycloak 應該怎麼做。這些選項存在

匯入失敗

中止匯入。

略過

略過重複的資源，而不中止程序

覆寫

將現有資源替換為正在匯入的資源。

管理控制台部分匯入也可以匯入由 CLI export 命令建立的檔案。換句話說，CLI 建立的完整匯出可以使用管理控制台匯入。如果檔案包含使用者，這些使用者也可以匯入到目前的 realm 中。
在此頁面上
編輯本指南