Ubuntu 22.04 安装 Apache Gravitino 1.3.1 指南

在 Ubuntu 22.04 上以官方 tar.gz 安装 Apache Gravitino 1.3.1，完成 JDK 17 与 PostgreSQL 14 前置、数据库 schema 初始化与 JDBC 驱动补齐、下载校验解压、配置与启动，并验证 REST（8090）/gcli/Web UI 全链路及 JVM 堆 256–512MB 生效。安装与验证在 Ubuntu 22.04.5 真实服务器实测通过。

Apache GravitinoApache Gravitino安装部署Apache大数据Ubuntu 22.042026/10/11

Ubuntu 22.04 安装 Apache Gravitino 1.3.1 指南

目标：在 Ubuntu 22.04.5 上以官方 tar.gz 安装 Apache Gravitino 1.3.1（data lakehouse 元数据统一治理平台），完成 JDK 17 与 PostgreSQL 14 前置、数据库 schema 初始化、JVM 堆内存限定，并打通 REST（8090）+ gcli CLI + Web UI 全链路。安装与验证流程在 Ubuntu 22.04.5 真实服务器实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 包管理器：apt / dpkg
  • 运行时环境：OpenJDK 17（17.0.20.1，Gravitino 1.2+ 运行需 JDK 17）
  • 组件版本：Apache Gravitino 1.3.1（gravitino-1.3.1-bin.tar.gz，约 918 MB）
  • 安装目录：/opt/gravitino/gravitino-1.3.1-bin
  • 元数据存储：本机 PostgreSQL 14.24（127.0.0.1:5432，库 gravitino）
  • 默认端口：REST/Web 8090（gravitino.server.webserver.httpPort）、iceberg-rest 辅助服务 9001、lance-rest 辅助服务 9101
  • JVM 堆：初始 256 MB / 上限 512 MB / 元空间 256 MB

二、前置条件

  • 拥有 root 权限，可访问 dlcdn.apache.org、repo1.maven.org
  • 已安装 wget、tar
  • 已安装 openjdk-17-jdk-headless，并确认 java -version 为 JDK 17
  • 已安装并启动 PostgreSQL 14，创建库 gravitino 与用户 gravitino
  • 本机 hostname -I 可返回内网地址（用于自检端口）

⚠️ 注意：Gravitino 1.2+ 运行依赖 Java 17。若系统默认 JDK 为 11 或更低，启动会因字节码版本不兼容而失败，请先安装并切换 JDK 17。

三、版本选型说明

Apache Gravitino 各版本与依赖差异：

版本说明建议
1.3.1Apache 官方当前最新稳定版（2026-09-30 发布，实测对象）推荐，本文按此版安装
1.2.x早期稳定系列，要求 JDK 17如需旧版可从同一官方镜像路径下载
1.1.x 及更早JDK 8/11 可运行命令与配置项与 1.3 存在差异，不推荐新装

💡 说明：Gravitino 1.2 起官方要求 Java 17 运行。元数据存储可用内嵌 H2（开箱即用）或 PostgreSQL / MySQL / MariaDB，本文采用本机 PostgreSQL 14 做真实持久化。

四、官方 tar.gz 安装方案

4.1 安装前置工具与 JDK 17

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk-headless wget tar

验证版本与安装路径：

which java && java -version

实测回显：

/usr/bin/java
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

JAVA_HOME 为 /usr/lib/jvm/java-17-openjdk-amd64，后续写入启动环境。

4.2 安装 PostgreSQL 14

Ubuntu 22.04 官方仓库默认提供 PostgreSQL 14，安装后自动 initdb：

DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql postgresql-contrib
systemctl start postgresql && systemctl is-active postgresql

实测回显：

Setting up postgresql (14+238) ...
active

确认版本并创建库与用户：

su - postgres -c "psql -t -c 'SELECT version();'"
su - postgres -c "psql -c \"CREATE USER gravitino WITH PASSWORD 'gravitino123';\""
su - postgres -c "psql -c \"CREATE DATABASE gravitino OWNER gravitino;\""

实测回显：

 PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu ...
CREATE ROLE
CREATE DATABASE

4.3 下载官方二进制并校验解压

mkdir -p /opt/gravitino
cd /opt/gravitino
wget https://dlcdn.apache.org/gravitino/1.3.1/gravitino-1.3.1-bin.tar.gz
ls -lh gravitino-1.3.1-bin.tar.gz

实测回显：

-rw-r--r-- 1 root root 918M Sep 24 08:04 gravitino-1.3.1-bin.tar.gz

下载官方 sha512 并以之校验：

wget https://dlcdn.apache.org/gravitino/1.3.1/gravitino-1.3.1-bin.tar.gz.sha512
cat gravitino-1.3.1-bin.tar.gz.sha512
sha512sum gravitino-1.3.1-bin.tar.gz

实测回显（sha512sum 结果与官方一致）：

2da4e0bb...ab46  gravitino-1.3.1-bin.tar.gz
2da4e0bb...ab46  gravitino-1.3.1-bin.tar.gz

解压并查看目录结构：

