编辑此页面

管理界面参考

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

本文档介绍了如何为管理端点使用单独的 HTTP 服务器(绑定到不同的网络接口和端口)。这避免了在主服务器上公开这些端点,从而防止了不期望的访问。

1. 启用管理界面

要启用管理界面,请使用以下 构建时 属性

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 扩展)已安装时,管理界面将被禁用。

2. 配置主机、端口和协议

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

您可以使用以下属性配置主机、端口和 TLS 配置名称

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

  • quarkus.management.port - 端口

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

  • quarkus.management.tls-configuration-name - TLS 配置名称,与主 HTTP 服务器相同

以下是一个将管理界面公开在https://:9002的配置示例

quarkus.management.enabled=true
quarkus.management.host=localhost
quarkus.management.port=9002
quarkus.management.tls-configuration-name=management

# Your TLS registry configuration
...

使用此配置,TLS 将被启用,并根据 TLS 注册表中 management 配置的定义进行配置。

您也可以为管理界面配置遗留 SSL 配置,就像 (主 HTTP 服务器) 一样。

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 服务器不同,管理界面不能同时处理 httphttps。如果配置了 https,则纯 HTTP 请求将被拒绝。

3. 配置根路径

管理端点的配置方式与标准 HTTP 端点不同。它们使用一个唯一的根路径,默认是 /q。这个管理根路径可以使用 quarkus.management.root-path 属性进行配置。例如,如果您想在 /management 下公开管理端点,请使用

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

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

  • 使用相对路径(不以 / 开头)配置的管理端点将从配置的根路径提供服务。例如,如果端点路径是 health,根路径是 management,则结果路径是 /management/health

  • 使用绝对路径(以 / 开头)配置的管理端点将从根目录提供服务。例如,如果端点路径是 /health,则结果路径是 /health,无论根路径如何。

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

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

4. 在扩展中创建管理端点

要从应用程序代码中将端点公开到管理界面,请参阅应用程序部分

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

如果您不启用管理界面,这些端点将使用主 HTTP 服务器(默认在 /q 下)提供服务。

扩展可以通过定义一个非应用程序路由并调用 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。否则,它将公开在:https://:8080/q/my-path

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

5. 在管理界面上公开端点(作为应用程序)

您可以通过在管理路由器上注册路由来公开端点到管理界面。要访问路由器,请使用以下代码。

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 访问。

有关 Router API 的更多详细信息,请参阅Vert.x Web 文档

6. 管理界面配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

