Nginx 中 IP Hash 如何实现持久化连接调度-Nginx-PHP中文网

ip hash 实现请求级会话持久化，通过客户端ip哈希取模固定映射至同一后端服务器，支持有状态服务；需配置set_real_ip_from等还原真实ip，并配合超时、缓冲、上传等优化项。

nginx 中 ip hash 如何实现持久化连接调度

IP Hash 实现的是请求级的会话持久化，不是连接级别的“长连接”本身，但它能让同一客户端 IP 的所有请求稳定落到同一台后端服务器上，从而间接支撑有状态的服务连续性（比如内存 Session、断点续传、文件分片上传等）。

核心原理：IP 哈希 + 取模固定映射

nginx 对客户端 IPv4 地址取前三个字节（如 192.168.1.x 全部视为 192.168.1），或对完整 IPv6 地址做哈希运算，再对当前 upstream 中**存活的后端节点数量**取模，得到一个固定索引。只要节点列表不变，同一 IP 每次计算结果都一样，请求就始终发往同一台 server。

这个映射不依赖 cookie、session 存储或外部组件，纯 Nginx 内置逻辑
它作用于 HTTP 请求层面，只适用于 http { upstream } 块，stream 模块需改用 hash $remote_addr consistent
IPv4 的“前三段”设计是为了缓解同一局域网内大量终端 IP 细微变化导致哈希剧烈抖动

基础配置要点

必须把 ip_hash; 放在 upstream 块的第一行或紧邻定义之后，且不能与其他 hash 类指令（如 hash $cookie_sessionid）共存：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

upstream app_backend {
    ip_hash;
    server 10.0.2.10:8080;
    server 10.0.2.11:8080;
    server 10.0.2.12:8080;
}

后端 server 行不能加 weight、backup 或 max_fails，否则 nginx 启动报错或忽略这些参数
某台 server 被健康检查标记为 down 时，Nginx 会自动从哈希计算的节点池中剔除它，剩余 IP 映射关系仍维持在其他存活节点上

真实 IP 必须准确还原

如果前端有 CDN、NAT 网关或反向代理，$remote_addr 默认是中间设备 IP，会导致哈希完全失效。必须配合以下配置还原真实客户端 IP：

在 http 或 server 块中声明可信代理段：set_real_ip_from 192.168.10.0/24;
指定真实 IP 来源头：real_ip_header X-Forwarded-For;（或 X-Real-IP，依上游实际传递为准）
同时在 location 中透传头信息：proxy_set_header X-Real-IP $remote_addr; 和 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

生产环境配套优化项

仅加 ip_hash 不足以应对大文件、高并发等场景，还需同步调整：

关闭响应缓冲：proxy_buffering off;，防止大响应体堆积内存
延长超时：proxy_connect_timeout 300;、proxy_send_timeout 300;、proxy_read_timeout 300;
放宽上传限制：client_max_body_size 10G;
启用 upstream 长连接池：keepalive 32;（放在 upstream 块内），并配 proxy_http_version 1.1; 和 proxy_set_header Connection "";