作者：xiaojing fang
最后更新：2026-01-26

概述

在本教程中，您将学习如何配置和使用 Gravitino Iceberg REST catalog 服务器。完成本指南后，您将拥有一个功能完整的 Iceberg REST 服务，使标准 Iceberg 客户端能够通过 HTTP API 与 Gravitino 交互。

您将完成的任务：

• 配置 Iceberg REST 服务：在 Gravitino 服务器中将其作为辅助服务，支持各种 catalog 后端
• 验证 REST 端点：通过测试服务端点确保功能正常
• 连接 Iceberg 客户端：包括 Apache Spark，通过 REST API 执行 Table 操作
• 探索后端选项：包括 Hive 和 JDBC 后端，支持本地和云存储配置

Apache Iceberg 定义了一个 REST catalog API，客户端使用该 API 来发现和管理 Iceberg Namespace 和 Table。Gravitino Iceberg REST 服务实现了这个 API，并充当代理，使 Iceberg 客户端能够通过标准 HTTP 接口与 Gravitino 通信。

核心概念：

• Iceberg REST catalog：用于 Iceberg 操作的标准 HTTP API
• Gravitino Iceberg REST 服务：实现 Iceberg REST API 并连接到 catalog 后端（Hive 或 JDBC）
• 客户端流程：Spark 或其他 Iceberg 客户端指向 REST 端点并执行命名空间/Table 操作

REST 端点基础路径为 http://<host>:<port>/iceberg/，符合 Apache Iceberg REST catalog 规范。

选择 Gravitino Iceberg catalog service 的原因：

• 符合标准：为 Iceberg 客户端提供 API，无需特定供应商的配置
• 集中治理：通过单一 REST 端点对 Namespace 和 Table 进行集中管理
• 后端灵活性：支持 Hive 或 JDBC 作为 catalog 存储
• 多引擎访问：Spark、Trino 和其他 Iceberg 客户端可以共享同一个 catalog
• 安全增强：启用时支持凭证分发和访问控制（ACL）
• 可观测性和运维：通过审计日志、指标和事件监听器来进行运维
• 性能改进：Table 元数据缓存和 Table scan plan 缓存

前提条件

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

系统要求：

• Linux 或 macOS 操作系统，具有互联网访问权限用于下载
• 已安装并正确配置 JDK 17 或更高版本

必需组件：

• 已安装并配置的 Gravitino 服务器（参见 02-setup-guide/README.md）

可选组件：

• 带有 Iceberg 运行时 JAR 的 Apache Spark，用于客户端验证（推荐用于测试）
• 如果使用 Hive catalog 后端，需要 Hive Metastore 服务
• 如果使用 JDBC catalog 后端，需要 MySQL 或 PostgreSQL 服务器

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

${JAVA_HOME}/bin/java -version

架构概述：

设置

步骤 1：启动带有 Iceberg REST 服务的 Gravitino 服务器

如果您希望将 Iceberg REST 服务嵌入到完整的 Gravitino 服务器中（包括 Web UI、统一 REST API 等），请使用此方法。

配置 Iceberg REST 作为辅助服务

1. 安装 Gravitino 服务器发行版

按照之前的教程 02-setup-guide/README.md 下载或构建 Gravitino 服务器包。

2. 启用 Iceberg REST 作为辅助服务

默认情况下，Gravitino 使用 memory 的 catalog 后端，这是最简单的选项，但重启后数据会丢失因此仅用于测试；您可以将其更改为 hive 或 jdbc，这是生产环境的正确选择（稍后介绍）。请在 conf/gravitino.conf 中配置：

# 启用 Iceberg REST 服务
gravitino.auxService.names = iceberg-rest
gravitino.iceberg-rest.classpath = iceberg-rest-server/libs,iceberg-rest-server/conf
gravitino.iceberg-rest.catalog-backend = memory
gravitino.iceberg-rest.warehouse = /tmp/

