【Starrocks】StarRocks 排错：`Invalid method name: ‘heartbeat‘`（BE 心跳端口/协议错误）

文章目录

• • 适用范围
  • 典型日志/现象（示例）
  • • 1) `SHOW BACKENDS\G` 片段 SHOW BACKENDS\G 片段)
  • 根因解释（为什么会报这个错）
  • 最常见根因（按概率排序）
  • • A) **BE 心跳端口注册错了（把 9060 当成 HeartbeatPort）** ✅ 最常见 BE 心跳端口注册错了（把 9060 当成 HeartbeatPort） ✅ 最常见)
    • B) **FE/BE 版本不一致导致 Thrift 接口不兼容** FE/BE 版本不一致导致 Thrift 接口不兼容)
    • C) **网络/端口被中间设备劫持到错误服务** 网络/端口被中间设备劫持到错误服务)
  • 排查步骤（最短路径）
  • • 1) 在 FE 上确认 HeartbeatPort 是否正确 在 FE 上确认 HeartbeatPort 是否正确)
    • 2) 在 BE 机器上核对端口配置（`conf/be.conf`） 在 BE 机器上核对端口配置（conf/be.conf）)
    • 3) 在 BE 机器确认心跳端口是否在监听 在 BE 机器确认心跳端口是否在监听)
  • 修复方法（推荐：删除错误登记后重新添加）
  • • [场景：FE 中登记成了 `HeartbeatPort=9060`](#场景：FE 中登记成了 HeartbeatPort=9060)
  • 修复后验证
  • • 1) FE 侧验证 FE 侧验证)
    • 2) 额外验证（可选） 额外验证（可选）)
  • 预防建议

适用范围

当你在 FE 执行 SHOW BACKENDS\G 时看到类似现象：

• Alive: false
• BePort/HttpPort/BrpcPort 可能为 -1
• ErrMsg 出现：Invalid method name: 'heartbeat'

本文仅针对这一类问题给出排查与修复步骤。

---

典型日志/现象（示例）

1) SHOW BACKENDS\G 片段

BackendId: <BE_ID>
IP: <BE_IP>
HeartbeatPort: 9060
BePort: -1
HttpPort: -1
BrpcPort: -1
Alive: false
ErrMsg: Invalid method name: 'heartbeat'
TotalCapacity: 0.000 B

关键点：HeartbeatPort 显示为 9060（高概率就是问题根因）。

---

根因解释（为什么会报这个错）

FE 给 BE 发心跳时，会用 HeartbeatPort 连接 BE，并调用 Thrift 的 HeartbeatService.heartbeat() 方法。

如果你把 BE 的 非心跳端口 （例如 be_port=9060）当作 HeartbeatPort 注册到 FE，FE 就会对一个"不提供 HeartbeatService 的服务端口"调用 heartbeat 方法，从而报：

• Invalid method name: 'heartbeat'

---

最常见根因（按概率排序）

A) BE 心跳端口注册错了（把 9060 当成 HeartbeatPort） ✅ 最常见

默认端口含义（以常见配置为例）：

• 9050 ：heartbeat_service_port（FE 心跳应该连这个）
• 9060 ：be_port（不是心跳服务）
• 8040 ：webserver_port
• 8060 ：brpc_port

当 FE 里登记为 HeartbeatPort: 9060 时，基本就可以判定是"端口填错"。

B) FE/BE 版本不一致导致 Thrift 接口不兼容

也可能出现"方法名不匹配/协议不兼容"的症状。此时需要核对 FE/BE 版本是否一致。

C) 网络/端口被中间设备劫持到错误服务

例如 DNAT/端口复用/反向代理把 9050 映射到了非心跳服务，导致方法不匹配。

---

排查步骤（最短路径）

1) 在 FE 上确认 HeartbeatPort 是否正确

在 FE 执行：

SHOW BACKENDS\G

检查：

• HeartbeatPort 是否为 9050 （或你在 BE conf/be.conf 中配置的 heartbeat_service_port）
• 若 HeartbeatPort=9060（或其他非 9050），继续下一步

2) 在 BE 机器上核对端口配置（conf/be.conf）

在 BE 机器执行：

grep -E "heartbeat_service_port|be_port|webserver_port|brpc_port" conf/be.conf

确保你期望的心跳端口为：

• heartbeat_service_port = 9050

3) 在 BE 机器确认心跳端口是否在监听

ss -lntp | egrep ':9050|:9060|:8040|:8060' || netstat -tlnp | egrep ':9050|:9060|:8040|:8060'

如果 9050 没监听，先修复 BE 启动/端口监听问题（重启 BE、检查日志等），再回到 FE 验证。

---

修复方法（推荐：删除错误登记后重新添加）

场景：FE 中登记成了 HeartbeatPort=9060

在 FE 上执行（把占位符换成你的真实 IP/端口）：

-- 删除错误登记（把 9060 当成 heartbeat port）
ALTER SYSTEM DROP BACKEND "<BE_IP>:9060";

-- 用正确的 heartbeat_service_port 重新添加（通常是 9050）
ALTER SYSTEM ADD BACKEND "<BE_IP>:9050";

注意：如果该 BE 上承载了 tablet/数据副本，删除前要评估风险；在生产环境建议按规范下线/迁移流程处理。

但如果 TabletNum=0，通常可以直接 DROP 再 ADD（风险较低）。

---

修复后验证

1) FE 侧验证

SHOW BACKENDS\G

期望：

• Alive: true
• ErrMsg 为空
• BePort/HttpPort/BrpcPort 不为 -1
• TotalCapacity/AvailCapacity 为正常值

2) 额外验证（可选）

从 FE 机器连通性验证（根据你的网络工具选择）：

nc -zv <BE_IP> 9050
nc -zv <BE_IP> 8060
nc -zv <BE_IP> 8040

---

预防建议

• 端口不要混用 ：把 heartbeat_service_port（通常 9050）作为 FE 注册 BE 的端口，而不是 be_port（通常 9060）。
• FE/BE 版本一致：升级/部署时保证 FE 与 BE 同版本，避免 Thrift 接口不兼容。
• 标准化 ADD BACKEND 命令 ：统一使用 ALTER SYSTEM ADD BACKEND "<be_ip>:<heartbeat_service_port>"。
• 上线前做一次健康检查 ：SHOW BACKENDS\G 确认 Alive/端口/容量都正常。