tar -xzf gravitino-1.3.1-bin.tar.gz
ls gravitino-1.3.1-bin/

实测回显：

LICENSE  NOTICE  README.md  authorizations  auxlib  bin  catalogs  conf  data
iceberg-rest-server  lance-rest-server  libs  licenses  optimizer  scripts  web  web-v2
  • 关键目录：bin/gravitino.sh（启停）、bin/gcli.sh（CLI 客户端）、conf/gravitino.conf、conf/gravitino-env.sh、scripts/postgresql/（建表 SQL）、auxlib/gravitino-cli-1.3.1.jar、libs/（运行 jar）。

4.4 配置 gravitino.conf（切换存储后端为 PostgreSQL）

默认 gravitino.entity.store.relational.jdbcUrl = jdbc:h2，改为本机 PostgreSQL：

cd /opt/gravitino/gravitino-1.3.1-bin
sed -i 's|gravitino.entity.store.relational.jdbcUrl = jdbc:h2|gravitino.entity.store.relational.jdbcUrl = jdbc:postgresql://127.0.0.1:5432/gravitino|' conf/gravitino.conf
sed -i 's|gravitino.entity.store.relational.jdbcDriver = org.h2.Driver|gravitino.entity.store.relational.jdbcDriver = org.postgresql.Driver|' conf/gravitino.conf
sed -i 's|gravitino.entity.store.relational.jdbcPassword = gravitino|gravitino.entity.store.relational.jdbcPassword = gravitino123|' conf/gravitino.conf
grep -nE 'jdbcUrl|jdbcDriver|jdbcUser|jdbcPassword' conf/gravitino.conf

实测回显：

61:gravitino.entity.store.relational.jdbcUrl = jdbc:postgresql://127.0.0.1:5432/gravitino
63:gravitino.entity.store.relational.jdbcDriver = org.postgresql.Driver
65:gravitino.entity.store.relational.jdbcUser = gravitino
67:gravitino.entity.store.relational.jdbcPassword = gravitino123

4.5 补齐 PostgreSQL JDBC 驱动

发行包 libs/ 只自带 H2 驱动，需自补 PostgreSQL 驱动，否则连接报 class not found: org.postgresql.Driver：

cd /opt/gravitino/gravitino-1.3.1-bin/libs
wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.4/postgresql-42.7.4.jar
ls -lh postgresql-42.7.4.jar

实测回显：

-rw-r--r-- 1 root root 1.1M Aug 22  2024 postgresql-42.7.4.jar

4.6 配置环境变量与 JVM 堆（gravitino-env.sh）

向 conf/gravitino-env.sh 追加 JAVA_HOME、GRAVITINO_HOME 与 JVM 堆参数（将默认 1G 堆压到 256–512MB）：

cd /opt/gravitino/gravitino-1.3.1-bin
printf '%s\n' \
    'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
    'export GRAVITINO_HOME=/opt/gravitino/gravitino-1.3.1-bin' \
    'export GRAVITINO_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"' >> conf/gravitino-env.sh
tail -3 conf/gravitino-env.sh
bash -n conf/gravitino-env.sh && echo SYNTAX_OK

实测回显：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export GRAVITINO_HOME=/opt/gravitino/gravitino-1.3.1-bin
export GRAVITINO_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
SYNTAX_OK

⚠️ 注意：若原文件末行无换行符，直接 append 会使首行粘连并导致语法异常；必要时用 sed 补齐换行，再用 bash -n conf/gravitino-env.sh 校验语法。

4.7 初始化数据库 schema 并授权

Gravitino 的 JDBC 存储不会自动建表（仅内嵌 H2 开箱即用）。以 PostgreSQL 超级用户执行发行包自带的 schema SQL：

su - postgres -c "psql -d gravitino -v ON_ERROR_STOP=1 \
    -f /opt/gravitino/gravitino-1.3.1-bin/scripts/postgresql/schema-1.3.0-postgresql.sql"

实测回显（建表与索引）：

CREATE TABLE / CREATE INDEX / COMMENT ...

schema 由超级用户执行后表 owner 为 postgres，需为服务账号 gravitino 授权：

su - postgres -c "psql -d gravitino -c 'GRANT ALL ON SCHEMA public TO gravitino;'"
su - postgres -c "psql -d gravitino -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO gravitino;'"
su - postgres -c "psql -d gravitino -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO gravitino;'"

实测回显：

GRANT
GRANT
GRANT

以 gravitino 账号确认可访问：

PGPASSWORD=gravitino123 psql -U gravitino -h 127.0.0.1 -d gravitino -tAc 'SELECT COUNT(*) FROM entity_change_log'

实测回显：

0

4.8 启动 Gravitino Server

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

实测回显：

Gravitino Server is running[PID:7006]

查看启动日志关键行（存储识别、辅助服务、Web 端口）：

grep -iE 'Detected database|web server started|Done, Gravitino' logs/gravitino-server.log

实测回显：

Detected database product: postgresql
AuxiliaryServiceManager ... AuxService name:iceberg-rest, config:{... httpPort=9001 ...}
jetty-9.4.58.v20250814 ... jvm 17.0.20.1
Gravitino-webserver web server started on host 0.0.0.0 port 8090.
Done, Gravitino server started.

