Apache Gravitino 1.3.1 常用 CLI 命令与工具详解

目标：详解 Apache Gravitino 1.3.1 的常用 CLI 命令与配套工具，覆盖 gcli（版本握手、metalake/catalog 管理）、gravitino.sh 服务启停、REST 接口（curl）、JVM 堆验证（jcmd）、端口与 Web UI 检查。每条命令均给出实测输入与回显，在 Gravitino 1.3.1 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS / CentOS 8（命令与 1.3.1 一致）
组件版本：Apache Gravitino 1.3.1
安装目录：/opt/gravitino/gravitino-1.3.1-bin
CLI 工具：gcli.sh（位于 bin/，默认连接 http://localhost:8090）
服务管理脚本：bin/gravitino.sh（start / status / stop）
配套工具：curl、jcmd（JDK 自带）、pgrep、tail
默认端口：REST/Web 8090、iceberg-rest 9001、lance-rest 9101

二、工具概览

工具	作用
`gcli.sh`	Gravitino 官方 CLI 客户端（metalake/catalog/schema/table 管理、版本握手）
`gravitino.sh`	Gravitino Server 启停与状态管理
`curl`	调用 REST 接口（版本、健康检查、metalake/catalog）与 Web UI
`jcmd`	校验 JVM 堆参数与 GC 堆信息
`pgrep` / `tail`	定位服务进程、跟踪服务日志

三、前置条件

已完成 Gravitino 1.3.1 安装并启动（bin/gravitino.sh start）
已确认 java -version 为 JDK 17
已知服务端口（默认 8090），本机可访问
执行 gcli 前位于安装根目录 /opt/gravitino/gravitino-1.3.1-bin

四、gcli 核心命令详解

4.1 版本握手（client / server）

cd /opt/gravitino/gravitino-1.3.1-bin
./bin/gcli.sh --client
./bin/gcli.sh -s

实测回显：

Apache Gravitino 1.3.1
Apache Gravitino 1.3.1

💡 说明：--client 显示客户端版本，-s 显示服务端版本，两端均为 1.3.1 即为握手成功。

4.2 metalake 管理（create / list）

创建 metalake：

./bin/gcli.sh metalake create --metalake demo_metalake --comment "test metalake from gcli"

实测回显：

demo_metalake created

列出 metalake：

./bin/gcli.sh metalake list

实测回显：

demo_metalake

⚠️ 注意：创建 metalake 用 --metalake（不是 --name），且为必填。

4.3 catalog 管理（create / list）

创建对接 PostgreSQL 的 catalog（--properties 为逗号分隔键值对，不可带空格）：

./bin/gcli.sh catalog create --metalake demo_metalake --name postgres_cat --provider postgres \
    --properties "jdbc-url=jdbc:postgresql://127.0.0.1:5432/gravitino,jdbc-user=gravitino,jdbc-password=gravitino123,jdbc-database=gravitino,jdbc-driver=org.postgresql.Driver"

实测回显：

postgres_cat catalog created

列出 catalog：

./bin/gcli.sh catalog list --metalake demo_metalake

实测回显：

postgres_cat

💡 说明：--provider 指定 catalog 类型（如 postgres、mysql、hive、iceberg 等）。该 postgres_cat 真实连接本机 PostgreSQL，即“catalog 对接”验证。

4.4 服务启停（gravitino.sh）

cd /opt/gravitino/gravitino-1.3.1-bin
./bin/gravitino.sh status
./bin/gravitino.sh stop
./bin/gravitino.sh start

实测回显（启动）：

Gravitino Server is running[PID:1973]

跟踪服务日志：

tail -f logs/gravitino-server.log

实测日志关键行：

Detected database product: postgresql
Gravitino-webserver web server started on host 0.0.0.0 port 8090.
Done, Gravitino server started.

💡 说明：gravitino.sh stop 会关闭主服务及其辅助服务进程；status 用于确认 PID 与运行状态。

五、REST API 调用（curl）

5.1 版本与健康检查

curl -s http://127.0.0.1:8090/api/version
curl -s http://127.0.0.1:8090/health

实测回显：

{"code":0,"version":{"version":"1.3.1","compileDate":"24/09/2026 07:52:42","gitCommit":"ab5d0a4d655e6a81d0b86f7d2733d1874ed3f41a"}}
{"code":0,"status":"up","checks":[{"name":"httpServer","status":"up","details":{}},{"name":"entityStore","status":"up","details":{}}]}

💡 说明：健康检查真值路径为 /health（/api/health/liveness、/api/health/readiness 在该版返回 404）；版本接口为 /api/version。

