Apache Gravitino 1.3.1 Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Apache Gravitino 1.3.1（Gravitino Server + PostgreSQL 后端），涵盖自构建 JDK 17 镜像、schema 自动初始化、挂载 entrypoint 启动脚本、JVM 堆内存限定、端口映射与 REST/gcli 验证，并给出等价的 docker run 运行方式。部署流程在 Ubuntu 22.04 + Docker（Compose v2）环境实测通过。

一、环境信息

宿主机操作系统：Ubuntu 22.04.5 LTS（x86_64）
Docker 版本：Docker Engine（含 Compose v2 插件）
基础镜像：ubuntu:22.04（自构建 Gravitino 镜像）+ postgres:14（后端）
组件版本：Apache Gravitino 1.3.1
服务名 / 容器名：gravitino / gravitino-server、postgres / gravitino-postgres
网络：compose 项目自定义 bridge 网络 gravitino-net
端口映射：8090（REST/Web）、9001（iceberg-rest aux）、9101（lance-rest aux）、5432（PostgreSQL）
部署目录：/opt/data/ops/gravitino-compose
JVM 堆：-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m

二、镜像选型说明

镜像	构建方式	版本	说明
自构建镜像（本文）	`ubuntu:22.04` 基础 + Dockerfile	Gravitino 1.3.1	构建时安装 JDK 17，从官方 dlcdn 下载 1.3.1 发行包并补 PostgreSQL JDBC 驱动
postgres 后端	官方 `postgres:14` 镜像	PostgreSQL 14	作为 Gravitino 元数据存储后端
自构建 centos 版	`centos:8` 基础 + 同款 Dockerfile（JDK 17 路径换为 `/usr/lib/jvm/java-17-openjdk`）	Gravitino 1.3.1	适用于 CentOS-based 宿主机

💡 说明：采用自构建 ubuntu:22.04 + 官方发行包，可精确锁定 1.3.1 版本，规避预构建镜像标签漂移。Gravitino 运行需 JDK 17。

三、前置条件

已安装 Docker Engine 与 Docker Compose 插件：docker --version && docker compose version
宿主机已规划部署目录 /opt/data/ops/gravitino-compose
可访问 dlcdn.apache.org 与 repo1.maven.org（构建阶段下载发行包与 JDBC 驱动）

四、部署步骤

4.1 创建部署目录与文件

mkdir -p /opt/data/ops/gravitino-compose
cd /opt/data/ops/gravitino-compose

目录内含 Dockerfile、gravitino-compose.yml、entrypoint.sh 三份文件。

4.2 编写 Dockerfile

保存为 /opt/data/ops/gravitino-compose/Dockerfile：

