遷移至 Quarkus 發行版

Keycloak 的 WildFly 發行版使用複雜的 XML 檔案進行配置，因此需要使用 CLI 工具 (jboss-cli) 來操作這些檔案。這些檔案也使升級變得複雜，需要使用容易出錯的指令碼來升級先前版本的設定。

新的 Quarkus 發行版改用簡單的設定檔，並將對應的 CLI 引數和環境變數作為選項，使得 Keycloak 的配置變得更加容易。然而，這導致無法自動遷移先前發行版的配置。

若要遷移到新的 Quarkus 發行版，第一步是瞭解您對舊版發行版進行了哪些配置變更，並按照新的伺服器指南，將必要的配置變更套用到新的發行版。

請注意，新發行版在配置方面更加固執己見。它旨在提供更好的預設值，讓您需要自行配置的內容減少。然而，我們可能無法始終保持平衡，並且可能存在未涵蓋的使用案例。

如果您無法在新的發行版中配置您需要調整的內容，請在 GitHub Discussions 中開啟討論。

在新的版本發布之前，可以透過直接套用 Quarkus 層級配置到 conf/quarkus.properties 檔案來配置新的發行版。我們建議您謹慎使用此功能，因為您將套用未經 Keycloak 團隊測試和支援的配置。

與 WildFly 不同，Quarkus 不是應用程式伺服器。應用程式伺服器可以動態部署應用程式，並在執行時變更載入記憶體的內容，但在 Quarkus 上無法實現此功能。

另一方面，Quarkus 為容器帶來了不可變性、更快的啟動速度和更高的可預測性。

雖然使用 WildFly 發行版可以熱部署自訂提供者，並將資料庫供應商變更為執行時配置，但現在已不再支援。

取而代之的是，Quarkus 發行版提供了一個單獨的建置步驟來最佳化執行時。這裡需要注意的重要一點是，建置步驟實際上並不是建置 Keycloak 原始碼，而只是透過增強流程來最佳化執行時，這個流程相當快速，並且能夠充分最佳化載入到執行時的內容。

我們建議您將此建置步驟作為安裝 Keycloak 的一部分，透過 CI 或建立擴展基礎 Keycloak 映像的自訂容器映像來完成。

然而，也有一種自動建置模式，可以讓 Keycloak 在這方面表現得或多或少與 WildFly 發行版相同。這會造成啟動時間的損失，但仍然能夠比 WildFly 發行版更好地最佳化執行時。

Keycloak Wildfly 發行版包含名為 add-user-keycloak.sh 的指令碼，用於將初始使用者新增至 Keycloak。這些指令碼不再包含在 Quarkus 發行版中。

若要新增初始管理員使用者，請設定環境變數 KC_BOOTSTRAP_ADMIN_USERNAME 和 KC_BOOTSTRAP_ADMIN_PASSWORD 作為使用者的使用者名稱和密碼。Keycloak 會在第一次啟動時使用它們來建立具有管理權限的初始使用者。一旦存在第一個具有管理權限的使用者，請使用命令列工具 kcadm.sh (Linux) 或 kcadm.bat (Windows) 來建立其他使用者。

預設情況下，新的 Quarkus 發行版會從內容路徑中移除 /auth。若要重新引入 /auth，請使用 http-relative-path 建置選項。例如：

當指定相對路徑時，仍然可以從根目錄重新導向到相對路徑。具體來說，當使用者存取 localhost:8080/ 時，頁面會重新導向到 localhost:8080/auth。

與 WildFly 發行版類似，自訂提供者透過將它們複製到部署目錄來部署到 Keycloak。在新發行版中，您應該將提供者複製到 providers 目錄，而不是不再存在的 standalone/deployments 目錄。其他相依性也複製到 providers 目錄。

在新發行版中，自訂提供者不再有單獨的類別路徑，因此您可能需要更仔細地處理您包含的其他相依性。此外，不再支援 EAR 封裝格式和 jboss-deployment-structure.xml 檔案。

雖然 WildFly 發行版會自動探索自訂提供者，甚至支援在 Keycloak 執行時熱部署自訂提供者，但現在已不再支援。當您對 providers 目錄中的提供者或相依性進行變更時，您必須在之後執行建置，或使用自動建置功能重新啟動伺服器。

根據您的提供者使用的 API，您可能也需要對提供者進行一些變更。如果您只使用了 Keycloak SPI 中的類別，則應該不需要變更，但如果您使用了 WildFly 中的其他 API，則可能需要進行一些變更。此外，不再支援 JavaEE API (如 session/stateless beans)。

若要在 Kubernetes 和 OpenShift 上使用 Quarkus 發行版，您需要使用新的 Operator，舊的 Operator 不支援新的發行版。

沒有「直接」的遷移路徑，若要使用新的 Operator 安裝 Keycloak，您需要建立新的自訂資源 (CR)，以獲得基於 Quarkus 發行版的新 Keycloak 部署。

舊的和新的 Operator 甚至可以在相同的命名空間中共存，因為它們在 CRD 中使用不同的 API 群組和版本。

對於舊的 Operator，apiVersion 為

對於新的 Operator，apiVersion 為

當使用 kubectl 命令時，如果叢集中安裝了 2 個 CRD，請確保使用包含 API 群組的完整名稱，例如：

新的 Operator 不直接支援 Client、User 和 Realm CRD。取而代之的是，它提供一個 CRD 來執行Realm 匯入。透過使用這個新的 CR，您可以透過包裝 Realm 匯入使用者、用戶端和更多內容。

在 Quarkus 中，X-Forwarded-Port 標頭的優先順序高於 X-Forwarded-Host 中包含的任何連接埠。這與 WildFly 發行版不同，在 WildFly 發行版中，X-Forwarded-Host 中包含的連接埠的優先順序高於 X-Forwarded-Port。