Apache Polaris 1.3 常用 CLI 命令与工具详解

目标：详解 Apache Polaris 1.3.0-incubating（数据湖目录服务）的常用 CLI 命令与工具，覆盖启动脚本 bin/server、管理工具 bin/admin（bootstrap/purge）以及通过 curl 操作的 REST API（config / oauth / catalogs / namespaces / tables），每条命令附真实回显与速查表。已在 Ubuntu 22.04 实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
组件版本：Apache Polaris 1.3.0-incubating（Quarkus 3.29.4）
安装目录：/opt/polaris/polaris-bin-1.3.0-incubating/
相关命令：bin/server、bin/admin、curl
服务端口：8181（REST API）、8182（Management）
示例 root 凭证（本文演示）：client_id c6a6dcd313a5d7fb，client_secret 28de31ce9b53445982f37ec2ee3cce27

二、工具概览

工具/命令	作用	交互方式
`bin/server`	启动 Polaris 服务器	命令行默认为前台/后台运行
`bin/admin`	管理维护工具（bootstrap / purge）	命令行
`curl`（REST API）	目录管理、认证、Catalog 操作	HTTP/JSON
健康检查 `curl /q/health`	检查服务状态	HTTP

💡 说明：Polaris 无内置 Web UI，管理操作主要通过 bin/admin 与 REST 管理 API 完成。

三、前置条件

已按《Ubuntu 22.04 安装 Apache Polaris 1.3 指南》部署并启动服务（8181 可访问）。
已配置 Java 21 环境：export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64。
具备 curl 与 base64/jq（可选）等工具。

四、bin/server 服务启动命令

4.1 直接启动

在安装目录下运行：

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
cd /opt/polaris/polaris-bin-1.3.0-incubating
bin/server

等价于：

java -jar server/quarkus-run.jar

启动成功关键日志（约 15.7s）：

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.

4.2 后台运行并输出日志

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 &

4.3 带 JVM 参数启动

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

💡 说明：bin/server 脚本会读取 ${POLARIS_JAVA_OPTS:-} 并传给 java；JVM 堆建议限 256–512MB。

五、bin/admin 管理工具

bin/admin 封装了 polaris-admin-tool.jar，用于 bootstrapping（初始化 realm 与 root 凭证）与 purge（清理）。

5.1 查看帮助

/bin/admin --help

真实回显：

Usage: polaris-admin-tool.jar [-hV] [COMMAND]
Polaris administration & maintenance tool
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help       Display help information about the specified command.
  bootstrap  Bootstraps realms and root principal credentials.
  purge      Purge realms and all associated entities.

💡 说明：路径应使用安装目录下的脚本，如 /opt/polaris/polaris-bin-1.3.0-incubating/bin/admin。

5.2 查看版本

bin/admin --version

真实回显：

1.3.0-incubating

5.3 bootstrap 子命令

初始化（bootstrap）realm 与 root principal 凭证。

bin/admin bootstrap --help

真实回显：

Usage: polaris-admin-tool.jar bootstrap [-hV] [-v=<schema version>]
                                        ([-r=<realm> [-r=<realm>]... [-c=<realm,
                                        clientId,clientSecret>]... [-p]] |
                                        [[-f=<file>]])
Bootstraps realms and root principal credentials.
  -h, --help                Show this help message and exit.
  -v, --schema-version=<schema version>
                            The version of the schema to load in [1, 2, 3,
                              LATEST].
  -V, --version             Print version information and exit.
Standard Input Options:
  -c, --credential=<realm,clientId,clientSecret>
                            Root principal credentials to bootstrap. Must be of
                              the form 'realm,clientId,clientSecret'.
  -p, --print-credentials   Print root credentials to stdout
  -r, --realm=<realm>       The name of a realm to bootstrap.
File Input Options:
  -f, --credentials-file=<file>
                            A file containing root principal credentials to
                              bootstrap.

常用示例——为 realm POLARIS 初始化 root 凭证并打印：

bin/admin bootstrap -r POLARIS -c POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27 -p

💡 说明：-c 参数格式为 realm,clientId,clientSecret。也可用 -f <file> 从文件读取。

5.4 purge 子命令

清理（purge）指定 realm 及其关联实体。

bin/admin purge --help

真实回显：

Usage: polaris-admin-tool.jar purge [-hV] -r=<realm> [-r=<realm>]...
Purge realms and all associated entities.
  -h, --help            Show this help message and exit.
  -r, --realm=<realm>   The name of a realm to purge.
  -V, --version         Print version information and exit.

常用示例——清理 realm POLARIS：

bin/admin purge -r POLARIS

