# ngx\_http\_memcached\_module

* [指令](#directives)
  * [memcached\_bind](#memcached_bind)
  * [memcached\_buffer\_size](#memcached_buffer_size)
  * [memcached\_connect\_timeout](#memcached_connect_timeout)
  * [memcached\_force\_ranges](#memcached_force_ranges)
  * [memcached\_gzip\_flag](#memcached_gzip_flag)
  * [memcached\_next\_upstream](#memcached_next_upstream)
  * [memcached\_next\_upstream\_timeout](#memcached_next_upstream_timeout)
  * [memcached\_next\_upstream\_tries](#memcached_next_upstream_tries)
  * [memcached\_pass](#memcached_pass)
  * [memcached\_read\_timeout](#memcached_read_timeout)
  * [memcached\_send\_timeout](#memcached_send_timeout)
* [内嵌变量](#embedded_variables)

`ngx_http_memcached_module` 模块用于从 memcached 服务器上获取响应。key 设置在 `$memcached_key` 变量中。应通过 nginx 之外的方式提前将响应放入 memcached。

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

```
server {
    location / {
        set            $memcached_key "$uri?$args";
        memcached_pass host:11211;
        error_page     404 502 504 = @fallback;
    }

    location @fallback {
        proxy_pass     http://backend;
    }
}
```

## 指令 <a href="#directives" id="directives"></a>

### memcached\_bind

|       - | 说明                                                     |
| ------: | ------------------------------------------------------ |
|  **语法** | **memcached\_bind** `address [transparent ]` \| `off`; |
|  **默认** | ——                                                     |
| **上下文** | http、server、location                                   |
|  **提示** | 该指令在 0.8.22 版本中出现                                      |

连接到一个指定了本地 IP 地址和可选端口（1.11.2）的 memcached 服务器。参数值可以包含变量（1.3.12）。特殊值 `off` （1.3.12）取消从上层配置级别继承的 `memcached_bind` 指令的作用，其允许系统自动分配本地 IP 地址和端口。

`transparent` 参数（1.11.0）允许出站从非本地 IP 地址到 memcached 服务器的连接（例如，来自客户端的真实 IP 地址）：

```
memcached_bind $remote_addr transparent;
```

为了使这个参数起作用，通常需要以[超级用户](https://github.com/DocsHome/nginx-docs/tree/f6135c42a499e9fab0adb433738fcf8cd4041627/%E6%A8%A1%E5%9D%97%E5%8F%82%E8%80%83/%E6%A0%B8%E5%BF%83%E6%A8%A1%E5%9D%97.md#user)权限运行 nginx worker 进程。在 Linux 上，不需要指定 `transparent` 参数，工作进程会继承 master 进程的 `CAP_NET_RAW` 功能。此外，还要配置内核路由表来拦截来自 memcached 服务器的网络流量。

### memcached\_buffer\_size

|       - | 说明                                  |
| ------: | ----------------------------------- |
|  **语法** | **memcached\_buffer\_size** `size`; |
|  **默认** | memcached\_buffer\_size 4k\|8k      |
| **上下文** | http、server、location                |

设置用于读取从 memcached 服务器收到的响应的缓冲区的大小（`size`）。一旦收到响应，响应便会同步传送给客户端。

### memcached\_connect\_timeout

|       - | 说明                                      |
| ------: | --------------------------------------- |
|  **语法** | **memcached\_connect\_timeout** `time`; |
|  **默认** | memcached\_connect\_timeout 60s         |
| **上下文** | http、server、location                    |

定义与 memcached 服务器建立连接的超时时间。需要说明的是，超时通常不能超过 75 秒。

### memcached\_force\_ranges

|       - | 说明                                          |
| ------: | ------------------------------------------- |
|  **语法** | **memcached\_force\_ranges** `on` \| `off`; |
|  **默认** | memcached\_force\_ranges off;               |
| **上下文** | http、server、location                        |
|  **提示** | 该指令在 1.7.7 版本中出现                            |

无论响应中的 **Accept-Ranges** 字段如何，都对来自 memcached 服务器的缓存和未缓存的响应启用 byte-range 支持。

### memcached\_gzip\_flag

|       - | 说明                                |
| ------: | --------------------------------- |
|  **语法** | **memcached\_gzip\_flag** `flag`; |
|  **默认** | ——                                |
| **上下文** | http、server、location              |
|  **提示** | 该指令在 1.3.6 版本中出现                  |

启用对 memcached 服务器响应中的 `flag` 存在测试，并在 flag 设置时将 **Content-Encoding** 响应头字段设置为 **gzip**。

### memcached\_next\_upstream

|       - | 说明                                                                                                    |
| ------: | ----------------------------------------------------------------------------------------------------- |
|  **语法** | **memcached\_next\_upstream** `error` \| `timeout` \| `invalid_response` \| `not_found` \| `off ...`; |
|  **默认** | memcached\_next\_upstream error timeout;                                                              |
| **上下文** | http、server、location                                                                                  |

指定在哪些情况下请求应传递给下一台服务器：

* `error`

  在与服务器建立连接、传递请求或读取响应头时发生错误
* `timeout`

  在与服务器建立连接、传递请求或读取响应头时发生超时
* `invalid_response`

  服务器返回空或无效的响应
* `not_found`

  在服务器上未找到响应
* `off`

  禁用将请求传递给下一个服务器。

我们应该记住，只有在没有任何内容发送给客户端的情况下，才能将请求传递给下一个服务器。也就是说，如果在响应传输过程中发生错误或超时，修复这样的错误是不可能的。

该指令还定义了与服务器进行通信的[失败尝试](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_upstream_module#max_fails)。`error`、`timeout` 和 `invalid_response` 的情况始终被视为失败尝试，即使它们没有在指令中指定。`not_found` 的情况永远不会被视为失败尝试。

将请求传递给下一个服务器可能受到[尝试次数](#grpc_next_upstream_tries)和[时间](#grpc_next_upstream_timeout)的限制。

### memcached\_next\_upstream\_tries

|       - | 说明                                             |
| ------: | ---------------------------------------------- |
|  **语法** | **memcached\_next\_upstream\_tries** `number`; |
|  **默认** | memcached\_next\_upstream\_tries 0;            |
| **上下文** | http、server、location                           |
|  **提示** | 该指令在 1.7.5 版本中出现                               |

限制尝试将请求传递到[下一个服务器](#grpc_next_upstream)的次数。`0` 值表示关闭此限制。

### memcached\_pass

|       - | 说明                             |
| ------: | ------------------------------ |
|  **语法** | **memcached\_pass** `address`; |
|  **默认** | ——                             |
| **上下文** | http、location 中 if             |

设置 memcached 服务器地址。该地址可以指定为域名或 IP 地址以及端口：

```
memcached_pass localhost:11211;
```

或使用 UNIX 域套接字路径：

```
memcached_pass unix:/tmp/memcached.socket;
```

如果域名解析为多个地址，则这些地址将以循环方式使用。另外，地址可以被指定为[服务器组](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_upstream_module)。

### memcached\_read\_timeout

|       - | 说明                                   |
| ------: | ------------------------------------ |
|  **语法** | **memcached\_read\_timeout** `time`; |
|  **默认** | memcached\_read\_timeout 60s;        |
| **上下文** | http、server、location                 |

memcached 定义从 gRPC 服务器读取响应的超时时间。超时间隔只在两次连续的读操作之间，而不是整个响应的传输过程。如果 memcached 服务器在此时间内没有发送任何内容，则连接关闭。

### memcached\_send\_timeout

|       - | 说明                                   |
| ------: | ------------------------------------ |
|  **语法** | **memcached\_send\_timeout** `time`; |
|  **默认** | memcached\_send\_timeout 60s;        |
| **上下文** | http、server、location                 |

设置将请求传输到 memcached 服务器的超时时间。超时间隔只在两次连续写入操作之间，而不是整个请求的传输过程。如果 memcached 服务器在此时间内没有收到任何内容，则连接将关闭。

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

* `$memcached_key`

  定义从 memcached 服务器获取响应的密钥

## 原文档

<http://nginx.org/en/docs/http/ngx_http_memcached_module.html>