StarRocks 3.3 存算分离部署踩坑实录：FE FQDN + CN 注册 + MinIO 内置存储卷

从零部署 StarRocks 3.3.22 存算分离集群，FE + CN 单节点架构，MinIO 作为对象存储后端。记录三个关键踩坑点及解决方案。

一、环境信息

组件	版本 / 配置
StarRocks	3.3.22-753696f
运行模式	`shared_data`（存算分离）
节点	单机，FE + CN 同机部署
对象存储	MinIO（S3 兼容）
网络模式	FQDN
Hostname	`sr-node-xxx`（打码）
内网 IP	`10.xxx.167.xx`

二、FE 部署：aws_s3_path 空值 FATAL

2.1 现象

按照官方文档配置 fe.conf，只设置了 run_mode = shared_data、meta_dir 和 enable_fqdn_mode = true，没有配置任何 S3 相关参数（文档说后续通过 SQL 配置）。启动 FE 后反复崩溃，fe.warn.log 出现：

复制代码

FATAL (stateChangeExecutor|81) [GlobalStateMgr.createBuiltinStorageVolume():2633]
The configuration item "Config.aws_s3_path = " is invalid.

重启三次，每次都是 FE 选为 LEADER 后立即崩溃。

2.2 根因

文档说的是用户存储卷 （CREATE STORAGE VOLUME SQL），那是集群跑起来后配的。但 StarRocks 3.x 在启动初始化阶段就会调用 createBuiltinStorageVolume() 创建内置存储卷 ，这个步骤走的是 Config.aws_s3_path，读到空字符串直接 FATAL------等不到你执行 SQL 那一步。

2.3 解决方案

在 fe.conf 中先填入占位 MinIO 配置，让内置存储卷初始化通过：

properties 复制代码

run_mode = shared_data
meta_dir = /data/starrocks/meta_dir
enable_fqdn_mode = true

# --- 占位 MinIO 配置（内置存储卷必须） ---
aws_s3_path = s3://defaultbucket/
aws_s3_region = us-east-1
aws_s3_endpoint = http://10.xxx.167.xx:9000
aws_s3_access_key = xxxxxxxxxx
aws_s3_secret_key = xxxxxxxxxx
aws_s3_use_aws_sdk_default_behavior = false
aws_s3_use_instance_profile = false
aws_s3_enable_path_style_access = true

注意：aws_s3_enable_path_style_access = true 是 MinIO 必需项，否则 AWS SDK 会走 Virtual-Hosted-Style 请求，MinIO 不认。

FE 起来后再用 SQL 建真正的存储卷覆盖即可。

三、FQDN 模式配置

3.1 背景

存算分离模式推荐使用 FQDN 而非 IP，避免节点 IP 变动导致集群不可用。

3.2 关键配置

/etc/hosts：

复制代码

10.xxx.167.xx   sr-node-xxx
127.0.0.1       localhost

fe.conf：

properties 复制代码

enable_fqdn_mode = true

启用 FQDN 后，StarRocks 直接通过 InetAddress.getLocalHost() 从 /etc/hosts 解析 IP，不再遍历网卡匹配。因此 priority_networks 在 FQDN 模式下不需要配置。

3.3 验证

bash 复制代码

# 确认 hostname 与 hosts 文件一致
hostname -f
# → sr-node-xxx

# 确认 FE 端口监听
ss -tlnp | grep -E "9010|9020|9030|8030"

FE 启动后通过 MySQL 客户端连接验证：

sql 复制代码

-- 连接
mysql -h 127.0.0.1 -P 9030 -u root

-- 查看 FE 状态
SHOW PROC '/frontends'\G

输出确认 IsLeader: true，Alive: true。

四、CN 部署与注册

4.1 CN 配置文件

cn.conf（与 BE 同目录，通过 --cn 参数启动）：

properties 复制代码

sys_log_level = INFO

be_port = 9060
be_http_port = 8040
heartbeat_service_port = 9050
brpc_port = 8060
starlet_port = 9070

# 指向 FE edit_log_port
helper = sr-node-xxx:9010

storage_root_path = /data/starrocks/storage_root_path

关键点 ：helper 指向 FE 的 edit_log_port（默认 9010），CN 通过这个端口向 FE 注册。我第一次启动时漏了这行，CN 虽然进程在跑但始终没有加入集群。

4.2 启动 CN

bash 复制代码

cd /data/starrocks/starrocks3
./be/bin/stop_cn.sh
./be/bin/start_cn.sh --daemon

日志确认：

复制代码

CN started successfully
BRPC server bind to host: 0.0.0.0, port: 8060
heartbeat has started listening port on 9050

CN 日志里有 JIT 禁用的 WARNING（内存 < 16GB 自动关），OLAP 场景影响很小，忽略即可。

4.3 注册到 FE

sql 复制代码

ALTER SYSTEM ADD COMPUTE NODE "sr-node-xxx:9050";

验证：

sql 复制代码

SHOW COMPUTE NODES\G

复制代码

ComputeNodeId: 10341
Host: sr-node-xxx
HeartbeatPort: 9050
Alive: true

五、创建存储卷并建表

5.1 创建 MinIO 存储卷

sql 复制代码

CREATE STORAGE VOLUME def_volume
TYPE = S3
LOCATIONS = ("s3://defaultbucket")
PROPERTIES(
    "enabled" = "true",
    "aws.s3.region" = "us-east-1",
    "aws.s3.endpoint" = "http://10.xxx.167.xx:9000",
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "xxxxxxxxxx",
    "aws.s3.use_aws_sdk_default_behavior" = "false",
    "aws.s3.enable_path_style_access" = "true"
);

