APISIX集群节点间配置同步失败如何排查？

Question

问题：APISIX集群中多个节点配置不一致，新增路由或上游在部分节点未生效，导致请求转发异常。初步排查发现控制平面（etcd）连接正常，但部分数据面节点未收到配置更新通知。如何定位是网络分区、etcd监听失效，还是节点本地缓存同步机制异常？需结合日志、监控及组件间通信状态进行系统性分析。

Answer 1

APISIX集群配置不一致问题的系统性排查与分析

1. 问题背景与现象描述

在APISIX生产环境中，常出现新增路由或上游服务后，部分数据面节点未能及时同步配置，导致请求转发失败或被错误地代理到非预期的服务实例。尽管控制平面（etcd）连接状态正常，且写入操作成功，但部分节点仍表现出“配置滞后”或“配置缺失”的行为。

此类问题直接影响服务可用性和灰度发布效果，核心需判断是网络分区、etcd监听机制失效，还是本地缓存同步逻辑异常所致。

2. 排查路径：由浅入深的三层定位模型

1. 第一层：日志与监控初步筛查
2. 第二层：组件间通信链路验证
3. 第三层：底层机制深度剖析

3. 第一层：日志与监控初步筛查

通过集中式日志系统（如ELK或Loki）收集所有APISIX节点的日志，重点关注以下关键词：

• watch request failed —— 表明etcd监听中断
• config is outdated —— 配置版本不一致
• failed to sync from etcd —— 同步失败
• worker process exit —— 工作进程异常退出
• stream closed —— gRPC流关闭

同时检查Prometheus中各节点的apisix_nginx_http_requests_total和apisix_etcd_reachable指标，确认是否存在节点级监控断点或请求分布不均。

4. 第二层：组件间通信链路验证

构建如下通信链路分析表，用于横向比对各节点状态：

节点IP	etcd连接延迟(ms)	last_config_update_time	watch_stream_active	local_cache_version	global_config_version	sync_status
192.168.1.101	12	2025-04-05T10:00:00Z	true	1003	1003	synced
192.168.1.102	15	2025-04-05T09:55:30Z	false	998	1003	stale
192.168.1.103	11	2025-04-05T10:00:00Z	true	1003	1003	synced
192.168.1.104	200	2025-04-05T09:50:00Z	false	995	1003	stale
192.168.1.105	13	2025-04-05T10:00:00Z	true	1003	1003	synced

从上表可见，102和104节点存在明显配置滞后，且watch_stream非活跃，提示etcd事件监听可能已中断。

5. 第三层：底层机制深度剖析

APISIX依赖etcd的Watch机制实现配置热更新，其核心流程如下：

-- APISIX 内部 watch 逻辑伪代码示意
local function start_watch()
    local watcher = etcd:watch("/apisix/routes", {
        recursive = true,
        index = current_index
    })

    watcher:on_event(function(event)
        core.config.update_local_cache(event)  -- 更新本地LRU缓存
        trigger_router_reload()               -- 触发路由重载
    end)

    watcher:on_error(function(err)
        log.error("watch failed: ", err)
        retry_with_backoff(start_watch)
    end)
end
    

若该watch流因网络抖动、etcd leader切换或gRPC Keepalive超时而中断，且重试机制未生效，则会导致配置停滞。

6. 网络分区检测方法

使用以下命令进行双向连通性测试：

tcping -t 1s 192.168.1.200 2379  # etcd端口探测
etcdctl --endpoints=http://192.168.1.200:2379 endpoint status
curl -s http://192.168.1.102:9090/v1/server_info | jq .up_time

结合Wireshark或tcpdump抓包分析，确认是否存在TCP重传、RST包或TLS握手失败等迹象。

7. etcd监听失效诊断

etcd Watch基于长连接gRPC流，常见失效原因包括：

• Keepalive参数设置不合理（默认keepalive-time=2s，过短易触发频繁重建）
• etcd集群负载过高，响应延迟超过client超时阈值
• Go runtime调度延迟导致watch goroutine阻塞

可通过etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds等指标辅助判断后端压力。

8. 本地缓存同步机制异常分析

APISIX使用Nginx共享内存（shm）存储本地缓存，若worker进程未正确接收配置变更通知，可能导致：

• 缓存版本号未更新
• 旧路由仍被命中
• hot-reload未广播至所有worker

可通过OpenResty的ngx.shared.DICT接口手动查询缓存状态：

apisix-cli config dump-cache --node 192.168.1.102

9. 根本原因判定流程图

graph TD
            A[配置不一致] --> B{所有节点能否访问etcd?}
            B -->|否| C[网络分区]
            B -->|是| D{etcd watch stream是否活跃?}
            D -->|否| E[etcd监听失效]
            D -->|是| F{本地缓存版本是否匹配?}
            F -->|否| G[本地缓存同步异常]
            F -->|是| H[其他业务逻辑问题]

10. 解决方案建议

针对不同层级问题提出应对策略：

• 网络层：部署BGP+Anycast提升etcd可达性，启用mTLS双向认证确保传输安全
• etcd层：调优keepalive参数，增加client-side watchdog定时ping
• APISIX层：开启config_provider: etcd的健康检查轮询兜底机制
• 运维层：建立配置同步SLA，定期执行diff-check脚本比对全局一致性
• 可观测性：集成OpenTelemetry，追踪配置从etcd到worker的完整传播路径

此外，可引入Sidecar模式将etcd watch解耦为独立协程，避免主事件循环阻塞影响监听稳定性。