StarRocks 部署完全手册：从环境准备到生产集群搭建（建议收藏）

今天我们把StarRocks手动部署存算一体集群的全流程讲透，包括环境准备、FE 启动、BE 启动、集群搭建、高可用配置、部署后的参数调优，以及一些官方文档没写但实战中必备的细节。文章偏长，建议先收藏，跟着敲一遍基本就能跑起来。

部署前先把环境搞干净

官网文档地址：https://docs.starrocks.io/zh/docs/deployment/deploy_manually/

这一步偷懒的话后面坑到你怀疑人生。

机器准备，FE 节点推荐 16 核 64G 500G SSD，BE 节点 32 核 128G 起步，磁盘用 NVMe SSD 多盘 JBOD 挂载（别做 RAID 5，IO 会被吃掉一半）。我们生产环境是 3 台 FE + 5 台 BE，每台 BE 8 块 4T NVMe，集群总容量 160T 实际可用 100T 左右，扛住了日均 30 亿条数据写入。

操作系统，CentOS 7.9 或者 Ubuntu 20.04/22.04 都行，内核建议 5.4 以上。文件系统用 ext4 或者 xfs，btrfs 不推荐，IO 调度对 StarRocks 不友好。

JDK 装好，必须是 JDK 1.8 或者 11，生产用 OpenJDK 就行（Temurin 或者 Zulu 都试过，稳）。JDK 17 千万别装，3.x 之前版本兼容性有问题，FE 启动直接报错 "Unsupported class file major version"。多 JDK 环境的机器记得在 fe.conf 和 be.conf 里指定 JAVA_HOME，不然它会自己挑，挑到 17 你就哭吧。

系统参数调一下，主要这几个：

# 关闭透明大页，StarRocks 大内存场景必须关
echo never > /sys/kernel/mm/transparent_hugepage/enabled
echo never > /sys/kernel/mm/transparent_hugepage/defrag

# 调整文件句柄数
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# 调整虚拟内存参数
sysctl -w vm.max_map_count=2000000
sysctl -w vm.overcommit_memory=1

这几个参数不改，启动时报 WARN 不报错，但运行起来后 JVM GC 抖动会让你怀疑人生。特别是 transparent_hugepage，开着的内存访问延迟能比关掉的高 5-10 倍。

时钟同步也要做，集群内 NTP 同步误差控制在 1 秒以内，不然 BDBJE 的复制选举会出问题。

端口规划提前列好，避免冲突：

组件	端口	用途
FE	8030	HTTP（Stream Load、Web UI）
FE	9030	MySQL 协议（客户端连接）
FE	9020	RPC
FE	9010	Edit Log
BE	9060	BE Thrift
BE	8040	BE HTTP
BE	9050	Heartbeat
BE	8060	BRPC
BE	9070	Starlet

启动 Leader FE 节点

所有 FE 和 BE 节点先把安装包准备好，下载到 /opt 目录解压：

cd /opt
tar -xzf StarRocks-3.2.6.tar.gz
ln -s StarRocks-3.2.6 starrocks

每台机器都做一遍，包括 FE 和 BE 节点。

第一步，建元数据目录。这个目录绝对不能放在部署目录下，不然升级的时候数据会被一起清掉。我们当时是单独挂了一块 SSD 元数据盘：

mkdir -p /data/starrocks/meta
chown -R starrocks:starrocks /data/starrocks

第二步，修改 fe.conf。文件在 fe/conf/fe.conf，重点改这几个：

# 元数据路径
meta_dir = /data/starrocks/meta

# 端口，如果被占用就改
http_port = 8030
rpc_port = 9020
query_port = 9030
edit_log_port = 9010

# 优先网段，CIDR 格式，**多网卡必须配**，不然集群分裂
priority_networks = 192.168.1.0/24

# JVM 堆，64G 内存机器直接拉满，别省
JAVA_OPTS = "-Xmx49152m -Xms49152m -Xmn16384m -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# 启用 FQDN 时配置 JAVA_HOME
JAVA_HOME = /usr/lib/jvm/temurin-11-jdk

priority_networks 是最容易踩的坑。机器多网卡的时候（比如同时有内网 IP 和管理 IP），FE 之间会拿到不同的 IP 注册，结果就是互相找不到对方，集群一直处于脑裂状态。看 SHOW PROC '/frontends' 会发现每个节点都显示 Alive 但 Role 都是 LEADER —— 这就是典型的网络识别问题。

JVM 堆一定要给足。官方说 8G 起步是骗人的，我们生产环境跑两个月后 fe/meta 涨到 30G，8G 堆直接 GC 地狱。64G 内存的机器直接给到 48G，别抠门。

第三步，启动第一个 FE：

cd /opt/starrocks/fe
./bin/start_fe.sh --daemon

用 FQDN 访问的话要加 --host_type FQDN，并且 /etc/hosts 里要配好所有节点的主机名。我们用 IP 访问比较多，这块简单点。

启动后看日志：

