Quarkus 中的管理介面

1. 簡介

隨著雲端技術的發展，應用程式的部署和管理變得更加無縫。然而，這種轉變也增加了對強大的營運數據的需求，以便有效地監控和維護這些應用程式。

為了實現這一點，我們需要一個控制平面來提供應用程式的健康狀況、效能和運行時行為的可見性。這就是管理介面發揮作用的地方——它提供了一個專用的安全端點，用於有效地監控和管理應用程式。

在本教程中，我們將深入研究 Quarkus 中的管理介面，它使開發人員和營運團隊能夠存取關鍵的運行時數據，例如健康狀態、指標和應用程式配置。

2. 啟用並設定管理介面

預設情況下，Quarkus 不公開管理介面。但是，一旦啟用，管理介面就會提供多個端點用於監控和診斷。

首先，讓我們使用 Quarkus 應用程式的application.properties檔案啟用它：

quarkus.management.enabled=true

然後，我們將使用 Maven 命令重新啟動我們的應用程式：

mvn quarkus:dev

現在，我們的 Quarkus 應用程式開始在所有網路介面（內建設定）上監聽連接埠9000 ，並將其與主應用程式端點分開：

2025-03-15 12:53:30,364 INFO [io.quarkus] (Quarkus Main Thread) quarkus-management-interface 1.0-SNAPSHOT

 on JVM (powered by Quarkus 3.5.0) started in 1.173s.

 Listening on: http://localhost:8080. Management interface listening on http://0.0.0.0:9000.

因此，預設管理介面端點可在http://localhost:9000/q/上使用，其中/q為預設根路徑。

此外，Quarkus 允許我們設定預設設置，如host 、 port和root-path ：

quarkus.management.host=localhost

 quarkus.management.port=9090

 quarkus.management.root-path=/management

這裡，我們在本地機器的9090連接埠上公開了管理接口， http://localhost:9090/management.

為了本教程的簡單起見，我們將始終使用 Quarkus 管理介面的預設值。

3. 可用端點及其用途

Quarkus 公開了多個管理端點，可以即時洞察我們的應用程式的執行時間狀態。

3.1.申請資訊

首先，讓我們透過將最新的quarkus-info Maven 依賴項新增至我們的pom.xml來檢查我們的應用程式的資訊詳細資訊：

<dependency>

 <groupId>io.quarkus</groupId>

 <artifactId>quarkus-info</artifactId>

 <version>3.19.3</version>

 </dependency>

新增後，我們可以使用/q/info端點檢索我們的應用程式詳細資訊：

curl http://localhost:9000/q/info

輸出結果如下：

{

 "java" : {

 "version" : "21.0.6"

 },

 "os" : {

 "name" : "Mac OS X",

 "version" : "15.3.1",

 "arch" : "aarch64"

 },

 "build" : {

 "group" : "com.baeldung.quarkus",

 "artifact" : "quarkus-management-interface",

 "version" : "1.0-SNAPSHOT",

 "time" : "2025-03-15T13:58:40.344217+05:30"

 }

 }

JSON 回應提供有關 Java 運行時、作業系統以及 Quarkus 應用程式的建置細節的資訊。

3.2.健康檢查

現在，讓我們新增最新的quarkus-smallrye-health Maven 依賴項以在我們的 Quarkus 應用程式中啟用健康檢查：

<dependency>

 <groupId>io.quarkus</groupId>

 <artifactId>quarkus-smallrye-health</artifactId>

 <version>3.19.3</version>

 </dependency>

因此，我們可以評估應用程式的準備：

curl http://localhost:9000/q/health/ready

成功的響應將如下所示：

{

 "status": "UP",

 "checks": []

 }

類似地，應用程式的活躍度也將可用：

curl http://localhost:9000/q/health/live

另外，我們可以檢查應用程式的整體健康狀況：

curl http://localhost:9000/q/health

因此，此端點結合了對就緒性和活躍性的檢查。

3.3. OpenAPI 文件和 Swagger UI

Quarkus 為/q/openapi和/q/swagger-ui等端點提供端點，分別用於存取 OpenAPI 和 Swagger UI。

讓我們新增最新的quarkus-smallrye-openapi Maven 依賴項：

<dependency>

 <groupId>io.quarkus</groupId>

 <artifactId>quarkus-smallrye-openapi</artifactId>

 <version>3.19.3</version>

 </dependency>

現在，我們可以存取我們的應用程式的 OpenAPI 文件：

curl http://localhost:9000/q/openapi

