从零开始搭建 Apache Gravitino

Setting up Apache Gravitino from Scratch.png

作者：王丹华
最后更新：[2025-01-12]

概述

在本教程中，您将学习如何从零开始安装和配置 Apache Gravitino。完成本指南后，您将拥有一个运行在您选择的存储后端上的完全功能的 Gravitino 服务器。

您将完成的任务：

安装 Apache Gravitino 从源码或预构建二进制文件，并配置基本服务器设置
配置存储后端 包括用于开发的 H2 和用于生产环境的 MySQL/PostgreSQL
配置 Gravitino 服务器 包括 Web 服务器、缓存和访问控制配置
验证安装 通过测试服务器端点和 Web UI 确保一切正常工作

前置条件

开始本教程之前，您需要：

系统要求：

Linux 或 macOS 操作系统，具有出站互联网访问权限用于下载需要的软件。
最低生产环境要求：4 CPU 核心，16GB 内存
最低开发环境要求：2 CPU 核心，8GB 内存

Java 开发工具包：

已安装并正确配置的 JDK 17 或更高版本

可选组件：

如果您选择 MySQL 或 PostgreSQL 作为存储后端，需要安装并正确配置相应的服务器

在继续之前，验证您的 Java 安装：

${JAVA_HOME}/bin/java -version

安装配置

步骤 1：获取 Gravitino 二进制文件

您有两种获取 Apache Gravitino 的选择：下载预构建版本或从源码构建。

选项 1：下载预构建版本

1. 下载最新版本

访问 Apache Gravitino GitHub Releases 页面并下载最新版本的压缩包。
例如，要下载版本 1.1.0，运行：

wget https://github.com/apache/gravitino/releases/download/v1.1.0/gravitino-1.1.0-bin.tar.gz

2. 解压包

tar -xzf gravitino-1.1.0-bin.tar.gz
cd gravitino-1.1.0-bin

选项 2：从源码构建

如果您更喜欢从源码构建或需要最新的开发功能，请参阅如何构建 Gravitino 获取详细的构建说明。

了解包结构

获取二进制文件后，熟悉目录布局：

gravitino-1.1.0-bin/
├── bin/                                    # 启动脚本
│   ├── gravitino.sh                        # 主服务器启动器
│   ├── gravitino-iceberg-rest-server.sh    # Iceberg REST 服务器启动器
│   └── gravitino-lance-rest-server.sh      # Lance REST 服务器启动器
├── conf/                                   # 配置文件
│   ├── gravitino.conf                      # 主服务器配置
│   ├── gravitino-iceberg-rest-server.conf  # Iceberg REST 配置
│   ├── gravitino-lance-rest-server.conf    # Lance REST 配置
│   ├── gravitino-env.sh                    # 环境变量
│   └── log4j2.properties                   # 日志配置
├── catalogs/                               # Catalog 特定配置
├── libs/                                   # 服务器依赖
├── iceberg-rest-server/                    # Iceberg REST 服务器包
├── lance-rest-server/                      # Lance REST 服务器包
├── logs/                                   # 日志文件（运行时创建）
├── data/                                   # 默认数据存储
└── scripts/                                # 数据库初始化脚本
└── web/                                    # 前端包

步骤 2：规划存储后端

为您的部署场景选择合适的存储后端。

开发/测试：H2 数据库（默认）

对于开发和测试环境，H2 提供快速设置：

优点：嵌入式数据库，无外部依赖，开箱即用
缺点：不适合生产环境，无数据一致性保证
配置：无需额外设置

生产环境：MySQL

对于生产环境，MySQL 是推荐的选择：

1. 安装和配置 MySQL 服务器

2. 创建数据库和用户

CREATE DATABASE gravitino;
CREATE USER 'gravitino'@'%' IDENTIFIED BY '<your_password>';
GRANT ALL PRIVILEGES ON gravitino.* TO 'gravitino'@'%';
FLUSH PRIVILEGES;

3. 初始化数据库模式

mysql -h <mysql_ip_address> -u gravitino -D gravitino -p < scripts/mysql/schema-1.1.0-mysql.sql

生产环境：PostgreSQL

作为替代的生产选项：

1. 安装和配置 PostgreSQL 服务器

2. 创建数据库和用户

CREATE DATABASE gravitino;
CREATE USER gravitino WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE gravitino TO gravitino;

3. 初始化数据库模式

psql -h <postgres_ip_address> -U gravitino -d gravitino -f scripts/postgresql/schema-1.1.0-postgresql.sql

步骤 3：配置 Gravitino Server

在 conf/gravitino.conf 文件中配置主服务器设置。

基本服务器配置

1. 配置 HTTP Server 设置

# HTTP 服务器配置
gravitino.server.webserver.host = 0.0.0.0
gravitino.server.webserver.httpPort = 8090
gravitino.server.webserver.minThreads = 24
gravitino.server.webserver.maxThreads = 200

2. 配置存储后端

对于 H2（开发环境）：

# 存储后端配置
gravitino.entity.store = relational
gravitino.entity.store.relational = JDBCBackend
gravitino.entity.store.relational.jdbcUrl = jdbc:h2
gravitino.entity.store.relational.jdbcDriver = org.h2.Driver
gravitino.entity.store.relational.jdbcUser = gravitino
gravitino.entity.store.relational.jdbcPassword = gravitino

对于 MySQL（生产环境）：

# 配置 MySQL
gravitino.entity.store.relational.jdbcUrl = jdbc:mysql://<mysql_ip_address>:3306/gravitino
gravitino.entity.store.relational.jdbcDriver = com.mysql.cj.jdbc.Driver
gravitino.entity.store.relational.jdbcUser = gravitino
gravitino.entity.store.relational.jdbcPassword = <your_password>

