# ngx\_http\_memcached\_module

* [指令](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#directives)
  * [memcached\_bind](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_bind)
  * [memcached\_buffer\_size](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_buffer_size)
  * [memcached\_connect\_timeout](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_connect_timeout)
  * [memcached\_force\_ranges](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_force_ranges)
  * [memcached\_gzip\_flag](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_gzip_flag)
  * [memcached\_next\_upstream](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_next_upstream)
  * [memcached\_next\_upstream\_timeout](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_next_upstream_timeout)
  * [memcached\_next\_upstream\_tries](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_next_upstream_tries)
  * [memcached\_pass](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_pass)
  * [memcached\_read\_timeout](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_read_timeout)
  * [memcached\_send\_timeout](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#memcached_send_timeout)
* [内嵌变量](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#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/模块参考/核心模块.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`

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

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

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

将请求传递给下一个服务器可能受到[尝试次数](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#grpc_next_upstream_tries)和[时间](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#grpc_next_upstream_timeout)的限制。

### memcached\_next\_upstream\_tries

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

限制尝试将请求传递到[下一个服务器](/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md#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;
```

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

### 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_memcached_module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.