Management interface reference

默认情况下，Quarkus 将在主 HTTP 服务器上 /q 下公开 management 端点。同一个 HTTP 服务器提供应用程序端点和管理端点。 本文档介绍了如何为管理端点使用一个单独的 HTTP 服务器（绑定到一个不同的网络接口和端口）。它避免在主服务器上公开这些端点，因此防止了不必要的访问。

Enabling the management interface

要启用管理界面，请使用以下 build-time 属性：

quarkus.management.enabled=true

默认情况下，管理端点将在以下位置公开： http://0.0.0.0:9000/q。例如，如果你已安装 smallrye-health，则就绪探测将公开在 http://0.0.0.0:9000/q/health/ready。

启用管理界面时，SmallRye Health Checks、SmallRye Metrics、Micrometer 和 Info 端点将被声明为管理端点。

如果没有依赖于它的扩展（例如 SmallRye Health 或 SmallRye OpenAPI 扩展）已安装，则管理界面将被停用。

Configure the host, port and scheme

默认情况下，管理界面在接口： 0.0.0.0 （所有接口）和端口 9000 （在测试模式下为 9001 ）上公开。默认情况下它不使用 TLS (https)。

你可以使用以下属性配置主机、端口和 TLS 证书：

  • quarkus.management.host - 接口/主机

  • quarkus.management.port - the port

  • quarkus.management.test-port - 在测试模式下使用的端口

  • quarkus.management.ssl - TLS 配置，same as for the main HTTP server.

以下是展示了在 https://localhost:9002 上公开管理界面的配置示例：

quarkus.management.enabled=true
quarkus.management.host=localhost
quarkus.management.port=9002
quarkus.management.ssl.certificate.key-store-file=server-keystore.jks
quarkus.management.ssl.certificate.key-store-password=secret

密钥库、信任库和证书文件可以定期重新加载。配置 quarkus.management.ssl.certificate.reload-period 属性以指定应重新加载证书的时间间隔：

quarkus.http.management.certificate.files=/mount/certs/tls.crt
quarkus.http.management.certificate.key-files=/mount/certs/tls.key
quarkus.http.management.certificate.reload-period=1h

文件从最初加载时相同的文件夹重新加载。如果没有内容更改，则重新加载将是无操作。如果重新加载失败，则服务器将继续使用以前的证书。

与主 HTTP 服务器不同，管理界面不会同时处理 http 和 https。如果配置了 https，将拒绝普通的 HTTP 请求。

Configure the root path

管理端点的配置方式不同于标准的 HTTP 端点。它们使用的是一个唯一的根路径，默认情况下为 /q。可以使用 quarkus.management.root-path property 来配置此管理根路径。例如，如果你希望在 /management 下公开管理端点，则可以使用：

quarkus.management.enabled=true
quarkus.management.root-path=/management

管理端点的装载规则与使用主 HTTP 服务器时的规则略有不同：

  • 使用 relative 路径（不以 / 开头）配置的管理端点将从已配置的根路径提供服务。例如，如果端点路径是 health 而根路径是 management，则生成路径是 /management/health

  • 使用 absolute 路径（以 / 开头）配置的管理端点将从根路径提供服务。例如，如果端点路径是 /health，则生成的路径是 /health，无论是什么根路径

  • 管理界面不会使用主 HTTP 服务器的 HTTP 根路径。

quarkus.http.root-path 属性仅应用于主 HTTP 服务器，不应用于管理界面。此外，不会使用 quarkus.http.non-application-root-path 属性来公开管理界面上的端点。

Create a management endpoint in an extension

若要从应用程序的代码中公开管理界面上的端点，请参阅 the application section。

启用管理界面后，SmallRye 健康检查、SmallRye 指标和 Micrometer 端点将声明为管理端点。

如果你没有启用管理界面，则这些端点将使用主 HTTP 服务器提供服务（默认情况下在 /q 下）。

扩展可以通过定义 non application 路由并调用 management() 方法来创建一个管理端点：

@BuildStep
void createManagementRoute(BuildProducer<RouteBuildItem> routes,
        NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
        MyRecorder recorder) {

    routes.produce(nonApplicationRootPathBuildItem.routeBuilder()
        .management() // Must be called BEFORE the routeFunction method
        .routeFunction("my-path", recorder.route())
        .handler(recorder.getHandler())
        .blockingRoute()
        .build());
    //...
}

如果启用了管理界面，则端点将公开在： http://0.0.0.0:9000/q/my-path 上。否则，它将公开在： http://localhost:8080/q/my-path 上。

管理端点只能由扩展声明，而不能由应用程序代码声明。

Exposing an endpoint on the management interface (as an application)