启用/禁用使用单独的接口/端口来公开管理端点。如果设置为 true,管理端点将被公开到不同的 HTTP 服务器。这可以避免在任何可用的服务器上公开管理端点(。

环境变量:QUARKUS_MANAGEMENT_ENABLED

显示更多

布尔值

false

是否应启用管理界面的身份验证。

环境变量:QUARKUS_MANAGEMENT_AUTH_ENABLED

显示更多

布尔值

${quarkus.management.auth.basic:false}

是否应启用基本身份验证。

环境变量:QUARKUS_MANAGEMENT_AUTH_BASIC

显示更多

布尔值

如果此设置为 true 且存在凭据,则用户将在请求继续之前始终进行身份验证。

如果此设置为 false,则仅在执行权限检查或出于其他原因需要当前用户时,才会尝试对用户进行身份验证。

环境变量:QUARKUS_MANAGEMENT_AUTH_PROACTIVE

显示更多

布尔值

true

配置引擎以要求/请求客户端身份验证。NONE、REQUEST、REQUIRED

环境变量:QUARKUS_MANAGEMENT_SSL_CLIENT_AUTH

显示更多

none, request, required

none

管理端点的通用根路径。各种扩展提供的管理端点(如指标和健康检查)默认在此路径下部署。

环境变量:QUARKUS_MANAGEMENT_ROOT_PATH

显示更多

字符串

/q

是否应压缩响应。

请注意,这将尝试压缩所有响应,为避免压缩已压缩的内容(如图像),您需要设置以下标头

Content-Encoding: identity

这将告诉 vert.x 不要压缩响应。

环境变量:QUARKUS_MANAGEMENT_ENABLE_COMPRESSION

显示更多

布尔值

false

启用时,vert.x 将解压缩请求的正文(如果已压缩)。

请注意,压缩格式(例如 gzip)必须在请求的 Content-Encoding 标头中指定。

环境变量:QUARKUS_MANAGEMENT_ENABLE_DECOMPRESSION

显示更多

布尔值

false

启用压缩支持时使用的压缩级别。

环境变量:QUARKUS_MANAGEMENT_COMPRESSION_LEVEL

显示更多

整数

SecurityIdentity 角色映射到部署特定的角色,并将匹配的角色添加到 SecurityIdentity

例如,如果 SecurityIdentity 具有 user 角色,并且端点受到 'UserRole' 角色的保护,请使用此属性将 user 角色映射到 UserRole 角色,并使 SecurityIdentity 同时拥有 userUserRole 角色。

环境变量:QUARKUS_MANAGEMENT_AUTH_ROLES_MAPPING__ROLE_NAME_

显示更多

Map<String,List<String>>

HTTP 端口

环境变量:QUARKUS_MANAGEMENT_PORT

显示更多

整数

9000

HTTP 端口

环境变量:QUARKUS_MANAGEMENT_TEST_PORT

显示更多

整数

9001

HTTP 主机

在开发/测试模式下,默认为 localhost;在生产模式下,默认为 0.0.0.0。

默认为 0.0.0.0 使 Quarkus 更容易部署到容器中,但它不适用于开发/测试模式,因为网络上的其他人可以连接到您的开发机器。

作为例外,当在 Windows Subsystem for Linux (WSL) 中运行时,即使在开发/测试模式下,HTTP 主机也默认为 0.0.0.0,因为使用 localhost 会使应用程序无法访问。

环境变量:QUARKUS_MANAGEMENT_HOST

显示更多

字符串

必需

启用监听主机:端口。

环境变量:QUARKUS_MANAGEMENT_HOST_ENABLED

显示更多

布尔值

true

CredentialsProvider。如果配置了此属性,则将使用匹配的 'CredentialsProvider' 来获取密钥库、密钥库密钥和信任库密码,除非这些密码已配置。

请注意,除非使用 CredentialsProvider 提供额外的安全性和动态性,否则应优先使用 Quarkus Configuration 直接支持的 MicroProfile ConfigSource

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_CREDENTIALS_PROVIDER

显示更多

字符串

凭据提供程序 bean 名称。

这是实现 CredentialsProvider 的 bean 的 bean 名称(如 @Named 中)。当存在多个凭据提供程序时,它用于选择凭据提供程序 bean。当只有一个凭据提供程序可用时,这是不必要的。

对于 Vault,凭据提供程序 bean 名称为 vault-credentials-provider

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_CREDENTIALS_PROVIDER_NAME

显示更多

字符串

使用 PEM 格式的服务器证书文件路径列表。指定多个文件需要启用 SNI。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_FILES

显示更多

路径列表

使用 PEM 格式的服务器证书私钥文件路径列表。指定多个文件需要启用 SNI。

密钥文件的顺序必须与证书的顺序匹配。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_FILES

显示更多

路径列表

一个可选的密钥库,它包含证书信息,而不是指定单独的文件。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_FILE

显示更多

path

一个可选参数,用于指定密钥库文件的类型。 如果未给出,则根据文件名自动检测类型。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_FILE_TYPE

显示更多

字符串

一个可选参数,用于指定密钥库文件的提供程序。如果未提供,则根据密钥库文件类型自动检测提供程序。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PROVIDER

显示更多

字符串

一个参数,用于指定密钥库文件的密码。如果未提供,并且无法从 CredentialsProvider 检索,则需要此参数。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PASSWORD

显示更多

字符串

一个参数,用于指定 CredentialsProvider 属性键,该键可用于从 CredentialsProvider 获取密钥库文件的密码。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PASSWORD_KEY

显示更多

字符串

一个可选参数,用于从密钥库中选择特定的密钥。当 SNI 被禁用,并且密钥库包含多个密钥而未指定别名时,行为是未定义的。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_ALIAS

显示更多

字符串

一个可选参数,用于定义密钥的密码,以防它与 key-store-password 不同。如果未提供,则可能从 CredentialsProvider 检索。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_ALIAS_PASSWORD

显示更多

字符串

一个参数,用于指定 CredentialsProvider 属性键,该键可用于从 CredentialsProvider 获取别名的密码。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_ALIAS_PASSWORD_KEY

显示更多

字符串

一个可选的信任库,它包含受信任证书的信息。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_FILE

显示更多

path

使用 PEM 格式的可选受信任证书列表。如果您提供多个文件,则必须使用 PEM 格式。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_FILES

显示更多

路径列表

一个可选参数,用于指定信任库文件的类型。如果未提供,则根据文件名自动检测类型。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_FILE_TYPE

显示更多

字符串

一个可选参数,用于指定信任库文件的提供程序。如果未提供,则根据信任库文件类型自动检测提供程序。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PROVIDER

显示更多

字符串

一个参数,用于指定信任库文件的密码。如果未提供,并且无法从 CredentialsProvider 检索,则需要此参数。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PASSWORD

显示更多

字符串

一个参数,用于指定 CredentialsProvider 属性键,该键可用于从 CredentialsProvider 获取信任库文件的密码。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PASSWORD_KEY

显示更多

字符串

一个可选参数,用于信任信任库中的单个证书,而不是信任信任库中的所有证书。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_CERT_ALIAS

显示更多

字符串

设置后,配置的证书将在给定周期后重新加载。请注意,仅当文件已修改时,证书才会重新加载。

此外,当 TLS 证书使用路径(而不是内存中)配置时,也可以发生更新。

重新加载周期必须等于或大于 30 秒。如果未设置,证书将不会重新加载。

建议使用 TLS 注册表来处理证书重新加载。

环境变量:QUARKUS_MANAGEMENT_SSL_CERTIFICATE_RELOAD_PERIOD

显示更多

Duration 

要使用的密码套件。 如果未给出,则选择合理的默认值。

环境变量:QUARKUS_MANAGEMENT_SSL_CIPHER_SUITES

显示更多

字符串列表

设置已启用 SSL/TLS 协议的有序列表。

如果未设置,则默认为 "TLSv1.3, TLSv1.2"。 支持以下协议列表:TLSv1, TLSv1.1, TLSv1.2, TLSv1.3。 要仅启用 TLSv1.3,请将值设置为 to "TLSv1.3"

请注意,设置一个空列表并启用 SSL/TLS 是无效的。 您必须至少有一个协议。

环境变量:QUARKUS_MANAGEMENT_SSL_PROTOCOLS

显示更多

字符串列表

TLSv1.3,TLSv1.2

启用服务器名称指示 (SNI),这是一种 TLS 扩展,允许服务器使用多个证书。客户端在 TLS 握手期间指示服务器名称,允许服务器选择正确的证书。

环境变量:QUARKUS_MANAGEMENT_SSL_SNI

显示更多

布尔值

false

要使用的 TLS 配置的名称。

如果未设置且默认 TLS 配置已配置(quarkus.tls.*),则将使用默认配置。如果配置了名称,则使用 quarkus.tls.<name>.* 的配置。如果配置了名称,但找不到具有该名称的 TLS 配置,则会引发错误。

如果未设置 TLS 配置,并且未配置 quarkus.tls.*,则将使用 quarkus.management.ssl

环境变量:QUARKUS_MANAGEMENT_TLS_CONFIGURATION_NAME

显示更多

字符串

当设置为 true 时,HTTP 服务器会在请求需要时(带有 Expect: 100-Continue 标头)自动发送 100 CONTINUE 响应。

环境变量:QUARKUS_MANAGEMENT_HANDLE_100_CONTINUE_AUTOMATICALLY

显示更多

布尔值

false

所有标头的最大长度,最多 Integer.MAX_VALUE 个字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE

显示更多

MemorySize 

20K

请求正文的最大大小,最多 Long.MAX_VALUE 个字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE

显示更多

MemorySize 

10240K

最大 HTTP 块大小,最多 Integer.MAX_VALUE 个字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE

显示更多

MemorySize 

8192

初始行的最大长度(例如 "GET / HTTP/1.0")。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH

显示更多

整数

4096

表单属性的最大长度,最多 Integer.MAX_VALUE 个字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

显示更多

MemorySize 

2048

设置表单的最大字段数。 设置为 -1 以允许无限数量的属性。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_FIELDS

显示更多

整数

256

设置服务器在解码表单时可以缓冲的最大字节数。 设置为 -1 以允许无限长度,最多 Integer.MAX_VALUE 个字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_BUFFERED_BYTES

显示更多

MemorySize 

1K

允许传入请求的最大 HTTP 请求参数数。

如果客户端在请求中发送的参数超过此数量,则连接将关闭。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_PARAMETERS

显示更多

整数

1000

一次允许的最大连接数。 如果设置了此值,建议设置一个短的空闲超时时间。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_CONNECTIONS

显示更多

整数

设置 SETTINGS_HEADER_TABLE_SIZE HTTP/2 设置。

允许发送方告知接收方用于解码头块的头压缩表的最大大小(以字节为单位)。编码器可以选择等于或小于此值的大小,通过在头块内部使用特定于头压缩格式的信号。初始值为 4,096 字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_HEADER_TABLE_SIZE

显示更多

long

设置 SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 设置。

指示发送方允许的最大并发流数。此限制是方向性的:它适用于发送方允许接收方创建的流数。最初,此值没有限制。建议此值不小于 100,以避免不必要地限制并行性。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_CONCURRENT_STREAMS

显示更多

long

设置 SETTINGS_MAX_FRAME_SIZE HTTP/2 设置。 指示发送方愿意接收的最大帧有效负载的大小(以八位字节为单位)。 初始值为 2^14 (16,384) 个八位字节。

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_FRAME_SIZE

显示更多

整数

设置 SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 设置。此咨询性设置告知对等方发送方准备接受的头列表的最大大小(以字节为单位)。该值基于头字段的未压缩大小,包括名称和值的长度(以字节为单位)加上每个头字段的 32 字节开销。默认值为 8192

环境变量:QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_LIST_SIZE

显示更多

long

设置时间窗口内允许的 RST 帧的最大数量,用于防止HTTP/2 RST 帧洪水 DDOS 攻击。默认值为 200,设置为零或负值会禁用洪水防护。

环境变量:QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

显示更多

整数

设置检查 RST 帧最大数量时的时间窗口持续时间,用于防止HTTP/2 RST 帧洪水 DDOS 攻击。默认值为 30 s,设置为零或负值会禁用洪水防护。

环境变量:QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_WINDOW_DURATION

显示更多

Duration 

HTTP 连接空闲超时

环境变量:QUARKUS_MANAGEMENT_IDLE_TIMEOUT

显示更多

Duration 

30M

使用 multipart/form-data 发送的文件是否会本地存储。

如果为 true,它们将存储在 quarkus.http.body-handler.uploads-directory 中,并通过 io.vertx.ext.web.RoutingContext.fileUploads() 提供。否则,使用 multipart/form-data 发送的文件将不会本地存储,并且 io.vertx.ext.web.RoutingContext.fileUploads() 将始终返回一个空集合。请注意,即使此选项设置为 falsemultipart/form-data 请求仍将被接受。

环境变量:QUARKUS_MANAGEMENT_BODY_HANDLE_FILE_UPLOADS

显示更多

布尔值

true

使用 multipart/form-data 发送的文件应存储的目录。

可以是绝对路径,也可以是相对于应用程序进程当前目录的路径。

环境变量:QUARKUS_MANAGEMENT_BODY_UPLOADS_DIRECTORY

显示更多

字符串

${java.io.tmpdir}/uploads

表单属性是否应添加到请求参数中。

如果为 true,则表单属性将被添加到请求参数中;否则,表单参数将不会被添加到请求参数中。

环境变量:QUARKUS_MANAGEMENT_BODY_MERGE_FORM_ATTRIBUTES

显示更多

布尔值

true

请求处理结束后是否应删除已上传的文件。

如果为 true,则存储在 quarkus.http.body-handler.uploads-directory 中的已上传文件将在处理请求后被删除。否则,文件将永远保留在那里。

环境变量:QUARKUS_MANAGEMENT_BODY_DELETE_UPLOADED_FILES_ON_END

显示更多

布尔值

true

是否应根据 Content-Length 标头值预先分配正文缓冲区。

如果为 true,则根据从 Content-Length 标头读取的大小预先分配正文缓冲区;否则,正文缓冲区预先分配为 1KB,并动态调整大小。

环境变量:QUARKUS_MANAGEMENT_BODY_PREALLOCATE_BODY_BUFFER

显示更多

布尔值

false

一个逗号分隔的 ContentType 列表,用于指示是否应将给定的 multipart 字段作为文件部分处理。

您可以使用此设置根据其内容类型强制基于 HTTP 的扩展将消息部分作为文件进行解析。

目前,此设置仅在使用 RESTEasy Reactive 时有效。

环境变量:QUARKUS_MANAGEMENT_BODY_MULTIPART_FILE_CONTENT_TYPES

显示更多

字符串列表

接受积压,这是在连接开始被拒绝之前可以等待被接受的连接数。

环境变量:QUARKUS_MANAGEMENT_ACCEPT_BACKLOG

显示更多

整数

-1

unix 域套接字路径

环境变量:QUARKUS_MANAGEMENT_DOMAIN_SOCKET

显示更多

字符串

/var/run/io.quarkus.management.socket

启用监听主机:端口。

环境变量:QUARKUS_MANAGEMENT_DOMAIN_SOCKET_ENABLED

显示更多

布尔值

false

设置服务器是否应在代理服务器后面处理请求时使用 HA PROXY 协议(请参阅PROXY 协议)。当设置为 true 时,返回的远程地址将是实际连接客户端的地址。如果设置为 false(默认值),则返回的远程地址将是代理的地址。

环境变量:QUARKUS_MANAGEMENT_PROXY_USE_PROXY_PROTOCOL

显示更多

布尔值

false

如果此设置为 true,则地址、协议等将从代理服务器转发的标头(如 X-Forwarded-For)设置。只有在您位于设置了这些标头的代理后面时,才应设置此项。

环境变量:QUARKUS_MANAGEMENT_PROXY_PROXY_ADDRESS_FORWARDING

显示更多

布尔值

false

如果此设置为 true,并且启用了代理地址转发,那么将使用标准的 Forwarded 标头。如果启用了非标准的 X-Forwarded-For 标头并在 HTTP 请求中检测到,则标准标头具有优先权。激活此项并与 quarkus.http.proxy.allow-x-forwarded 一起使用会带来安全风险,因为客户端可以伪造未被代理覆盖的转发标头。因此,代理应删除客户端的意外 ForwardedX-Forwarded-* 标头。

环境变量:QUARKUS_MANAGEMENT_PROXY_ALLOW_FORWARDED

显示更多

布尔值

false

如果此项或 allow-forwarded 为 true 且启用了代理地址转发,则将使用非标准的 Forwarded 标头。如果启用了标准 Forwarded 标头并在 HTTP 请求中检测到,则标准标头具有优先权。激活此项并与 quarkus.http.proxy.allow-forwarded 一起使用会带来安全风险,因为客户端可以伪造未被代理覆盖的转发标头。因此,代理应删除客户端的意外 ForwardedX-Forwarded-* 标头。

环境变量:QUARKUS_MANAGEMENT_PROXY_ALLOW_X_FORWARDED

显示更多

布尔值

当 Forwarded 和 X-Forwarded 标头都启用(分别为 allow-forwardedallow-x-forwarded)且 strict-forwarded-control 强制要求相同的标头必须具有相同值时,则执行此检查。

环境变量:QUARKUS_MANAGEMENT_PROXY_STRICT_FORWARDED_CONTROL

显示更多

布尔值

true

当 Forwarded 和 X-Forwarded 标头都启用(分别为 allow-forwardedallow-x-forwarded)且 strict-forwarded-control 强制要求相同的标头必须具有相同值被禁用时,选择是 Forwarded 还是 X-Forwarded 匹配标头值具有优先权。

例如,如果 Forwarded 优先于 X-Forwarded,Forwarded 协议是 http,X-Forwarded 协议是 https,则最终协议值是 http。如果 X-Forwarded 优先,则最终协议值是 https

环境变量:QUARKUS_MANAGEMENT_PROXY_FORWARDED_PRECEDENCE

显示更多

forwarded, x-forwarded

forwarded

启用通过转发的主机标头覆盖收到的请求主机。

环境变量:QUARKUS_MANAGEMENT_PROXY_ENABLE_FORWARDED_HOST

显示更多

布尔值

false

如果启用了覆盖,则配置要使用的转发主机标头。

环境变量:QUARKUS_MANAGEMENT_PROXY_FORWARDED_HOST_HEADER

显示更多

字符串

X-Forwarded-Host

启用通过转发前缀标头添加收到的请求路径。

环境变量:QUARKUS_MANAGEMENT_PROXY_ENABLE_FORWARDED_PREFIX

显示更多

布尔值

false

如果启用了前缀,则配置要使用的转发前缀标头。

环境变量:QUARKUS_MANAGEMENT_PROXY_FORWARDED_PREFIX_HEADER

显示更多

字符串

X-Forwarded-Prefix

如果请求由受信任的代理转发,则添加 X-Forwarded-Trusted-Proxy 标头。如果请求由受信任的代理转发,则值为 true,否则为 null

转发解析器会检测伪造尝试,如果传入请求包含此标头,则会将其从请求中移除。

X-Forwarded-Trusted-Proxy 标头是自定义标头,不是标准 Forwarded 标头的一部分。

环境变量:QUARKUS_MANAGEMENT_PROXY_ENABLE_TRUSTED_PROXY_HEADER

显示更多

布尔值

false

配置受信任代理地址列表。来自任何其他代理地址的 ForwardedX-ForwardedX-Forwarded-* 标头将被忽略。受信任代理地址应指定为 IP 地址(IPv4 或 IPv6)、主机名或无类别域间路由 (CIDR) 表示法。请注意,Quarkus 在请求期间需要对所有主机名执行 DNS 查找。因此,不建议使用主机名。

套接字地址的示例,形式为 hosthost:port

  • 127.0.0.1:8084

  • [0:0:0:0:0:0:0:1]

  • [0:0:0:0:0:0:0:1]:8084

  • [::]

  • localhost

  • localhost:8084

CIDR 表示法的示例

  • ::/128

  • ::/0

  • 127.0.0.0/8

请记住,IPv4 CIDR 不会匹配从 IPv6 地址发送的请求,反之亦然。

环境变量:QUARKUS_MANAGEMENT_PROXY_TRUSTED_PROXIES

显示更多

TrustedProxyCheckPart 列表

所有代理地址都受信任

确定是否启用整个权限集。

默认情况下,如果定义了权限集,则启用它。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__ENABLED

显示更多

布尔值

此权限集链接到的 HTTP 策略。

有三种内置策略:permit、deny 和 authenticated。可以定义基于角色的策略,扩展可以添加自己的策略。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__POLICY

显示更多

字符串

必需

此权限集适用的方法。如果未设置,则它们适用于所有方法。

请注意,如果请求匹配任何权限集中的任何路径,但由于未列出该方法而与约束不匹配,则该请求将被拒绝。

方法特定的权限优先于没有任何方法设置的匹配项。

这意味着例如,如果 Quarkus 配置为允许 GET 和 POST 请求到 /admin,并且没有配置其他权限,则对 /admin 的 PUT 请求将被拒绝。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__METHODS

显示更多

字符串列表

此权限检查适用的路径。如果路径以 /* 结尾,则将其视为路径前缀,否则将其视为完全匹配。

匹配是基于长度完成的,因此最具体的路径匹配优先。

如果多个权限集匹配同一路径,则显式方法匹配优先于没有方法设置的匹配,否则将应用最严格的权限。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__PATHS

显示更多

字符串列表

路径特定的身份验证机制,必须用于验证用户身份。它需要匹配 io.quarkus.vertx.http.runtime.security.HttpCredentialTransport 身份验证方案,例如“basic”、“bearer”、“form”等。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__AUTH_MECHANISM

显示更多

字符串

指示此策略始终应用于匹配的路径,以及具有获胜路径的策略。避免创建多个共享策略以最大限度地减少性能影响。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__SHARED

显示更多

布尔值

false

权限检查应应用于所有匹配的路径,还是 Jakarta REST 资源特定的路径。

环境变量:QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__APPLIES_TO

显示更多

all应用于所有匹配的路径。, jaxrs声明权限检查仅应用于 Jakarta REST 请求路径。使用此选项可以延迟权限检查,如果使用特定于匹配的 Jakarta REST 端点的注释选择了身份验证机制。如果使用了以下 REST 端点注释,则必须设置此选项: - io.quarkus.oidc.Tenant 注释,用于选择具有租户标识符的 OIDC 身份验证机制 - io.quarkus.vertx.http.runtime.security.annotation.BasicAuthentication 注释,用于选择基本身份验证机制 - io.quarkus.vertx.http.runtime.security.annotation.FormAuthentication 注释,用于选择基于表单的身份验证机制 - io.quarkus.vertx.http.runtime.security.annotation.MTLSAuthentication 注释,用于选择 mTLS 身份验证机制 - io.quarkus.security.webauthn.WebAuthn 注释,用于选择 WebAuthn 身份验证机制 - io.quarkus.oidc.BearerTokenAuthentication 注释,用于选择 OpenID Connect 承载令牌身份验证机制 - io.quarkus.oidc.AuthorizationCodeFlow 注释,用于选择 OpenID Connect Code 身份验证机制

all应用于所有匹配的路径。

允许访问受此策略保护的资源的各个角色。默认情况下,允许任何经过身份验证的用户访问。

环境变量:QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__ROLES_ALLOWED

显示更多

字符串列表

**

根据 SecurityIdentity 已有的角色,授予 SecurityIdentity 的角色。例如,Quarkus OIDC 扩展可以从验证过的 JWT 访问令牌映射角色,您可能希望将它们重新映射到特定于部署的角色。

环境变量:QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__ROLES__ROLE_NAME_

显示更多

Map<String,List<String>>

如果此策略成功应用(策略允许请求继续),并且已认证的请求具有必需的角色,则授予 SecurityIdentity 的权限。例如,您可以通过设置 quarkus.http.auth.policy.role-policy1.permissions.admin=perm1:action1,perm1:action2 配置属性,将权限 perm1 和操作 action1action2 映射到角色 admin。授予的权限用于使用 @PermissionsAllowed 注释进行授权。

环境变量:QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__PERMISSIONS__ROLE_NAME_

显示更多

Map<String,List<String>>

此策略授予的权限将使用此配置属性指定的 java.security.Permission 实现创建。权限类必须声明一个接受权限名称 (String) 或权限名称和操作 (String, String[]) 的构造函数。如果在原生模式下运行应用程序,则必须注册权限类以进行反射。

环境变量:QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__PERMISSION_CLASS

显示更多

字符串

io.quarkus.security.StringPermission

应应用此标头的路径

环境变量:QUARKUS_MANAGEMENT_HEADER__HEADER__PATH

显示更多

字符串

/*

此标头配置的值

环境变量:QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE

显示更多

字符串

必需

此标头配置的 HTTP 方法。

如果未指定 HTTP 方法,则将始终添加标头。

环境变量:QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS

显示更多

字符串列表

与此配置匹配的路径的正则表达式

环境变量:QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES

显示更多

字符串

必需

始终在响应中发送的其他 HTTP 标头

环境变量:QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER__HEADER_NAME_

显示更多

Map<String,String>

此路径配置的 HTTP 方法

环境变量:QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS

显示更多

字符串列表

应用此路径配置的顺序。 优先级越高,优先级越高

环境变量:QUARKUS_MANAGEMENT_FILTER__FILTER__ORDER

显示更多

整数

关于 Duration 格式

要写入持续时间值,请使用标准的 java.time.Duration 格式。有关更多信息,请参阅Duration#parse() Java API 文档

您还可以使用简化的格式,以数字开头

  • 如果该值仅为一个数字,则表示以秒为单位的时间。

  • 如果该值是一个数字后跟 ms,则表示以毫秒为单位的时间。

在其他情况下,简化格式将被转换为 java.time.Duration 格式以进行解析

  • 如果该值是一个数字后跟 hms,则在其前面加上 PT

  • 如果该值是一个数字后跟 d,则在其前面加上 P

关于 MemorySize 格式

大小配置选项识别以下格式的字符串(显示为正则表达式):[0-9]+[KkMmGgTtPpEeZzYy]?

如果未给出后缀,则假定为字节。

7. 在反向代理后面运行

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

激活此功能可能会使服务器面临信息伪造等安全风险。仅在反向代理后面运行时激活它。

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

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

要将此行为限制为标准的 Forwarded 标头(并忽略 X-Forwarded 变体),请在 src/main/resources/application.properties 中设置 quarkus.management.proxy.allow-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

如果启用了两种标头变体(ForwardedX-Forwarded-*),则 Forwarded 标头将具有优先权。

同时使用 ForwardedX-Forwarded 标头可能存在安全隐患,因为它可能允许客户端使用代理未覆盖的标头伪造请求。

确保您的代理已配置为从客户端请求中剥离意外的 ForwardedX-Forwarded-* 标头。

8. Kubernetes

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

KNative

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

9. 安全

在单独的 HTTP 服务器上公开的管理端点的安全性需要显式启用,如下面的示例所示。

quarkus.management.enabled=true
quarkus.management.auth.enabled=true

启用后,您可以使用已为主服务器配置的相同身份验证机制,或使用不同的机制。所有这些机制的详细信息都在Quarkus 中的身份验证机制指南中。

9.1. 使用 HTTP 安全策略启用基于路径的身份验证

以下配置示例演示了如何为给定请求路径强制执行单个可选择的身份验证机制。

quarkus.management.auth.permission.metrics.paths=/q/metrics/*
quarkus.management.auth.permission.metrics.policy=authenticated
quarkus.management.auth.permission.metrics.auth-mechanism=basic (1)

quarkus.management.auth.permission.health.paths=/q/health/*
quarkus.management.auth.permission.health.policy=authenticated
quarkus.management.auth.permission.health.auth-mechanism=bearer (2)
1 指标端点只能通过基本身份验证进行访问。
2 如果存在 Quarkus OIDC 扩展,健康端点将通过OIDC 承载令牌身份验证进行身份验证。

9.2. 基本身份验证

您可以使用以下属性启用基本身份验证。

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

有关 Quarkus 中基本身份验证的更多详细信息,请参阅基本身份验证指南

10. 在测试中注入管理 URL

在测试您的应用程序时,您可以使用 @TestHTTPResource 注释注入管理 URL。

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

management 属性设置为 true,表示注入的 URL 是管理界面的。context-root 会自动添加。因此,在前面的示例中,注入的 URL 是 https://:9001/q/management

@TestHTTPResource 在将管理 test-port 设置为 0 时特别有用,这意味着系统将为管理界面分配一个随机端口。

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

相关内容