FROM ubuntu:22.04
RUN apt-get update && DEBIAN_FRONTEND=noninteractive \
    apt-get install -y openjdk-17-jdk-headless wget tar postgresql-client && \
    rm -rf /var/lib/apt/lists/*
RUN mkdir -p /opt/gravitino && cd /opt/gravitino && \
    wget -q https://dlcdn.apache.org/gravitino/1.3.1/gravitino-1.3.1-bin.tar.gz && \
    tar -xzf gravitino-1.3.1-bin.tar.gz && rm -f gravitino-1.3.1-bin.tar.gz
RUN cd /opt/gravitino/gravitino-1.3.1-bin/libs && \
    wget -q https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.4/postgresql-42.7.4.jar
ENV JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
ENV GRAVITINO_HOME=/opt/gravitino/gravitino-1.3.1-bin
ENV GRAVITINO_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
ENV PATH=$GRAVITINO_HOME/bin:$JAVA_HOME/bin:$PATH
WORKDIR /opt/gd

💡 说明：构建阶段安装 JDK 17（Gravitino 1.2+ 运行需 JDK 17）、下载 1.3.1 发行包解压到 /opt/gravitino/gravitino-1.3.1-bin，并补齐 PostgreSQL JDBC 驱动（发行包 libs/ 只自带 H2 驱动）。

4.3 编写 gravitino-compose.yml

保存为 /opt/data/ops/gravitino-compose/gravitino-compose.yml：

services:
  postgres:
    image: postgres:14
    container_name: gravitino-postgres
    environment:
      POSTGRES_USER: gravitino
      POSTGRES_PASSWORD: gravitino123
      POSTGRES_DB: gravitino
    ports:
      - "5432:5432"
    volumes:
      - ./data/pg:/var/lib/postgresql/data
    networks: [gravitino-net]

  gravitino:
    build: .
    container_name: gravitino-server
    hostname: gravitino
    entrypoint: ["/opt/gd/entrypoint.sh"]
    depends_on: [postgres]
    ports:
      - "8090:8090"   # REST / Web UI
      - "9001:9001"   # iceberg-rest aux
      - "9101:9101"   # lance-rest aux
    volumes:
      - ./entrypoint.sh:/opt/gd/entrypoint.sh:ro
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8090/health"]
      interval: 10s
      timeout: 5s
      retries: 30
networks:
  gravitino-net:
    driver: bridge

💡 说明：gravitino 依赖 postgres 就绪后启动；DB 用户即库 owner（gravitino），schema 由其创建，故表 owner 与连接用户一致，无需额外 GRANT。

4.4 编写 entrypoint.sh

保存为 /opt/data/ops/gravitino-compose/entrypoint.sh，并赋执行权限：

chmod +x /opt/data/ops/gravitino-compose/entrypoint.sh

内容如下：

#!/usr/bin/env bash
set -x
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"
export PATH=$GRAVITINO_HOME/bin:$JAVA_HOME/bin:$PATH

# 1) 等待 PostgreSQL 就绪
until PGPASSWORD=gravitino123 pg_isready -h postgres -U gravitino -d gravitino; do
  echo "waiting for postgres ..."
  sleep 2
done

# 2) 将存储后端由 H2 切换为 PostgreSQL
sed -i 's|jdbcUrl = jdbc:h2|jdbcUrl = jdbc:postgresql://postgres:5432/gravitino|' $GRAVITINO_HOME/conf/gravitino.conf
sed -i 's|jdbcDriver = org.h2.Driver|jdbcDriver = org.postgresql.Driver|' $GRAVITINO_HOME/conf/gravitino.conf
sed -i 's|jdbcPassword = gravitino|jdbcPassword = gravitino123|' $GRAVITINO_HOME/conf/gravitino.conf

# 3) 初始化 schema（幂等）
PGPASSWORD=gravitino123 psql -h postgres -U gravitino -d gravitino -v ON_ERROR_STOP=1 \
  -f $GRAVITINO_HOME/scripts/postgresql/schema-1.3.0-postgresql.sql

# 4) 启动 Gravitino Server 并保持前台
$GRAVITINO_HOME/bin/gravitino.sh start
echo "=== gravitino ready, keep alive ==="
tail -f /dev/null

💡 说明：JDBC 后端不自动建表，entrypoint.sh 在启动前显式执行发行包自带的 schema-1.3.0-postgresql.sql（由库 owner 用户执行，避免权限问题）。用挂载脚本启动比内联 sh -c 的引号嵌套更稳妥。

4.5 构建并启动

cd /opt/data/ops/gravitino-compose
docker compose -f gravitino-compose.yml up -d --build

实测回显（典型）：

 Image gravitino-compose-gravitino Built
 Network gravitino-compose_gravitino-net Created
 Container gravitino-postgres Created
 Container gravitino-server   Created
 Container gravitino-postgres Started
 Container gravitino-server   Started

查看容器状态：

cd /opt/data/ops/gravitino-compose
docker compose ps

实测回显（典型）：

NAME                 IMAGE                          SERVICE    STATUS                        PORTS
gravitino-postgres   postgres:14                    postgres   Up                            0.0.0.0:5432->5432/tcp
gravitino-server     gravitino-compose-gravitino    gravitino  Up (health: starting)         0.0.0.0:8090-8090->8090/tcp, ...

4.6 验证服务（REST / Web）

宿主机访问 REST 接口：

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

实测回显：

{"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":{}}]}
HTTP 200

查看服务启动日志关键行：

cd /opt/data/ops/gravitino-compose
docker compose logs gravitino | grep -iE 'Detected database|port 8090|Done, Gravitino'

实测回显：

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

4.7 gcli 建元数据验证

docker exec -it gravitino-server bash \
  -c "export PATH=/opt/gravitino/gravitino-1.3.1-bin/bin:/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  gcli.sh --client"

实测回显：

Apache Gravitino 1.3.1

创建 metalake 与 postgres catalog：

docker exec -it gravitino-server bash \
  -c "export PATH=/opt/gravitino/gravitino-1.3.1-bin/bin:/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  gcli.sh metalake create --metalake demo_metalake --comment 'created from gcli in compose'"
docker exec -it gravitino-server bash \
  -c "export PATH=/opt/gravitino/gravitino-1.3.1-bin/bin:/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  gcli.sh metalake list"

实测回显：

demo_metalake created
demo_metalake

创建对接容器内 PostgreSQL 的 catalog，并列出：

docker exec -it gravitino-server bash \
  -c "export PATH=/opt/gravitino/gravitino-1.3.1-bin/bin:/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  gcli.sh catalog create --metalake demo_metalake --name postgres_cat --provider postgres \
  --properties 'jdbc-url=jdbc:postgresql://postgres:5432/gravitino,jdbc-user=gravitino,jdbc-password=gravitino123,jdbc-database=gravitino,jdbc-driver=org.postgresql.Driver'"
docker exec -it gravitino-server bash \
  -c "export PATH=/opt/gravitino/gravitino-1.3.1-bin/bin:/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  gcli.sh catalog list --metalake demo_metalake"

实测回显：

postgres_cat catalog created
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":"created from gcli in compose","properties":{"in-use":"true"},"audit":{"creator":"anonymous","createTime":"2026-10-11T12:56:34.334380393Z"}}]}
{"code":0,"identifiers":[{"namespace":["demo_metalake"],"name":"postgres_cat"}]}

4.8 验证 JVM 堆生效与端口

docker exec -it gravitino-server bash \
  -c "export PATH=/usr/lib/jvm/java-17-openjdk-amd64/bin:\$PATH; \
  PID=\$(pgrep -f GravitinoServer | head -1); jcmd \$PID VM.flags | tr ' ' '\n' | grep -iE 'HeapSize|MaxMetaspace'"

实测回显：

-XX:InitialHeapSize=268435456
-XX:MaxHeapSize=536870912
-XX:MaxMetaspaceSize=268435456

宿主机逐一验证映射端口：

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

五、数据持久化说明

Gravitino 的元数据存于 PostgreSQL 数据卷，日志与运行态存于安装目录。若要持久化，把以下目录挂载回宿主机：

volumes:
  - ./data/pg:/var/lib/postgresql/data
  - ./data/gravitino/logs:/opt/gravitino/gravitino-1.3.1-bin/logs

💡 说明：PostgreSQL 数据卷持久化后，容器重建不丢 metalake/catalog 元数据；日志目录挂载便于直接在宿主机查看 gravitino-server.log。

六、常用环境变量表

本例通过 Dockerfile ENV 与 entrypoint 脚本内的 export 注入，Compose 层也可用 environment: 注入：

环境变量	实测值	说明
`JAVA_HOME`	`/usr/lib/jvm/java-17-openjdk-amd64`	JDK 17 家目录
`GRAVITINO_HOME`	`/opt/gravitino/gravitino-1.3.1-bin`	Gravitino 安装根目录
`GRAVITINO_MEM`	`-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m`	JVM 堆参数（256–512MB）
`GRAVITINO_USE_WEB_V2`	`true`（默认）	启用 Web UI v2
`PATH`	`$GRAVITINO_HOME/bin:$JAVA_HOME/bin:$PATH`	命令搜索路径

七、常用配置参数说明

配置	说明
`gravitino.entity.store.relational.jdbcUrl`	JDBC 连接串，容器内为 `jdbc:postgresql://postgres:5432/gravitino`
`gravitino.entity.store.relational.jdbcDriver`	`org.postgresql.Driver`（PostgreSQL 后端）
`gravitino.entity.store.relational.jdbcUser`	`gravitino`
`gravitino.entity.store.relational.jdbcPassword`	`gravitino123`
`gravitino.server.webserver.httpPort`	REST/Web 端口，默认 `8090`
iceberg-rest aux `httpPort`	`9001`
lance-rest aux `httpPort`	`9101`

八、等价 docker run 运行方式

不加 Compose，可用两条 docker run 启同一套服务（先建网络）：

docker network create gravitino-net

docker run -d --name gravitino-postgres --network gravitino-net \
  -e POSTGRES_USER=gravitino -e POSTGRES_PASSWORD=gravitino123 -e POSTGRES_DB=gravitino \
  -p 5432:5432 -v /opt/data/ops/gravitino-compose/data/pg:/var/lib/postgresql/data postgres:14

docker run -d --name gravitino-server --network gravitino-net --hostname gravitino \
  -p 8090:8090 -p 9001:9001 -p 9101:9101 \
  -v /opt/data/ops/gravitino-compose/entrypoint.sh:/opt/gd/entrypoint.sh:ro \
  gravitino-compose-gravitino

💡 说明：镜像默认名即 gravitino-compose-gravitino；entrypoint.sh 内已等待 postgres 就绪并初始化 schema。

九、常用运维命令

# 停止并移除容器
cd /opt/data/ops/gravitino-compose
docker compose down

# 重建并后台启动
docker compose up -d --build

# 查看日志（跟踪启动过程）
docker compose logs -f gravitino

# 重启服务
docker compose restart gravitino

# 容器内交互式进入 Gravitino 命令行
docker exec -it gravitino-server bash

十、常见问题（FAQ）

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

JDBC 后端不自动建表。确认 entrypoint.sh 已执行 scripts/postgresql/schema-1.3.0-postgresql.sql。

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

镜像 libs/ 缺 PostgreSQL 驱动，确认 Dockerfile 已下载 postgresql-42.7.4.jar 到 libs/。

Q3：gravitino 启动时连不上数据库。

depends_on 只保证启动顺序，不保证就绪；entrypoint 中的 pg_isready 轮询即用于等待 PostgreSQL 真正可用，保留该逻辑即可。

Q4：健康检查 /api/health/liveness 返回 404。

1.3.1 健康检查真值路径为 /health（healthcheck 已按此配置）；版本接口为 /api/version。

Q5：gcli.sh 提示找不到命令。

需在 docker exec 内显式 export PATH=$GRAVITINO_HOME/bin:$JAVA_HOME/bin:$PATH 后再执行 gcli.sh。

十一、参考链接

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