⚠️ 注意：purge 会删除该 realm 下的所有实体（catalog、principal、principal-role 等），操作不可逆，生产慎用。

六、REST API 与 curl 命令集

Polaris 同时开放 Iceberg 协议的 Catalog API（前缀 /api/catalog/v1）与管理 API（前缀 /api/management/v1），以下命令均可用 curl 执行。

6.1 健康检查

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

真实回显：

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

6.2 未认证访问 config（验证鉴权是否生效）

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

6.3 OAuth2 获取 token

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":"eyJhbGciOiJSUzI1NiIs...","token_type":"bearer","issued_token_type":"urn:ietf:params:oauth:token-type:access_token","expires_in":3600}

token 有效期 3600 秒。为便于后续命令，把 token 存入环境变量：

TOKEN="<上一步拿到的 access_token 完整值>"

6.4 创建 Catalog（管理 API）

curl -s -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，请用 S3 类型。

6.5 查看 Catalog 列表

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

真实回显：

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

6.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（含 namespaces、tables、transactions/commit、policies 等 Iceberg REST 端点）。

6.7 创建 Namespace

curl -s -X POST "http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"namespace":["default"]}'

真实回显（HTTP 200 OK）：

{"namespace":["default"],"properties":{"location":"s3://mybucket/polaris/default/"}}

6.8 查看 Namespace 列表

curl -s "http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces" -H "Authorization: Bearer $TOKEN"

真实回显：

{"namespaces":[["default"]],"next-page-token":null}

6.9 查看 Namespace 下的表

curl -s "http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/default/tables" -H "Authorization: Bearer $TOKEN"

真实回显（无表时）：

{"identifiers":[],"next-page-token":null}

💡 说明：创建表需定义 Iceberg schema/partition-spec，且因表创建涉及 S3 临时凭证，需服务端配置 AWS region 或 polaris.features."SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION"=true 才能成功（见配置参数详解篇）。

七、速查表

目标	命令
启动服务	`bin/server`
后台启动	`nohup java -jar server/quarkus-run.jar > /opt/polaris/server.log 2>&1 &`
健康检查	`curl http://localhost:8182/q/health`
未认证 config	`curl http://localhost:8181/api/catalog/v1/config`
获取 token	`curl -s -X POST .../oauth/tokens -d "grant_type=client_credentials&client_id=...&client_secret=..."`
创建 catalog	`curl -s -X POST .../management/v1/catalogs -H "Authorization: Bearer $TOKEN" ...`
列表 catalog	`curl -s .../management/v1/catalogs -H "Authorization: Bearer $TOKEN"`
认证后 config	`curl -s ".../config?warehouse=<catalog>" -H "Authorization: Bearer $TOKEN"`
创建 namespace	`curl -s -X POST .../quickstart_catalog/namespaces -d '{"namespace":["default"]}'`
列表 namespace	`curl .../quickstart_catalog/namespaces`
列表表	`curl .../quickstart_catalog/namespaces/default/tables`
admin 帮助	`bin/admin --help`
admin 版本	`bin/admin --version`
bootstrap	`bin/admin bootstrap -r POLARIS -c POLARIS,<clientId>,<clientSecret> -p`
purge	`bin/admin purge -r POLARIS`

八、注意事项

bin/admin 与 curl 命令需要正确设置 JAVA_HOME（Java 21）与路径。
管理 API 前缀是 /api/management/v1，Catalog API 前缀是 /api/catalog/v1，两者勿混（如 /api/catalog/v1/catalogs 会 404）。
二进制版不支持 storageType: FILE，用 S3/GCS/AZURE。
表/文件写入类操作可能依赖 AWS S3 临时凭证，测试环境建议开启 SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION。

九、常见问题

Q1：bin/admin 报 "Java not found"？

未设置 JAVA_HOME 或 PATH 中没有 java。设 export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 后再运行。

Q2：为什么 /api/catalog/v1/catalogs 返回 404？

该路径属于管理 API，应访问 /api/management/v1/catalogs。Catalog 前缀下没有 catalog 管理接口。

Q3：json parse 命令缺失怎么办？

本环境为精简镜像无 jq，可用 grep -o/sed 提取 token，或安装 apt-get install -y jq。

Q4：为什么 create table 报 "Unable to load region"？

表创建需要 S3 临时凭证端点，缺 AWS region。测试环境可设置 polaris.features."SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION"=true 跳过凭证下发，或为服务配置 AWS region。

十、参考链接

Apache Polaris 官方文档：https://polaris.apache.org/
Apache Polaris GitHub：https://github.com/apache/polaris
Iceberg REST Catalog 规范：https://iceberg.apache.org/rest-catalog/