tail -f fe/log/fe.log | grep -i thrift

出现 thrift server started with port 9020 就说明启动成功了。

如果启动失败，先看 fe/log/fe.warn.log，90% 的启动问题都在里面。常见的有端口被占用、meta 目录权限不对、priority_networks 配错、JDK 版本不匹配。

启动 BE 节点

FE 起来之后，开始搞 BE。每台 BE 机器都执行。

第一步，建数据目录。多盘的情况下每块盘都建一个目录：

mkdir -p /data1/storage /data2/storage /data3/storage /data4/storage
chown -R starrocks:starrocks /data{1..4}

第二步，修改 be.conf：

# 数据存储路径，多块盘用分号隔开
storage_root_path = /data1/storage;/data2/storage;/data3/storage;/data4/storage

# 端口
be_port = 9060
be_http_port = 8040
heartbeat_service_port = 9050
brpc_port = 8060
starlet_port = 9070

# 优先网段，必须配
priority_networks = 192.168.1.0/24

# JVM 堆
JAVA_OPTS = "-Xmx32768m -Xms32768m -Xmn8192m -XX:+UseG1GC"

JAVA_HOME = /usr/lib/jvm/temurin-11-jdk

storage_root_path 千万别写错格式，多盘是分号 ; 不是逗号。我们之前有人写错成逗号，BE 起来之后只认了一块盘，导入的时候报磁盘满。

第三步，启动 BE：

cd /opt/starrocks/be
./bin/start_be.sh --daemon

看日志：

cat be/log/be.INFO | grep heartbeat

出现 heartbeat has started listening port on 9050 就 OK。

每台 BE 机器都重复上面三步，5 台 BE 就跑 5 遍。

把集群搭起来

所有 FE 和 BE 节点启动后，还不算一个集群，得在 MySQL 客户端里把 BE 加到 FE 那儿去。

连接 FE：

mysql -h 192.168.1.10 -P 9030 -uroot

初始 root 密码为空，进去之后先看一眼 FE 状态：

SHOW PROC '/frontends'\G

Alive: true 且 Role: LEADER 就说明 Leader FE 起来了。

添加 BE 节点：

ALTER SYSTEM ADD BACKEND "192.168.1.20:9050", "192.168.1.21:9050", "192.168.1.22:9050", "192.168.1.23:9050", "192.168.1.24:9050";

一条 SQL 能加多个 BE，逗号分隔。

等个 30 秒左右，验证一下：

SHOW PROC '/backends'\G

所有 BE 都显示 Alive: true，磁盘容量、TabletNum 都正常，集群就算搭起来了。

注意：至少 3 个 BE 节点才能形成高可用集群。如果只部署 1 个 BE，必须在 fe.conf 里设 default_replication_num = 1，不然建表会失败（默认副本数 3，单 BE 凑不齐）。

部署高可用 FE 集群

单 FE 是不能上生产的，挂了就完蛋。生产环境必须部署 3 个 Follower FE 做高可用（奇数台，BDBJE 的多数派协议要求）。

第一步，在 Leader FE 上添加 Follower：

ALTER SYSTEM ADD FOLLOWER "192.168.1.11:9010";
ALTER SYSTEM ADD FOLLOWER "192.168.1.12:9010";

注意 SQL 里只能一次加一个 Follower，不能像 BE 那样批量加。

第二步，在新 FE 节点上启动 Follower。注意 必须用 --helper 参数启动，否则新 FE 不会从 Leader 同步元数据，会形成一个独立的小集群：

cd /opt/starrocks/fe
./bin/start_fe.sh --helper 192.168.1.10:9010 --daemon

--helper 参数只在第一次启动时需要，重启就不用了。

等个 1-2 分钟（新 FE 需要从 Leader 拉元数据），在 Leader FE 上查看：

SHOW PROC '/frontends'\G

应该能看到 3 个 FE 节点，1 个 LEADER + 2 个 FOLLOWER，Alive 都 true。

如果想加 Observer 节点（只读，不参与选举，可以是任意数量），用 ADD OBSERVER：

ALTER SYSTEM ADD OBSERVER "192.168.1.13:9010";

Observer 启动时也要带 --helper，但启动命令和 Follower 一样。Observer 不参与 Leader 选举，适合做查询负载分担。

部署后必须改的几个参数

集群搭起来只是第一步，默认参数在生产环境几乎都跑不顺，必须调。

FE 关键参数（fe.conf）：

# 副本数，生产至少 3 副本
default_replication_num = 3

# 动态分区参数，按需开启
dynamic_partition_enable = true
dynamic_partition_time_unit = DAY
dynamic_partition_start = -7
dynamic_partition_end = 3
dynamic_partition_prefix = p
dynamic_partition_buckets = 16

# 查询超时
qe_max_connection = 1024
query_timeout = 300

BE 关键参数（be.conf）：

# 单个查询内存限制
exec_mem_limit = 8589934592  # 8G

# 导入相关
max_stream_load_timeout_second = 7200
stream_load_default_timeout_second = 600

