CentOS 8 安装 Apache Gravitino 1.3.1 指南

在 CentOS 8 上以官方 tar.gz 安装 Apache Gravitino 1.3.1，完成 JDK 17 与 PostgreSQL 13 前置、数据库 schema 初始化与 JDBC 驱动补齐、下载校验解压、gravitino.conf/gravitino-env.sh 配置、JVM 堆 256–512MB 限定，并验证 REST（8090）/gcli/Web UI 全链路。安装与验证在 CentOS Linux 8.4 真实服务器实测通过。

Apache GravitinoApache Gravitino安装部署Apache大数据CentOS 82026/10/11

CentOS 8 安装 Apache Gravitino 1.3.1 指南

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

一、环境信息

  • 操作系统：CentOS Linux release 8.4.2105（x86_64）
  • 包管理器：dnf 4.4.2
  • 运行时环境：OpenJDK 17（17.0.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 13.5（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 权限，可访问 mirrors.tuna.tsinghua.edu.cn 与 dlcdn.apache.org
  • 已安装 wget、tar
  • 已安装 java-17-openjdk-devel，并确认 java -version 为 JDK 17
  • 已安装并初始化 PostgreSQL 13，创建库 gravitino 与用户 gravitino
  • 本机 hostname -I 可返回内网地址（用于自检端口）

⚠️ 注意：CentOS 8 默认不预装任何 JDK（java: command not found），且不含 which 命令。本次实测以 command -v 与 readlink -f 替代 which，请勿照搬使用 which。

三、版本选型说明

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 运行（构建可用 8/11/17，运行需 17）。元数据存储可用内嵌 H2（开箱即用）或 PostgreSQL / MySQL / MariaDB，本文采用本机 PostgreSQL 13 做真实持久化。

四、官方 tar.gz 安装方案

4.1 安装前置工具与 JDK 17

CentOS 8 系统无预装 JDK，需显式安装：

java -version

实测回显：

bash: java: command not found

安装 JDK 17（AppStream 默认流即 17.0.1）：

dnf install -y java-17-openjdk-devel wget tar

验证版本与安装路径：

command -v java && java -version
readlink -f /usr/lib/jvm/java-17-openjdk

实测回显：

/usr/bin/java
openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)
/usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64

JAVA_HOME 取软链路径 /usr/lib/jvm/java-17-openjdk，后续写入启动环境。

4.2 安装 PostgreSQL 13

CentOS 8 AppStream 的 PostgreSQL 默认 module stream 为 10，需切换到 13：

dnf module list postgresql

实测回显（[d] 为默认、[e] 为当前启用）：

postgresql   9.6    ...
postgresql   10     [d][e]
postgresql   12     ...
postgresql   13     ...

重置并启用 13 流后安装：

dnf module reset -y postgresql
dnf module enable -y postgresql:13
dnf install -y postgresql-server postgresql-contrib

首次初始化数据库，实测因 locale 报错：

postgresql-setup --initdb

实测回显：

ERROR: Initializing database failed, possibly see /var/lib/pgsql/initdb_postgresql.log

查看日志与可用 locale：

cat /var/lib/pgsql/initdb_postgresql.log
locale -a
rpm -q glibc-langpack-en

实测回显：

initdb: error: invalid locale settings; check LANG and LC_* environment variables
C
C.utf8
POSIX
package glibc-langpack-en is not installed

以 C.UTF-8 重建数据目录：

rm -rf /var/lib/pgsql/data
su - postgres -c 'LANG=C.UTF-8 initdb -D /var/lib/pgsql/data --locale=C.UTF-8'
systemctl start postgresql && systemctl is-active postgresql

实测回显：

Success. You can now start the database server using: /usr/bin/pg_ctl ...
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 13.5 on x86_64-redhat-linux-gnu, compiled by gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-4), 64-bit
CREATE ROLE
CREATE DATABASE

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

dlcdn 在本网络链路被限速（实测 ≈45 KB/s），改用 Apache 官方镜像（清华大学 TUNA）全速下载：

mkdir -p /opt/gravitino
cd /opt/gravitino
wget https://mirrors.tuna.tsinghua.edu.cn/apache/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
sha512sum -c gravitino-1.3.1-bin.tar.gz.sha512

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

gravitino-1.3.1-bin.tar.gz: OK

解压并查看目录结构：

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）、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|jdbcUrl = jdbc:h2|jdbcUrl = jdbc:postgresql://127.0.0.1:5432/gravitino|' conf/gravitino.conf
sed -i 's|jdbcDriver = org.h2.Driver|jdbcDriver = org.postgresql.Driver|' conf/gravitino.conf
sed -i 's|jdbcPassword = gravitino|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' \
    'export GRAVITINO_HOME=/opt/gravitino/gravitino-1.3.1-bin' \
    'export GRAVITINO_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"' >> conf/gravitino-env.sh
tail -4 conf/gravitino-env.sh
bash -n conf/gravitino-env.sh && echo SYNTAX_OK

实测回显：

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

⚠️ 注意：该文件原末行无换行符，直接 append 会使首行粘连（如 ...:-true}"export JAVA_HOME=...），导致语法异常。必要时用 sed 's|:-true}"export|:-true}"\nexport|' 补齐换行，再用 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:1973]

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

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

实测回显：

Detected database product: postgresql
jetty-9.4.58.v20250814 ... jvm 17.0.1+12-LTS
iceberg-rest web server started on host 0.0.0.0 port 9001.
lance-rest web server started on host 0.0.0.0 port 9101.
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-11T12:56:34.334380393Z"}}]}
{"code":0,"identifiers":[{"namespace":["demo_metalake"],"name":"postgres_cat"}]}

六、配置说明（含 JVM 堆）

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

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

PID=$(pgrep -f GravitinoServer | head -1); echo "server PID=$PID"
/usr/lib/jvm/java-17-openjdk/bin/jcmd $PID VM.flags | tr ' ' '\n' | grep -iE 'HeapSize|MaxMetaspace|UseG1'
/usr/lib/jvm/java-17-openjdk/bin/jcmd $PID GC.heap_info | head -4

实测回显：

server PID=1973
-XX:InitialHeapSize=268435456
-XX:MaxHeapSize=536870912
-XX:MaxMetaspaceSize=268435456
-XX:+UseG1GC
 garbage-first heap   total 262144K, used 116732K ...
 Metaspace       used 47292K, committed 47744K, reserved 262144K

即 InitialHeapSize=256MB、MaxHeapSize=512MB、MaxMetaspaceSize=256MB，与 GRAVITINO_MEM 完全一致。

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
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。
  • 系统缺 which：CentOS 8 极简安装无 which，请用 command -v / readlink -f 替代。
  • PG 默认流偏低：AppStream PostgreSQL 默认 stream 为 10，需 dnf module enable postgresql:13 后再装。
  • PG 需先 initdb：postgresql-setup --initdb 未执行时服务起不来；缺 glibc-langpack-en 会报 invalid locale，可用 LANG=C.UTF-8 ... --locale=C.UTF-8 重建。
  • JDBC 后端不自动建表：首次用 PostgreSQL 必须手工执行 scripts/postgresql/schema-<ver>-postgresql.sql 并授权。
  • PG 驱动需自补：libs/ 仅自带 H2 驱动，需下载 postgresql-42.7.4.jar。
  • 下载源：dlcdn 可能限速，可换用 Apache 官方镜像（TUNA），并以官方 sha512 校验一致性。

八、常见问题（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（REASSIGN OWNED 因含系统对象会失败，不建议）。

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
dnf remove -y java-17-openjdk-devel

十、参考链接

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