Ubuntu 22.04 安装 Apache Polaris 1.3 指南

目标：在 Ubuntu 22.04 上从官方二进制包安装 Apache Polaris 1.3.0-incubating（数据湖目录服务，支持 Iceberg REST Catalog），并完成 Java 21 环境、下载校验、启动、REST API 验证与 JVM 内存配置。本文已在 Ubuntu 22.04.5 LTS 上实测通过，路径 /opt/polaris/polaris-bin-1.3.0-incubating/。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Kernel 6.8.0-138-generic）
架构：x86_64
用户：root
Java：openjdk-21-jre-headless 21.0.12.1（官方要求 Java SE 21 或更高）
组件：Apache Polaris 1.3.0-incubating（Java/Quarkus 3.29.4）
安装包：polaris-bin-1.3.0-incubating.tgz（275MB）
安装目录：/opt/polaris/polaris-bin-1.3.0-incubating/
监听端口：8181（REST Catalog API）、8182（Quarkus Management 接口）
数据目录：/opt/polaris/（安装根目录）、/opt/downloads/（下载临时目录）

二、前置条件

安装前确认系统与网络满足：

具备 root 权限：后续安装目录都在 /opt/ 下，需要 root 或 sudo。
可访问 Apache 官方下载站：https://downloads.apache.org。
已安装 wget 与 tar：下载与解压所需。未安装则先安装：

apt-get update
apt-get install -y wget tar ca-certificates

Java SE 21 或更高：Polaris 官方要求 Java 21+，不支持 Java 8/11。本文使用 openjdk-21（实测在 Ubuntu 22.04 仓库中可用）。

⚠️ 注意：openjdk-17 也能启动服务，但官方 README 明确要求 "Java SE 21 or higher"，本文以 21 为准。

三、版本选型说明

Apache Polaris 尚处孵化期（incubating），发布归属路径、下载路径与版本号都带 incubating 后缀，选型时需注意：

项	说明
下载路径	`https://downloads.apache.org/incubator/polaris/`（正式目录 `/polaris/` 为空/不存在）
当前最新版	`1.3.0-incubating`（本文撰写时）
发布包类型	`polaris-bin-*.tgz`（二进制发行版，含 server 与 admin 工具）
源码包	`apache-polaris-*.tar.gz`（源码，需自行编译）
是否提供 Web UI	否，1.3.0 无内置图形界面，管理走 REST 管理 API 或 `bin/admin` 工具

实测 https://downloads.apache.org/incubator/polaris/ 目录，可见 1.3.0-incubating/ 子目录与 KEYS 签名文件：

$ wget -qO- https://downloads.apache.org/incubator/polaris/
href="1.3.0-incubating/"
href="helm-chart/"
href="KEYS"

1.3.0-incubating/ 目录下包含：

apache-polaris-1.3.0-incubating.tar.gz        # 源码包
apache-polaris-1.3.0-incubating.tar.gz.sha512
polaris-bin-1.3.0-incubating.tgz              # ★ 二进制发布包
polaris-bin-1.3.0-incubating.tgz.sha512
polaris-bin-1.3.0-incubating.zip

💡 说明：本项目选择二进制发布包 polaris-bin-1.3.0-incubating.tgz，免编译、开箱即用。

四、部署步骤

4.1 创建目录

mkdir -p /opt/polaris /opt/downloads

4.2 下载二进制包与校验文件

cd /opt/downloads
wget https://downloads.apache.org/incubator/polaris/1.3.0-incubating/polaris-bin-1.3.0-incubating.tgz
wget https://downloads.apache.org/incubator/polaris/1.3.0-incubating/polaris-bin-1.3.0-incubating.tgz.sha512

下载完成确认包大小为 275M：

ls -lh /opt/downloads/polaris-bin-1.3.0-incubating.tgz
# -rw-r--r-- 1 root root 275M ...

4.3 校验 sha512 完整性

# 将 sha512 文件中的哈希与包本身比对
echo "$(awk '{print $1}' /opt/downloads/polaris-bin-1.3.0-incubating.tgz.sha512)  /opt/downloads/polaris-bin-1.3.0-incubating.tgz" | sha512sum -c -

预期输出：

/opt/downloads/polaris-bin-1.3.0-incubating.tgz: OK

⚠️ 注意：若输出不含 : OK（而是 : FAILED），说明包被篡改或下载不完整，应删除并重新下载，禁止使用。

4.4 解压并重命名

tar -xzf /opt/downloads/polaris-bin-1.3.0-incubating.tgz -C /opt/polaris

解压后目录为 /opt/polaris/polaris-bin-1.3.0-incubating/，结构如下：

ls -la /opt/polaris/polaris-bin-1.3.0-incubating/

DISCLAIMER
LICENSE
NOTICE
README.md
admin/             # 管理工具（bin/admin 包装）
bin/               # server / admin 启动脚本
server/            # quarkus-run.jar 与依赖

