PrivateLink 状态异常告警处理指南
PrivateLink 状态异常告警表示 EMQX Cloud 与外部服务之间配置的 PrivateLink 连接处于异常状态，通常表现为 Failed。
该情况通常意味着 EMQX Cloud 无法通过 Interface Endpoint（ENI）访问客户侧服务，可能进一步导致数据集成动作失败或认证、鉴权请求失败。
PrivateLink 关键链路说明
PrivateLink 的完整网络链路如下所示：
text
EMQX VPC
└─ 终端节点
↓
PrivateLink 内部通道
↓
终端节点服务（客户侧）
↓
负载均衡（Load Balancer）
↓
服务器组
↓
后端服务器（EC2 / ECS / Pod）该告警的本质含义是：EMQX Cloud 的终端节点无法通过上述链路访问到健康且可用的后端服务。
对端负载均衡健康检查失败
问题描述
当终端节点服务所关联的负载均衡后端服务器组中不存在健康的后端实例时，PrivateLink 无法建立有效连接，从而触发状态异常告警。
在该场景下，PrivateLink 或终端节点服务本身可能无明显报错日志，但实际流量无法被成功转发。
常见原因
- 服务器组中所有后端实例均处于 unhealthy 状态。
- 后端实例未通过负载均衡的健康检查。
处理方法
- 检查负载均衡后端服务器的健康状态，确认是否存在 unhealthy 的实例。
- 根据负载均衡控制台的健康检查结果，进一步排查后端实例的运行状态。
后端服务未监听或端口配置错误
问题描述
当后端服务未正确监听负载均衡所配置的端口或网络接口时，负载均衡的健康检查将持续失败，导致 PrivateLink 无法正常工作。
在该场景下，服务器组状态通常显示为 unhealthy，且后端服务日志中未出现任何来自负载均衡的访问记录。
常见原因
- 后端服务未启动或进程异常退出。
- 后端服务监听端口与服务器组中配置的端口不一致。
- 服务仅监听在
127.0.0.1，未监听0.0.0.0。 - 健康检查协议为 TCP，但对应端口未开放或被防火墙阻断。
处理方法
- 确认后端服务已正常启动，并监听在正确的网络接口和端口上。
- 核对服务器组中的端口配置与后端服务实际监听端口是否一致。
- 避免服务仅监听本地回环地址，确保负载均衡能够建立 TCP 连接。
后端安全组未放行负载均衡子网流量
问题描述
对于使用 NLB 的场景，负载均衡本身不绑定安全组，实际进入后端实例的流量源 IP 为 NLB 所在子网的 CIDR。
如果后端服务器的安全组未允许来自 NLB 子网 CIDR 到健康检查端口的入站访问，健康检查将失败，从而导致 PrivateLink 状态异常。
常见原因
- 后端安全组规则未放行 NLB 子网 CIDR。
- 健康检查端口未包含在允许的入站规则中。
处理方法
- 检查并修改后端服务器的安全组规则。
- 确保已放行来自 NLB 所在子网 CIDR 的入站流量，并覆盖健康检查所使用的端口。
终端节点/终端节点服务/负载均衡器被误修改或删除
问题描述
PrivateLink 对终端节点服务和负载均衡配置具有强依赖关系。如果在未对 EMQX Cloud 做任何变更的情况下，PrivateLink 原本可用但突然进入异常状态，通常意味着对端关键资源发生了变更。
常见原因
- 删除或重建了负载均衡器（NLB）。
- 修改了服务器组配置或替换了后端服务器。
- 停止或移除了后端实例。
- 关闭了某个可用区（AZ）的子网。
- 修改了终端节点服务允许访问的 AZ 范围。
- 终端节点被手动删除了
处理方法
- 核查近期是否对终端节点、终端节点服务、负载均衡或后端资源做过变更。
- 建立严格的网络资源变更审核机制，避免无意操作破坏 PrivateLink 依赖链路。
排查步骤
- 登录云平台控制台，检查 PrivateLink 状态，确认其是否处于
Failed或其他异常状态。 - 检查负载均衡器是否仍然存在，并确认其运行状态和监控指标是否正常。
- 查看服务器组状态，确认是否所有后端实例均为 healthy。
- 核对当前负载均衡启用的可用区（AZ）是否与后端服务所在 AZ 一一对应。
- 检查后端服务器的安全组 配置，确认已放行来自负载均衡子网 CIDR 的入站流量。
- 配合 EMQX 技术支持人员，使用
telnet <endpoint-ip> <port>或nc等工具测试终端节点到后端服务端口的连通性。