SET def_volume AS DEFAULT STORAGE VOLUME;

5.2 建表（存算分离专属语法）

sql 复制代码

CREATE TABLE IF NOT EXISTS detail_demo (
    recruit_date  DATE           NOT NULL COMMENT "YYYY-MM-DD",
    region_num    TINYINT        COMMENT "range [-128, 127]",
    num_plate     SMALLINT       COMMENT "range [-32768, 32767]",
    tel           INT            COMMENT "range [-2147483648, 2147483647]",
    id            BIGINT         COMMENT "range [-2^63 + 1 ~ 2^63 - 1]",
    password      LARGEINT       COMMENT "range [-2^127 + 1 ~ 2^127 - 1]",
    name          CHAR(20)       NOT NULL COMMENT "range char(m),m in (1-255)",
    profile       VARCHAR(500)   NOT NULL COMMENT "upper limit 65533 bytes",
    ispass        BOOLEAN        COMMENT "true/false"
)
DUPLICATE KEY(recruit_date, region_num)
DISTRIBUTED BY HASH(recruit_date, region_num)
PROPERTIES (
    "storage_volume" = "def_volume",
    "datacache.enable" = "true",
    "datacache.partition_duration" = "1 MONTH"
);

存算分离模式下，建表 PROPERTIES 必须指定 "storage_volume"，否则数据不知道往哪个对象存储写。

5.3 批量写入 1 万条测试数据

sql 复制代码

INSERT INTO detail_demo
SELECT
    date_add('2026-01-01', interval seq DAY) AS recruit_date,
    CAST((seq % 127) + 1 AS TINYINT)         AS region_num,
    CAST(seq + 1000 AS SMALLINT)              AS num_plate,
    CAST(13800000000 + seq AS INT)            AS tel,
    CAST(10000000000 + seq AS BIGINT)         AS id,
    CAST(12345678901234567890 + seq AS LARGEINT) AS password,
    CONCAT('user_', seq)                      AS name,
    CONCAT('profile_desc_for_user_', seq)     AS profile,
    (seq % 2 = 0)                             AS ispass
FROM (
    SELECT (a * 1000 + b * 100 + c * 10 + d) AS seq
    FROM
        (SELECT 0 a UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) t1
    CROSS JOIN
        (SELECT 0 b UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) t2
    CROSS JOIN
        (SELECT 0 c UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) t3
    CROSS JOIN
        (SELECT 0 d UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) t4
) t
LIMIT 10000;

无表笛卡尔积技巧生成连续序列，比存储过程轻量、兼容性好。

验证：

sql 复制代码

SELECT count(*) FROM detail_demo;
-- → 10005（前 5 条 + 批量 10000）

六、MinIO 存储结构揭秘

数据写入后，在 MinIO 控制台观察到如下目录结构：

复制代码

defaultbucket/
  └─ {cluster_id}/                  ← 集群 UUID（如 4cab7f71-xxxx-xxxx）
       ├─ db10001/                  ← 业务数据库（cloud_db）
       ├─ db10565/                  ← 系统数据库（_statistics_）
       │    └─ {table_id}/          ← 表目录（如 10472 = detail_demo）
       │         └─ {tablet_id}/    ← Tablet 目录（如 10471）
       │              ├─ SCHEMA_xxx  ← 表 DDL 定义文件
       │              └─ meta/       ← Tablet 元数据
       │                   ├─ {rowset_version}_{segment_id}.meta
       │                   └─ ...
       └─ ...

关键点：

cluster_id 是集群唯一标识，一个 bucket 可以挂多个 StarRocks 集群
db10001 是用户创建的数据库在 SR 内部的数字 ID
数据文件（.dat）不会立即出现------INSERT 数据先写内存 MemTable，满足条件后才落盘成 Segment 文件
meta/ 下的 .meta 文件记录 Rowset 版本和 Segment 映射关系

七、三个关键踩坑点总结

序号	问题	根因	解决
1	FE 反复崩溃：`aws_s3_path` 为空	内置存储卷初始化发生在启动阶段，不等 SQL 配置	`fe.conf` 中填入占位 MinIO 配置
2	CN 进程在跑但不加入集群	漏配 `helper` 指向 FE edit_log_port	`cn.conf` 配置 `helper = hostname:9010`
3	FQDN 模式下仍报 FQDN 解析失败	未启用 `enable_fqdn_mode`，仍走网卡匹配逻辑	`fe.conf` 配置 `enable_fqdn_mode = true`

八、常用排查命令速查

bash 复制代码

# FE 日志
tail -100 fe/log/fe.warn.log
tail -100 fe/log/fe.log

# CN 日志
tail -100 be/log/cn.INFO
cat be/log/cn.WARNING

# FE 状态
mysql -h 127.0.0.1 -P 9030 -u root -e "SHOW PROC '/frontends'\G"

# CN 状态
mysql -h 127.0.0.1 -P 9030 -u root -e "SHOW COMPUTE NODES\G"

# 数据库与表统计
mysql -h 127.0.0.1 -P 9030 -u root -e "SHOW PROC '/statistic'"

# 存储卷
mysql -h 127.0.0.1 -P 9030 -u root -e "SHOW STORAGE VOLUMES"

部署日期：2026-05-28