管理界面参考
默认情况下,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 服务器不同,管理界面不能同时处理 http 和 https。如果配置了 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 根路径。
|
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 且存在凭据,则用户将在请求继续之前始终进行身份验证。 如果此设置为 false,则仅在执行权限检查或出于其他原因需要当前用户时,才会尝试对用户进行身份验证。 环境变量: 显示更多 |
布尔值 |
|
||
配置引擎以要求/请求客户端身份验证。NONE、REQUEST、REQUIRED 环境变量: 显示更多 |
|
|
||
管理端点的通用根路径。各种扩展提供的管理端点(如指标和健康检查)默认在此路径下部署。 环境变量: 显示更多 |
字符串 |
|
||
是否应压缩响应。 请注意,这将尝试压缩所有响应,为避免压缩已压缩的内容(如图像),您需要设置以下标头 Content-Encoding: identity 这将告诉 vert.x 不要压缩响应。 环境变量: 显示更多 |
布尔值 |
|
||
启用时,vert.x 将解压缩请求的正文(如果已压缩)。 请注意,压缩格式(例如 gzip)必须在请求的 Content-Encoding 标头中指定。 环境变量: 显示更多 |
布尔值 |
|
||
整数 |
||||
将 例如,如果 环境变量: 显示更多 |
Map<String,List<String>> |
|||
整数 |
|
|||
整数 |
|
|||
HTTP 主机 在开发/测试模式下,默认为 localhost;在生产模式下,默认为 0.0.0.0。 默认为 0.0.0.0 使 Quarkus 更容易部署到容器中,但它不适用于开发/测试模式,因为网络上的其他人可以连接到您的开发机器。 作为例外,当在 Windows Subsystem for Linux (WSL) 中运行时,即使在开发/测试模式下,HTTP 主机也默认为 0.0.0.0,因为使用 localhost 会使应用程序无法访问。 环境变量: 显示更多 |
字符串 |
必需 |
||
布尔值 |
|
|||
请注意,除非使用 环境变量: 显示更多 |
字符串 |
|||
凭据提供程序 bean 名称。 这是实现 对于 Vault,凭据提供程序 bean 名称为 环境变量: 显示更多 |
字符串 |
|||
使用 PEM 格式的服务器证书文件路径列表。指定多个文件需要启用 SNI。 环境变量: 显示更多 |
路径列表 |
|||
使用 PEM 格式的服务器证书私钥文件路径列表。指定多个文件需要启用 SNI。 密钥文件的顺序必须与证书的顺序匹配。 环境变量: 显示更多 |
路径列表 |
|||
一个可选的密钥库,它包含证书信息,而不是指定单独的文件。 环境变量: 显示更多 |
path |
|||
一个可选参数,用于指定密钥库文件的类型。 如果未给出,则根据文件名自动检测类型。 环境变量: 显示更多 |
字符串 |
|||
一个可选参数,用于指定密钥库文件的提供程序。如果未提供,则根据密钥库文件类型自动检测提供程序。 环境变量: 显示更多 |
字符串 |
|||
一个参数,用于指定密钥库文件的密码。如果未提供,并且无法从 环境变量: 显示更多 |
字符串 |
|||
一个参数,用于指定 环境变量: 显示更多 |
字符串 |
|||
一个可选参数,用于从密钥库中选择特定的密钥。当 SNI 被禁用,并且密钥库包含多个密钥而未指定别名时,行为是未定义的。 环境变量: 显示更多 |
字符串 |
|||
一个可选参数,用于定义密钥的密码,以防它与 环境变量: 显示更多 |
字符串 |
|||
一个参数,用于指定 环境变量: 显示更多 |
字符串 |
|||
一个可选的信任库,它包含受信任证书的信息。 环境变量: 显示更多 |
path |
|||
使用 PEM 格式的可选受信任证书列表。如果您提供多个文件,则必须使用 PEM 格式。 环境变量: 显示更多 |
路径列表 |
|||
一个可选参数,用于指定信任库文件的类型。如果未提供,则根据文件名自动检测类型。 环境变量: 显示更多 |
字符串 |
|||
一个可选参数,用于指定信任库文件的提供程序。如果未提供,则根据信任库文件类型自动检测提供程序。 环境变量: 显示更多 |
字符串 |
|||
一个参数,用于指定信任库文件的密码。如果未提供,并且无法从 环境变量: 显示更多 |
字符串 |
|||
一个参数,用于指定 环境变量: 显示更多 |
字符串 |
|||
一个可选参数,用于信任信任库中的单个证书,而不是信任信任库中的所有证书。 环境变量: 显示更多 |
字符串 |
|||
设置后,配置的证书将在给定周期后重新加载。请注意,仅当文件已修改时,证书才会重新加载。 此外,当 TLS 证书使用路径(而不是内存中)配置时,也可以发生更新。 重新加载周期必须等于或大于 30 秒。如果未设置,证书将不会重新加载。
环境变量: 显示更多 |
||||
要使用的密码套件。 如果未给出,则选择合理的默认值。 环境变量: 显示更多 |
字符串列表 |
|||
设置已启用 SSL/TLS 协议的有序列表。 如果未设置,则默认为 请注意,设置一个空列表并启用 SSL/TLS 是无效的。 您必须至少有一个协议。 环境变量: 显示更多 |
字符串列表 |
|
||
启用服务器名称指示 (SNI),这是一种 TLS 扩展,允许服务器使用多个证书。客户端在 TLS 握手期间指示服务器名称,允许服务器选择正确的证书。 环境变量: 显示更多 |
布尔值 |
|
||
要使用的 TLS 配置的名称。 如果未设置且默认 TLS 配置已配置( 如果未设置 TLS 配置,并且未配置 环境变量: 显示更多 |
字符串 |
|||
当设置为 环境变量: 显示更多 |
布尔值 |
|
||
所有标头的最大长度,最多 环境变量: 显示更多 |
|
|||
请求正文的最大大小,最多 环境变量: 显示更多 |
|
|||
最大 HTTP 块大小,最多 环境变量: 显示更多 |
|
|||
初始行的最大长度(例如 环境变量: 显示更多 |
整数 |
|
||
表单属性的最大长度,最多 环境变量: 显示更多 |
|
|||
设置表单的最大字段数。 设置为 环境变量: 显示更多 |
整数 |
|
||
设置服务器在解码表单时可以缓冲的最大字节数。 设置为 环境变量: 显示更多 |
|
|||
允许传入请求的最大 HTTP 请求参数数。 如果客户端在请求中发送的参数超过此数量,则连接将关闭。 环境变量: 显示更多 |
整数 |
|
||
一次允许的最大连接数。 如果设置了此值,建议设置一个短的空闲超时时间。 环境变量: 显示更多 |
整数 |
|||
设置 SETTINGS_HEADER_TABLE_SIZE HTTP/2 设置。 允许发送方告知接收方用于解码头块的头压缩表的最大大小(以字节为单位)。编码器可以选择等于或小于此值的大小,通过在头块内部使用特定于头压缩格式的信号。初始值为 环境变量: 显示更多 |
long |
|||
设置 SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 设置。 指示发送方允许的最大并发流数。此限制是方向性的:它适用于发送方允许接收方创建的流数。最初,此值没有限制。建议此值不小于 100,以避免不必要地限制并行性。 环境变量: 显示更多 |
long |
|||
设置 SETTINGS_MAX_FRAME_SIZE HTTP/2 设置。 指示发送方愿意接收的最大帧有效负载的大小(以八位字节为单位)。 初始值为 环境变量: 显示更多 |
整数 |
|||
设置 SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 设置。此咨询性设置告知对等方发送方准备接受的头列表的最大大小(以字节为单位)。该值基于头字段的未压缩大小,包括名称和值的长度(以字节为单位)加上每个头字段的 32 字节开销。默认值为 环境变量: 显示更多 |
long |
|||
设置时间窗口内允许的 RST 帧的最大数量,用于防止HTTP/2 RST 帧洪水 DDOS 攻击。默认值为 环境变量: 显示更多 |
整数 |
|||
设置检查 RST 帧最大数量时的时间窗口持续时间,用于防止HTTP/2 RST 帧洪水 DDOS 攻击。默认值为 环境变量: 显示更多 |
||||
|
||||
使用 如果为 环境变量: 显示更多 |
布尔值 |
|
||
使用 可以是绝对路径,也可以是相对于应用程序进程当前目录的路径。 环境变量: 显示更多 |
字符串 |
|
||
表单属性是否应添加到请求参数中。 如果为 环境变量: 显示更多 |
布尔值 |
|
||
请求处理结束后是否应删除已上传的文件。 如果为 环境变量: 显示更多 |
布尔值 |
|
||
是否应根据 如果为 环境变量: 显示更多 |
布尔值 |
|
||
一个逗号分隔的 您可以使用此设置根据其内容类型强制基于 HTTP 的扩展将消息部分作为文件进行解析。 目前,此设置仅在使用 RESTEasy Reactive 时有效。 环境变量: 显示更多 |
字符串列表 |
|||
接受积压,这是在连接开始被拒绝之前可以等待被接受的连接数。 环境变量: 显示更多 |
整数 |
|
||
字符串 |
|
|||
启用监听主机:端口。 环境变量: 显示更多 |
布尔值 |
|
||
设置服务器是否应在代理服务器后面处理请求时使用 HA 环境变量: 显示更多 |
布尔值 |
|
||
如果此设置为 true,则地址、协议等将从代理服务器转发的标头(如 环境变量: 显示更多 |
布尔值 |
|
||
如果此设置为 true,并且启用了代理地址转发,那么将使用标准的 环境变量: 显示更多 |
布尔值 |
|
||
如果此项或 环境变量: 显示更多 |
布尔值 |
|||
当 Forwarded 和 X-Forwarded 标头都启用(分别为 环境变量: 显示更多 |
布尔值 |
|
||
当 Forwarded 和 X-Forwarded 标头都启用(分别为 例如,如果 Forwarded 优先于 X-Forwarded,Forwarded 协议是 环境变量: 显示更多 |
|
|
||
启用通过转发的主机标头覆盖收到的请求主机。 环境变量: 显示更多 |
布尔值 |
|
||
如果启用了覆盖,则配置要使用的转发主机标头。 环境变量: 显示更多 |
字符串 |
|
||
启用通过转发前缀标头添加收到的请求路径。 环境变量: 显示更多 |
布尔值 |
|
||
如果启用了前缀,则配置要使用的转发前缀标头。 环境变量: 显示更多 |
字符串 |
|
||
如果请求由受信任的代理转发,则添加 转发解析器会检测伪造尝试,如果传入请求包含此标头,则会将其从请求中移除。
环境变量: 显示更多 |
布尔值 |
|
||
配置受信任代理地址列表。来自任何其他代理地址的 套接字地址的示例,形式为
CIDR 表示法的示例
请记住,IPv4 CIDR 不会匹配从 IPv6 地址发送的请求,反之亦然。 环境变量: 显示更多 |
TrustedProxyCheckPart 列表 |
|
||
确定是否启用整个权限集。 默认情况下,如果定义了权限集,则启用它。 环境变量: 显示更多 |
布尔值 |
|||
此权限集链接到的 HTTP 策略。 有三种内置策略:permit、deny 和 authenticated。可以定义基于角色的策略,扩展可以添加自己的策略。 环境变量: 显示更多 |
字符串 |
必需 |
||
此权限集适用的方法。如果未设置,则它们适用于所有方法。 请注意,如果请求匹配任何权限集中的任何路径,但由于未列出该方法而与约束不匹配,则该请求将被拒绝。 方法特定的权限优先于没有任何方法设置的匹配项。 这意味着例如,如果 Quarkus 配置为允许 GET 和 POST 请求到 /admin,并且没有配置其他权限,则对 /admin 的 PUT 请求将被拒绝。 环境变量: 显示更多 |
字符串列表 |
|||
此权限检查适用的路径。如果路径以 /* 结尾,则将其视为路径前缀,否则将其视为完全匹配。 匹配是基于长度完成的,因此最具体的路径匹配优先。 如果多个权限集匹配同一路径,则显式方法匹配优先于没有方法设置的匹配,否则将应用最严格的权限。 环境变量: 显示更多 |
字符串列表 |
|||
路径特定的身份验证机制,必须用于验证用户身份。它需要匹配 环境变量: 显示更多 |
字符串 |
|||
指示此策略始终应用于匹配的路径,以及具有获胜路径的策略。避免创建多个共享策略以最大限度地减少性能影响。 环境变量: 显示更多 |
布尔值 |
|
||
权限检查应应用于所有匹配的路径,还是 Jakarta REST 资源特定的路径。 环境变量: 显示更多 |
|
|
||
允许访问受此策略保护的资源的各个角色。默认情况下,允许任何经过身份验证的用户访问。 环境变量: 显示更多 |
字符串列表 |
|
||
根据 环境变量: 显示更多 |
Map<String,List<String>> |
|||
如果此策略成功应用(策略允许请求继续),并且已认证的请求具有必需的角色,则授予 环境变量: 显示更多 |
Map<String,List<String>> |
|||
此策略授予的权限将使用此配置属性指定的 环境变量: 显示更多 |
字符串 |
|
||
字符串 |
|
|||
字符串 |
必需 |
|||
此标头配置的 HTTP 方法。 如果未指定 HTTP 方法,则将始终添加标头。 环境变量: 显示更多 |
字符串列表 |
|||
与此配置匹配的路径的正则表达式 环境变量: 显示更多 |
字符串 |
必需 |
||
始终在响应中发送的其他 HTTP 标头 环境变量: 显示更多 |
Map<String,String> |
|||
此路径配置的 HTTP 方法 环境变量: 显示更多 |
字符串列表 |
|||
应用此路径配置的顺序。 优先级越高,优先级越高 环境变量: 显示更多 |
整数 |
关于 Duration 格式
要写入持续时间值,请使用标准的 您还可以使用简化的格式,以数字开头
在其他情况下,简化格式将被转换为
|
关于 MemorySize 格式
大小配置选项识别以下格式的字符串(显示为正则表达式): 如果未给出后缀,则假定为字节。 |
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
如果启用了两种标头变体(Forwarded
和 X-Forwarded-*
),则 Forwarded
标头将具有优先权。
同时使用 Forwarded 和 X-Forwarded 标头可能存在安全隐患,因为它可能允许客户端使用代理未覆盖的标头伪造请求。 |
确保您的代理已配置为从客户端请求中剥离意外的 Forwarded
或 X-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
----