KnowForge/Apache Polaris 1.7.0 简体中文
配置

生产环境配置

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

为生产环境配置 Polaris

默认的服务器配置面向开发与测试场景。在生产环境部署 Polaris 时，请审查并应用以下检查清单：

  • 配置 OAuth2 密钥
  • 启用 realm 请求头校验（require-header=true）
  • 使用持久化元存储（JDBC + PostgreSQL）
  • 在元存储中初始化有效的 realm
  • 禁用本地 FILE 存储

📝 注意

如果您是使用 Helm Chart 部署 Polaris 的，请务必同时参阅 Helm Chart 生产环境配置 指南。

配置 OAuth2

Polaris 的身份认证需要指定 token broker 工厂类型。开箱即用支持两种实现：

默认情况下，Polaris 使用 rsa-key-pair，密钥为随机生成。

❗ 重要

默认的 rsa-key-pair 配置不适用于部署多个 Polaris 副本的场景，因为每个副本都会拥有各自独立的密钥。当请求被路由到与签发 token 的副本不同的副本时，token 校验将会失败。

强烈建议使用预先生成的 RSA 密钥来配置 Polaris。可以通过设置以下属性来实现：

polaris.authentication.token-broker.type=rsa-key-pair
polaris.authentication.token-broker.rsa-key-pair.public-key-file=/tmp/public.key
polaris.authentication.token-broker.rsa-key-pair.private-key-file=/tmp/private.key

要生成 PKCSdevlive-community/knowforge#8 格式的 RSA 密钥对，可以使用以下命令：

openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private.key -pubout -out public.key

或者，您可以通过设置以下属性来使用对称密钥：

polaris.authentication.token-broker.type=symmetric-key
polaris.authentication.token-broker.symmetric-key.file=/tmp/symmetric.key

注意：也可以直接在配置文件中设置对称密钥密文。如果可能，请通过环境变量传递该密钥，以避免在配置文件中存储敏感信息：

polaris.authentication.token-broker.symmetric-key.secret=${POLARIS_SYMMETRIC_KEY_SECRET}

最后，你还可以通过设置以下属性来为令牌代理配置最大存活时间：

polaris.authentication.token-broker.max-token-generation=PT1H

通常在 Kubernetes 中，你会将这些密钥定义为 Secret，并将其以文件形式挂载到容器中。

Realm 上下文解析器

默认情况下，Polars 会根据传入的请求头解析 realm。你可以在 application.properties 中设置以下属性来配置 realm 上下文解析器：

polaris.realm-context.realms=POLARIS,MY-REALM
polaris.realm-context.header-name=Polaris-Realm

其中：

  • realms 是允许的 realm 的逗号分隔列表。此设置必须正确配置。至少要指定一个 realm。
  • header-name 是用于解析 realm 的请求头名称；默认为 Polaris-Realm。

如果请求包含指定的请求头，Polaris 将使用该请求头中指定的 realm。如果该 realm 不在允许的 realm 列表中，Polaris 将返回 404 Not Found 响应。

但是，如果请求不包含指定的请求头，默认情况下 Polaris 会使用列表中的第一个 realm 作为默认 realm。在上面的示例中，POLARIS 是默认 realm，当请求中不存在 Polaris-Realm 请求头时将使用它。

不建议在生产环境中这样使用，因为它可能导致安全漏洞。为避免这种情况，请将以下属性设置为 true：

polaris.realm-context.require-header=true

这将导致当请求中不存在 realm 头时，Polaris 同样返回 404 Not Found 响应。

元存储配置

元存储应配置为能够持久保存 Polaris 实体的实现。默认情况下，Polaris 使用内存中的元存储。

❗重要

默认的内存元存储不适用于生产环境，因为服务器重启时会丢失所有数据；并且在使用多个 Polaris 副本时无法正常使用。

要启用持久元存储，请将系统配置为使用基于关系型数据库的 JDBC 元存储。该实现借助 Quarkus 进行数据源管理，并支持在启动时通过环境变量或 JVM -D 参数进行配置。有关更多信息，请参阅 Quarkus 配置参考。

通过设置以下环境变量来配置元存储：