5.2 metalake 与 catalog 查询

curl -s http://127.0.0.1:8090/api/metalakes
curl -s http://127.0.0.1:8090/api/metalakes/demo_metalake/catalogs

实测回显：

{"code":0,"metalakes":[{"name":"demo_metalake","comment":"test metalake from gcli","properties":{"in-use":"true"},"audit":{"creator":"anonymous","createTime":"2026-10-11T09:33:08.209986566Z"}}]}
{"code":0,"identifiers":[{"namespace":["demo_metalake"],"name":"postgres_cat"}]}

💡 说明：创建前 /api/metalakes 返回 {"code":0,"metalakes":[]}，创建后即返回上述单一 metalake，可据此确认元数据已生效。

六、jcmd：JVM 堆验证

定位服务进程并查看 JVM 参数与堆信息：

PID=$(pgrep -f GravitinoServer | head -1); echo "server PID=$PID"
jcmd $PID VM.flags
jcmd $PID GC.heap_info

实测回显：

server PID=7006
InitialHeapSize=268435456
MaxHeapSize=536870912
MaxMetaspaceSize=268435456
UseG1GC
 garbage-first heap   total 262144K, used 59574K ...
 Metaspace       used 52729K ...

💡 说明：InitialHeapSize=256MB、MaxHeapSize=512MB 即 GRAVITINO_MEM="-Xms256m -Xmx512m" 生效的证据；GC.heap_info 展示 G1 堆与元空间使用量。

七、端口与 Web UI 检查

7.1 Web UI

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8090/

实测回显：

HTTP 200

浏览器访问 http://<服务器IP>:8090/ 即为 Gravitino Web UI v2。

7.2 端口连通性

逐一验证 REST/Web 与两个辅助服务端口：

curl -s -o /dev/null -w 'port 8090 -> HTTP %{http_code}\n' http://127.0.0.1:8090/
curl -s -o /dev/null -w 'port 9001 -> HTTP %{http_code}\n' http://127.0.0.1:9001/
curl -s -o /dev/null -w 'port 9101 -> HTTP %{http_code}\n' http://127.0.0.1:9101/

实测回显：

port 8090 -> HTTP 200
port 9001 -> HTTP 404
port 9101 -> HTTP 404

💡 说明：9001（iceberg-rest）、9101（lance-rest）根路径 404 属正常（服务存活但无根路由）。默认端口中 iceberg-rest 为 9001，并非 9000。

7.3 元数据落库复核（PostgreSQL 后端）

PGPASSWORD=gravitino123 psql -U gravitino -h 127.0.0.1 -d gravitino -tAc "SELECT metalake_name FROM metalake_meta WHERE deleted_at=0"
PGPASSWORD=gravitino123 psql -U gravitino -h 127.0.0.1 -d gravitino -tAc "SELECT catalog_name FROM catalog_meta WHERE deleted_at=0"

实测回显：

demo_metalake
postgres_cat

八、注意事项

gcli 需在安装根目录执行，或使用绝对路径 ./bin/gcli.sh；默认连接 http://localhost:8090。
创建 metalake 用 --metalake，非 --name；catalog create 用 --metalake + --name。
--properties 逗号分隔不可带空格，否则解析失败。
健康检查用 /health，非 /api/health/*。
JVM 堆建议 256–512MB，用 jcmd VM.flags 复核生效。
辅助服务端口：iceberg-rest 9001、lance-rest 9101。

九、常见问题（FAQ）

Q1：gcli.sh 找不到命令。

需在安装根目录执行，或用绝对路径 /opt/gravitino/gravitino-1.3.1-bin/bin/gcli.sh；确认 JAVA_HOME 为 JDK 17。

Q2：metalake create --name=xxx 报参数错误。

创建 metalake 用 --metalake=xxx（--name 用于 catalog）。

Q3：catalog create 的 --properties 报解析错误。

键值对以逗号分隔且不可含空格，如 "k=v,k2=v2"。

Q4：curl /api/health/liveness 返回 404。

1.3.1 健康检查真值路径为 /health；版本接口为 /api/version。

Q5：jcmd 提示找不到命令。

JDK 17 的 jcmd 位于 $JAVA_HOME/bin（如 /usr/lib/jvm/java-17-openjdk-amd64/bin/jcmd），请用绝对路径或在 PATH 中包含它。

十、参考链接

Apache Gravitino 官方下载：https://dlcdn.apache.org/gravitino/1.3.1/
Apache Gravitino 项目主页：https://gravitino.apache.org/