Nginx外置缓存-redis2-nginx-module

一、引言：当Lua成为瓶颈，回归C层的必然选择

在《Nginx外置缓存》系列中，我们反复强调OpenResty + lua-resty-redis是生产环境对接Redis的首选方案。这个判断在95%的场景下成立，但剩下的5%恰恰是最极端的性能场景：

• API网关层纯透传缓存：无需任何业务逻辑，仅需GET/SET+TTL，LuaJIT的协程调度开销占比超过30%；
• 超高频计数器/限流：QPS > 50万，每次请求仅执行INCRBY，Lua层的函数调用和GC压力成为天花板；
• 嵌入式/Nginx精简部署：无法引入LuaJIT运行时（内存受限或安全合规要求），但仍需Redis缓存能力；
• 团队技术栈限制：运维团队不熟悉Lua，但精通Nginx C模块开发和配置指令。

这些场景的共同特征是：操作极度简单、调用频率极高、对延迟的容忍度以微秒计。此时，直接在Nginx C层通过原生模块对接Redis，省去Lua虚拟机的一切开销，成为唯一正解。

redis2-nginx-module正是为此而生。它不是ngx_http_redis_module的升级版，而是一个完整的RESP协议客户端实现，支持读写、Pipeline、连接池，且完全运行在Nginx事件循环中，零阻塞、零额外线程。本文将从协议原理、指令体系、生产配置到与Lua方案的选型边界，彻底讲透这个被低估的原生利器。

二、为什么不是 ngx_http_redis_module？

2.1 历史包袱与功能残缺

⚠️ 核心认知：ngx_http_redis_module是2008年为“从Redis读取预渲染HTML”设计的只读适配器，其协议实现甚至不符合现代RESP规范。在任何新项目中都不应再使用它。redis2-nginx-module才是Nginx原生Redis对接的事实标准。

2.2 与 lua-resty-redis 的本质区别

📌 选型铁律：能用指令解决的不用Lua，需要逻辑判断的不用原生模块。两者不是替代关系，而是不同抽象层级的工具。

三、核心指令体系详解

3.1 基础读写指令

1location /cache/get {
2    # ⭐ 声明Redis上游
3    redis2_pass 127.0.0.1:6379;
4    
5    # 构建RESP协议并发送
6    redis2_query get $arg_key;
7    
8    # 设置响应类型
9    default_type text/plain;
10}
11
12location /cache/set {
13    redis2_pass 127.0.0.1:6379;
14    
15    # SETEX key ttl value
16    redis2_query setex $arg_key $arg_ttl $request_body;
17    
18    default_type text/plain;
19}

3.2 Pipeline批量操作

这是redis2-nginx-module相比Lua方案的核心性能优势——多条命令在一次TCP往返中完成：

1location /cache/batch {
2    redis2_pass 127.0.0.1:6379;
3    
4    # ⭐ 多条query自动合并为Pipeline
5    redis2_query get $arg_k1;
6    redis2_query get $arg_k2;
7    redis2_query get $arg_k3;
8    
9    # 响应体包含多个RESP回复，需客户端自行解析
10    default_type application/octet-stream;
11}

⚠️ 注意：Pipeline模式下，响应体是原始RESP协议的拼接，不是JSON也不是纯文本。客户端必须具备RESP解析能力，或在Nginx层用header_filter_by_lua_block做格式转换（此时又引入了Lua，需权衡）。

3.3 连接池配置

1upstream redis_backend {
2    server 10.0.0.1:6379;
3    server 10.0.0.2:6379;
4    
5    # ⭐ 关键：keepalive连接池
6    keepalive 200;           # 每worker保持的空闲连接数
7    keepalive_timeout 10s;   # 空闲连接保活时间
8    keepalive_requests 1000; # 单连接最大请求数
9}
10
11server {
12    location /api/cache/ {
13        redis2_pass redis_backend;
14        redis2_query get $uri;
15        
16        # ⭐ 必须设置HTTP版本和清除Connection头
17        proxy_http_version 1.1;
18        proxy_set_header Connection "";
19    }
20}

📌 避坑：keepalive指令必须在server指令之后声明，否则不生效。同时proxy_http_version 1.1和Connection ""是keepalive生效的前提条件，缺一不可。

3.4 超时与错误处理

1location /cache/safe {
2    redis2_pass redis_backend;
3    
4    # 独立超时控制（毫秒级精度）
5    redis2_connect_timeout 100ms;
6    redis2_send_timeout 200ms;
7    redis2_read_timeout 200ms;
8    
9    redis2_query get $arg_key;
10    
11    # ⭐ 错误时返回自定义内容而非502
12    error_page 502 504 = @cache_fallback;
13}
14
15location @cache_fallback {
16    internal;
17    default_type application/json;
18    return 503 '{"error":"cache unavailable","fallback":true}';
19}