五、安装验证（REST / Web UI / gcli）

5.1 REST API 验证

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

实测回显：

{"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":{}}]}
{"code":0,"metalakes":[]}

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

5.2 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。

5.3 gcli CLI 验证

版本握手（客户端与服务器两端）：

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

创建 metalake 与 postgres catalog：

./bin/gcli.sh metalake create --metalake demo_metalake --comment "test metalake from gcli"
./bin/gcli.sh metalake list
./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"
./bin/gcli.sh catalog list --metalake demo_metalake

实测回显：

demo_metalake created
demo_metalake
postgres_cat catalog created
postgres_cat

💡 说明：gcli 默认连接 http://localhost:8090；catalog create 的 --properties 为逗号分隔键值对，不可带空格。postgres_cat 真实连接本机 PostgreSQL，即“catalog 对接”验证。

5.4 元数据落库验证

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

进一步以 REST 复核：

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"}]}

5.5 端口连通性验证

8090（REST/Web）、9001（iceberg-rest aux）、9101（lance-rest aux）逐一验证：

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/9101 根路径返回 404 属正常（辅助服务存活但无根路由）；任务常提到的默认 9000 并非本版默认，1.3.1 的 iceberg-rest 实际为 9001。

六、配置说明（含 JVM 堆）

6.1 JVM 堆内存限定与生效验证

服务进程为 org.apache.gravitino.server.GravitinoServer，堆限制在 256–512MB，经 jcmd 逐项确认生效：

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、MaxMetaspaceSize=256MB，与 GRAVITINO_MEM 完全一致。服务器进程 RSS 约 352MB（含堆 + 元空间 + 原生）。

6.2 systemd 托管（可选）

若以 systemd 将服务托管为本机单元，新建 /etc/systemd/system/gravitino.service：

[Unit]
Description=Apache Gravitino Server
After=network.target postgresql.service

[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Environment=GRAVITINO_HOME=/opt/gravitino/gravitino-1.3.1-bin
Environment=GRAVITINO_MEM=-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m
ExecStart=/opt/gravitino/gravitino-1.3.1-bin/bin/gravitino.sh start
ExecStop=/opt/gravitino/gravitino-1.3.1-bin/bin/gravitino.sh stop
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 注意：Environment= 每行只能声明一个变量；装载后执行 systemctl daemon-reload && systemctl enable --now gravitino。

七、注意事项

  • 必须 JDK 17：Gravitino 1.2+ 运行需 JDK 17，JAVA_HOME 指向 /usr/lib/jvm/java-17-openjdk-amd64。
  • JDBC 后端不自动建表：首次用 PostgreSQL 必须手工执行 scripts/postgresql/schema-<ver>-postgresql.sql 并授权。
  • PG 驱动需自补：libs/ 仅自带 H2 驱动，需下载 postgresql-42.7.4.jar。
  • 授权而非改属主：schema 由超级用户创建后表 owner 为 postgres，用 GRANT 授权给 gravitino；REASSIGN OWNED 因含系统对象会失败。
  • 健康检查路径：使用 /health，而非 /api/health/liveness、/api/health/readiness。
  • 端口默认值：REST/Web 8090、iceberg-rest 9001、lance-rest 9101（并非 9000）。

八、常见问题（FAQ）

Q1：启动后日志报 relation "entity_change_log" does not exist。

JDBC 后端不自动建表。以超级用户执行 scripts/postgresql/schema-1.3.0-postgresql.sql 后重启。

Q2：日志报 permission denied for table entity_change_log。

schema 由超级用户执行，表 owner 为 postgres。执行 GRANT ALL ON SCHEMA public 与 GRANT ALL PRIVILEGES ON ALL TABLES/SEQUENCES IN SCHEMA public TO gravitino。

Q3：日志报 class not found: org.postgresql.Driver。

libs/ 缺 PostgreSQL 驱动，下载 postgresql-42.7.4.jar 到 libs/ 后重启。

Q4：gcli.sh 创建命令报参数错误。

创建用 --metalake（创建 metalake 时必填）；catalog create --provider postgres --properties "k=v,k2=v2"，键值对逗号分隔且不可带空格。

Q5：/api/health/liveness 返回 404。

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

Q6：gravitino-env.sh 追加后启动语法报错。

原文件末行可能无换行导致首行粘连，用 sed 补 \n 后以 bash -n conf/gravitino-env.sh 校验。

九、卸载方式

# 1. 停止服务
cd /opt/gravitino/gravitino-1.3.1-bin
./bin/gravitino.sh stop

# 2. 删除安装目录（含 conf、日志、env 文件）
rm -rf /opt/gravitino

# 3.（可选）删除 PostgreSQL 库与用户
su - postgres -c "psql -c 'DROP DATABASE gravitino;'"
su - postgres -c "psql -c 'DROP USER gravitino;'"

# 4.（可选）移除 JDK 17
apt-get purge -y openjdk-17-jdk-headless

十、参考链接

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