大网数据广告活动
数据库部署与 SQL 参考

StarRocks 中文参考:ALTER SYSTEM

· 52CE 我爱测

目标必须是存活的 Follower FE。该语句在当前 Leader FE 上执行,将 Leader 角色交接给目标 Follower,原 Leader 随后原地降级为 Follower(而非重启)。可通过 确认新的 Leader。指定 时会抢占一个 BDBJE 层已在进行中的 Leader 切换;不指定 时,若存在此类切换则该语句失败。并发执行的 语句在 Leader 上串行执行:排队中的语句会等待前一条完成,轮到执行时若当前 FE 已不再是 Leader,则直接报错(不会触发第二次切换)。

ALTER SYSTEM

功能

管理 StarRocks 集群中的 FE、BE、CN 和 Broker。

注意

只有拥有 cluster_admin 角色的用户才可以执行集群管理相关操作。

语法和参数说明

FE

  • 添加 Follower FE。添加后,可使用 SHOW PROC '/frontends'\G 命令查看新增FE 的状态。

     ALTER SYSTEM ADD FOLLOWER "host:edit_log_port"
    
  • 删除 Follower FE。

    ALTER SYSTEM DROP FOLLOWER "host:edit_log_port"
    
  • 添加 Observer FE。添加后,可通过 SHOW PROC '/frontends'\G 命令查看新增FE 的状态。

    ALTER SYSTEM ADD OBSERVER "host:edit_log_port"
    
  • 删除 Observer FE。

    ALTER SYSTEM DROP OBSERVER "host:edit_log_port"
    
  • 将 Leader 角色优雅切换到另一个 Follower FE(原地交接,不重启进程)。

    ALTER SYSTEM TRANSFER LEADER TO "host:edit_log_port" [FORCE]
    

    目标必须是存活的 Follower FE。该语句在当前 Leader FE 上执行,将 Leader 角色交接给目标 Follower,原 Leader 随后原地降级为 Follower(而非重启)。可通过 SHOW PROC '/frontends'\G 确认新的 Leader。指定 FORCE 时会抢占一个 BDBJE 层已在进行中的 Leader 切换;不指定 FORCE 时,若存在此类切换则该语句失败。并发执行的 TRANSFER LEADER 语句在 Leader 上串行执行:排队中的语句会等待前一条完成,轮到执行时若当前 FE 已不再是 Leader,则直接报错(不会触发第二次切换)。

    失败语义:若切换本身失败(例如目标在内部 30 秒窗口内未能追平日志,或其集群成员资格尚未完全确认),语句报错且当前 Leader 保持不变——这是安全结果,重试即可。若切换成功但原 Leader 未能在 leader_demotion_drain_timeout_sec 内排空在途工作,原 Leader 进程会退出并以 Follower 身份重启,新 Leader 不受影响。

    存算分离集群不支持该语句(执行将报错);如需在存算分离模式下切换 Leader,请重启当前 Leader FE 以触发选举。

    参数说明如下:

    参数 必选 说明
    host:edit_log_port 是
    • host:FE 机器的 FQDN 或 IP 地址。如果机器存在多个 IP 地址,则该参数取值应为 priority_networks 配置项下设定的唯一通信 IP 地址。
    • edit_log_port:FE 上的 BDBJE 通信端口,默认为 9010。
    FORCE 否 抢占一个 BDBJE 层已在进行中的 Leader 切换。不指定时,若存在此类切换则语句失败。并发的 TRANSFER LEADER 语句本身串行执行,无需 FORCE。
  • 创建 image。

    ALTER SYSTEM CREATE IMAGE
    

    执行该语句会通过 Leader FE 主动触发创建新的 Image(元数据快照)文件。该操作异步执行,您可以通过查看 FE 日志文件 fe.log 确认操作何时开始执行及结束。Leader FE 的 fe.log 中出现 triggering a new checkpoint manually... 表明操作开始执行,finished save image... 则表明 Image 创建完成。自 v3.4.0 起,Leader FE 会选择一个 FE 作为 Checkpoint Worker 来创建 Image,优先选择堆内存使用率较低的 FE 而非 Leader FE(除非将 checkpoint_only_on_leader 设置为 true),因此 finished save image... 会打印在该 FE 的 fe.log 中。在更早版本中,Image 由 Leader FE 创建。

