Nginx可通过$HTTP_变量结合limit_conn_zone实现基于自定义Header（如X-User-ID）的连接数限制：需在http块声明zone，location中启用limit_conn，并由网关注入、标准化及校验Header以确保标识稳定可信。
Nginx 本身不直接支持基于自定义 Header（如 X-User-ID 或 X-Account-Code）做连接数限制，但可以通过 limit_conn_zone 指令配合 $http_* 变量间接实现——关键在于让 Nginx 能稳定提取并哈希业务账号标识。
1. 正确声明 limit_conn_zone，使用 $http_x_user_id 作为键
在 http 块中定义共享内存区域，以请求头中的账号字段为 key：
limit_conn_zone $http_x_user_id zone=per_account:10m;
说明：
-
$http_x_user_id是 Nginx 内置变量，自动映射请求头X-User-ID的值（自动转小写、下划线转短横）；若 header 为X-Account-Code，则用$http_x_account_code - 该变量为空或不存在时，Nginx 视为同一 key（即空字符串），会导致所有无 header 请求被归为一组限流，需前置校验或默认兜底
-
zone=per_account:10m表示最多记录约 6–8 万个唯一账号（具体取决于账号长度），生产建议按预估账号量预留 2–3 倍内存
2. 在 server 或 location 中启用 limit_conn，并设置合理阈值
在需要控制的上下文中添加限流规则：
location /api/ {
limit_conn per_account 5;
limit_conn_status 429;
# 其他配置...
}
说明：
- 每个唯一
X-User-ID值最多维持 5 个并发 TCP 连接（非请求数），适用于长连接场景（如 WebSocket、HTTP/2 流） -
limit_conn_status 429将超限响应码设为 429 Too Many Requests，更符合语义；默认是 503 - 注意：该限制作用于连接建立阶段（accept 阶段），不是请求处理阶段；若需限制每秒请求数，应搭配
limit_req
3. 确保客户端携带合法且稳定的账号 Header
业务系统必须在每次请求中带上一致、不可伪造的账号标识：
- 推荐由网关层（如 Kong、API Gateway）统一注入
X-User-ID，后端服务不再信任原始 header - 避免前端直接构造该 header，防止绕过；可通过鉴权中间件在入口校验 JWT 或 session 后动态设置
- 账号值建议使用 UUID、加密 ID 或服务端签发的短 token，避免使用用户名等易变/重复字段
- 若 header 值含空格、逗号、分号等特殊字符，Nginx 会截断或解析异常，建议服务端做标准化清洗（如 Base64 编码或正则过滤）
4. 处理边界情况：缺失、重复、恶意 header
增强健壮性，避免因 header 异常导致误限流或失效：
# 提取前先清理和标准化
map $http_x_user_id $clean_user_id {
"" "-";
default $http_x_user_id;
}
<p>limit_conn_zone $clean_user_id zone=per_account:10m;</p><h1>或更严格地只接受字母数字+短横</h1><p>map $http_x_user_id $valid_user<em>id {
~^[a-zA-Z0-9</em>-]{4,64}$ $http_x_user_id;
default "-";
}</p><p>limit_conn_zone $valid_user_id zone=per_account:10m;</p>说明：
- 用
map预处理 header，将空值、非法格式统一映射为固定占位符（如"-"），防止大量空值挤占 zone 空间 - 对非法账号统一限流到同一组（
"-"），便于监控和告警，而非放行 - 可配合
log_format记录$http_x_user_id和$valid_user_id，用于排查 header 问题
不复杂但容易忽略：连接数限制生效的前提是 Nginx 能稳定拿到账号标识，而这个标识必须由可信链路注入、标准化、验证。单纯依赖客户端传入的 header 是有风险的，务必结合身份认证环节做端到端保障。