bin/ 下包含两个脚本，server/ 目录下是实际运行的 quarkus-run.jar：

ls /opt/polaris/polaris-bin-1.3.0-incubating/bin/
# admin  server
ls /opt/polaris/polaris-bin-1.3.0-incubating/server/
# app/  lib/  quarkus-run.jar  quarkus/

💡 说明：bin/server 与 bin/admin 是官方提供的启动/管理脚本，脚本内容即为 exec java [POLARIS_JAVA_OPTS] -jar quarkus-run.jar，可直接运行，也可手动 java -jar 等价启动。

4.5 配置 Java 21 环境

确认系统 Java 版本为 21（或更高）：

/usr/lib/jvm/java-21-openjdk-amd64/bin/java -version

预期输出：

openjdk version "21.0.12.1" 2026-08-18

若系统中同时存在多个 JDK，在启动前显式指定 JAVA_HOME：

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

4.6 启动服务

进入 server 目录并后台启动：

cd /opt/polaris/polaris-bin-1.3.0-incubating/server
nohup "$JAVA_HOME/bin/java" -jar quarkus-run.jar > /opt/polaris/server.log 2>&1 &

等价于官方脚本 bin/server。启动约需 15.7 秒（Quarkus 冷启动）。查看关键启动日志：

grep -E "started in|Listening on|root principal" /opt/polaris/server.log

预期关键回显：

INFO  Apache Polaris Server (incubating) 1.3.0-incubating on JVM (powered by Quarkus 3.29.4)
      started in 15.675s. Listening on: http://0.0.0.0:8181. Management interface listening on http://0.0.0.0:8182.
INFO  Profile prod activated.

4.7 查看监听端口

ss -ltnp | grep java

预期输出（8181 与 8182 均在监听）：

LISTEN  0  4096  *:8181  *:*  users:(("java",pid=3635,fd=259))   # REST Catalog API
LISTEN  0  4096  *:8182  *:*  users:(("java",pid=3635,fd=260))   # Management 接口