# 压缩算法
compress_rowbatches = true

# compaction 线程数
compaction_task_num_per_cpu = 2

# 物化视图刷新线程
max_materialized_view_tablet_num = 256

所有节点改完参数都要重启才生效，FE 滚动重启没问题（一次重启一个），BE 也可以滚动重启。

部署后验证测试

参数调完之后，跑几个验证 SQL 确认集群真的能干活：

-- 建测试库
CREATE DATABASE IF NOT EXISTS test_db;
USE test_db;

-- 建表
CREATE TABLE test_table (
    id INT,
    name STRING,
    value BIGINT
) DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 16
PROPERTIES (
    "replication_num" = "3"
);

-- 插数据
INSERT INTO test_table VALUES (1, 'a', 100), (2, 'b', 200), (3, 'c', 300);

-- 查数据
SELECT * FROM test_table;

-- 看表状态
SHOW TABLE STATUS FROM test_db\G

-- 清理
DROP TABLE test_table;
DROP DATABASE test_db;

跑一下 Stream Load 导入测试：

# 准备一个测试 CSV
echo -e "1,test1,100\n2,test2,200\n3,test3,300" > /tmp/test.csv

# 导入
curl --location-trusted -u root \
  -T /tmp/test.csv \
  -H "label:test_load_001" \
  -H "column_separator:," \
  -XPUT http://127.0.0.1:8030/api/test_db/test_table/_stream_load

返回 Status: Success 就 OK。

几个部署时容易踩的坑

坑一：JDK 版本不对。CentOS 默认装的是 JDK 1.8.0_xxx，但某些云厂商镜像里同时装了 JDK 11 和 JDK 17，StarRocks 启动时如果挑到 17 就会直接报错。显式指定 JAVA_HOME 是最稳的。

坑二：priority_networks 没配。多网卡环境下 FE/BE 之间互相识别不到对方 IP，集群看着起来了但元数据同步有问题。所有节点都必须配。

坑三：FE 元数据目录权限不对。经常遇到 Permission denied 错误，chown 给 starrocks 用户就行。千万别用 root 跑 StarRocks，官方说能用，但安全审计那边过不了。

坑四：磁盘做了 RAID。RAID 5/6 的写性能比 JBOD 差不少，RAID 0 也不行（没冗余）。多盘 JBOD 让 StarRocks 自己管，性能反而最好。

坑五：第一次启动 Follower FE 没带 --helper。这个我们已经提过，但生产环境几乎每个新人都踩过。Follower/Observable 第一次启动必须带 --helper。

坑六：副本数没设。默认副本数是 3，但有些同学部署时只用了 1-2 台 BE，结果建表报错 "failed to find enough backend"。解决方法两种：扩 BE 到 3 台，或者 default_replication_num = 1（不推荐生产用）。

坑七：时钟不同步。集群节点时间差超过 5 秒，BDBJE 选举会出问题。所有节点装 ntpdate 或者 chrony 同步时间。

坑八：transparent_hugepage 没关。开启状态 StarRocks 内存访问延迟高，查询慢且 GC 抖动大。关掉。

停止集群的正确姿势

如果需要停机维护，先停 BE 再停 FE。FE 先停了 BE 还在写入会报错。

每台 BE 上：

cd /opt/starrocks/be
./bin/stop_be.sh

所有 BE 停止后，再停 FE：

cd /opt/starrocks/fe
./bin/stop_fe.sh

启动顺序反过来：先启 FE，等 Leader 选举完（10 秒左右）再启 BE。

写在最后

StarRocks 部署的难点不在于命令本身，而在于那些"官方文档没写但生产环境必备"的细节。比如 priority_networks、JDK 版本、transparent_hugepage 这些，缺一个集群就出问题。

按这套流程走下来，3 台 FE + 5 台 BE 的生产集群大概半天就能搭完，再花一两天调参数、加监控，基本就能稳定运行了。后续的 Stream Load、Routine Load、物化视图、调优这些，等集群稳定后再慢慢加。

生产环境部署 checklist 整理一下：

[ ] JDK 1.8/11 装好，多版本显式指定 JAVA_HOME
[ ] 操作系统参数调好（透明大页、文件句柄、vm.max_map_count）
[ ] NTP 时钟同步
[ ] 端口规划好，没冲突
[ ] priority_networks 配置正确
[ ] 存储目录用 JBOD 模式
[ ] FE 至少 3 台（Follower），BE 至少 3 台
[ ] Follower FE 启动带 --helper
[ ] 副本数 ≥ 3
[ ] JVM 堆按机器内存给足
[ ] 跑通验证测试

下期会写 StarRocks 的监控体系搭建和告警配置，Prometheus + Grafana 的完整方案，关注不迷路。

👆 觉得有用的话别忘了点赞、收藏、转发三连，让更多朋友少踩坑！

个人博客：躬行笔记 上有更多实战文章，部署、调优、监控、故障复盘都有，欢迎来撩。