Apache APISIX 中删除上游节点的正确方法

Apache APISIX 是一个高性能的云原生API网关，在使用过程中管理上游节点是常见的运维操作。本文将详细介绍在APISIX中如何正确删除路由中的上游节点。

问题背景

在APISIX 3.6.0版本中，用户尝试使用PATCH请求通过将节点值设置为null来删除路由中的上游节点时，会遇到400错误。错误信息显示节点验证失败，这表明APISIX对上游节点的删除操作有特定的要求。

正确操作方法

1. 完全替换上游节点列表

APISIX要求上游配置中必须至少保留一个有效节点。要删除特定节点，正确的方法是获取当前完整的节点列表，移除不需要的节点后，将更新后的完整节点列表重新提交。

# 首先获取当前路由配置
curl http://127.0.0.1:9180/apisix/admin/routes/12345 -H 'X-API-KEY: xxxxxx'

# 然后修改节点列表并PUT完整配置
curl http://127.0.0.1:9180/apisix/admin/routes/12345 \
-H 'X-API-KEY: xxxxxx' -X PUT -i -d '
{
    "upstream": {
        "nodes": {
            "10.46.12.10:8800": 100,
            "10.46.12.12:8800": 100
        }
    }
}'

2. 使用健康检查机制

如果目标是临时下线节点进行维护，而不是永久删除，更推荐的做法是配置健康检查功能。APISIX支持主动和被动两种健康检查模式：

• 主动健康检查：APISIX定期探测节点健康状态
• 被动健康检查：根据请求响应自动判断节点状态

配置健康检查后，当节点不可用时APISIX会自动将其从负载均衡池中移除，维护完成后又会自动恢复，无需手动操作。

技术原理

APISIX使用etcd存储配置，其数据模型要求上游节点必须是一个完整的对象，不支持部分更新。当使用PATCH方法尝试删除单个节点时，会导致schema验证失败，因为：

1. 节点列表必须是非空对象
2. 每个节点必须有有效的权重值
3. 部分更新可能破坏数据一致性

最佳实践建议

1. 对于节点维护操作，优先考虑使用健康检查机制
2. 必须删除节点时，采用完整替换方式
3. 在维护前确保剩余节点有足够容量承接流量
4. 考虑使用蓝绿部署或金丝雀发布策略减少影响

通过理解APISIX的设计原理和采用正确的方法，可以安全高效地管理上游节点，确保API网关的稳定运行。