可选性能配置

1. 启用缓存以获得更好的性能

缓存提供显著的性能改进，特别是对于授权操作和元数据查找：

授权性能：通过缓存用户角色、权限和访问控制决策，显著减少权限检查的延迟
元数据检索：通过避免重复的数据库查找，加速频繁的 catalog、schema 和 table 元数据查询

# 启用缓存以获得更好的性能
gravitino.cache.enabled = true
gravitino.cache.implementation = caffeine
gravitino.cache.maxEntries = 10000
gravitino.cache.expireTimeInMs = 3600000

可选访问控制配置

配置授权

Gravitino 包含内置的元数据授权，您可以通过以下配置启用：

# 启用访问控制
gravitino.authorization.enable = true
gravitino.authorization.serviceAdmins = admin,gravitino

gravitino.authorization.serviceAdmins 定义负责创建 metalake 的服务管理员。
当服务管理员创建 metalake 时，他们自动成为所有者。作为所有者，他们对 metalake 拥有完全控制权，包括删除它的能力。如果需要，所有权可以转移给另一个用户。

有关全面的访问控制文档，请参阅访问控制。

配置身份验证

Apache Gravitino 支持三种身份验证机制：simple、OAuth 和 Kerberos。成功身份验证后，来自任何这些方法的用户身份直接映射到授权主体以管理访问控制决策。

默认行为：如果未明确配置身份验证，Gravitino 默认为 simple 身份验证模式。
登录方法：使用 gravitino.authorization.serviceAdmins 配置中指定的服务管理员登录。

有关详细的身份验证设置，请参阅如何进行身份验证。

环境配置

在 conf/gravitino-env.sh 中配置环境变量

# JVM 内存设置
export GRAVITINO_MEM="-Xms4g -Xmx4g -XX:MaxMetspaceSize=1g"

# Debug 选项（取消注释以进行 debug）
# export GRAVITINO_DEBUG_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000 -Dlog4j2.debug=true"

有关详细的服务器配置，请参阅 Apache Gravitino 服务器配置。

步骤 4：增强功能的可选 REST 服务

您可以在启动 Gravitino 服务器时将 Iceberg REST 或 Lance REST 服务作为辅助服务启用，或将它们作为独立服务运行。我们在后续文章中为它们准备了详细指南。

# 启用 Iceberg REST/Lance REST 作为辅助服务
gravitino.auxService.names = iceberg-rest,lance-rest

步骤 5：启动和验证安装

启动 Gravitino 服务器并验证安装。

启动 Gravitino Server

1. 以守护进程模式启动

./bin/gravitino.sh start

2. 检查 Server 状态

./bin/gravitino.sh status

3. 查看 Server 日志

tail -f logs/gravitino-server.log

验证安装

1. 检查 Server 健康状况

curl -v -X GET \
  -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" \
  http://localhost:8090/api/version

成功时，响应如下所示：

{"code":0,"version":{"version":"1.1.0","compileDate":"12/12/2025 12:38:33","gitCommit":"5a6b5ae772d50aff98878ae3659fba3598a9027f"}}

2. 访问 Web UI

打开浏览器并导航到 http://localhost:8090 以访问 Gravitino Web UI。

使用简单身份验证模式时的默认登录页面（启用访问控制）：
Gravitino 登录页面
如果禁用访问控制，直接进入 metalake 管理页面：

Gravitino metalake 页面

3. 验证辅助服务（如果启用）

# 检查 Iceberg REST 服务
curl http://localhost:9001/iceberg/v1/config

# 检查 Lance REST 服务
curl http://localhost:9101/lance/v1/namespace/%24/list

创建示例元数据

通过创建示例元数据对象来测试安装。

创建第一个 metalake

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_metalake", "comment": "My first metalake"}' \
  http://localhost:8090/api/metalakes

注意：如果已启用访问控制，需要在命令中添加 Authorization 头（假设使用用户名 'admin' 和密码 '123'）：
curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:123' | base64)" \
  -d '{"name": "my_metalake", "comment": "My first metalake"}' \
  http://localhost:8090/api/metalakes

创建示例 catalog

注意：此示例创建 Hive catalog。在继续之前，请确保有一个运行的 Hive 集群，其中 Hive Metastore 服务可访问。如果您没有 Hive 集群，可以使用不同的 catalog 类型（如 MySQL catalog）。

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "catalog_hive",
    "type": "relational",
    "provider": "hive",
    "comment": "My Hive catalog",
    "properties": {
      "metastore.uris": "thrift://<hive_metastore_host>:<port>"
    }
  }' \
  http://localhost:8090/api/metalakes/my_metalake/catalogs

在 Web GUI 上管理 catalog

创建 catalog：
Gravitino catalog 创建

查看/管理所有 catalog：
Gravitino catalog 页面

恭喜

您已成功完成 Apache Gravitino 设置！现在拥有一个完全功能的 Apache Gravitino 安装，包括：

在端口 8090 上运行的元数据服务器
为您的环境配置的存储后端
用于 Iceberg 和 Lance 集成的可选辅助 REST 服务
用于验证功能的示例元数据对象

Apache Gravitino 服务器已准备好管理整个数据生态系统中的元数据。

下一步

继续阅读 Iceberg Catalog
关注并收藏 Apache Gravitino 仓库

Apache Gravitino 正在快速发展，本文基于最新版本编写。如果您遇到问题，请参考官方文档或在 GitHub 上提交问题。