KnowForge/Apache Polaris 1.7.0 简体中文
配置

配置 Polaris

师成师成· 更新于 2026-09-29· 阅读 12 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

配置 Polaris

概述

本页介绍如何配置 Apache Polaris。除非另有说明，本文所述内容同时适用于 Polaris Docker 镜像（以及 Kubernetes 部署）和 Polaris 二进制发行版。

📝 注意

有关生产环境的提示与最佳实践，请参阅 为生产环境配置 Polaris。

首先，Polaris 服务端基于 Quarkus 运行，并使用其配置机制。请阅读 Quarkus 的配置指南以熟悉基础知识。

Quarkus 会从多个来源聚合配置属性，并按特定的优先级顺序应用它们。当某个属性在多个来源中都有定义时，优先级较高的来源中的值会覆盖优先级较低来源中的值。

以下按优先级从高到低列出各来源：

  1. 系统属性：通过 Java 命令行使用 -Dproperty.name=value 设置的属性。
  2. 环境变量（详见下文的重要说明）。
  3. $PWD/config/application.properties 文件中的设置。
  4. Polaris 内置打包的 application.properties 文件。
  5. 默认值：应用程序中硬编码的默认值。

使用环境变量时，有两种命名约定：

  1. 如果可能，直接使用属性名作为环境变量名。这在大多数场景下都能正常工作，例如在 Kubernetes 部署中。例如，polaris.realm-context.realms 可以原样写入容器的 YAML 定义：

    env:
- name: "polaris.realm-context.realms"
  value: "realm1,realm2"

  2. 但如果是在脚本或 shell 提示符中运行，则适用更严格的命名规则：变量名只能由大写字母、数字和 _（下划线）组成。在这种情况下，必须从属性名推导出环境变量名，方法是将所有字符转换为大写，并把所有点、短横线和引号替换为下划线。例如，polaris.realm-context.realms 应转换为 POLARIS_REALM_CONTEXT_REALMS。更多详情请参阅此处。

❗重要

虽然使用全大写的环境变量很方便，但对于复杂的属性名可能会带来问题。在这种情况下，建议改用系统属性或配置文件。

如上所述，配置文件也可以在运行时提供；要让 Polaris 服务端识别它，该文件应位于（挂载到）$PWD/config/application.properties。在 Polaris 官方 Docker 镜像中，该路径为 /deployment/config/application.properties。

对于 Kubernetes 部署，配置文件通常定义为 ConfigMap，然后挂载到容器的 /deployment/config/application.properties。该文件可以以只读方式挂载，因为 Polaris 仅在启动时读取一次配置文件。

Polaris 配置选项

有关所有 Polaris 配置选项的完整参考，请参阅配置参考页面。

Quarkus 配置选项

下面列出了一些常用的 Quarkus 配置属性。更多详情请参阅 Quarkus 文档。

配置属性Polaris 中的默认值说明
quarkus.log.levelINFO定义根日志级别。
quarkus.log.category."org.apache.polaris".level定义特定类别的日志级别。
quarkus.default-locale系统区域设置强制使用特定的区域设置，例如 en_US。
quarkus.http.port8181定义 HTTP 端口号。
quarkus.http.auth.basicfalse启用 HTTP 基本身份验证。
quarkus.http.limits.max-body-size10240K定义 HTTP 请求体大小上限。
quarkus.http.cors.enabledfalse启用 HTTP CORS 过滤器。必须设置为 true，其他 CORS 属性才会生效。
quarkus.management.enabledtrue启用管理服务器。
quarkus.management.port8182定义 Polaris 管理服务器的端口号。
quarkus.management.root-path定义 /metrics 和 /health 端点所基于的根路径。
quarkus.otel.sdk.disabledtrue启用 OpenTelemetry 层。

JVM 配置选项

📝 注意

本节仅适用于 Polaris Docker 镜像和 Kubernetes 部署。

官方 Polaris Docker 镜像中还提供了许多其他可操作的环境变量：

环境变量描述
JAVA_OPTS 或 JAVA_OPTIONS不推荐使用。传递给 java 命令的 JVM 选项（例如：-verbose:class）。设置此变量会覆盖本表中其他所有变量设置的任何选项。若要传递额外设置，请改用 JAVA_OPTS_APPEND。
JAVA_OPTS_APPEND用户指定的 Java 选项，将被追加到 JAVA_OPTS 中生成的选项之后（例如：-Dsome.property=foo）。
JAVA_TOOL_OPTIONS此变量由所有 OpenJDK 发行版定义并支持，详见此处。此处定义的选项优先于所有其他选项；通常无需使用此变量，但在某些场景下很有用，例如强制设置 JVM 启动参数、配置远程调试或定义 JVM 代理。
JAVA_MAX_MEM_RATIO用于根据容器的限制计算默认的最大堆内存。如果在没有为容器设置任何内存限制的容器中使用，则此选项不起作用。如果存在内存限制，则 -XX:MaxRAMPercentage 会被设置为这里所设定的容器可用内存的比例。默认值为 80，表示将可用内存的 80% 作为上限。您可以将此值设置为 0 来跳过此机制，此时将不会添加 -XX:MaxRAMPercentage 选项。
JAVA_DEBUG如果设置，将启用远程调试。默认禁用（例如：true）。
JAVA_DEBUG_PORT用于远程调试的端口。默认为 5005（提示：使用 *:5005 可在所有网络接口上启用调试）。
GC_MIN_HEAP_FREE_RATIOGC 后为避免堆扩展所需的最小空闲堆百分比。默认为 10。
GC_MAX_HEAP_FREE_RATIOGC 后为避免堆收缩所需的最大空闲堆百分比。默认为 20。
GC_TIME_RATIO指定花在垃圾回收之外的时间的比例。默认为 4。
GC_ADAPTIVE_SIZE_POLICY_WEIGHT当前 GC 时间与之前 GC 时间相比所占的权重。默认为 90。
GC_METASPACE_SIZE初始元空间大小。没有默认值（例如：20）。
GC_MAX_METASPACE_SIZE最大元空间大小。没有默认值（例如：100）。
GC_CONTAINER_OPTIONS指定要使用的 Java GC。此变量的值应包含指定所需 GC 所必需的 JRE 命令行选项，它将覆盖默认的 -XX:+UseParallelGC（例如：-XX:+UseG1GC）。

以下是几个示例：

示例docker run 选项
使用其他垃圾回收器-e GC_CONTAINER_OPTIONS="-XX:+UseShenandoahGC" 让 Polaris 使用 Shenandoah GC，而非默认的并行 GC。
将 Java 堆大小设置为固定值-e JAVA_OPTS_APPEND="-Xms8g -Xmx8g" 让 Polaris 使用 8g 的 Java 堆。
设置最大堆内存百分比-e JAVA_MAX_MEM_RATIO="70" 让 Polaris 使用可用内存的 70%。

排查配置问题

如果遇到配置相关的问题，可以让 Polaris 打印出它正在使用的配置。为此，请将 io.smallrye.config 日志类别的日志级别设置为 DEBUG，并同时将控制台附加器的级别设置为 DEBUG：

quarkus.log.console.level=DEBUG
quarkus.log.category."io.smallrye.config".level=DEBUG

❗重要提示

这会打印出所有配置值，包括密码等敏感信息。请勿在生产环境中执行，也不要与任何你不信任的人分享这些输出！

评论

登录后参与评论

正在加载评论…