8181：REST Catalog API（Iceberg 协议 + 管理 API /api/management/v1/*）
8182：Quarkus Management 接口（/q/health 返回 UP）
8080：未监听。1.3.0-incubating 不提供独立 Web UI，也没有 /ui、/realm 页面（访问均 404）。

💡 说明：用户如无图形界面需求可跳过 Web UI；管理操作通过 REST 管理 API 与 bin/admin 命令行工具完成。

4.8 获取 root 初始凭证（关键）

Polaris 1.3.0 默认没有预设 root:12345678。首次启动时若未通过环境变量提供 root 凭证，会自动生成 root principal 凭证并打印到 stdout（日志中），格式为 client_id:client_secret：

INFO  Realm 'POLARIS' automatically bootstrapped ...
realm: POLARIS root principal credentials: c6a6dcd313a5d7fb:28de31ce9b53445982f37ec2ee3cce27

从 /opt/polaris/server.log 中取出这行凭证，后续认证使用：

grep "root principal credentials" /opt/polaris/server.log

⚠️ 注意：该自动生成的凭证是随机产生的，请记下自己的值；重启且配置不变时会保留。为防止丢失，可在启动前显式配置（见「常见问题」Q：如何固定 root 凭证）。

五、验证运行

5.1 健康检查（Management 接口）

curl -s http://localhost:8182/q/health

预期输出：

{"status":"UP","checks":[{"name":"Database connections health check","status":"UP"}]}

5.2 未认证访问 config（应 401）

curl -s -i http://localhost:8181/api/catalog/v1/config

预期输出：

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
X-Request-ID: 4b43191a-..._0000000000000000001
content-length: 0

5.3 OAuth2 获取 Token

使用上一步获取的 root 凭证（client_id 与 client_secret）换取 JWT：

curl -s -X POST http://localhost:8181/api/catalog/v1/oauth/tokens \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=c6a6dcd313a5d7fb&client_secret=28de31ce9b53445982f37ec2ee3cce27" \
  -d "scope=PRINCIPAL_ROLE:ALL"

预期输出（JWT，截断展示）：

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

Token 有效期 3600 秒（1 小时）；
JWT payload 中 sub 为 root、scope 为 PRINCIPAL_ROLE:ALL。

5.4 创建 Catalog（管理 API）

管理 API 前缀为 /api/management/v1。使用上一步拿到的 access_token 创建 catalog：

TOKEN=eyJhbGciOiJSUzI1NiIs...
curl -s -i -X POST http://localhost:8181/api/management/v1/catalogs \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"quickstart_catalog","type":"INTERNAL",
       "storageConfigInfo":{"storageType":"S3","allowedLocations":["s3://mybucket/polaris"]},
       "properties":{"default-base-location":"s3://mybucket/polaris"}}'

预期输出（HTTP 201 Created）：

{"type":"INTERNAL","name":"quickstart_catalog","properties":{"default-base-location":"s3://mybucket/polaris"},"createTimestamp":1791718757246,"lastUpdateTimestamp":0,"entityVersion":1,"storageConfigInfo":{"pathStyleAccess":false,"storageType":"S3","allowedLocations":["s3://mybucket/polaris"]}}

⚠️ 注意：二进制发行版不支持 storageType: FILE（报 Unsupported storage type: FILE），本实验用 S3 类型通过（仅做元数据校验，不真正连接 S3）。

5.5 查看 Catalog 列表

curl -s http://localhost:8181/api/management/v1/catalogs -H "Authorization: Bearer $TOKEN"

预期输出：

{"catalogs":[{"type":"INTERNAL","name":"quickstart_catalog",...}]}

5.6 认证后访问 config 接口

curl -s "http://localhost:8181/api/catalog/v1/config?warehouse=quickstart_catalog" -H "Authorization: Bearer $TOKEN"

不带 warehouse 参数 → 400 {"error":{"message":"Please specify a warehouse",...}}；
指定存在的 warehouse → 200 OK，返回 defaults/overrides/endpoints，其中 endpoints 含 /v1/{prefix}/namespaces、/v1/{prefix}/namespaces/{namespace}/tables、/v1/{prefix}/transactions/commit、/polaris/v1/{prefix}/namespaces/{namespace}/policies 等 Iceberg REST 端点。

至此，Polaris 服务安装并验证通过。

六、配置说明

6.1 JVM 内存配置（必配）

Polaris 为 Java 进程，建议将 JVM 堆限制在 256–512MB，避免占用过大内存。改法如下。

启动时通过 java 的 -Xms/-Xmx 参数指定，或通过环境变量 POLARIS_JAVA_OPTS 注入（官方推荐方式）：

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export POLARIS_JAVA_OPTS="-Xms256m -Xmx512m"

cd /opt/polaris/polaris-bin-1.3.0-incubating/server
nohup "$JAVA_HOME/bin/java" $POLARIS_JAVA_OPTS -jar quarkus-run.jar > /opt/polaris/server.log 2>&1 &

💡 说明：bin/server 脚本本身就读取 ${POLARIS_JAVA_OPTS:-} 并将其传给 java，因此按 POLARIS_JAVA_OPTS="-Xms256m -Xmx512m" bin/server 启动同样生效。

修改后确认生效（ps 查看 java 命令行参数）：

ps -ef | grep [j]ava

预期输出应能看到 -Xms256m -Xmx512m：

root 5735 ... /usr/lib/jvm/java-21-openjdk-amd64/bin/java -Xms256m -Xmx512m -jar quarkus-run.jar

⚠️ 注意：若用 nohup 前后台切分写命令，务必在 export 之后、java 之前完成拼接，并确保目标机器内存足够（建议 ≥1GB）。

6.2 其他常用配置项

监听端口：quarkus.http.port（默认 8181）、quarkus.management.port（默认 8182），同其他 Quarkus 配置。例如：

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

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

七、常见问题

Q1：默认有 root:12345678 吗？

没有。1.3.0-incubating 默认不预设账号密码，首次启动自动生成 root principal 凭证并打印到 stdout。使用产品时须从日志中取出 client_id:client_secret。

Q2：如何固定 root 凭证，避免重启丢失？

启动前通过环境变量显式提供（格式 realm,clientId,clientSecret）：

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

💡 注意：POLARIS_BOOTSTRAP_CREDENTIALS 是逗号分隔的 realm,clientId,clientSecret 三元组，而不是 stdout 打印的 clientId:clientSecret 显示格式，两者需区分。

Q3：为什么用 FILE 存储类型创建 catalog 报错？

二进制发行版不支持 storageType: FILE，编译/源码包与文档示例常用 FILE + file:// 位置，但二进制版实际操作会报 Unsupported storage type: FILE。本地功能测试应改用 S3/GCS/AZURE（仅做元数据校验，不影响功能）。

Q4：没有 Web UI 吗？

是的。1.3.0-incubating 无内置图形界面（8080 未监听），管理操作通过 REST 管理 API（/api/management/v1/*）与 bin/admin 命令行工具完成。

Q5：如何停止服务？

找到 java 进程 PID 并 kill：

ps -ef | grep [j]ava        # 找到 PID，如 3635
kill <PID>

八、卸载方式

停止服务（见常见问题 Q5）；
删除安装目录与日志：

rm -rf /opt/polaris/polaris-bin-1.3.0-incubating
rm -f /opt/polaris/server.log

删除下载的临时件（可选）：

rm -rf /opt/downloads

⚠️ 注意：若不再使用 JDK 21，可用 apt-get remove --purge -y openjdk-21-jre-headless 一并卸载，按需决定。

九、参考链接

Apache Polaris 官方文档：https://polaris.apache.org/
Apache Polaris 下载页：https://downloads.apache.org/incubator/polaris/
Polaris GitHub：https://github.com/apache/polaris