配置管理接口

了解如何配置 Keycloak 的管理接口，用于指标和健康检查等端点。

管理接口允许通过与主 HTTP 服务器不同的 HTTP 服务器访问管理端点。它提供了从外部世界隐藏 /metrics 或 /health 等端点的可能性，从而加强了安全性。在 Kubernetes 环境中，最重要的优势可能在于特定的管理端口可能不会暴露。

管理接口配置

当管理接口上暴露某些内容时，管理接口就会被启用。当启用指标和健康检查时，管理端点（如 /metrics 和 /health）会在默认管理端口 9000 上暴露。管理接口提供了一系列选项，并且是完全可配置的。

如果管理接口属性未显式设置，则其值会自动从默认 HTTP 服务器继承。

端口

为了更改管理接口的端口，您可以使用 Keycloak 选项 http-management-port。

相对路径

您可以更改管理接口的相对路径，因为管理端点的前缀路径可能不同。您可以通过 Keycloak 选项 http-management-relative-path 来实现。

例如，如果您设置 CLI 选项 --http-management-relative-path=/management，则指标和健康检查端点将在 /management/metrics 和 /management/health 路径上访问。

当指定相对路径时，用户会自动重定向到 Keycloak 托管的路径。这意味着当相对路径设置为 /management，并且用户访问 localhost:9000/ 时，页面将重定向到 localhost:9000/management。

如果您未显式设置其值，则会使用 http-relative-path 属性的值。例如，如果您设置 CLI 选项 --http-relative-path=/auth，则这些端点可在 /auth/metrics 和 /auth/health 路径上访问。

TLS 支持

当为默认 Keycloak 服务器设置 TLS 时，管理接口也可以通过 HTTPS 访问。管理接口只能在 HTTP 或 HTTPS 上运行，而不能像主服务器那样同时运行两者。

提供了带有前缀 https-management-* 的特定 Keycloak 管理接口选项，用于为管理 HTTP 服务器设置不同的 TLS 参数。它们的功能与主 HTTP 服务器的对应选项类似，有关详细信息，请参阅 配置 TLS。当这些选项未显式设置时，TLS 参数将从默认 HTTP 服务器继承。

禁用管理接口

当管理接口上未暴露任何内容时，管理接口会自动关闭。目前，只有健康检查和指标会暴露在管理接口上。如果您想禁用在管理接口上暴露它们，请将 Keycloak 属性 legacy-observability-interface 设置为 true。

出于安全原因，不建议在默认服务器上暴露健康检查和指标端点，您应始终使用管理接口。请注意，legacy-observability-interface 选项已弃用，并将在未来版本中删除。它仅允许您为迁移留出更多时间。

相关选项

值

http-management-port

管理接口的端口。

仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --http-management-port
Env: KC_HTTP_MANAGEMENT_PORT

9000 (默认)

http-management-relative-path

设置相对于 / 的路径，用于从管理接口提供资源。

路径必须以 / 开头。如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --http-management-relative-path
Env: KC_HTTP_MANAGEMENT_RELATIVE_PATH

/ (默认)

https-management-certificate-file

服务器证书或 PEM 格式证书链的文件路径，用于管理服务器。

如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificate-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE

https-management-certificate-key-file

PEM 格式私钥的文件路径，用于管理服务器。

如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificate-key-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE

https-management-certificates-reload-period

重新加载密钥库、信任库以及 https-management-* 选项引用的证书文件的间隔，用于管理服务器。

可以是 java.time.Duration 值、整数秒数或后跟 [ms, h, m, s, d] 之一的整数。必须大于 30 秒。使用 -1 禁用。如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificates-reload-period
Env: KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD

1h (默认)

https-management-client-auth

配置管理接口以要求/请求客户端身份验证。

如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none (默认), request, required

https-management-key-store-file

密钥库，用于保存证书信息，而不是为管理服务器指定单独的文件。

如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-key-store-file
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_FILE

https-management-key-store-password

密钥库文件的密码，用于管理服务器。

如果未给定，则值从 HTTP 选项继承。仅当管理接口上暴露某些内容时相关 - 请参阅指南了解详细信息。

CLI: --https-management-key-store-password
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD

password (默认)

legacy-observability-interface

是否应在主 HTTP 服务器上暴露指标/健康检查端点（不推荐）。

如果设置为 true，则禁用管理接口。

CLI: --legacy-observability-interface
Env: KC_LEGACY_OBSERVABILITY_INTERFACE

已弃用。

true, false (默认)
在此页上
编辑本指南