Nginx 用于客户端唯一标识的是 ngx_http_userid_module 模块，通过设置 uid Cookie 实现用户级追踪，适用于 UV 统计与粗粒度行为归因；其 $userid 变量需配合 userid on; 启用，并与 $request_id（单请求维度）严格区分，不可混用。
Nginx 本身没有官方名为 “User ID 模块” 的内置模块，也没有 ngx_http_userid_module 以外常被误称为“User ID 模块”的组件。真正用于客户端标记追踪的，是 Nginx 自带的 ngx_http_userid_module（User ID 模块），它通过在响应中自动设置 Cookie（如 uid）来为客户端分配并持久化一个唯一标识，适用于简单、无状态的用户级日志关联（如统计去重、基础会话绑定），但不适用于全链路请求追踪（那是 $request_id 的职责）。
以下是该模块的正确配置方式与关键注意事项：
启用并配置 userid_module
该模块默认编译进大多数发行版 Nginx（可通过 nginx -V 2>&1 | grep -o with-http_userid-module 验证）。启用只需两步：
-
在
http或server块中启用模块功能：userid on; userid_name uid; # Cookie 名称，默认 uid userid_domain example.com; # 可选：指定作用域（需匹配实际域名） userid_path /; # 可选：Cookie 路径，默认 / userid_expires max; # 可选：有效期，max 表示永久（浏览器关闭不销毁，依赖 expires 时间） userid_p3p 'policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV PSA PSD OUR COM NAV"'; # 可选：P3P 头（旧 IE 兼容，现基本不用）
-
在
log_format中记录该 ID，便于后续分析：log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" "$http_user_agent" ' 'uid:"$userid";'; access_log /var/log/nginx/access.log main;
✅ 注意：
$userid变量仅在userid on;生效后才可用，且只在响应已设置或复用 uid 时有值；首次请求若未携带有效 uid Cookie，Nginx 会生成新 ID 并写入响应头 Set-Cookie，但$userid在本次日志中可能为空（取决于处理阶段）。建议搭配userid_service on;（见下文）提升一致性。
控制 ID 生命周期与服务级行为
为避免每次请求都生成新 ID 或跨子请求丢失上下文，推荐补充：
userid_service on;
启用后，Nginx 会在内部子请求（如auth_request、SSI）中复用主请求的 uid，防止 ID 断裂。userid_flags HttpOnly Secure;（Nginx ≥ 1.19.4）
安全加固：添加HttpOnly和Secure标志到 Set-Cookie 头，防止 XSS 窃取、确保仅 HTTPS 传输。
与 $request_id 的本质区别
| 特性 |
$userid（来自 userid_module） |
$request_id（来自 core） |
|---|---|---|
| 作用对象 | 客户端（浏览器），长期稳定（按 Cookie 存续） | 单次 HTTP 请求，每次新请求都不同 |
| 生成时机 | 首次访问无 Cookie 时生成，后续复用 | 每个请求进入 Nginx 时即时生成 |
| 用途 | 用户去重、PV/UV 统计、粗粒度行为归因 | 全链路日志串联、问题定位、重试一致性 |
| 是否透传后端 | ❌ 不自动透传，需手动 proxy_set_header X-UID $userid;
|
✅ 推荐透传 X-Request-ID
|
⚠️ 常见误区：试图用
userid替代request_id做接口级追踪——会导致同一用户多次点击产生相同 ID，无法区分请求，完全失去调试价值。
简单验证是否生效
- 访问站点，检查响应头中是否有类似：
Set-Cookie: uid=00000123456789ab; Path=/; Domain=example.com; HttpOnly; Secure - 查看 access.log，确认
uid:"00000123456789ab"字段稳定出现 - 清除浏览器 Cookie 后重访，观察 uid 是否变更
不复杂但容易忽略：userid 是客户端维度标记，不是请求维度标识。需要什么粒度，就选对变量。
