<!-- review: finished -->

<a id="http-userid"></a>

# UserID

该模块设置适合客户端识别的 cookies。接收到的和设置的 cookies 可以使用内置变量 [$uid_got](#v-uid-got) 和 [$uid_set](#v-uid-set) 进行记录。该模块与 Apache 的 [mod_uid](http://www.lexa.ru/programs/mod-uid.html) 模块兼容。

<a id="configuration-example-47"></a>

## 配置示例

```nginx
userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';
```

<a id="directives-50"></a>

## 指令

<a id="index-0"></a>

<a id="id3"></a>

### userid

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid` `on` | `v1` | `log` | `off`;   |
|--------------------------------------------------------------------------------------|-----------------------------------------|
| 默认值                                                                                  | `userid off;`                           |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

启用或禁用设置 cookies 和记录接收到的 cookies：

| `on`   | 启用设置版本 2 的 cookies 和记录接收到的 cookies；   |
|--------|---------------------------------------|
| `v1`   | 启用设置版本 1 的 cookies 和记录接收到的 cookies；   |
| `log`  | 禁用设置 cookies，但启用记录接收到的 cookies；       |
| `off`  | 禁用设置 cookies 和记录接收到的 cookies。         |

<a id="index-1"></a>

<a id="userid-domain"></a>

### userid_domain

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_domain` name | `none`;   |
|--------------------------------------------------------------------------------------|----------------------------------|
| 默认值                                                                                  | `userid_domain none;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

定义设置 cookies 的域。参数 `none` 禁用设置 cookies 的域。

<a id="index-2"></a>

<a id="userid-expires"></a>

### userid_expires

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_expires` time | `max` | `off`;   |
|--------------------------------------------------------------------------------------|------------------------------------------|
| 默认值                                                                                  | `userid_expires off;`                    |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

设置浏览器应保持 cookies 的时间。参数 `max` 会导致 cookie 在"2037年12月31日 23:55:55 GMT"过期。参数 `off` 会导致 cookie 在浏览器会话结束时过期。

<a id="index-3"></a>

<a id="userid-flags"></a>

### userid_flags

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_flags` `off` | flag ...;   |
|--------------------------------------------------------------------------------------|------------------------------------|
| 默认值                                                                                  | `userid_flags off;`                |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

如果参数不是 `off`，则定义一个或多个 cookies 的附加标志： `secure`, `httponly`, `samesite=strict`, `samesite=lax`, `samesite=none`。

<a id="index-4"></a>

<a id="userid-mark"></a>

### userid_mark

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_mark` letter | digit | = | `off`;   |
|--------------------------------------------------------------------------------------|---------------------------------------------|
| 默认值                                                                                  | `userid_mark off;`                          |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

如果参数不是 `off`，则启用 cookie 标记机制并设置用作标记的字符。该机制用于在保持客户端标识符的同时添加或更改 [userid_p3p](#userid-p3p) 和/或 cookies 过期时间。标记可以是任何英文字母（区分大小写）、数字或"="字符。

如果设置了标记，则将其与传递在 cookie 中的客户端标识符的 base64 表示的第一个填充符号进行比较。如果它们不匹配，则会使用指定的标记、过期时间和:samp:P3P 头重新发送 cookie。

<a id="index-5"></a>

<a id="userid-name"></a>

### userid_name

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_name` name;    |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值                                                                                  | `userid_name uid;`     |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

设置 cookie 名称。

<a id="index-6"></a>

<a id="userid-p3p"></a>

### userid_p3p

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_p3p` string | `none`;   |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值                                                                                  | `userid_p3p none;`              |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

设置将与 cookie 一起发送的:samp:P3P 头字段的值。如果指令设置为特殊值 `none`，则在响应中将不发送:samp:P3P 头。

<a id="index-7"></a>

<a id="userid-path"></a>

### userid_path

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_path` path;    |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值                                                                                  | `userid_path /;`       |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

定义设置 cookies 的路径。

<a id="index-8"></a>

<a id="userid-service"></a>

### userid_service

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_service` number;     |
|--------------------------------------------------------------------------------------|------------------------------|
| 默认值                                                                                  | `userid_service 服务器的 IP 地址;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

如果由多个服务器（服务）发出标识符，则应为每个服务分配其自己的 `number` 以确保客户端标识符的唯一性。对于版本 1 的 cookies，默认值为零。对于版本 2 的 cookies，默认值为由服务器的 IP 地址的最后四个八位字节组成的数字。

<a id="built-in-variables-16"></a>

## 内置变量

<a id="v-uid-got"></a>

### `$uid_got`

cookie 名称和接收到的客户端标识符。

<a id="v-uid-reset"></a>

### `$uid_reset`

如果变量设置为非空字符串且不是 `0`，则客户端标识符将被重置。特殊值 `log` 还会导致关于重置标识符的消息输出到 [error_log](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log)。

<a id="v-uid-set"></a>

### `$uid_set`

cookie 名称和发送的客户端标识符。