四、生产级配置模板

4.1 完整网关缓存层

1http {
2    upstream redis_pool {
3        least_conn;
4        server redis-01.internal:6379 max_fails=3 fail_timeout=10s;
5        server redis-02.internal:6379 max_fails=3 fail_timeout=10s;
6        server redis-03.internal:6379 max_fails=3 fail_timeout=10s;
7        
8        keepalive 150;
9        keepalive_timeout 15s;
10        keepalive_requests 500;
11    }
12
13    server {
14        listen 80;
15
16        # ===== 纯KV读取（零Lua）=====
17        location = /kv/get {
18            redis2_pass redis_pool;
19            redis2_connect_timeout 80ms;
20            redis2_read_timeout 150ms;
21            
22            redis2_query get $arg_k;
23            
24            default_type text/plain;
25            add_header X-Cache-Layer "native-redis" always;
26            
27            error_page 502 504 = @kv_miss;
28        }
29
30        # ===== KV写入（带TTL）=====
31        location = /kv/set {
32            limit_except POST { deny all; }
33            
34            redis2_pass redis_pool;
35            redis2_connect_timeout 80ms;
36            redis2_send_timeout 200ms;
37            
38            # 从Header读取TTL，默认300s
39            set $ttl $http_x_cache_ttl;
40            if ($ttl = '') { set $ttl 300; }
41            
42            redis2_query setex $arg_k $ttl $request_body;
43            
44            default_type text/plain;
45        }
46
47        # ===== 原子计数器（INCRBY）=====
48        location = /counter/incr {
49            redis2_pass redis_pool;
50            redis2_read_timeout 100ms;
51            
52            redis2_query incrby $arg_key $arg_delta;
53            
54            default_type text/plain;
55            add_header X-Counter-Type "atomic-native" always;
56        }
57
58        # ===== MISS降级 =====
59        location @kv_miss {
60            internal;
61            proxy_pass http://backend_service;
62            proxy_connect_timeout 3s;
63            proxy_read_timeout 5s;
64            add_header X-Cache-Degraded "redis-unavailable" always;
65        }
66    }
67}

4.2 配置要点解析

五、RESP协议响应处理

5.1 理解原生响应格式

redis2-nginx-module直接将Redis的RESP回复作为HTTP响应体输出，不做任何转换：

5.2 客户端适配策略

⚠️ 关键决策点：如果你的下游消费者无法解析RESP，那么在Nginx层加一层轻量Lua做格式转换是合理的。此时的性能损失远小于全程使用Lua处理缓存逻辑，因为只有响应格式化走Lua，Redis交互仍在C层完成。

5.3 判断MISS vs ERROR

1# 在header_filter中根据响应体首字符判断
2header_filter_by_lua_block {
3    local body = ngx.arg[1]
4    if body and body:sub(1, 3) == "$-1" then
5        ngx.header["X-Cache"] = "MISS"
6    elseif body and body:sub(1, 1) == "-" then
7        ngx.header["X-Cache"] = "ERROR"
8    else
9        ngx.header["X-Cache"] = "HIT"
10    end
11}

📌 注意：这仅在需要区分缓存状态时使用。若下游能自行解析RESP，则完全不需要Lua介入。

六、性能对比实测

6.1 测试环境

• Nginx: 8 workers, Intel Xeon Platinum 8369B
• Redis: 单节点, 同机房网络延迟0.05ms
• 压测工具: wrk, 64 connections, 10s duration
• 操作: 单KEY GET (1KB value)

6.2 结果

📌 结论：在纯KV读取场景下，redis2-nginx-module比Lua方案QPS高44%，P99低40%。差距随操作复杂度降低而扩大，随业务逻辑增加而缩小。

七、局限性与边界

7.1 不支持的场景

7.2 选型决策树

1你的缓存操作？
2├─ 纯GET/SET/INCR + 无条件分支 → redis2-nginx-module ✅
3├─ 需要Cluster/MOVED处理 → lua-resty-redis
4├─ 需要根据缓存结果做业务判断 → lua-resty-redis
5├─ 需要JSON/Protobuf序列化 → lua-resty-redis
6├─ QPS < 10万且有复杂逻辑 → lua-resty-redis
7└─ QPS > 30万且操作单一 → redis2-nginx-module ✅

📌 原则：redis2-nginx-module是手术刀，lua-resty-redis是瑞士军刀。不要用手术刀拧螺丝，也不要用瑞士军刀做眼科手术。

八、生产安全检查清单

九、常见踩坑速查表

十、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！

《Nginx外置缓存-redis2-nginx-module》 是转载文章，点击查看原文。