Nginx 不提供分库分表语义，但可通过 hash 指令基于请求变量（如 Header、URI）实现业务键定向代理；支持普通哈希（取模）和一致性哈希（1.19.0+原生），后者更适配动态扩缩容；需用 map 等安全提取 key，真实分库分表仍由后端中间件完成。
Nginx 本身不提供“分库分表键”的语义抽象，也没有内置的数据库路由逻辑，但它可以通过 hash 指令结合变量（如请求参数、Header 或 URI 片段）做一致性或普通哈希分发，从而实现**基于业务键的定向代理**——这是分库分表场景中“路由到指定后端实例”的轻量级前置方案。
理解 Nginx 的 hash 机制与适用边界
Nginx 的 upstream hash 支持两种模式：hash $key consistent;（一致性哈希）和 hash $key;（取模哈希）。两者都可将相同 key 映射到固定后端，但行为不同：
- 普通 hash：Nginx 对 key 做哈希后对后端数量取模，简单高效；但增减 upstream server 会导致大量 key 重映射，适合后端稳定的场景
-
consistent hash：使用 ketama 算法，节点增减仅影响少量 key，更适配动态扩缩容，但需注意 Nginx 开源版从 1.19.0+ 才原生支持
consistent参数（旧版本需第三方模块） - ⚠️ 关键限制：Nginx 不解析 SQL、不识别分库分表逻辑（如 user_id % 4 → db0、user_id / 4 % 8 → table_2），它只负责把某个字符串 key 映射到某台 proxy 后端。真正的分库分表仍由应用或中间件（如 ShardingSphere、MyCat）完成
提取分库分表键并构造 hash 变量
你需要让 Nginx 从请求中可靠地提取出业务主键（例如 user_id、order_no、tenant_id），常用方式有：
-
从查询参数提取：
set $shard_key $arg_user_id;（适用于 GET 接口带 id 查询） - 从请求体提取（需配合 lua 或 body_filter_by_lua*）：Nginx 原生不解析 POST body，若必须用 body 中字段，建议改用 OpenResty + lua-resty-json 解析，或推动前端改用 Header/URL 透传
-
从 Header 提取：
set $shard_key $http_x_shard_key;（推荐方式，由上游服务统一注入，语义清晰、稳定可控） -
从 URI 路径提取：
set $shard_key $uri;或用正则捕获：if ($request_uri ~ ^/api/users/(\d+)/) { set $shard_key $1; }（注意 if 在 location 外不推荐，应改用 map）
配置 upstream hash 实现定向代理
以下是一个典型配置示例（假设按 user_id 分发到 4 台 DB Proxy）：
http {
# 预定义分片后端集群
upstream db_proxy_cluster {
hash $shard_key consistent;
server 10.0.1.10:3306 weight=1;
server 10.0.1.11:3306 weight=1;
server 10.0.1.12:3306 weight=1;
server 10.0.1.13:3306 weight=1;
}
<pre class="brush:php;toolbar:false;"># 提取 key（这里用 Header 方式）
map $http_x_user_id $shard_key {
"" "default";
default "$http_x_user_id";
}
server {
listen 80;
location /mysql/ {
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://db_proxy_cluster;
}
}}
说明：
- 使用
map指令安全提取变量，避免空值导致 hash 异常 -
hash $shard_key consistent;保证 user_id 相同的请求始终打到同一台 proxy，proxy 再根据自身规则（如 JDBC URL 中的 database name 或自定义分表逻辑）访问对应物理库表 - 若不用一致性哈希，直接写
hash $shard_key;即可（取模），性能略高，但扩容需谨慎
验证与注意事项
上线前建议验证 key 分布是否均匀、故障转移是否符合预期：
- 用
log_format记录$shard_key和$upstream_addr，抽样检查映射稳定性 - 模拟新增一台 upstream server，观察已有 key 是否发生大规模漂移（普通 hash 会，consistent hash 不会）
- 确保所有客户端在请求中正确携带分片键（如
X-User-ID），缺失时 fallback 到默认 server 或返回 400 - 不建议在 hash 中混用多个变量（如
hash "$arg_user_id.$arg_tenant_id"），除非业务明确需要联合分片；否则优先单维度强一致
