ip_hash是nginx原生会话持久化方式，基于客户端ip哈希实现请求固定路由，适用于内网稳定ip、文件分片上传等场景，但受限于后端扩缩容导致会话漂移、不支持weight等参数、仅限http upstream且需配合real_ip配置还原真实ip。
ip_hash 是 Nginx 原生支持的会话持久化方式，不依赖外部模块或状态存储，适合内网稳定 IP、文件分片上传、断点续传等需服务端状态连续性的场景。
ip_hash 的适用前提和限制
它通过客户端 IPv4 的前三个字节（如 192.168.1.x → 视为 192.168.1）或完整 IPv6 地址做哈希，再对后端节点数取模，实现请求固定路由。但要注意：
- 后端列表增减会导致哈希映射重分布，已建立的会话可能漂移
- 不支持 weight、backup、max_fails 等参数，开启 ip_hash 后这些配置会被忽略
- 仅适用于 HTTP upstream，stream 模块需改用 hash $remote_addr consistent
- 经 CDN、NAT 或多层代理时，$remote_addr 可能是中间设备 IP，必须配合 set_real_ip_from + real_ip_header 正确还原真实客户端 IP
基础配置写法与关键细节
ip_hash 必须放在 upstream 块的第一行或紧邻定义之后，且不能与其他 hash 类指令（如 hash $cookie_session）共存。示例如下：
upstream minio_backend {
ip_hash;
server node-a.example.com:9000;
server node-b.example.com:9000;
server node-c.example.com:9000;
}
同时，在 server 块中需确保传递真实 IP 头信息：
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- 若上游有可信代理，还需添加 set_real_ip_from 和 real_ip_header 配置
生产环境必须调整的配套参数
单纯加 ip_hash 不足以支撑高并发文件类业务。需同步优化以下项：
- 关闭 proxy_buffering：防止大文件上传时内存堆积溢出
- 延长超时时间：proxy_connect_timeout / send_timeout / read_timeout 建议设为 300 秒以上
- 放宽上传限制：client_max_body_size 根据业务设为 5G、10G 或更高
- 启用 keepalive 连接池：upstream 内配置 keepalive 32，减少 TCP 握手开销
替代方案与切换建议
当遇到大量 NAT 用户、移动网络动态 IP 或需要横向扩缩容频繁的场景，ip_hash 效果会明显下降。此时可考虑：
- 基于 cookie 的 sticky 机制（需第三方模块 nginx-sticky-module-ng）
- 应用层统一 Session 存储（如 Redis），配合轮询负载均衡
- MinIO 自身支持分布式锁和对象元数据一致性，部分场景可弱化服务端会话依赖