BE

  • 添加 BE。 添加后,可通过 SHOW BACKENDS 查看新增 BE 的状态。

    ALTER SYSTEM ADD BACKEND "host:heartbeat_service_port"[, ...]
    
  • 删除 BE。不指定 FORCE 时,如果有表是单副本且该表的部分 tablet 分布在要删除的 BE 上,则不允许删除该 BE。指定 FORCE 时会跳过该检查直接删除 BE,该 BE 上单副本表的 tablet 可能丢失。

    ALTER SYSTEM DROP BACKEND "host:heartbeat_service_port"[, ...] [FORCE]
    
  • 下线 BE。

    ALTER SYSTEM DECOMMISSION BACKEND "host:heartbeat_service_port"[, ...]
    

    下线前,该 BE 上的数据会迁移到其他 BE 上,过程中不影响数据导入和查询。下线 BE 为异步操作,可通过 SHOW BACKENDS 语句查看是否下线成功,如下线成功,该 BE 不会在 SHOW BACKENDS 返回的信息中显示。您可以手动撤销下线操作,详情参见 CANCEL DECOMMISSION。

    参数说明如下:

    参数 必选 说明
    host:heartbeat_service_port 是
    • host:BE 机器的 FQDN 或 IP 地址。如果机器存在多个 IP 地址,则该参数取值应为 priority_networks 配置项下设定的唯一通信 IP 地址。
    • heartbeat_service_port:BE 的心跳端口,用于接收来自 FE 的心跳,默认为 9050。

CN

  • 添加 CN。 添加后,可通过 SHOW PROC '/compute_nodes'\G 查看新增 CN 的状态。

    ALTER SYSTEM ADD COMPUTE NODE "host:heartbeat_service_port"[, ...]
    
  • 删除 CN。

    ALTER SYSTEM DROP COMPUTE NODE "host:heartbeat_service_port"[, ...]
    

说明

CN 暂不支持通过 ALTER SYSTEM DECOMMISSION 命令下线。

参数说明如下:

| **参数**                    | **必选** | **说明**                                                     |
| --------------------------- | -------- | ------------------------------------------------------------ |
| host:heartbeat_service_port | 是       |<ul><li> `host`:CN 机器的 FQDN 或 IP 地址。如果机器存在多个 IP 地址,则该参数取值应为 `priority_networks` 配置项下设定的唯一通信 IP 地址。</li><li>`heartbeat_service_port`:CN 的心跳端口,用于接收来自 FE 的心跳,默认为 `9050`。</li></ul> |

Broker

  • 添加 Broker。添加后,您可以使用 Broker Load 将 HDFS 或外部云存储系统中的数据导入到 StarRocks 中。详情参见从 HDFS 导入或从云存储导入。

    ALTER SYSTEM ADD BROKER broker_name "host:port"[, ...]
    

    在一条 SQL 语句中,如同时添加多个 Broker(一个host:port为一个 Broker),那么这些 Broker 共用同一个 broker_name。添加后,可通过 SHOW BROKER 语句查看 Broker 的详细信息。

  • 删除 Broker。注意如一个 Broker 上有正在执行的导入任务,那么删除该 Broker 会导致该任务中断。

    • 删除 broker_name 下的一个或多个 Broker。

      ALTER SYSTEM DROP BROKER broker_name "host:broker_ipc_port"[, ...]
      
    • 删除所有名为 broker_name 下的 Broker。

      ALTER SYSTEM DROP ALL BROKER broker_name
      

      参数说明如下:

      参数 必选 说明
      broker_name 是 一个 Broker 的名称或多个 Broker 共用的名称。
      host:broker_ipc_port 是
      • host:Broker 机器的 FQDN 或 IP 地址。
      • broker_ipc_port:Broker 上的 thrift server 端口,用于接受 FE 或 BE 的请求,默认为 8000。

使用说明

添加和删除 FE、添加和删除 BE 以及添加和删除 Broker 均为同步操作。执行删除语句后,FE、BE 或 Broker 会直接删除,不可手动撤销该操作。

示例

示例一:添加一个 Follower FE。

ALTER SYSTEM ADD FOLLOWER "x.x.x.x:9010";

示例二:删除一个 Observer FE。

ALTER SYSTEM DROP OBSERVER "x.x.x.x:9010";

示例三:添加一个 BE。

ALTER SYSTEM ADD BACKEND "x.x.x.x:9050";

示例四:同时删除两个 BE。

ALTER SYSTEM DROP BACKEND "x.x.x.x:9050", "x.x.x.x:9050";

示例五:同时下线两个 BE。

ALTER SYSTEM DECOMMISSION BACKEND "x.x.x.x:9050", "x.x.x.x:9050";

示例六:同时添加两个名为 hdfs 的 Broker。

ALTER SYSTEM ADD BROKER hdfs "x.x.x.x:8000", "x.x.x.x:8000";

示例七:删除 amazon_s3 下的两个 Broker。

ALTER SYSTEM DROP BROKER amazon_s3 "x.x.x.x:8000", "x.x.x.x:8000";

示例八:删除 amazon_s3 下的所有 Broker。

ALTER SYSTEM DROP ALL BROKER amazon_s3;

示例九:将 Leader 角色切换到指定的 Follower FE。

ALTER SYSTEM TRANSFER LEADER TO "x.x.x.x:9010";

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。