1. 引言
随着云技术的演进，应用部署和管理变得更加无缝。但这种转变也增加了对强大运维数据的需求，以便有效监控和维护应用程序。
要实现这一目标，我们需要一个控制平面来提供应用健康、性能和运行时行为的可见性。管理接口正是为此而生——它提供专用且安全的接口，用于高效监控和管理应用程序。
本教程将深入探讨 Quarkus 中的管理接口，帮助开发和运维团队访问关键运行时数据，如健康状态、指标和应用配置。
2. 启用与配置管理接口
默认情况下，Quarkus 不暴露管理接口。但一旦启用，它会提供多个监控和诊断接口。
首先，在 application.properties 中启用它：
quarkus.management.enabled=true
然后通过 Maven 命令重启应用：
mvn quarkus:dev
现在应用将在所有网络接口的 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
此时管理接口地址变为 http://localhost:9090/management。
为简化演示，后续均使用默认配置。
3. 可用接口及使用场景
Quarkus 提供多个管理接口，实时洞察应用运行状态。
3.1. 应用信息
添加最新版 quarkus-info 依赖：
<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 运行时、操作系统和构建信息。
3.2. 健康检查
添加 quarkus-smallrye-health 依赖启用健康检查：
<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 依赖：
<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 获取交互式 API 测试界面。
3.4. Micrometer 指标
**Quarkus 提供 Micrometer 指标并支持 Prometheus**。
添加 quarkus-micrometer-registry-prometheus 依赖：
<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使用 Eclipse Microprofile 指标，但此方案已废弃，Quarkus 升级到 MicroProfile 6 后将停止支持。
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：
curl http://localhost:9000/q/custom
触发自定义路由：
Custom Management Endpoint Active
确认自定义接口已成功注册并可访问。
5. 保护管理接口安全
管理接口暴露敏感信息，必须防止未授权访问。Quarkus 提供内置认证和授权机制。
5.1. 基础认证
添加配置启用基础认证：
quarkus.management.auth.enabled=true
quarkus.management.auth.basic=true
启用后，所有管理接口请求均需认证。
5.2. 基于角色的访问控制
通过 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 指标等内置接口
✅ 创建自定义管理接口
✅ 通过认证和基于角色的访问控制保护接口安全
合理利用这些功能，可显著提升云原生应用的运维效率。