Nginx upstream 稳定运行 consistent_hash 需满足四点：1.确认编译 consistent_hash 模块（如 OpenResty/Tengine）；2.合理选择哈希键（如 $http_x_real_ip）；3.正确配置 upstream 块并启用 consistent_hash；4.配套健康检查与规范节点扩缩容。
要让 Nginx 的 upstream 真正通过 consistent_hash 实现稳定、可预期的一致性哈希分发，不能只写一行指令，得从模块支持、键选择、配置写法、节点管理四个层面协同落地。
确认 consistent_hash 模块已可用
官方 Nginx 不内置该功能，必须使用已集成模块的发行版或自行编译：
- 推荐直接用 OpenResty（开箱即用）或 Tengine（阿里原生支持）
- 若用自编译 Nginx，需添加第三方模块：ngx_http_consistent_hash
- 验证是否生效：执行
nginx -V 2>&1 | grep consistent_hash，有输出才表示模块加载成功；否则 reload 会报错 “unknown directive ‘consistent_hash’”
选对哈希键（variable_name）是关键
键决定请求如何“绑定”到节点，选错会导致负载不均或会话断裂：
-
consistent_hash $http_x_real_ip：适合前置 CDN 或 LB 场景，需确保X-Real-IP正确透传 -
consistent_hash $remote_addr：仅适用于无 NAT、无代理的直连环境；IPv6 或多层代理下易失真 -
consistent_hash $request_uri：适合静态资源、商品详情页等缓存服务，提升缓存命中率 -
consistent_hash $cookie_session_id：适合登录态强绑定场景（如 Grafana、后台系统），抗 NAT 和代理干扰更强 - 避免用
$host、$scheme等低区分度或易变变量
正确编写 upstream 块
标准配置需兼顾哈希逻辑、权重调节与容错能力：
- 指令必须写在
upstream块首行，格式为consistent_hash $variable;（注意无空格） - 每个
server行仍支持weight，用于按比例分配基础负载 - 务必配置
max_fails和fail_timeout，否则节点宕机后哈希环无法自动绕过失效节点 - 建议开启
keepalive（如keepalive 64;），减少连接重建开销
示例：
upstream api_backend {consistent_hash $http_x_real_ip;
server 10.0.10.1:8000 weight=3 max_fails=2 fail_timeout=30s;
server 10.0.10.2:8000 weight=3 max_fails=2 fail_timeout=30s;
server 10.0.10.3:8000 weight=3 max_fails=2 fail_timeout=30s;
keepalive 64;
}
配套健康检查与节点扩缩容规范
一致性哈希不是“一配了之”，节点动态变化时需配合运维策略：
- 启用主动健康检查（如
nginx_upstream_check_module），避免请求打到临时不可用节点 - 扩容节点时，建议逐步上线并观察流量分布，避免一次性加入多个高权重节点引发倾斜
- 缩容前，先将目标节点的
weight=0并 reload，等待活跃连接自然退出，再下线机器 - 若业务允许，可在 fallback 场景补充兜底逻辑（例如无 Cookie 时退回到 IP 哈希）
