Apache Gravitino 1.3.1 配置参数详解

系统讲解 Apache Gravitino 1.3.1 核心配置参数，覆盖存储后端（H2/PostgreSQL，entity.store.relational.*）、Web 服务端口（8090）、iceberg-rest（9001）与 lance-rest（9101）辅助服务、认证与 JVM 堆内存（256–512MB），给出每个参数的作用、默认值、修改方式与生产配置模板。默认值取自 1.3.1 真实环境实测。

Apache GravitinoApache Gravitino参数调优Apache大数据配置详解2026/10/11

Apache Gravitino 1.3.1 配置参数详解

目标：系统讲解 Apache Gravitino 1.3.1 的核心配置参数，覆盖存储后端、Web 服务端口、辅助服务、认证与 JVM 堆内存，并给出每个参数的作用、默认值、修改方式与生产配置模板。所有默认值均在 Apache Gravitino 1.3.1 真实环境实测（conf/gravitino.conf + conf/gravitino-env.sh + 启动日志）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS / CentOS 8（Gravitino 1.3.1 跨平台配置一致）
  • 组件版本：Apache Gravitino 1.3.1
  • 安装目录：/opt/gravitino/gravitino-1.3.1-bin
  • 主配置文件：conf/gravitino.conf（服务端参数）
  • 环境变量文件：conf/gravitino-env.sh（JAVA_HOME、GRAVITINO_HOME、JVM 堆）
  • 运行日志：logs/gravitino-server.log
  • 存储后端：内嵌 H2（默认）或 PostgreSQL / MySQL / MariaDB

二、前置条件

  • 已完成 Gravitino 1.3.1 安装（发行包解压到 /opt/gravitino/gravitino-1.3.1-bin）
  • 已确认 java -version 为 JDK 17
  • 若使用 PostgreSQL：已建库/用户、补齐 JDBC 驱动、执行 schema SQL 并授权
  • 具备读取 conf/ 与 logs/ 的权限

三、参数查看与修改方式

3.1 查看当前配置

查看存储后端相关键（编号为文件行号）：

cd /opt/gravitino/gravitino-1.3.1-bin
grep -nE 'jdbcUrl|jdbcDriver|jdbcUser|jdbcPassword' conf/gravitino.conf
grep -n 'webserver.httpPort' conf/gravitino.conf
tail -3 conf/gravitino-env.sh

实测回显：

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
gravitino.server.webserver.httpPort = 8090
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"

辅助服务端口可从启动日志确认：

grep -iE 'web server started' logs/gravitino-server.log

实测回显：

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.

3.2 修改方式对比

方式操作生效时机
conf/gravitino.conf直接编辑键值对服务重启后
conf/gravitino-env.sh编辑 JAVA_HOME/GRAVITINO_HOME/GRAVITINO_MEM服务重启后
libs/放置/替换 JDBC 驱动 jar服务重启后
scripts/postgresql/数据库 schema 初始化 SQL首次建表时

💡 说明：Gravitino 以文件配置为主，修改 gravitino.conf 或 gravitino-env.sh 后需 ./bin/gravitino.sh stop && ./bin/gravitino.sh start 重启生效。

四、参数总览

本文覆盖的参数汇总（默认值均为 1.3.1 实测）：

分类参数默认值（实测/官方）说明
存储后端gravitino.entity.store.relational.jdbcUrljdbc:h2JDBC 连接串
存储后端gravitino.entity.store.relational.jdbcDriverorg.h2.DriverJDBC 驱动类
存储后端gravitino.entity.store.relational.jdbcUsergravitino数据库用户
存储后端gravitino.entity.store.relational.jdbcPasswordgravitino数据库密码
Web 服务gravitino.server.webserver.httpPort8090REST/Web 端口
辅助服务iceberg-rest httpPort9001Iceberg REST 服务端口
辅助服务lance-rest httpPort9101Lance REST 服务端口
环境变量JAVA_HOME系统 JDK 17 路径JDK 家目录
环境变量GRAVITINO_HOME安装根目录安装目录
环境变量GRAVITINO_MEM默认约 1GJVM 堆参数
环境变量GRAVITINO_USE_WEB_V2true启用 Web UI v2

五、核心参数分类详解

5.1 存储后端段（entity.store.relational.*）

Gravitino 的实体（metalake、catalog、schema、table 等元数据）默认落在内嵌 H2 文件库；生产建议切换为外部关系库。相关键位于 conf/gravitino.conf 第 61–67 行附近：

# conf/gravitino.conf（切换为 PostgreSQL 后）
gravitino.entity.store.relational.jdbcUrl = jdbc:postgresql://127.0.0.1:5432/gravitino
gravitino.entity.store.relational.jdbcDriver = org.postgresql.Driver
gravitino.entity.store.relational.jdbcUser = gravitino
gravitino.entity.store.relational.jdbcPassword = gravitino123
参数默认值说明
jdbcUrljdbc:h2连接串；H2 开箱即用，PostgreSQL 需 JDBC 驱动与 schema 初始化
jdbcDriverorg.h2.Driver驱动类；PostgreSQL 为 org.postgresql.Driver
jdbcUsergravitino数据库用户
jdbcPasswordgravitino数据库密码

