ngx_http_memcached_module模块概述

一、模块概述

• 模块名称：ngx_http_memcached_module

• 引入版本：0.7.21

• 功能：

  1. 根据 $memcached_key 向 Memcached 服务器发送 “get” 请求；
  2. 从 Memcached 读取响应并原样返回给客户端（包括头部与主体）；
  3. 在缓存未命中、超时或错误时，可自动回退到下游（next_upstream）或通过 error_page 跳转到备用后端。

• 应用场景：高性能缓存查询，如静态内容缓存、会话数据缓存、API 数据缓存等。

二、示例配置

http {
    upstream memcached_servers {
        server cache1.example.com:11211;
        server cache2.example.com:11211;
    }

    server {
        listen 80;
        server_name www.example.com;

        location / {
            # 1. 根据 URI 和查询参数生成缓存键
            set $memcached_key "$uri?$args";

            # 2. 将请求转发到 Memcached 后端
            memcached_pass   memcached_servers;

            # 3. 缓存未命中或错误时，回退到后端应用服务器
            error_page 404 502 504 = @fallback;
        }

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

三、主要指令详解

1. memcached_pass

Syntax:   memcached_pass <address|unix:socket|upstream_group>;
Context:  location, if in location
Default:  —

• 功能：指定要连接的 Memcached 服务器地址或上游组。

• 参数形式：

  • host:port
  • unix:/path/to/socket
  • 已定义的 upstream 组名

• 示例：

  memcached_pass localhost:11211;
  memcached_pass unix:/tmp/memcached.sock;
  memcached_pass memcached_servers;
  

• 负载均衡：当域名或 upstream 组包含多地址时，模块以轮询方式分发请求。

2. memcached_bind

Syntax:   memcached_bind <address> [transparent] | off;
Context:  http, server, location
Default:  —  
Since:    0.8.22  (`transparent` in 1.11.0, `off` in 1.3.12)

• 功能：为与 Memcached 后端的出连接指定本地源地址和（可选）端口。

• 参数：

  • <address>：本地 IP 地址（可含端口或变量）
  • transparent：使用原始客户端 IP（需要内核或特权支持）
  • off：取消继承的 memcached_bind，让系统自动分配本地地址/端口

• 示例：

  # 强制使用本地 192.168.0.10 作为源 IP
  memcached_bind 192.168.0.10:0;
  
  # 使用客户端原始 IP（需 root 或 CAP_NET_RAW）
  memcached_bind $remote_addr transparent;
  
  # 取消绑定，让系统自动选择
  memcached_bind off;
  

3. memcached_buffer_size

Syntax:   memcached_buffer_size <size>;
Context:  http, server, location
Default:  4k | 8k

• 功能：设置用于读取 Memcached 响应的缓冲区大小。
• 说明：缓存数据越大，可能需要更大缓冲区以避免分段读取。

4. memcached_connect_timeout

Syntax:   memcached_connect_timeout <time>;
Context:  http, server, location
Default:  60s

• 功能：建立到 Memcached 服务器的 TCP 连接时限（秒、毫秒等）。
• 注意：部分系统对 connect 超时时间上限约 75s。

5. memcached_send_timeout

Syntax:   memcached_send_timeout <time>;
Context:  http, server, location
Default:  60s

• 功能：向 Memcached 发送请求数据包时的写操作超时。
• 范围：超时限制为连续两次写操作之间的间隔，不是整个请求。

6. memcached_read_timeout

Syntax:   memcached_read_timeout <time>;
Context:  http, server, location
Default:  60s

• 功能：从 Memcached 读取响应时的读操作超时。
• 范围：限制两次读操作之间的最大等待时间。

7. memcached_socket_keepalive

Syntax:   memcached_socket_keepalive on | off;
Context:  http, server, location
Default:  off
Since:    1.15.6

• 功能：开启/关闭 TCP SO_KEEPALIVE 选项，以保持长连接。
• 用途：减少短连接建立开销。

8. memcached_gzip_flag

Syntax:   memcached_gzip_flag <flag>;
Context:  http, server, location
Default:  —
Since:    1.3.6

• 功能：检测 Memcached 存储时设置的标志位（一般由客户端写入时指定），
  若命中此标志，则在返回响应时自动添加 Content-Encoding: gzip 头。

• 示例：在存入时设定 flag=1，再通过：

  memcached_gzip_flag 1;
  

  让 Nginx 解读并设置压缩响应头。

9. memcached_next_upstream

Syntax:   memcached_next_upstream <error|timeout|invalid_response|not_found|off> [...];
Context:  http, server, location
Default:  error timeout

• 功能：指定哪些情况发生时，将请求失败后切换到下一台 Memcached 服务器或上游：

  • error：连接、写入、读 header 时发生错误
  • timeout：连接、写入、读取超时
  • invalid_response：收到空或格式不正确的响应
  • not_found：Memcached 返回 NOT_FOUND
  • off：禁用任何切换

• 说明：

  • 默认只在 error 与 timeout 时切换；
  • “无响应”或“键不存在”仅当显式配置时才切换；
  • 切换次数与时长可用下述指令进一步限制。

10. memcached_next_upstream_tries

Syntax:   memcached_next_upstream_tries <number>;
Context:  http, server, location
Default:  0 (不限制)
Since:    1.7.5

• 功能：限制最多可切换到下一台服务器的次数。

• 示例：

  memcached_next_upstream_tries 3;
  

11. memcached_next_upstream_timeout

Syntax:   memcached_next_upstream_timeout <time>;
Context:  http, server, location
Default:  0 (不限制)
Since:    1.7.5

• 功能：限制在多长时间内允许切换到下一台服务器。

• 示例：

  memcached_next_upstream_timeout 200ms;
  

四、嵌入变量

$memcached_key

• 用途：指定向 Memcached 查询的键（Key）。

• 典型写法：

  set $memcached_key "$uri?$args";
  

• 注意：必须在 memcached_pass 之前设置，且值不能为空，否则请求会被视作无效。

五、使用小贴士

1. 缓存预热

   • 必须在外部程序中事先将数据 set key value 写入 Memcached，否则首次请求会命中 404，然后触发 fallback 逻辑。

2. Key 设计

   • 为避免键冲突，应在 $memcached_key 中包含业务标识、Host、URI、Query 等信息。

3. 超时与重试

   • 根据后台集群网络状况适当调整 connect|send|read 超时与 next_upstream 策略，避免因单节点不可用导致全局挂起。

4. 长连接

   • 若后端支持，开启 memcached_socket_keepalive on 可显著减少频繁握手带来的性能损耗。

5. 压缩标志

   • 使用 memcached_gzip_flag，可让客户端透明获得已压缩内容的响应头，而无需 Nginx 再次压缩。

通过合理配置以上指令，ngx_http_memcached_module 能助力 Nginx 高效地将缓存层接入请求处理流程，实现超高性能的缓存查询与命中回退逻辑。