此端點提供了符合 OpenAPI 規範的我們應用程式的 RESTful API 的全面描述。

類似地，我們可以透過http://localhost:9000/q/swagger-ui存取 Swagger UI。

這提供了一個互動式使用者介面來探索和測試我們的 API。

3.4.微米度量

Quarkus 為我們的應用程式提供 Micrometer 指標以及 Prometheus 支援。

首先，讓我們將所需的quarkus-micrometer-registry-prometheus Maven 依賴項加入我們的pom.xml ：

<dependency>

 <groupId>io.quarkus</groupId>

 <artifactId>quarkus-micrometer-registry-prometheus</artifactId>

 </dependency>

添加後，我們可以訪問與 Prometheus 相容的指標：

curl http://localhost:9000/q/metrics

例如，包含 JVM 和應用程式指標的回應如下所示：

# HELP worker_pool_completed_total Number of times resources from the pool have been acquired

 # TYPE worker_pool_completed_total counter

 worker_pool_completed_total{pool_name="vert.x-internal-blocking",pool_type="worker",} 0.0

 worker_pool_completed_total{pool_name="vert.x-worker-thread",pool_type="worker",} 6.0

 # HELP http_server_bytes_read Number of bytes received by the server

 # TYPE http_server_bytes_read summary

 http_server_bytes_read_count 0.0

 http_server_bytes_read_sum 0.0

 # HELP http_server_bytes_read_max Number of bytes received by the server

 # TYPE http_server_bytes_read_max gauge

 http_server_bytes_read_max 0.0

本質上，我們檢索了 Quarkus 應用程式運行時健康和效能的快照。

此外，我們也可以使用quarkus-smallrye-metrics Maven 依賴項存取基於 Eclipse Microprofile 的指標。但是，它已被棄用，當 Quarkus 升級到 Eclipse MicroProfile 6 時，SmallRye Metrics 支援將停止。

4. 管理介面上的自訂端點

Quarkus 允許我們透過在管理介面路由器上註冊路由來在管理介面上定義自訂管理端點。

為此，我們將觀察[ManagementInterface](https://javadoc.io/doc/io.quarkus/quarkus-vertx-http/latest/io/quarkus/vertx/http/ManagementInterface.html)事件是否被觸發並路由到我們的自訂端點以回傳回應：

public void registerManagementRoutes(@Observes ManagementInterface mi) {

 mi.router()

 .get("/q/custom")

 .handler(rc -> rc.response()

 .end("Custom Management Endpoint Active"));

 }

在這裡我們註冊了一個自訂管理端點/q/custom ，它以String回應回應：

curl http://localhost:9000/q/custom

自訂路由會在管理介面初始化回應的時候觸發：

Custom Management Endpoint Active

這確認我們的自訂端點已成功註冊並可在 Quarkus 管理介面中存取。

5. 保護管理接口

由於管理介面公開了關鍵的應用程式詳細信息，我們必須有一種方法可以防止未經授權的存取。

為了解決這個問題， Quarkus 也為管理介面提供了內建的身份驗證和授權機制。

5.1.基本驗證

我們可以添加以下配置以在我們的應用程式的管理介面上啟用基本身份驗證：

quarkus.management.auth.enabled=true

 quarkus.management.auth.basic=true

當兩個屬性都啟用時，對管理端點的任何請求都需要身份驗證。

5.2.基於角色的存取控制

Quarkus 也支援使用基於角色的授權透過屬性quarkus.management.auth.roles-mapping.”role-name”

quarkus.management.auth.roles-mapping.admin=true

 quarkus.management.auth.roles-mapping.operator=true

這確保只有具有admin或operator角色的使用者才能與管理介面互動。

5.3. HTTPS 設定

啟用 HTTPS 可確保用戶端和管理介面之間的加密通訊。因此，我們也可以為管理端點啟用建議的 SSL：

quarkus.management.ssl.certificate.key-store-file=keystore.jks

 quarkus.management.ssl.certificate.key-store-password=secret

因此，透過配置身份驗證、基於角色的存取和安全通信，我們可以有效地保護 Quarkus 管理介面免受未經授權的存取。

6. 結論

在本文中，我們探討了 Quarkus 中的管理介面及其在有效監控和管理應用程式中的作用。

我們討論瞭如何啟用和配置管理接口，使用內建端點（例如健康檢查、OpenAPI 和 Micrometer 指標）以及如何建立自訂管理端點。

此外，我們還研究了一些保護管理端點的常用方法，包括身份驗證和基於角色的存取控制。

與往常一樣，本文的程式碼可在 GitHub 上取得。