Apache Polaris：用 Iceberg REST 协议把元数据目录做成公共设施

它解决的是目录碎片化问题

在 Iceberg 生态里，表元数据原本可以由每个引擎各自管理，但这会导致同一张表在不同引擎眼中状态不一致。Polaris 把元数据目录抽出来，做成一个独立服务，所有引擎通过 Iceberg REST API 访问同一份元数据。这样 Spark 建的表，Trino 能看到，Flink 写入的变更，Doris 也能读到。它面向的是多引擎共存的团队，尤其是那些已经受够了 Hive Metastore 或各自为政的目录方案的人。Polaris 不是存储引擎，它不碰数据文件，只负责表的定义、快照、命名空间和权限。

REST API 是核心，管理面与数据面分离

Polaris 实现了 Iceberg 的 REST catalog API，这是它跨引擎兼容的根基。同时它还提供了一套 Polaris Management API，用于管理目录、命名空间和授权。从仓库的 API 模块可以看到，`polaris-api-iceberg-service` 负责 Iceberg REST 服务，而 `polaris-api-management-service` 负责管理操作。这种分离意味着，引擎只通过标准 Iceberg 协议读写元数据，而管理员通过另一套接口做配置。数据流大致是：客户端向 Polaris 发送 Iceberg REST 请求，Polaris 校验身份和权限，然后从持久化层读取或写入实体。持久化层默认是 JDBC 实现，也就是关系型数据库。

从源码到本地运行：命令与配置

构建 Polaris 需要 Java 21 和 Docker 27，因为集成测试依赖容器。最直接的方式是 `./gradlew run`，它会启动一个本地服务，监听 8181 端口。默认凭据是 `POLARIS,root,s3cr3t`，其中 POLARIS 是 realm，root 是 client id，s3cr3t 是 secret。你可以用 `-Dpolaris.bootstrap.credentials=POLARIS,root,secret` 覆盖。连接 Spark SQL 时，仓库提供了 `./regtests/run_spark_sql.sh` 脚本，里面可以直接执行 `create database db1` 和 `create table db1.table1` 这类语句。注意，`./gradlew build` 会跑集成测试，如果不想跑，用 `./gradlew assemble` 跳过测试。

模块划分：核心、运行时、持久化与扩展

仓库按 Gradle 子项目组织，核心是 `polaris-core`，包含实体定义和业务逻辑。运行时部分包括 `polaris-server`（Quarkus 服务器）、`polaris-admin`（用于引导持久化的管理工具）和 `polaris-runtime-service`（服务打包）。持久化目前只有 `polaris-relational-jdbc` 一个实现，这意味着如果你不想用 JDBC 兼容的数据库，就得自己写持久化层。扩展方面有联邦目录：`polaris-extensions-federation-hive`、`hadoop`、`bigquery`，它们允许 Polaris 代理到现有目录。鉴权扩展支持 OPA 和 Ranger。这些模块的存在说明 Polaris 不是铁板一块，它预留了替换和增强的接口。

联邦与鉴权：真实场景中的两个关键旋钮

联邦目录扩展是 Polaris 的一个务实设计。如果你的公司已经用 Hive Metastore 或 BigQuery 存了一批表，Polaris 可以充当统一入口，把请求转发给底层目录。这避免了“推倒重来”的迁移。但要注意，联邦扩展是分开的，Hive 和 BigQuery 各自独立，不是开箱即用的全家桶。鉴权方面，默认的 bootstrap 凭据是写死在文档里的，生产环境必须改。Ranger 和 OPA 扩展允许你接入已有的权限体系，但这也意味着你要维护额外的组件。如果你的权限需求很简单，也许直接用 Polaris 内置的授权模型就够了。

限制与失败模式：不是银弹

Polaris 的文档没有隐藏它的运行前提：Docker 是集成测试的硬依赖，Java 21 是构建门槛。如果你在隔离环境里跑，没有容器运行时，`./gradlew check` 会失败。另一个限制是持久化层只有 JDBC 实现，这意味着你至少需要一个关系型数据库。对于小团队或单机实验，这有点重。更实际的风险是，Iceberg REST 协议本身还在演进，不同引擎对协议的支持程度不一。Polaris 支持 Doris、Flink、Spark、Dremio、StarRocks、Trino，但如果你用的是冷门引擎，最好先验证它是否实现了完整的 REST catalog 接口。否则你可能会遇到“能连上但某些操作不支持”的尴尬。

替代方案：Hive Metastore 与自建目录

最直接的替代是继续使用 Hive Metastore（HMS）。HMS 是 Iceberg 早期常用的目录实现，很多引擎默认支持。但 HMS 的元数据模型是为 Hive 表设计的，对 Iceberg 的命名空间、快照和权限支持是后加的，而且它没有标准的 REST 管理接口。Polaris 的不同在于，它把 Iceberg 的 REST 协议作为一等公民，管理操作也是通过 OpenAPI 定义的，这意味着你可以用任何语言写客户端来管理目录，而不必依赖 Hive 的 Thrift 接口。另一个替代是自己写一个目录服务，但那需要你维护 Iceberg 协议兼容性，成本远高于使用 Polaris。如果你只需要一个简单的目录，且没有多引擎需求，HMS 可能更省事。

维护成本与许可证考量

Polaris 是 Apache 2.0 许可证，你可以自由使用、修改和分发，但要注意商标声明，README 里明确写了 Apache Polaris 和 Apache Iceberg 是商标。维护成本主要来自版本升级。项目发布节奏看起来是月度级，1.7.0 在 1.6.0 之后不到一个月就发布了，这意味着你需要跟进上游变化，尤其是 API 变更。仓库里有 `polaris-tools` 独立仓库，说明工具链是外置的，你需要额外关注。另外，集成测试依赖 Docker，如果你在 CI 里跑 Polaris 的测试，必须准备容器环境。从项目结构看，测试模块 `polaris-tests` 被设计为可复用，这有助于下游项目做兼容性验证，但这也意味着测试基础设施本身有学习成本。

编辑结论

如果你的团队同时使用 Spark、Flink、Trino 或 Doris 处理同一批 Iceberg 表，并且厌倦了为每个引擎分别维护权限和命名空间，Polaris 值得评估。它把元数据操作收敛到一套 REST 协议上，管理面与数据面分离，这种设计比直接让各引擎连接 Hive Metastore 更干净。但如果你只有单一引擎，或者元数据规模极小，引入一个独立目录服务反而是负担。Polaris 的运维复杂度不低，它需要 Java 21、Docker 27 以及一个关系型数据库来持久化元数据，而且默认的 bootstrap 凭据是公开的，生产环境必须显式覆盖。在决定采用之前，先确认你的引擎是否完整支持 Iceberg REST 协议，尤其是你依赖的 Iceberg 版本与 Polaris 1.7.0 的兼容性。还要检查联邦目录（如 Hive、BigQuery）是否覆盖你现有的表来源，否则迁移成本可能高于收益。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes