# ngx\_http\_userid\_module

* [示例配置](#example_configuration)
* [指令](#directives)
  * [userid](#userid)
  * [userid\_domain](#userid_domain)
  * [userid\_expires](#userid_expires)
  * [userid\_mark](#userid_mark)
  * [userid\_name](#userid_name)
  * [userid\_p3p](#userid_p3p)
  * [userid\_path](#userid_path)
  * [userid\_service](#userid_service)
* [内嵌变量](#embedded_variables)

`ngx_http_userid_module` 模块设置方便客户端识别的 cookie。可以使用内嵌变量 [$uid\_got](#uid_got) 和 [$uid\_set](#uid_set) 记录已接收和设置的 cookie。该模块与 Apache 的 [mod\_uid](http://www.lexa.ru/programs/mod-uid-eng.html) 模块兼容。

## 示例配置 <a href="#example_configuration" id="example_configuration"></a>

```
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 href="#directives" id="directives"></a>

### userid

| -       | 说明                                         |
| ------- | ------------------------------------------ |
| **语法**  | **userid** `on` \| `v1` \| `log` \| `off`; |
| **默认**  | userid off;                                |
| **上下文** | http、server、location                       |

启用或禁用设置 cookie 和记录接受到的 cookie：

* `on`

  启用版本 2 cookie 设置并记录接收到的 cookie
* `v1`

  启用版本 1 cookie 设置并记录接收到的 cookie
* `log`

  禁用 cookie 设置，但允许记录接收到的 cookie
* `off`

  禁用 cookie 设置和记录接收到的 cookie

### userid\_domain

| -       | 说明                                   |
| ------- | ------------------------------------ |
| **语法**  | **userid\_domain** `name` \| `none`; |
| **默认**  | userid\_domain none;                 |
| **上下文** | http、server、location                 |

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

### userid\_expires

| -       | 说明                                            |
| ------- | --------------------------------------------- |
| **语法**  | **userid\_expires** `time` \| `max` \| `off`; |
| **默认**  | userid\_expires off;                          |
| **上下文** | http、server、location                          |

设置浏览器保留 cookie 的时间（`time`）。特殊值 `max` 将 cookie 设置在 `31 Dec 2037 23:55:55 GMT` 时到期。如果未指定参数，cookie 将在浏览器会话结束时到期。

### userid\_mark

| -       | 说明                                                    |
| ------- | ----------------------------------------------------- |
| **语法**  | **userid\_mark** `letter` \| `digit` \| `=` \| `off`; |
| **默认**  | userid\_mark off;                                     |
| **上下文** | http、server、location                                  |

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

如果设置了标记，则将其与 cookie 中传递的客户端标识符的 base64 形式中的第一个填充符号进行比较。如果它们不匹配，则会重新发送带有指定标记、到期时间和 **P3P** 头的 cookie。

### userid\_name

| -       | 说明                       |
| ------- | ------------------------ |
| **语法**  | **userid\_name** `name`; |
| **默认**  | userid\_name uid;        |
| **上下文** | http、server、location     |

设置 cookie 的名称。

### userid\_p3p

| -       | 说明                                  |
| ------- | ----------------------------------- |
| **语法**  | **userid\_p3p** `string` \| `none`; |
| **默认**  | userid\_p3p none;                   |
| **上下文** | http、server、location                |

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

### userid\_path

| -       | 说明                       |
| ------- | ------------------------ |
| **语法**  | **userid\_path** `path`; |
| **默认**  | userid\_path /;          |
| **上下文** | http、server、location     |

为设置的 cookie 定义路径。

### userid\_service

| -       | 说明                            |
| ------- | ----------------------------- |
| **语法**  | **userid\_service** `number`; |
| **默认**  | userid\_service 服务器的 IP 地址;   |
| **上下文** | http、server、location          |

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

## 内嵌变量 <a href="#embedded_variables" id="embedded_variables"></a>

`ngx_http_userid_module` 模块支持以下内嵌变量：

* `$uid_got`

  cookie 名称和收到的客户端标识符
* `$uid_reset`

  如果变量设置为非空字符串且非 `"0"`，则重置客户端标识符。特殊值 `log` 会将关于重置标识符的消息输出到 [error\_log](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/..#error_log)。
* `$uid_set`

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

## 原文档 <a href="#uid_set" id="uid_set"></a>

* <http://nginx.org/en/docs/http/ngx_http_userid_module.html>