3. 启动 Gravitino 服务器

./bin/gravitino.sh start

4. 检查服务器日志（可选）

tail -f logs/gravitino-server.log

步骤 2：验证 Iceberg REST 端点

测试服务端点

curl http://localhost:9001/iceberg/v1/config

成功时，您应该看到包含 catalog 配置详细信息的 JSON 响应。

步骤 3：从客户端连接并创建 Table

配置您的 Iceberg 客户端使用 REST catalog。下面的 Spark 示例使用 rest catalog 类型和上述 REST 端点。

使用 Iceberg REST catalog 配置 Spark

1. 使用 Iceberg 运行时启动 Spark SQL

spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1 \
  --conf spark.sql.catalog.gravitino=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.gravitino.type=rest \
  --conf spark.sql.catalog.gravitino.uri=http://localhost:9001/iceberg

注意：将 Iceberg 运行时构件中的 3.5 替换为您环境中的 Spark 版本，并将 Gravitino URI 替换成真实的地址。

创建和测试 Table

2. 执行示例 SQL 操作

在 Spark SQL 中：

USE gravitino;
CREATE NAMESPACE IF NOT EXISTS demo;

CREATE TABLE demo.events (
  id BIGINT,
  event_type STRING,
  ts TIMESTAMP
) USING iceberg;

INSERT INTO demo.events VALUES (1, 'click', TIMESTAMP '2024-01-01 10:00:00');

SELECT * FROM demo.events;

Catalog 后端配置示例

这些示例展示了如何配置不同的 catalog 后端和各种存储选项。在 conf/gravitino.conf 中更新以下配置。

使用 HDFS 的 Hive Catalog 后端

适用于具有现有 Hive Metastore 存储 Iceberg 元数据的环境：

# Hive 后端配置
gravitino.iceberg-rest.catalog-backend = hive
gravitino.iceberg-rest.uri = thrift://127.0.0.1:9083
gravitino.iceberg-rest.warehouse = hdfs://127.0.0.1:9000/user/hive/warehouse-hive

使用 HDFS 的 JDBC Catalog 后端

适用于偏好直接使用数据库存储 Iceberg 元数据的环境：

# JDBC 后端配置
gravitino.iceberg-rest.catalog-backend = jdbc
gravitino.iceberg-rest.jdbc-driver = org.postgresql.Driver
gravitino.iceberg-rest.uri = jdbc:postgresql://127.0.0.1:5432/postgres
gravitino.iceberg-rest.warehouse = hdfs://127.0.0.1:9000/user/hive/warehouse-jdbc
gravitino.iceberg-rest.jdbc-user = YOUR_DB_USER
gravitino.iceberg-rest.jdbc-password = YOUR_DB_PASSWORD
gravitino.iceberg-rest.jdbc-initialize = true

配置说明：

• 将 JDBC 驱动程序 jar 放在 iceberg-rest-server/libs 中，以便 Iceberg REST 服务可以加载它
• 对于 MySQL，使用 com.mysql.cj.jdbc.Driver 并相应更新 JDBC URL、用户名和密码

使用 S3 的 Hive Catalog 后端

适用于使用 S3 存储的云原生部署：

# 使用 S3 存储的 Hive 后端
gravitino.iceberg-rest.catalog-backend = hive
gravitino.iceberg-rest.uri = thrift://127.0.0.1:9083
gravitino.iceberg-rest.warehouse = s3a://my-bucket/iceberg-warehouse

# S3 配置
gravitino.iceberg-rest.io-impl = org.apache.iceberg.aws.s3.S3FileIO
gravitino.iceberg-rest.s3-access-key-id = YOUR_ACCESS_KEY
gravitino.iceberg-rest.s3-secret-access-key = YOUR_SECRET_KEY
gravitino.iceberg-rest.s3-region = us-west-2
gravitino.iceberg-rest.credential-providers = s3-secret-key

