本文档适用于 StarRocks 4.1 存算一体架构离线部署基于 7 台 Linux 服务器3 FE 4 BE从环境准备到集群验证全流程可直接执行。一、集群规划服务器角色核心端口数据目录61FE FollowerLeader9030(query) / 9010(editlog) / 9020(rpc) / 8030(http)/opt/starrocks/fe/meta62FE Follower同上/opt/starrocks/fe/meta63FE Follower同上/opt/starrocks/fe/meta64BE9060(be) / 9050(heartbeat) / 8040(http) / 8060(brpc)/data1/starrocks/be/storage65BE同上/data1/starrocks/be/storage66BE同上/data1/starrocks/be/storage67BE同上/data1/starrocks/be/storageFE 高可用原理3 台 Follower FE 通过 Raft 协议自动选举 Leader任意 1 台故障不影响服务。BE 节点负责数据存储和查询计算4 台 BE 建议使用 3 副本容忍 1 台故障。二、部署前环境准备2.1 硬件配置建议节点类型最低配置推荐配置说明FE4核 / 8GB16核 / 32GB元数据存储建议 SSD200GBBE8核 / 16GB32核 / 128GB数据盘建议 SSD/NVMe容量按需CPU 要求必须支持 AVX2 指令集StarRocks 依赖矢量化计算加速可通过以下命令检查grep -q avx2 /proc/cpuinfo echo 支持 AVX2 || echo 不支持 AVX22.2 软件要求操作系统CentOS 7.9 / Ubuntu 22.04 / RHEL 7.9 及以上JDKStarRocks 4.1 二进制包已自带 JDK无需额外安装MySQL 客户端5.5 及以上用于连接 FE 管理集群2.3 系统配置7 台服务器全部执行① 关闭防火墙# CentOS / RHEL systemctl stop firewalld systemctl disable firewalld # Ubuntu ufw disable② 关闭 SELinuxsetenforce 0 sed -i s/SELINUXenforcing/SELINUXdisabled/g /etc/selinux/config③ 关闭 Swap必须关闭否则 BE 可能异常swapoff -a sed -i /swap/s/^/#/ /etc/fstab④ 设置文件句柄数与进程数cat /etc/security/limits.conf EOF * soft nofile 65536 * hard nofile 65536 * soft nproc 65536 * hard nproc 65536 EOF⑤ 内核参数优化cat /etc/sysctl.conf EOF vm.swappiness 0 vm.overcommit_memory 1 vm.max_map_count 2000000 fs.file-max 6553560 EOF sysctl -p⑥ 时钟同步生产环境必须# CentOS / RHEL yum install -y chrony systemctl start chronyd systemctl enable chronyd # Ubuntu apt install -y chrony systemctl start chrony systemctl enable chrony # 验证同步状态 chronyc sources⑦ 创建专用运行用户不建议用 rootuseradd -m -s /bin/bash starrocks echo starrocks | passwd --stdin starrocks # CentOS # echo starrocks:starrocks | chpasswd # Ubuntu⑧ 配置主机名与 hosts每台机器设置对应主机名# 61 上执行 hostnamectl set-hostname sr-fe-01 # 62 上执行 hostnamectl set-hostname sr-fe-02 # 63 上执行 hostnamectl set-hostname sr-fe-03 # 64 上执行 hostnamectl set-hostname sr-be-01 # 65/66/67 依次设为 sr-be-02 ~ sr-be-04所有机器的/etc/hosts都添加以下内容替换为实际内网 IPcat /etc/hosts EOF 192.168.1.61 sr-fe-01 192.168.1.62 sr-fe-02 192.168.1.63 sr-fe-03 192.168.1.64 sr-be-01 192.168.1.65 sr-be-02 192.168.1.66 sr-be-03 192.168.1.67 sr-be-04 EOF⑨ 安装 MySQL 客户端FE 节点安装即可# CentOS / RHEL yum install -y mysql # Ubuntu apt install -y mysql-client三、上传并解压安装包3.1 上传安装包到 61 服务器将离线安装包StarRocks-4.1.tar.gz上传到 61 服务器的/opt/目录。3.2 解压cd /opt tar -zxvf StarRocks-4.1.tar.gz mv StarRocks-4.1 starrocks chown -R starrocks:starrocks /opt/starrocks解压后目录结构/opt/starrocks/ ├── fe/ # FE 部署文件 │ ├── bin/ # 启动/停止脚本 │ ├── conf/ # 配置文件 │ ├── lib/ # 依赖库 │ └── jdk/ # 自带 JDK ├── be/ # BE 部署文件 │ ├── bin/ │ ├── conf/ │ ├── lib/ │ └── jdk/ # 自带 JDK └── LICENSE.txt四、分发部署文件到各节点在 61 服务器上执行将 FE 和 BE 文件分别分发到对应节点4.1 分发 FE 到 62、63scp -r /opt/starrocks/fe rootsr-fe-02:/opt/starrocks/ scp -r /opt/starrocks/fe rootsr-fe-03:/opt/starrocks/4.2 分发 BE 到 64、65、66、67scp -r /opt/starrocks/be rootsr-be-01:/opt/starrocks/ scp -r /opt/starrocks/be rootsr-be-02:/opt/starrocks/ scp -r /opt/starrocks/be rootsr-be-03:/opt/starrocks/ scp -r /opt/starrocks/be rootsr-be-04:/opt/starrocks/如果用 starrocks 用户运行分发后需在各节点执行chown -R starrocks:starrocks /opt/starrocks修正权限。五、配置并启动第一台 FE61 服务器5.1 创建元数据目录mkdir -p /opt/starrocks/fe/meta chown -R starrocks:starrocks /opt/starrocks/fe/meta5.2 修改 fe.conf 配置文件vi /opt/starrocks/fe/conf/fe.conf找到并修改/添加以下核心参数# 基础配置 # 元数据存储路径必改 meta_dir /opt/starrocks/fe/meta # 绑定内网网卡多网卡环境必须指定必改替换为实际网段 priority_networks 192.168.1.0/24 # 端口配置默认即可被占用再改 http_port 8030 rpc_port 9020 query_port 9030 edit_log_port 9010 # JVM 配置 # 堆内存生产建议 8G~16G按机器内存调整 JAVA_OPTS -Xmx8192m -XX:UseG1GC # 集群配置 # 默认副本数4 台 BE 建议设为 3 default_replication_num 3 # 元数据延迟容忍时间秒 meta_delay_toleration_second 3005.3 启动 FE# 切换到 starrocks 用户如果用专用用户 su - starrocks # 启动 FE cd /opt/starrocks/fe ./bin/start_fe.sh --daemon5.4 验证 FE 启动成功# 方法一查看日志出现 thrift server started 即成功 cat /opt/starrocks/fe/log/fe.log | grep thrift # 方法二查看进程 ps -ef | grep StarRocksFE # 方法三查看 HTTP 端口 curl -s http://127.0.0.1:8030/api/bootstrap日志中出现以下字样表示启动成功thrift server started with port 9020六、配置并启动 BE 节点64~67 四台以下操作在64、65、66、67每台 BE 上都要执行操作完全相同。6.1 创建数据存储目录# 根据实际磁盘情况多块盘就建多个目录 mkdir -p /data1/starrocks/be/storage mkdir -p /data2/starrocks/be/storage # 有第二块盘就建 chown -R starrocks:starrocks /data1/starrocks /data2/starrocks6.2 修改 be.conf 配置文件vi /opt/starrocks/be/conf/be.conf核心配置参数# 存储配置 # 数据存储路径必改多块盘用分号分隔 # SSD 盘加 ,medium:ssdHDD 盘加 ,medium:hdd storage_root_path /data1/starrocks/be/storage,medium:ssd;/data2/starrocks/be/storage,medium:ssd # 网络配置 # 绑定内网网卡多网卡必须指定必改 priority_networks 192.168.1.0/24 # 端口配置默认即可 be_port 9060 be_http_port 8040 heartbeat_service_port 9050 brpc_port 8060 # 内存配置 # BE 总内存限制建议设为机器总内存的 70%~80% mem_limit 80% # 查询内存占比 query_mem_limit 60% # 导入内存占比 load_mem_limit 30% # 并发与性能 # 并发线程数建议 CPU 核数 * 2 be_thread_concurrency 64 # BRPC 线程数 max_brpc_threads 1286.3 启动 BEsu - starrocks cd /opt/starrocks/be ./bin/start_be.sh --daemon6.4 验证 BE 启动# 查看日志 cat /opt/starrocks/be/log/be.INFO | grep heartbeat # 查看进程 ps -ef | grep starrocks_be看到以下字样表示 BE 进程启动成功heartbeat has started listening port on 9050此时 BE 进程虽然启动了但还没有加入集群需要在 FE 中执行 ADD BACKEND 后才算正式加入。七、将 BE 添加到集群在 61 上操作7.1 用 MySQL 客户端连接 FEmysql -h 192.168.1.61 -P 9030 -u root初始用户为root密码默认为空直接回车即可。7.2 添加 4 台 BE 节点ALTER SYSTEM ADD BACKEND 192.168.1.64:9050, 192.168.1.65:9050, 192.168.1.66:9050, 192.168.1.67:9050;注意添加 BE 时用的端口是 heartbeat_service_port默认 9050不是 be_port90607.3 查看 BE 状态SHOW PROC /backends\G每台 BE 的Alive: true表示成功加入集群。八、FE 高可用扩容62、63 加入集群第一步在 61 的 MySQL 中添加 Follower 节点ALTER SYSTEM ADD FOLLOWER 192.168.1.62:9010; ALTER SYSTEM ADD FOLLOWER 192.168.1.63:9010;添加 FE 时用的端口是 edit_log_port默认 9010。一条 SQL 只能加一个 Follower。第二步配置并启动 62 的 FE在62 服务器上操作# 创建元数据目录 mkdir -p /opt/starrocks/fe/meta chown -R starrocks:starrocks /opt/starrocks/fe/meta # 修改 fe.conf配置和 61 完全一致 vi /opt/starrocks/fe/conf/fe.conf配置内容参考 5.2 节确保meta_dir、priority_networks、端口等参数与 61 一致。带 helper 参数启动第一次启动必须加指向已有 FE 以同步元数据su - starrocks cd /opt/starrocks/fe ./bin/start_fe.sh --helper 192.168.1.61:9010 --daemon--helper参数只在第一次启动时需要后续重启不用加。第三步配置并启动 63 的 FE操作与 62 完全相同mkdir -p /opt/starrocks/fe/meta chown -R starrocks:starrocks /opt/starrocks/fe/meta vi /opt/starrocks/fe/conf/fe.conf # 配置同 61 su - starrocks cd /opt/starrocks/fe ./bin/start_fe.sh --helper 192.168.1.61:9010 --daemon第四步验证 FE 集群在 61 上连接 MySQL 执行SHOW PROC /frontends\G正常情况下应看到 3 台 FE1 台Role: LEADER主节点自动选举2 台Role: FOLLOWER跟随者参与选举所有节点Alive: true九、连接测试与验证9.1 连接数据库# 连接任意一台 FE 均可 mysql -h 192.168.1.61 -P 9030 -u root9.2 建库建表测试-- 建库 CREATE DATABASE test_db; USE test_db; -- 建表4 台 BE 使用 3 副本 CREATE TABLE test_table ( id INT, name VARCHAR(50), age INT ) DUPLICATE KEY(id) DISTRIBUTED BY HASH(id) BUCKETS 3 PROPERTIES ( replication_num 3 ); -- 插入数据 INSERT INTO test_table VALUES (1, zhangsan, 25), (2, lisi, 30); -- 查询验证 SELECT * FROM test_table;能正常查到数据说明集群读写均正常。9.3 集群状态检查清单检查项SQL 命令预期结果FE 节点状态SHOW PROC /frontends\G3 台 Alive: trueBE 节点状态SHOW PROC /backends\G4 台 Alive: true数据库列表SHOW DATABASES;能看到 test_dbFE 配置SHOW FRONTEND CONFIG;参数生效BE 配置SHOW BACKEND CONFIG;参数生效十、启停命令汇总FE 节点# 启动 cd /opt/starrocks/fe ./bin/start_fe.sh --daemon # 停止 ./bin/stop_fe.sh # 查看日志 tail -f log/fe.log tail -f log/fe.warn.logBE 节点# 启动 cd /opt/starrocks/be ./bin/start_be.sh --daemon # 停止 ./bin/stop_be.sh # 查看日志 tail -f log/be.INFO tail -f log/be.WARNING十一、常见问题排查问题现象排查方法常见原因FE 启动失败cat fe/log/fe.warn.log端口被占用 / meta 目录权限 / JVM 内存不足BE 启动失败cat be/log/be.WARNINGpriority_networks 配错 / 存储目录权限 / AVX2 不支持BE 加入后 Alive 为 false检查 FE 到 BE 的 9050 端口连通性防火墙未关 / IP 配错 / 端口不一致FE 选主失败检查 3 台 FE 之间 9010 端口互通时钟不同步 / 网络不通 / 少于半数存活连不上 9030 端口netstat -tlnp | grep 9030FE 未启动 / query_port 配置错误建表报错副本数不对检查 BE 节点数量replication_num 不能超过 BE 节点数改配置后重启注意如果元数据或数据目录已有脏数据比如之前启动失败过需要先清空目录再重启FErm -rf /opt/starrocks/fe/meta/* BErm -rf /data1/starrocks/be/storage/*十二、生产环境优化建议12.1 安全加固修改 root 默认密码SET PASSWORD PASSWORD(your_password);创建业务专用账号按库表分配权限FE 前面挂负载均衡LVS / HAProxy应用连接 VIP 而非单节点 IP12.2 性能优化BE 数据盘使用 SSD/NVMe避免 HDD 成为瓶颈万兆网络BE 之间数据同步流量大根据数据量合理设置 tablet 数量和 bucket 数开启自动 Compaction关注 Compaction 状态12.3 监控与运维部署 StarRocks Manager 或 Prometheus Grafana 监控定期备份 FE 元数据关注 BE 磁盘使用率超过 80% 及时扩容建立慢查询监控定期优化慢 SQL12.4 StarRocks 4.1 新特性提示支持基于范围的数据分布与 Tablet 自动分裂合并需开启enable_range_distribution存算分离架构下单 Tablet 容量上限提升Java UDF/UDAF/UDTF 支持更多数据类型Hive Connector 默认使用原生 C Avro Scanner性能提升部署完成后建议执行一次完整的读写压测验证集群性能是否符合预期再正式投入生产使用。十三、建表模型选择与最佳实践StarRocks 提供四种数据模型不同模型适用于不同业务场景。选对模型直接影响查询性能、存储成本和数据更新能力。13.1 四种数据模型对比对比维度Duplicate KeyAggregate KeyUnique KeyPrimary Key数据保留保留全部明细按维度聚合保留最新版本保留最新版本更新方式仅追加聚合追加整行更新整行/部分列更新查询性能快直接读快预聚合较慢读时合并快删写分离写入性能最快快较快中等存储占用最大最小中等中等适用场景原始日志、明细报表、指标汇总需更新的维表高频更新场景引入版本v1.0v1.0v1.0v4.013.2 Duplicate Key明细模型模型特点完全保留导入的原始数据不做任何聚合或去重相同 Key 的数据会全部保留。适用场景原始日志数据访问日志、行为日志、审计日志需要保留每条明细记录的业务数据数据不需要更新只追加写入不确定聚合维度需要灵活分析的明细层建表示例CREATE TABLE access_log ( log_id BIGINT, user_id INT, page_url VARCHAR(500), visit_time DATETIME, ip VARCHAR(64), status_code INT ) DUPLICATE KEY(log_id, user_id, visit_time) PARTITION BY RANGE(visit_time) ( PARTITION p202401 VALUES LESS THAN (2024-02-01) ) DISTRIBUTED BY HASH(user_id) BUCKETS 32 PROPERTIES ( replication_num 3 );优缺点优点缺点写入最快直接追加存储占用最大全量保留查询简单无需合并不支持数据更新/删除数据零丢失可追溯聚合查询需要实时计算较慢13.3 Aggregate Key聚合模型模型特点按维度列Key 列对指标列Value 列进行预聚合相同 Key 的数据会自动合并。Value 列支持 SUM、REPLACE、MAX、MIN、REPLACE_IF_NOT_NULL 等聚合函数。适用场景报表统计、数据看板、BI 分析按固定维度汇总的指标数据写入多为追加查询多为聚合统计数仓 ADS/DWS 层的汇总表建表示例CREATE TABLE user_daily_stat ( stat_date DATE, user_id INT, city VARCHAR(64), -- 以下是指标列需指定聚合函数 pv INT SUM DEFAULT 0, uv INT SUM DEFAULT 0, order_amount DECIMAL(18,2) SUM DEFAULT 0, last_visit_time DATETIME REPLACE, max_order_amount DECIMAL(18,2) MAX ) AGGREGATE KEY(stat_date, user_id, city) PARTITION BY RANGE(stat_date) ( START (2024-01-01) END (2024-12-31) EVERY (INTERVAL 1 MONTH) ) DISTRIBUTED BY HASH(user_id) BUCKETS 16 PROPERTIES ( replication_num 3, dynamic_partition.enable true, dynamic_partition.time_unit MONTH, dynamic_partition.start -12, dynamic_partition.end 1, dynamic_partition.prefix p );常用聚合函数聚合函数说明SUM求和最常用REPLACE替换后写入的覆盖先写入的REPLACE_IF_NOT_NULL非空值才替换空值保留原值适合部分列更新MAX取最大值MIN取最小值HLL_UNIONHLL 去重计数近似去重性能极高BITMAP_UNIONBitmap 去重精确去重适合整数优缺点优点缺点存储占用最小预聚合压缩比高Key 列必须固定不灵活聚合查询性能最好不支持明细查询查不到原始数据写入时自动聚合查询零延迟不支持整行更新只能追加聚合13.4 Unique Key主键模型模型特点保证主键唯一相同主键的新数据会覆盖旧数据。底层基于 Merge-on-Read查询时合并不同版本。适用场景需要频繁更新的维度表用户信息、商品信息数据有唯一主键需要 Upsert 语义更新频率不高分钟级以上对查询性能要求不是极致建表示例CREATE TABLE user_info ( user_id INT, user_name VARCHAR(64), email VARCHAR(128), phone VARCHAR(32), level INT, register_time DATETIME, update_time DATETIME ) UNIQUE KEY(user_id) DISTRIBUTED BY HASH(user_id) BUCKETS 16 PROPERTIES ( replication_num 3, enable_unique_key_merge_on_write false -- 默认 false读时合并 );优缺点优点缺点支持整行 Upsert插入或更新查询时需要合并版本查询性能较差语义简单主键唯一Compaction 压力大写入放大兼容 MySQL Upsert 语义不支持部分列更新只能整行13.5 Primary Key主键模型 v2推荐模型特点StarRocks 4.0 推出的新一代主键模型基于 Delete-and-Insert 实现主键索引常驻内存查询性能接近明细模型同时支持高效更新。适用场景高频更新场景实时数仓、CDC 同步需要部分列更新的业务对查询性能要求高的维表从 MySQL 等数据库同步的明细表Replace 场景多、查询性能要求高建表示例CREATE TABLE order_detail ( order_id BIGINT, user_id INT, product_id INT, amount DECIMAL(18,2), status TINYINT, create_time DATETIME, pay_time DATETIME, update_time DATETIME ) PRIMARY KEY(order_id) PARTITION BY RANGE(create_time) ( START (2024-01-01) END (2024-12-31) EVERY (INTERVAL 1 MONTH) ) DISTRIBUTED BY HASH(order_id) BUCKETS 32 PROPERTIES ( replication_num 3, enable_persistent_index true -- 主键索引持久化减少重启加载时间 );部分列更新示例-- 只更新订单状态和支付时间其他列不变 INSERT INTO order_detail (order_id, status, pay_time, update_time) VALUES (1001, 2, 2024-01-15 10:30:00, NOW());优缺点优点缺点查询性能接近明细模型快主键索引占用内存主键列不能太大支持部分列更新灵活高效写入性能比明细模型略低支持 Delete 操作4.0 版本才支持支持 MvCC 多版本并发控制主键列总长度建议不超过 128 字节选型建议StarRocks 4.1 版本下需要更新能力的场景优先选择 Primary Key 模型性能比 Unique Key 好很多。只有在版本较低或主键过大的情况下才考虑 Unique Key。13.6 分布键Distribution Key选择分布键决定数据如何分散到不同 BE 节点上选对分布键是性能优化的第一步。选择原则高基数列优先选择值多、分布均匀的列如 user_id、order_id避免数据倾斜查询关联列优先如果两表经常 Join用相同的分布键可以实现 Local Join避免数据重分布常用过滤列优先查询中经常作为 Where 条件的列可减少扫描的 BE 节点数避免热点不要选只有少数几个值的列如性别、状态会导致数据集中在少数节点常见分布键选择表类型推荐分布键原因用户表user_id高基数查询常用订单表order_id高基数唯一日志表user_id 或 log_id分布均匀商品表product_id高基数按天统计表user_id 或 stat_dateuser_id避免单日数据集中13.7 分区设计分区策略选择分区类型适用场景建议范围分区Range时间序列数据、按日期查询最常用按天/月分区列表分区List枚举值分区如地区、类型适合分区键值固定且少的场景表达式分区基于函数计算分区灵活但性能略差分区数量建议单表分区数建议控制在100~300 个以内过多会增加 FE 元数据压力按天分区的数据保留 1 年 365 个分区接近上限数据量小的表可以按月分区减少分区数量配合动态分区Dynamic Partition自动管理历史分区动态分区配置示例PROPERTIES ( dynamic_partition.enable true, dynamic_partition.time_unit DAY, -- 按天分区 dynamic_partition.start -30, -- 保留最近 30 天 dynamic_partition.end 3, -- 预创建未来 3 天 dynamic_partition.prefix p, -- 分区名前缀 dynamic_partition.buckets 16 -- 每个分区的 bucket 数 );13.8 Bucket 数量设置每个分区内的数据进一步分成多个 BucketBucket 是数据分布的最小单位。设置原则每个 Bucket 数据量建议 1GB ~ 10GB最佳 2~5GBBucket 数应是 BE 节点数的整数倍保证数据均匀分布总 Bucket 数 分区数 × 每分区 Bucket 数不宜过多参考设置数据规模单分区建议 Buckets4 台 BE 时 10GB4~84 / 810GB ~ 50GB8~168 / 1650GB ~ 200GB16~3216 / 32200GB ~ 1TB32~6432 / 644 台 BE 时Bucket 数建议设为 4 的倍数4、8、16、32这样每台 BE 分到的 Bucket 数相同负载均衡。13.9 建表选型决策树需要数据更新能力吗 ├── 不需要 → 数据是明细还是汇总 │ ├── 明细 → Duplicate Key明细模型 │ └── 汇总 → Aggregate Key聚合模型 └── 需要 → 更新频率高吗 ├── 高实时/分钟级 → Primary Key主键模型 v2 └── 低小时/天级 → 版本是 4.0 吗 ├── 是 → Primary Key推荐 └── 否 → Unique Key主键模型 v113.10 常见建表踩坑提醒分布键选错导致数据倾斜用低基数列如性别、状态做分布键数据集中在少数节点查询性能差。解决用高基数列或多列组合分布键。Bucket 数过多小表设太多 Bucket导致小文件多Compaction 压力大。解决按数据量合理设置每 Bucket 1~10GB。分区过多按天分区保留 3 年 1000 分区FE 元数据压力大。解决冷热分离历史数据归档或按月分区。Aggregate 模型 Key 列太多Key 列太多导致聚合效果差存储压缩比低。解决只保留必要的维度列作为 Key。Unique Key 模型查询慢读时合并开销大。解决升级到 4.0 用 Primary Key 模型。Primary Key 主键过大主键列总长度超过 128 字节索引内存占用大。解决用整数主键或缩短主键长度。忽略副本数设置4 台 BE 用 3 副本是安全的容忍 1 台故障但如果只有 3 台 BE 就不能用 3 副本挂 1 台就不可写。