StarRocks Iceberg MinIO S3 301报错完整修复文档（Docker环境）

一、问题现象

1.1 核心报错

StarRocks 执行 INSERT VALUES 写入数据时报错：

ERROR 1064 (HY000): The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint. (Service: S3, Status Code: 301)

特征：SQL语法无问题，写入本地VALUES却触发S3 301重定向错误。

1.2 衍生语法报错汇总

SET SESSION s3.xxx 报错：旧版StarRocks不支持带 . 的会话变量语法
CREATE EXTERNAL CATALOG type=s3 报错：StarRocks无独立S3类型Catalog，为文档误导
SHOW CREATE EXTERNAL CATALOG 报错：语法冗余，正确语法为 SHOW CREATE CATALOG

二、根本原因

2.1 核心问题

错误混用两种表结构，导致S3配置不生效：

错误操作 ：在 default_catalog（内部目录）创建了 Object Table 对象表 ，仅配置 location=s3://，无任何S3鉴权、访问模式配置
配置缺失 ：已存在的Iceberg外部Catalog缺少关键参数 client.factory，导致StarRocks无法识别MinIO的S3兼容配置，强制触发301重定向
环境适配问题：MinIO必须开启路径访问模式，默认虚拟主机模式会直接301报错

2.2 关键概念区分（核心避坑点）

表类型	所属Catalog	是否需要写location	S3配置来源	是否适配本次Iceberg环境
Object Table 对象表	default_catalog（内部）	是	Storage Volume（存储卷）	否（易报错，不推荐）
Iceberg 数据表	demo（外部Iceberg）	否	Catalog内置aws.s3配置	是（标准官方方案）

三、环境现状确认

当前已部署服务：StarRocks + Iceberg Rest Catalog + MinIO（Docker Compose）

已有Catalog配置（缺失核心参数）：

Catalog名称：demo（Iceberg类型外部目录）
Iceberg服务地址：http://iceberg-rest:8181
MinIO内网地址：http://minio:9000
已开启路径访问：aws.s3.enable_path_style_access=true
缺失参数 ：client.factory（导致S3配置不生效）

四、完整修复步骤（可直接复制执行）

步骤1：清理错误的对象表

切回内部目录，删除之前报错的Object Table，彻底规避S3存储卷问题：

Plain 复制代码

SET CATALOG default_catalog;
DROP TABLE IF EXISTS demo.nyc.taxis;

步骤2：重建完整可用的Iceberg Catalog

外部Catalog不支持修改属性，需删除重建，补充缺失的工厂类参数：

Plain 复制代码

DROP EXTERNAL CATALOG demo;

CREATE EXTERNAL CATALOG demo
COMMENT "External catalog to Apache Iceberg on MinIO"
PROPERTIES
(
  "type"="iceberg",
  "iceberg.catalog.type"="rest",
  "iceberg.catalog.uri"="http://iceberg-rest:8181",
  "iceberg.catalog.warehouse"="warehouse",
  "aws.s3.access_key"="admin",
  "aws.s3.secret_key"="password",
  "aws.s3.endpoint"="http://minio:9000",
  "aws.s3.enable_path_style_access"="true",
  "client.factory"="com.starrocks.connector.iceberg.IcebergAwsClientFactory"
);

步骤3：创建Iceberg库表并写入数据

切换至Iceberg外部目录，创建标准Iceberg表（无需手动指定S3路径）：

Plain 复制代码

-- 切换Iceberg目录
SET CATALOG demo;

-- 创建数据库
CREATE DATABASE IF NOT EXISTS nyc;
USE nyc;

-- 创建Iceberg数据表
CREATE TABLE taxis (
    trip_id            bigint,
    trip_distance      float,
    fare_amount        double,
    store_and_fwd_flag string,
    vendor_id          bigint
)
PARTITION BY (vendor_id);

-- 插入测试数据（核心执行语句，彻底解决301报错）
INSERT INTO taxis
VALUES
(1000371, 1.8, 15.32, 'N', 1),
(1000372, 2.5, 22.15, 'N', 2),
(1000373, 0.9, 9.01, 'N', 2),
(1000374, 8.4, 42.13, 'Y', 1);

-- 验证数据
SELECT * FROM taxis;

五、关键参数详解

aws.s3.enable_path_style_access=true：MinIO必备参数，关闭虚拟主机模式，解决S3 301重定向报错
client.factory 工厂类：核心修复参数，告知StarRocks Iceberg连接器加载MinIO的S3鉴权、地址配置，无此参数所有S3配置失效
内网域名配置 ：Docker环境必须使用 minio:9000、iceberg-rest:8181，禁止使用127.0.0.1（容器本地回环）

六、环境验证方式

6.1 命令行连通性验证（BE容器内执行）

Plain 复制代码

# 验证Iceberg-rest服务连通
curl http://iceberg-rest:8181/catalog

# 验证MinIO服务连通
curl http://minio:9000/minio/health/live

6.2 结果验证

SQL执行无报错，查询可返回插入数据
MinIO warehouse Bucket 下生成 nyc/taxis 目录，包含Parquet数据文件+Iceberg元数据文件

七、常见踩坑总结

禁止在 default_catalog 用Object Table做Iceberg实验，极易触发S3权限/重定向报错
旧版StarRocks不支持 SET SESSION s3.xxx 带点号变量，切勿使用该语法
Iceberg外部Catalog无法修改属性，配置错误只能删除重建
MinIO环境必须开启路径访问模式，否则100%触发S3 301错误

（注：部分内容可能由 AI 生成）