S3 配置说明：

• 请正确更新您的 S3 Access Key ID、Secret Access Key 和区域代码

使用 S3 的 JDBC Catalog 后端

结合 JDBC 元数据存储和 S3 数据存储：

# 使用 S3 存储的 JDBC 后端
gravitino.iceberg-rest.catalog-backend = jdbc
gravitino.iceberg-rest.jdbc-driver = org.postgresql.Driver
gravitino.iceberg-rest.uri = jdbc:postgresql://127.0.0.1:5432/postgres
gravitino.iceberg-rest.warehouse = s3://my-bucket/iceberg-warehouse
gravitino.iceberg-rest.jdbc-user = YOUR_DB_USER
gravitino.iceberg-rest.jdbc-password = YOUR_DB_PASSWORD
gravitino.iceberg-rest.jdbc-initialize = true

# S3 配置
gravitino.iceberg-rest.io-impl = org.apache.iceberg.aws.s3.S3FileIO
gravitino.iceberg-rest.s3-access-key-id = YOUR_ACCESS_KEY
gravitino.iceberg-rest.s3-secret-access-key = YOUR_SECRET_KEY
gravitino.iceberg-rest.s3-region = us-west-2
gravitino.iceberg-rest.credential-providers = s3-secret-key

额外的 S3 设置要求

1. 安装所需依赖

除了您需要的任何 JDBC 驱动程序 jar 之外，还要将 gravitino-iceberg-aws-bundle jar 放在 Iceberg REST 服务类路径中（iceberg-rest-server/libs）。

从以下地址下载：https://mvnrepository.com/artifact/org.apache.gravitino/gravitino-iceberg-aws-bundle

2. 配置 Spark 以访问 S3

spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.gravitino:gravitino-iceberg-aws-bundle:1.1.0 \
  --conf spark.sql.catalog.gravitino=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.gravitino.type=rest \
  --conf spark.sql.catalog.gravitino.uri=http://localhost:9001/iceberg \
  --conf spark.sql.catalog.gravitino.header.X-Iceberg-Access-Delegation=vended-credentials

故障排除

常见问题及其解决方案：

服务连接问题：

• curl 返回 404：验证 Iceberg REST 基础路径是 /iceberg，端口与 gravitino.iceberg-rest.httpPort 匹配
• 服务未运行：检查 logs/gravitino-server.log 和 logs/gravitino-server.out 中的启动错误

后端连接问题：

• Catalog 后端连接错误：确认 JDBC URL、用户名/密码和 JDBC 驱动程序 jar 的可用性
• 仓库错误：验证仓库路径存在且服务用户可以访问

客户端连接问题：

• Spark 连接失败：确保 REST URL 可从 Spark 驱动程序访问，并设置了 spark.sql.catalog.<name>.type=rest
• Spark 找不到 Iceberg 类：通过 --packages 或 spark.jars 添加匹配的 Iceberg Spark 运行时 jar

恭喜

您已成功完成 Gravitino Iceberg REST catalog 服务器配置教程！

您现在拥有一个功能完整的 Iceberg REST 服务，包括：

• 在端口 9001 上运行的已配置 Iceberg REST 端点
• 为您的存储环境配置的 catalog 后端
• 通过 Apache Spark 验证的客户端连接
• 对各种后端和存储配置选项的理解

您的 Gravitino Iceberg REST 服务已准备好为整个数据生态系统中的 Iceberg 客户端提供服务。

进一步阅读

有关更高级配置和详细文档：

• 查看 Iceberg REST 服务文档，了解云存储支持、访问控制和凭证分发等高级选项：Gravitino Iceberg REST 服务
• 阅读 Gravitino Iceberg REST Catalog 博客，了解背景和部署说明：Gravitino Iceberg REST Catalog 服务博客
• Iceberg REST catalog API 规范：Apache Iceberg REST API

下一步

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

---

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