Apache Iceberg Rest Fixture 镜像文档

镜像概述和主要用途

Apache Iceberg Rest Fixture 是一个轻量级的 Docker 镜像，用于快速部署模拟的 Apache Iceberg REST 服务端点。该镜像旨在为开发、测试和集成验证场景提供便捷的 Iceberg REST API 环境，无需部署完整的 Iceberg 集群或依赖外部存储服务。其核心目标是降低 Iceberg 客户端开发、功能演示和自动化测试的门槛。

核心功能和特性

核心功能

• REST API 模拟：提供与 Apache Iceberg 规范兼容的 REST 端点，支持表元数据管理（创建/删除/更新表）、快照操作、分区管理等核心功能。
• 轻量级存储：内置内存存储引擎，支持无持久化的临时数据处理；同时支持本地文件系统存储，用于需要数据持久化的测试场景。
• 协议兼容：兼容 Iceberg 客户端协议（如 Apache Spark、Flink 等 Iceberg 集成工具），可直接作为客户端的 REST 服务端使用。

关键特性

• 零依赖部署：无需预先配置 Hadoop、Hive 或对象存储，镜像内置所有必要组件。
• 内存模式优先：默认使用内存存储，启动速度快，适合短暂测试任务，测试完成后数据自动清理。
• 配置灵活：支持通过环境变量或配置文件自定义服务端口、存储类型、日志级别等参数。
• 低资源占用：基础镜像体积小，运行时内存占用低（默认配置下<200MB），适合本地开发机或 CI/CD 容器环境。

使用场景和适用范围

适用场景

• 开发环境测试：供开发人员在本地验证 Iceberg 客户端代码（如 Spark Iceberg Connector）的正确性。
• CI/CD 集成测试：作为自动化测试环节的依赖服务，验证客户端与 Iceberg REST API 的交互逻辑。
• 功能演示：快速搭建 Iceberg 服务演示环境，展示表创建、快照管理等核心功能。
• 学*与研究**：帮助开发者熟悉 Iceberg REST API 规范及请求/响应格式。

适用范围限制

• 非生产环境：不支持高可用性、数据持久化（默认内存模式）和性能优化，不可用于生产环境。
• 单节点部署：仅支持单实例运行，不提供集群模式或水平扩展能力。
• 有限存储能力：文件系统存储模式依赖容器内存储，需手动挂载卷实现数据持久化。

使用方法和配置说明

快速启动

基础启动命令

通过 docker run 快速启动内存模式的服务：

bash
docker run -d -p 8181:8181 --name iceberg-rest-fixture apache/iceberg-rest-fixture:latest

• -p 8181:8181：映射容器内默认端口（8181）到主机。
• --name iceberg-rest-fixture：指定容器名称，便于后续操作（如日志查看、停止）。

环境变量配置

镜像支持通过环境变量自定义服务行为，常用配置如下：

示例：文件系统存储模式启动

使用文件系统存储元数据（需持久化测试数据时）：

bash
docker run -d \
  -p 8182:8182 \
  -e PORT=8182 \
  -e STORAGE_TYPE=file \
  -e METADATA_PATH=/data/iceberg-metadata \
  -v $(pwd)/local-metadata:/data/iceberg-metadata \  # 挂载主机目录到容器，实现数据持久化
  --name iceberg-rest-fixture-file \
  apache/iceberg-rest-fixture:latest

Docker Compose 配置示例

适用于多服务集成测试场景（如同时启动 Iceberg Rest Fixture 和客户端应用）：

yaml
# docker-compose.yml
version: '3.8'

services:
  iceberg-rest:
    image: apache/iceberg-rest-fixture:latest
    container_name: iceberg-rest-fixture
    ports:
      - "8181:8181"
    environment:
      - PORT=8181
      - STORAGE_TYPE=memory
      - LOG_LEVEL=DEBUG  # 调试模式下输出详细请求日志
    restart: unless-stopped

  # 示例：Iceberg 客户端测试容器（如 Python/Java 客户端）
  test-client:
    image: python:3.9-slim
    container_name: iceberg-test-client
    depends_on:
      - iceberg-rest
    command: ["sleep", "3600"]  # 保持容器运行，便于手动执行测试命令

启动命令：docker-compose up -d

数据持久化

默认内存模式下，服务重启后数据会丢失。如需在测试中保留元数据，可通过以下方式实现：

1. 文件系统存储 + 卷挂载（推荐）：
   如上文 STORAGE_TYPE=file 示例，将容器内 METADATA_PATH 挂载到主机目录，实现元数据持久化。

2. 外部存储集成（高级场景）：
   通过自定义配置文件（需挂载配置卷）指定外部存储（如 S3、GCS），但需额外提供存储访问密钥（不推荐测试环境使用）。

API 使用示例

服务启动后，可通过 HTTP 请求调用 Iceberg REST API，以下为常用操作示例：

1. 获取服务状态

bash
curl http://localhost:8181/v1/health
# 响应：{"status":"UP","version":"1.0.0"}

2. 创建测试表

bash
curl -X POST http://localhost:8181/v1/catalogs/default/tables \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "test_db.test_table",
    "schema": {
      "type": "struct",
      "fields": [
        {"name": "id", "type": "int", "required": true},
        {"name": "data", "type": "string", "required": false}
      ]
    },
    "location": "s3://test-bucket/test_db/test_table"  # 仅为模拟路径，实际存储由 STORAGE_TYPE 控制
  }'

3. 查询表元数据

bash
curl http://localhost:8181/v1/catalogs/default/tables/test_db.test_table

注意事项

1. 生产环境禁用：该镜像仅为测试工具，不提供数据备份、高可用或性能保障，严禁用于生产环境。
2. 内存模式数据安全：STORAGE_TYPE=memory 模式下，容器重启或崩溃会导致所有元数据丢失，需提前备份关键测试数据。
3. 端口冲突处理：若主机端口 8181 已被占用，通过 PORT 环境变量自定义端口（如 -e PORT=8282），并调整主机端口映射（如 -p 8282:8282）。
4. 客户端兼容性：需确保 Iceberg 客户端版本（如 Spark Iceberg 连接器）与镜像模拟的 API 版本匹配（默认兼容 Iceberg 1.3.0+ 规范）。