⚠️ 注意：Gravitino 的 JDBC 存储不会自动建表（仅 H2 开箱即用），且发行包 libs/ 只自带 H2 驱动。使用 PostgreSQL 时必须：① 将 postgresql-<ver>.jar（本次 42.7.4）放入 libs/；② 执行 scripts/postgresql/schema-1.3.0-postgresql.sql 建表；③ 对服务账号授权（GRANT ALL ON SCHEMA public 及 ALL TABLES/SEQUENCES IN SCHEMA public）。

5.2 Web 服务端口段（webserver.httpPort）

# conf/gravitino.conf
gravitino.server.webserver.httpPort = 8090
参数默认值说明
gravitino.server.webserver.httpPort8090REST API 与 Web UI 对外端口

💡 说明：启动日志回显 Gravitino-webserver web server started on host 0.0.0.0 port 8090.，即服务监听 0.0.0.0:8090；REST 健康检查路径为 /health，版本接口为 /api/version。

5.3 辅助服务段（iceberg-rest / lance-rest）

发行包内置两个辅助 REST 服务，随主服务一并启动：

# 启动日志中的辅助服务回显
AuxiliaryServiceManager ... AuxService name:iceberg-rest, config:{... httpPort=9001 ...}
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.
服务默认端口（实测）说明
iceberg-rest9001提供 Iceberg REST Catalog 网关
lance-rest9101提供 Lance REST 接口

💡 说明：两辅助服务根路径返回 HTTP 404 属正常（无根路由，服务存活）。注意默认端口中 iceberg-rest 为 9001，并非 9000；如需变更，在对应辅助服务配置段调整 httpPort 后重启。

5.4 认证与鉴权（可选）

Gravitino 默认未启用认证，REST 与 gcli 可直接访问（实测 audit.creator 为 anonymous）。生产环境建议在 conf/gravitino.conf 中配置认证与鉴权（如 OAuth / Kerberos 等插件），并在 gcli 侧携带相应凭据。示例管理账号可用 root + 密码 q1w2e3r4（属安全插件范畴，需按官方文档启用）。

配置项默认说明
认证（authenticator）未启用启用后 REST/gcli 需携带凭据
鉴权（authorization）未启用控制 metalake/catalog 等资源的访问权限

5.5 JVM 堆内存段（GRAVITINO_MEM）

conf/gravitino-env.sh 中通过 GRAVITINO_MEM 控制 JVM 堆（默认约 1G，按要求压到 256–512MB）：

# conf/gravitino-env.sh
export GRAVITINO_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
变量实测值说明
GRAVITINO_MEM-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m初始堆 256MB / 上限 512MB / 元空间 256MB

生效验证（jcmd）：

PID=$(pgrep -f GravitinoServer | head -1)
jcmd $PID VM.flags

实测回显：

InitialHeapSize=268435456
MaxHeapSize=536870912
MaxMetaspaceSize=268435456
UseG1GC

⚠️ 注意：修改 gravitino-env.sh 时注意文件末行换行符，避免 append 造成粘连；修改后用 bash -n conf/gravitino-env.sh 校验语法。

六、生产配置模板

本模板面向「16GB 内存、本机 PostgreSQL、单实例元数据治理」的典型场景：

# /opt/gravitino/gravitino-1.3.1-bin/conf/gravitino.conf
gravitino.entity.store.relational.jdbcUrl = jdbc:postgresql://127.0.0.1:5432/gravitino
gravitino.entity.store.relational.jdbcDriver = org.postgresql.Driver
gravitino.entity.store.relational.jdbcUser = gravitino
gravitino.entity.store.relational.jdbcPassword = gravitino123
gravitino.server.webserver.httpPort = 8090

# /opt/gravitino/gravitino-1.3.1-bin/conf/gravitino-env.sh
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"

配套初始化（PostgreSQL 后端）：

# 1) 补 JDBC 驱动
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

# 2) 初始化 schema
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'
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;'"

💡 说明：内存紧张或仅做元数据验证场景，可不改 GRAVITINO_MEM（保持 256–512MB）；元数据量大时应在测试环境观测基线后再上调堆上限，但始终不超出本机物理内存。

七、常见问题（FAQ）

Q1：改成 PostgreSQL 后启动报 relation "entity_change_log" does not exist。

JDBC 后端不自动建表，执行 scripts/postgresql/schema-1.3.0-postgresql.sql 后重启。

Q2：报 class not found: org.postgresql.Driver。

libs/ 缺 PostgreSQL 驱动，放入 postgresql-42.7.4.jar 后重启。

Q3：报 permission denied for table entity_change_log。

schema 由超级用户创建，表 owner 为 postgres；对 gravitino 执行 GRANT ALL ON SCHEMA public 及 ALL TABLES/SEQUENCES。

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

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

Q5：修改配置后未生效。

gravitino.conf 与 gravitino-env.sh 的改动需重启服务（gravitino.sh stop/start）方生效；JVM 堆参数改动仅在重启后由 jcmd 可见。

八、参考链接

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