nginx的ngx_http_userid_module通过cookie实现无状态用户标识，启用需配置userid on、userid_name等指令，并在log_format中使用$uid_got记录；uid为32位十六进制字符串，仅适用于uv统计等低敏感场景。
Nginx 的 ngx_http_userid_module 是一个轻量级、无状态的用户标识模块，它不依赖数据库或外部服务，而是通过客户端 Cookie 实现基础的跨请求用户识别。配置它记录用户唯一标识，关键在于启用模块、设置 Cookie 行为，并确保日志能捕获该标识。
启用 userid 模块并生成 UID Cookie
该模块自 Nginx 1.1.21 起已内置，无需编译安装，但默认关闭。只需在 http、server 或 location 块中添加配置：
-
userid on;：启用版本 2 Cookie（推荐），自动签发并记录； -
userid_name uid;：指定 Cookie 名为uid（可自定义，如__uid）； -
userid_domain example.com;：设置 Domain 属性，支持子域共享（如设为.example.com）； -
userid_path /;：限制 Cookie 生效路径，默认根路径； -
userid_expires 365d;：设有效期为 365 天（也可用max或off）； -
userid_flags secure httponly samesite=Strict;：添加安全标记（Nginx ≥1.19.3）。
示例：
http {
userid on;
userid_name uid;
userid_domain .example.com;
userid_path /;
userid_expires 365d;
userid_flags secure httponly samesite=Lax;
}
注意：若只希望记录已有 UID（不下发新 Cookie），可用
userid log;；若完全禁用，设为userid off;。
在 access_log 中记录用户标识
模块提供两个内置变量供日志使用：
-
$uid_got：从请求中读取到的合法 UID（客户端携带的值）； -
$uid_set：本次响应中实际写入的 UID（新生成或复用的值）。
推荐优先使用 $uid_got，因为它反映客户端真实携带的标识，避免因重定向或并发导致日志与实际行为错位。
在 log_format 中加入该变量：
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" '
'"$uid_got"';
access_log /var/log/nginx/access.log main;
若
$uid_got为空（如首次访问），对应日志字段将显示短横线-，符合常规日志习惯。
验证与注意事项
- 检查响应头：成功配置后，首次请求应收到类似
Set-Cookie: uid=00000000000000000000000000000000; Domain=.example.com; Path=/; Expires=...; HttpOnly; Secure; SameSite=Lax的头； - UID 格式固定为 32 位小写十六进制字符串（MD5 哈希结果），不可读但高唯一；
- 不代表真实用户身份：同一设备换浏览器、清 Cookie、无痕模式都会产生新 UID；
- 多实例部署时，若配置了
userid_domain和一致的userid_name，UID 可跨 server 共享（依赖域名 CRC 计算，非全局随机）； - 不可用于登录态管理或权限控制，仅适合 UV 统计、基础行为归因等低敏感场景。
不复杂但容易忽略。
