Management interface reference

默认情况下，Quarkus 将在主 HTTP 服务器上 /q 下公开 management 端点。同一个 HTTP 服务器提供应用程序端点和管理端点。

By default, Quarkus exposes the management endpoints under /q on the main HTTP server. The same HTTP server provides the application endpoints and the management endpoints.

本文档介绍了如何为管理端点使用一个单独的 HTTP 服务器（绑定到一个不同的网络接口和端口）。它避免在主服务器上公开这些端点，因此防止了不必要的访问。

This document presents how you can use a separate HTTP server (bound to a different network interface and port) for the management endpoints. It avoids exposing these endpoints on the main server and, therefore, prevents undesired accesses.

Enabling the management interface

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

To enable the management interface, use the following build-time property:

quarkus.management.enabled=true

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

By default, management endpoints will be exposed on: http://0.0.0.0:9000/q. For example, if you have smallrye-health installed, the readiness probe will be exposed at http://0.0.0.0:9000/q/health/ready.

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

SmallRye Health Checks, SmallRye Metrics, Micrometer and Info endpoints will be declared as management endpoints when the management interface is enabled.

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

The management interface is disabled when no extensions relying on it (such as the SmallRye Health or SmallRye OpenAPI extensions) are installed.

Configure the host, port and scheme

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

By default, the management interface is exposed on the interface: 0.0.0.0 (all interfaces) and on the port 9000 (9001 in test mode). It does not use TLS (https) by default.

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

You can configure the host, ports, and TLS certificates using the following properties:

  • quarkus.management.host - the interface / host

  • quarkus.management.port - the port

  • quarkus.management.test-port - the port to use in test mode

  • quarkus.management.ssl - the TLS configuration, same as for the main HTTP server.

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

Here is a configuration example exposing the management interface on 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 属性以指定应重新加载证书的时间间隔：

Key store, trust store and certificate files can be reloaded periodically. Configure the quarkus.management.ssl.certificate.reload-period property to specify the interval at which the certificates should be reloaded:

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

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

The files are reloaded from the same location as they were initially loaded from. If there is no content change, the reloading is a no-op. It the reloading fails, the server will continue to use the previous certificates.

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

Unlike the main HTTP server, the management interface does not handle http and https at the same time. If https is configured, plain HTTP requests will be rejected.

Configure the root path

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

Management endpoints are configured differently than standard HTTP endpoints. They use a unique root path, which is /q by default. This management root path can be configured using the quarkus.management.root-path property. For example, if you want to expose the management endpoints under /management use:

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

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

The mounting rules of the management endpoints slightly differ from the ones used when using the main HTTP server:

  • Management endpoints configured using a relative path (not starting with /) will be served from the configured root path. For example, if the endpoint path is health and the root path is management, the resulting path is /management/health

  • Management endpoints configured using an absolute path (starting with /) will be served from the root. For example, if the endpoint path is /health, the resulting path is /health, regardless of the root path

  • The management interface does not use the HTTP root path from the main HTTP server.

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

The quarkus.http.root-path property is only applied to the main HTTP server and not to the management interface. In addition, the quarkus.http.non-application-root-path property is not used for endpoint exposed on the management interface.

Create a management endpoint in an extension

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

To expose an endpoint on the management interface from the code of an application, refer to management-endpoint-application.

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

SmallRye Health Checks, SmallRye Metrics, and Micrometer endpoints will be declared as management endpoints when the management interface is enabled.

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

if you do not enable the management interface, these endpoints will be served using the main HTTP server (under /q by default).

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

Extensions can create a management endpoint by defining a non application route and calling management() method:

@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 上。

If the management interface is enabled, the endpoint will be exposed on: http://0.0.0.0:9000/q/my-path. Otherwise, it will be exposed on: http://localhost:8080/q/my-path.

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

Management endpoints can only be declared by extensions and not from the application code.

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

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

You can expose endpoints on the management interface by registering routes on the management router. To access the router use the following code:

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

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

The io.quarkus.vertx.http.ManagementInterface event is fired when the management interface is initialized. So, if the management interface is not enabled, the method won’t be called.

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

The router() method returns a io.vertx.ext.web.Router object which can be used to register routes. The paths are relative to /. For example, the previous snippet registers a route on /admin. This route is accessible on http://0.0.0.0:9000/admin, if you use the default host and port.

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

More details about the Router API can be found on the Vert.x Web documentation.

Management Interface Configuration

Unresolved directive in management-interface-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.management.adoc[]

Running behind a reverse proxy

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

Quarkus can be accessed through proxies that generate headers (e.g. X-Forwarded-Host) to preserve information about the original request. Quarkus can be configured to automatically update information like protocol, host, port and URI to use the values from those headers.

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

Activating this feature can expose the server to security issues like information spoofing. Activate it only when running behind a reverse proxy.

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

To set up this feature for the management interface, include the following lines in 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 变体）：

To constrain this behavior to the standard Forwarded header (and ignore X-Forwarded variants) by setting quarkus.management.proxy.allow-forwarded in src/main/resources/application.properties:

quarkus.management.proxy.allow-forwarded=true

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

Alternatively, you can prefer X-Forwarded-* headers using the following configuration in src/main/resources/application.properties (note allow-x-forwarded instead of 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

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

Supported forwarding address headers are:

  • Forwarded

  • X-Forwarded-Proto

  • X-Forwarded-Host

  • X-Forwarded-Port

  • X-Forwarded-Ssl

  • X-Forwarded-Prefix

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

If both header variants (Forwarded and X-Forwarded-*) are enabled, the Forwarded header will have precedence.

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

Using both Forwarded and X-Forwarded headers can have security implications as it may allow clients to forge requests with a header that is not overwritten by the proxy.

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

Ensure that your proxy is configured to strip unexpected Forwarded or X-Forwarded-* headers from the client request.

Kubernetes

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

When Quarkus generates the Kubernetes metadata, it checks if the management interface is enabled and configures the probes accordingly. The resulting descriptor defines the main HTTP port (named http) and the management port (named management). Health probes (using HTTP actions) and Prometheus scrape URLs are configured using the management port.

Example 1. KNative

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

Until KNative#8471 is resolved, you cannot use the management interface, as KNative does not support containers will multiple exposed ports.

Security

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

You can enable basic authentication using the following properties:

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/*

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

You can also use different permissions for different paths or use role bindings:

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 中基本认证的更多详细信息。

More details about Basic authentication in Quarkus can be found in the Basic authentication guide.

Injecting management URL in tests

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

When testing your application, you can inject the management URL using the @TestHTTPResource annotation:

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

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

The management attribute is set to true to indicate that the injected URL is for the management interface. The context-root is automatically added. Thus, in the previous example, the injected URL is http://localhost:9001/q/management.

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

@TestHTTPResource is particularly useful when setting the management test-port to 0, which indicates that the system will assign a random port to the management interface:

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