你可以通过在管理路由器上注册路由，公开管理界面上的端点。要访问路由器，请使用以下代码：

public void registerManagementRoutes(@Observes ManagementInterface mi) {
       mi.router().get("/admin").handler(rc ->
            rc.response().end("admin it is")
       );
}

初始化管理界面时，会触发 io.quarkus.vertx.http.ManagementInterface 事件。因此，如果未启用管理界面，则不会调用该方法。

router() 方法返回一个 io.vertx.ext.web.Router 对象，该对象可用于注册路由。路径相对于 /。例如，上一个代码段在 /admin 上注册一个路由。如果你使用默认主机和端口，则可以通过 http://0.0.0.0:9000/admin 访问此路由。

可在 the Vert.x Web documentation 中找到有关 Router API 的更多详细信息。

Management Interface Configuration

Unresolved include directive in modules/ROOT/pages/management-interface-reference.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-vertx-http_quarkus.management.adoc[]

Running behind a reverse proxy

Quarkus 可通过生成标头（例如 X-Forwarded-Host）的代理访问，以保留有关原始请求的信息。Quarkus 可配置为自动更新协议、主机、端口和 URI 等信息，以使用这些标头中的值。

激活此功能可能会使服务器面临信息欺骗等安全问题。仅在反向代理后运行时才激活它。

要为管理界面设置此功能，请在 src/main/resources/application.properties 中包含以下行：

quarkus.management.proxy.proxy-address-forwarding=true

要通过在 src/main/resources/application.properties 中设置 quarkus.management.proxy.allow-forwarded 来将此行为限定为标准 Forwarded 标头（并忽略 X-Forwarded 变体）：

quarkus.management.proxy.allow-forwarded=true

或者，您可以使用 src/main/resources/application.properties 中的以下配置首选 X-Forwarded-* 标头（请注意使用 allow-x-forwarded 替代 allow-forwarded）：

quarkus.management.proxy.proxy-address-forwarding=true
quarkus.management.proxy.allow-x-forwarded=true
quarkus.management.proxy.enable-forwarded-host=true
quarkus.management.proxy.enable-forwarded-prefix=true

支持的转发地址标头包括：

  • Forwarded

  • X-Forwarded-Proto

  • X-Forwarded-Host

  • X-Forwarded-Port

  • X-Forwarded-Ssl

  • X-Forwarded-Prefix

如果启用两个标头变体（Forwarded 和 X-Forwarded-*），则 Forwarded 标头将具有优先级。

同时使用 Forwarded 和 X-Forwarded 标头可能会产生安全影响，因为它可能允许客户端伪造具有不会被代理覆盖的标头的请求。

确保将代理配置为从客户端请求中删除意外的 Forwarded 或 X-Forwarded-* 标头。

Kubernetes

Quarkus 生成 Kubernetes 元数据时，它会检查管理界面是否已启用并相应配置探测。生成描述符定义主 HTTP 端口（命名为 http）和管理端口（命名为 management）。使用 management 端口配置健康探测（使用 HTTP 操作）和 Prometheus 抓取 URL。

Example 1. KNative

在解决 KNative#8471 之前，您无法使用管理界面，因为 KNative 不支持具有多个公开端口的容器。

Security

您可以使用以下属性启用 basic 认证：

quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Require all access to /q/* to be authenticated
quarkus.management.auth.permission.all.policy=authenticated
quarkus.management.auth.permission.all.paths=/q/*

您还可以对不同路径使用不同的权限或使用角色绑定：

quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Configure a management policy if needed, here the policy `management-policy` requires users to have the role `management`.
quarkus.management.auth.policy.management-policy.roles-allowed=management

# For each endpoint you can configure the permissions
# Health used the management-policy (so requires authentication + the `management` role)
quarkus.management.auth.permission.health.paths=/q/health/*
quarkus.management.auth.permission.health.policy=management-policy

# Metrics just requires authentication
quarkus.management.auth.permission.metrics.paths=/q/metrics/*
quarkus.management.auth.permission.metrics.policy=authenticated

可在 Basic authentication guide 中找到有关 Quarkus 中基本认证的更多详细信息。

Injecting management URL in tests

测试应用程序时，可以使用 @TestHTTPResource 批注注入管理 URL：

@TestHTTPResource(value="/management", management=true)
URL management;

将 management 属性设置为 true 以表明注入的 URL 用于管理界面。自动添加 context-root。因此，在前面的示例中，注入的 URL 是 http://localhost:9001/q/management 。

当将管理 test-port 设置为 0 时，@TestHTTPResource 尤其有用，这表明系统将向管理界面分配一个随机端口：

----]
quarkus.management.test-port=0