POLARIS_PERSISTENCE_TYPE=relational-jdbc

QUARKUS_DATASOURCE_USERNAME=<your-username>
QUARKUS_DATASOURCE_PASSWORD=<your-password>
QUARKUS_DATASOURCE_JDBC_URL=<jdbc-url-of-postgres>

关系型 JDBC 元数据存储库是由 Quarkus 管理的数据源，目前仅支持 Postgres 和 H2。请参阅此处的文档：在 Quarkus 中配置数据源

❗重要

请务必保护好你的元数据存储后端，因为它将存储敏感数据和目录元数据。

注意：Polaris 在引导过程中始终会在所配置的数据库下创建 schema polaris_schema。

引导

在使用 Polaris 之前，你必须对元数据存储库执行引导（bootstrap）。这是一项手动操作，每个 realm 只需执行一次，用于准备元数据存储库以与 Polaris 集成。

默认情况下，在引导新的 realm 时，Polaris 会为 root 主体创建随机的 CLIENT_ID 和 CLIENT_SECRET，并将它们的哈希值存储在元数据存储后端。

这取决于你所使用的数据库，可能并不方便，因为生成的凭据不会以明文形式存储在数据库中。

如果你要为 root 主体提供自己的凭据（以便通过 api/catalog/v1/oauth/tokens 请求令牌），请使用 Polaris 管理工具的 Bootstrap 命令。

你可以通过尝试为 root 主体签发令牌来验证配置：

curl -X POST http://localhost:8181/api/catalog/v1/oauth/tokens \
  -d "grant_type=client_credentials" \
  -d "client_id=my-client-id" \
  -d "client_secret=my-client-secret" \
  -d "scope=PRINCIPAL_ROLE:ALL"

哪个应当返回访问令牌：

{
  "access_token": "...",
  "token_type": "bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 3600
}

如果你使用了非默认的 realm 名称，请在 curl 命令中添加相应的请求头，否则 Polaris 会将 realm 解析为配置项 polaris.realm-context.realms 中的第一个值。下面是一个设置 realm 请求头的示例：

curl -X POST http://localhost:8181/api/catalog/v1/oauth/tokens \
  -H "Polaris-Realm: my-realm" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-client-id" \
  -d "client_secret=my-client-secret" \
  -d "scope=PRINCIPAL_ROLE:ALL"

禁用 FILE 存储类型

默认情况下，Polaris 允许将本地文件系统（FILE）用作目录存储。这种方式适用于测试，但不建议在生产环境中使用。如需禁用，可按如下方式设置支持的存储类型：

polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES" = [ "S3", "Azure" ]

省略 FILE 可防止其被使用。只需包含你的部署所需的存储类型。

审查位置兼容性标志

将非默认的位置兼容性标志视为生产部署审查的一部分。ALLOW_UNSTRUCTURED_TABLE_LOCATION、ALLOW_EXTERNAL_METADATA_FILE_LOCATION、ALLOW_TABLE_LOCATION_OVERLAP 以及允许位置的通配符都会放宽默认的存储边界模型，只有在特定的互操作性或迁移需求下才应启用。ALLOW_EXTERNAL_TABLE_LOCATION 是 ALLOW_EXTERNAL_METADATA_FILE_LOCATION 的已弃用兼容别名。OPTIMIZED_SIBLING_CHECK 并非绕过模式，但它会改变重叠检测的执行方式，只有在确认所需的索引和回填状态正确时才应启用。

Polaris 可以使用 Quarkus 内置的响应头配置输出信息性的 Server HTTP 响应头。在任意受支持的配置源（例如 application.properties）中添加以下属性，即可启用该响应头并附带 Polaris 版本字符串：

quarkus.http.header."Server".value=Polaris/${quarkus.application.version}

如果你希望将该标头的作用范围限定到特定环境，只需为所需配置设置该属性即可（例如 %prod）。

升级注意事项

Polaris Evolution 页面讨论了向后兼容性与升级相关的问题。

为云存储配置 Polaris

有关配置特定云存储提供商的说明，请参阅子页面（链接位于左侧面板）。

评论

登录后参与评论

正在加载评论…