Apache Polaris 1.3 配置参数详解

目标：详解 Apache Polaris 1.3.0-incubating（数据湖目录服务，Java/Quarkus）的配置参数，按 HTTP/存储/认证/Realm/Token 分类给出关键键、默认值与生产建议，并说明参数查看、修改方式与生产配置模板。配置在 Ubuntu 22.04 上实测生效。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• 组件版本：Apache Polaris 1.3.0-incubating（Quarkus 3.29.4）
• 配置来源：server/ 目录中的 Quarkus 运行时配置（application.properties / polaris-server.yml）与环境变量
• 生效机制：Polaris 基于 Quarkus，配置可通过系统属性、环境变量、配置文件注入
• 关键验证命令：ps -ef | grep [j]ava、curl http://localhost:8182/q/health、bin/admin --help

二、前置条件

• 已按安装指南完成 Polaris 1.3 部署并能启动（见《Ubuntu 22.04 安装 Apache Polaris 1.3 指南》）。
• 具备 root 权限，可修改 /opt/polaris/ 下配置。
• 了解 Quarkus 配置优先级：命令行参数 > 系统属性 > 环境变量 > 配置文件 > 默认值。

三、参数查看与修改方式

3.1 查看生效参数

Polaris 无独立的 config show 命令，生效值可通过以下方式确认：

• JVM/HTTP 类参数：ps -ef | grep [j]ava 或查看启动日志 grep "started in" /opt/polaris/server.log
• 注入参数：启动日志的 Profile prod activated. 与 console/config 告警段会列出部分配置项

ps -ef | grep [j]ava
# root 5735 ... /usr/lib/jvm/java-21-openjdk-amd64/bin/java -Xms256m -Xmx512m -jar quarkus-run.jar（ps 输出截断展示）

3.2 修改方式（按优先级）

1. 环境变量（最常用的托管方式）：如 POLARIS_JAVA_OPTS、POLARIS_BOOTSTRAP_CREDENTIALS、POLARIS_REALM_CONTEXT_REALMS。Quarkus 将小写点号键自动映射为大写下划线环境变量（如 quarkus.http.port → QUARKUS_HTTP_PORT）。
2. Java 系统属性：启动时以 -D 传入，如 -Dquarkus.http.port=8080。推荐通过 POLARIS_JAVA_OPTS 批量注入。
3. 配置文件：application.properties 或 polaris-server.yml（放于工作目录/可挂载路径）。

💡 说明：bin/server 启动脚本会读取 ${POLARIS_JAVA_OPTS:-} 并传给 java，是最简洁的注入入口。

四、参数总览

五、核心参数分类详解

5.1 HTTP 与端口段

Polaris 服务包含两个监听端口，通过 quarkus.http.port 与 quarkus.management.port 控制。

quarkus.http.port=8181
quarkus.management.port=8182

• quarkus.http.port：REST Catalog API（/api/catalog/v1/*）与管理 API（/api/management/v1/*）监听端口，默认 8181。
• quarkus.management.port：Quarkus 管理接口端口，默认 8182，用于健康检查 /q/health。

修改示例（改用 8080 作为 REST 端口）：

export POLARIS_JAVA_OPTS="-Dquarkus.http.port=8080"
bin/server

⚠️ 注意：1.3.0-incubating 无内置 Web UI，8080 端口不会默认监听；需要 Web UI 需自行对接前端或使用管理 API/CLI。

5.2 持久化存储段

polaris.persistence.type 决定 Polaris 元数据存储后端。

polaris.persistence.type=relational-jdbc

• in-memory：嵌入式测试元数据库，无需外部 DB，仅建议测试/演示（启动会有生产就绪告警 "current metastore is intended for tests only"，且数据重启丢失）。
• relational-jdbc：关系型数据库后端，生产使用（jar 内已含 jdbc-postgresql 依赖）。

JDBC 相关重试参数：

polaris.persistence.relational.jdbc.max-retries=1
polaris.persistence.relational.jdbc.max_duaration_in_ms=5000
polaris.persistence.relational.jdbc.initial_delay_in_ms=100

💡 说明：本系列实测默认 in-memory 测试库即可完成功能验证；生产部署建议改为 relational-jdbc 并连接 PostgreSQL。

5.3 认证与会话凭证段

root 初始凭证通过环境变量 POLARIS_BOOTSTRAP_CREDENTIALS 或系统属性 polaris.bootstrap.credentials 提供，格式为 realm,clientId,clientSecret（分号分隔多组）。未提供时服务自动生成并打印到 stdout。

export POLARIS_BOOTSTRAP_CREDENTIALS="POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27"
bin/server

⚠️ 注意：环境变量内的三元组用逗号分隔（realm,clientId,clientSecret），而日志中打印的 root 凭证显示格式是 clientId:clientSecret，二者不要混淆。

5.4 Realm 段

polaris.realm-context.* 控制多租户 realm 解析。

polaris.realm-context.realms=POLARIS
polaris.realm-context.type=default
polaris.realm-context.require-header=false
polaris.realm-context.header-name=Polaris-Realm

• realms：可用 realm 列表，多 realm 用逗号分隔。
• require-header：默认 false，将不带 realm 头的请求映射到默认 realm（生产就绪会告警，多租户建议开启）。

5.5 Token 签发与密钥段

polaris.authentication.token-broker.* 控制 JWT 签发器与 RSA 密钥。

polaris.authentication.token-broker.type=rsa-key-pair
polaris.authentication.token-broker.max-token-generation=PT1H
polaris.authentication.token-broker.rsa-key-pair.public-key-file=
polaris.authentication.token-broker.rsa-key-pair.private-key-file=

• type=rsa-key-pair：默认 RSA 非对称签发。
• 公/私钥文件未提供时会自动生成临时密钥对（每次重启密钥变化，旧 token 失效、多实例不兼容），生产应显式配置 public-key-file 与 private-key-file。

5.6 存储访问凭证段

polaris.storage.aws.* 与 polaris.storage.gcp.* 定义对象存储访问凭证。

polaris.storage.aws.access-key=AKIAIOSFODNN7EXAMPLE
polaris.storage.aws.secret-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
polaris.storage.gcp.token=0123456789abcdef0123456789abcdef01234567
polaris.storage.gcp.lifespan=PT1H

⚠️ 注意：上表为 AWS/GCP 官方示例值，仅用于演示格式；生产必须替换为真实云厂商凭证，禁止明文入库。

5.7 存储类型与功能开关段

polaris.features.* 控制功能开关与存储类型限制。

• polaris.features."ALLOW_SETTING_S3_ENDPOINTS"：默认 true，允许 S3 自定义 endpoint。
• polaris.features."SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION"：默认 false，置 true 可跳过凭证子作用域下发、直接用服务端默认凭证（单租户/测试部署常用）。
• polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES"：默认 S3, AZURE, GCS（二进制版不支持 FILE）。

⚠️ 注意：二进制发行版不支持 storageType: FILE，创建 catalog 时用 S3 等类型。

六、生产配置模板

以下按业务场景给出推荐配置模板（内存/磁盘/场景标注）。

6.1 单机测试压测场景（8GB 内存、SSD、功能验证）

quarkus.http.port=8181
quarkus.management.port=8182
polaris.persistence.type=relational-jdbc
polaris.realm-context.require-header=false
polaris.authentication.token-broker.type=rsa-key-pair

启动环境 JVM：

export POLARIS_JAVA_OPTS="-Xms256m -Xmx512m"
export POLARIS_BOOTSTRAP_CREDENTIALS="POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27"
bin/server

6.2 单机生产场景（16GB 内存、NVMe SSD、OLTP 目录）

quarkus.http.port=8181
quarkus.management.port=8182
polaris.persistence.type=relational-jdbc
polaris.persistence.relational.jdbc.max-retries=3
polaris.realm-context.require-header=true
polaris.authentication.token-broker.type=rsa-key-pair
polaris.authentication.token-broker.rsa-key-pair.public-key-file=/etc/polaris/public.pem
polaris.authentication.token-broker.rsa-key-pair.private-key-file=/etc/polaris/private.pem

启动环境 JVM：

export POLARIS_JAVA_OPTS="-Xms512m -Xmx512m"
export POLARIS_BOOTSTRAP_CREDENTIALS="POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27"
bin/server

⚠️ 注意：生产应显式配置 RSA 密钥文件，否则重启后既有 token 全部失效、多实例互相不兼容；明文密钥文件建议存放于权限收紧的 /etc/polaris/。POLARIS_BOOTSTRAP_CREDENTIALS 三元组中 c6a6dcd313a5d7fb 为演示 clientId，生产请改用自定的随机值。

七、常见问题

Q1：为什么启动有 "intended for tests only" 告警？

默认 polaris.persistence.type 为 in-memory 测试库，仅测试用。生产改为 relational-jdbc 并配置数据库即可消除。

Q2：如何让重启后 token 不失效？

显式配置 rsa-key-pair.public-key-file 与 private-key-file，指向持久化的密钥文件（再用 polaris.storage.aws.* 等持久化配置）。

Q3：POLARIS_BOOTSTRAP_CREDENTIALS 为什么报 "Invalid credentials format"？

因为格式化错误：该变量需要逗号分隔的 realm,clientId,clientSecret 三元组，不是 clientId:clientSecret。写成 POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27 即可。

Q4：为什么 8080 没起来？

1.3.0 无 Web UI，8080 默认不监听。若需改 REST 端口，用 -Dquarkus.http.port=8080 注入。

八、参考链接

• Apache Polaris 官方文档：https://polaris.apache.org/
• Polaris 配置文档：https://polaris.apache.org/in-dev/unreleased/configuration.md
• Apache Polaris GitHub：https://github.com/apache/polaris