Nginx stream模块代理Redis实战：配置、TLS与避坑指南

1. 为什么要把Redis塞进Nginx的代理流——先想清楚动机再动手我碰到过不少团队明明Redis用得挺顺非要问一句“能不能用Nginx代理Redis”。这类问题第一次听会觉得奇怪Redis本身就是一套TCP服务客户端直连不就行了多一个Nginx在中间不是平白多一跳延迟吗但实际深入了解后你会发现在不少场景下Nginx代理Redis是个非常合理的选择解决的痛点直击日常运维的软肋。我印象最深的一次是给一套老系统做“入口收编”。当时内部环境里有好几套Redis实例有单机、有Sentinel高可用、还有一套Redis Cluster应用的配置文件里塞了十多个IP和端口每次环境迁移都要逐个改、逐个验证光理清连接关系就花了一个下午。后来我把Redis的访问入口统一收敛到Nginx做代理应用侧只需要知道一个固定端口。后端Redis怎么扩容、怎么迁移、怎么切换对客户端完全透明。这个改动做完之后配置下发的成本一下就降下来了。先说说Nginx代理Redis真正适用的三类场景。第一类是入口收敛和迁移透明。当Redis实例数量变多、拓扑变复杂时客户端不直连Redis而是统一走Nginx的代理端口后端可以随时调整Redis实例列表。客户端只认Nginx后端随便折腾这在实际运维中价值巨大。第二类是安全加固。Redis默认没有TLS加密原生协议在网络上就是明文如果跨机房、跨网络访问数据裸奔风险很高。把TLS终止放在Nginx层证书只需在Nginx上部署一套后端Redis可以继续跑明文省去在每一个客户端里配置证书的工作。同时IP白名单、连接数限制也可以在Nginx这一层集中做。第三类是访问审计与流量治理。通过Nginx的访问日志可以统一记录“谁在什么时间连了Redis、发了多少字节、连接了多久”。这个能力在合规审计场景里非常有用。不过这里有个关键点必须拎清楚Nginx代理Redis走的是四层流量转发也就是stream模块不是普通的HTTP反向代理。Redis基于TCP通信Nginx在传输层把来自客户端的字节流原封不动转发给后端Redis对Redis的RESP协议不做任何解析。这意味着无论你用的是GET、SET还是更复杂的Lua脚本、事务命令Nginx都当普通字节流处理不存在协议兼容性问题。也正因为不解析协议Nginx代理Redis的上限和边界都很清楚它只解决“连接入口”问题不解决“数据分布”问题。比如Redis Cluster客户端需要根据key做分片路由这个逻辑Nginx根本做不了必须靠客户端自己处理。所以Nginx代理Redis适合单实例入口收敛、主从读负载、TLS终止这类场景不适合把Nginx当作Redis Cluster的统一智能路由。如果你现在的Redis规模就是三五台、应用也不复杂客户端直连完全够用那你其实不需要引入Nginx。多一层代理就多一个故障点这个道理在任何架构里都成立。我推荐Nginx代理Redis前提是你真的遇到了入口分散、迁移频繁、安全管控缺失这些具体问题而不是为了“用Nginx”而用Nginx。2. 准备阶段确认stream模块就位别到配置报错才后悔Nginx的stream模块从1.9.0版本开始正式引入用于TCP和UDP协议的四层代理。绝大多数通过官方源或者发行版编译安装的Nginx会自带这个模块但确实存在部分精简编译的二进制不带stream模块配置加载时会直接报“unknown directive stream”错误。所以动手之前先花两分钟确认模块状态能省掉后面排查的一次折腾。2.1 检查Nginx编译参数在服务器上执行nginx -V 21 | grep -- --with-stream如果Nginx已经加入系统服务也可以替换成nginx -V 21 | tr \n | grep stream来单独过滤。我习惯用前一种方式一次能看到完整编译参数。命令有输出说明当前Nginx支持stream模块可以直接进入配置阶段。没有输出的话就需要重新编译或者换一个带stream模块的发行版Nginx包。这里多说一句如果你用的是线上生产环境我不建议为了这个功能单独替换系统Nginx风险太大。更稳妥的方式是用源码编译一个独立目录的Nginx或者通过容器方式把Nginx跑起来把代理能力隔离在一个独立实例里。2.2 没有stream模块时的补救方案源码编译其实不复杂只需要在configure时加上对应参数./configure \ --prefix/usr/local/nginx \ --with-stream \ --with-stream_ssl_module \ --with-stream_realip_module \ --with-stream_ssl_preread_module编译依赖需要gcc、make、libpcre3-dev、libssl-dev、zlib1g-dev这些在大多数Linux发行版里都能通过包管理器一次装齐。如果你是Ubuntu/Debian系统编译前先执行apt-get update apt-get install -y gcc make libpcre3-dev libssl-dev zlib1g-dev在CentOS/RHEL上则是yum install -y gcc make pcre-devel openssl-devel zlib-devel。编译参数里我特别标注了--with-stream_ssl_module这个模块是做TLS终止时必需的。如果你只是做纯TCP转发不打算加TLS那么--with-stream就够用但我的建议是既然编译一次就把SSL能力一起编上后续要升级配置就不用再折腾一次Nginx了。2.3 目录规划stream配置和http配置分开很多人的Nginx配置文件是单一nginx.conf把http块、server块全塞在一起。如果你的Nginx同时承载HTTP反向代理和TCP流代理我强烈建议把stream的配置独立出来维护的时候会清晰很多。在nginx.conf的主配置里加上stream { include /etc/nginx/stream.d/*.conf; }然后在/etc/nginx/stream.d/下新建Redis代理的相关配置文件。这样http块和stream块互不干扰哪个出问题可以快速定位。stream块和http块是同一层级的不是包含关系千万别把stream配置写在http块里面这个问题我见过不止一次配置一加载就报错。3. 核心配置样板stream块里的Redis代理长什么样配置Redis代理最核心的就是一组upstream和一个server监听块。我直接给出一份我常用的配置然后逐项拆解关键参数。3.1 一份可以直接抄的配置stream { log_format proxy $remote_addr [$time_local] $protocol $status $bytes_sent $bytes_received $session_time; upstream redis_backend { server 127.0.0.1:6379; keepalive 32; } server { listen 16379; proxy_pass redis_backend; proxy_connect_timeout 5s; proxy_timeout 300s; access_log /var/log/nginx/redis_access.log proxy; } }这份配置做了几件事定义了一个名为redis_backend的上游服务器组指向本机的Redis服务端口6379在16379端口监听外部连接将收到的TCP连接转发到Redis同时记录访问日志。配置里的keepalive 32值得单独说明它指的是Nginx与后端Redis之间保持的空闲连接数上限注意不是最大连接数。Nginx会把这批连接缓存下来下次再有客户端需要访问Redis时直接复用空闲连接省去一次TCP握手。这个参数在高并发场景下能明显降低连接建立的开销。3.2 监听端口的选择不一定要用6379配置里我用了listen 16379而不是直接复用Redis默认的6379。理由主要有两点一是如果Nginx和Redis部署在同一台机器上监听6379会跟本机Redis端口冲突二是一个相对独立的代理端口能让你通过简单的端口映射关系一眼就知道流量走向。内网环境没有强制的端口规范时我习惯用“原端口10000”的方式Redis是6379代理入口就是16379好记也好排查。如果你的场景里Nginx和Redis完全分离Nginx可以独占6379端口那直接listen 6379也完全可以客户端原来的端口都不用改配置切换的侵入性更低。3.3 为什么不直接proxy_pass到IP而是用upstream直接写proxy_pass 127.0.0.1:6379也能跑但我几乎不用这种写法。原因很简单upstream把后端地址抽象出来了以后Redis换个IP、加一台机器只需要改upstream里的server列表配置的可维护性完全不一样。举个例子如果Redis要做一主一从的读写分离读流量可以均衡到从库你可以在upstream里写两个serverupstream redis_backend { server 192.168.1.10:6379; server 192.168.1.11:6379; keepalive 32; }默认的调度策略是轮询两个后端各分一半连接。但这里又一个坑我必须提前讲清楚这个负载均衡只说了连接层面的事它不区分Redis命令是读还是写。如果你的应用访问Redis时读多写少并且能容忍一些请求落到从库读到稍微旧一点的副本那可以这么干但如果写操作比较多一定要保证所有写命令只会到master那这个简单配置就不能直接用需要把写入口单独指向master或者用额外的代理层做读写区分。四层转发不解析Redis协议这是它高效的原因也是很多高级策略没法在Nginx直接做的原因。3.4 超时参数怎么设置才合理配置里有两个超时参数职责完全不同。proxy_connect_timeout是Nginx与后端Redis建立TCP连接的超时时间默认60秒这个值在绝大多数情况下太长。我习惯设置为5秒如果Redis连不上5秒就应该快速失败并返回给客户端错误而不是让客户端在那里干等一分钟。proxy_timeout是两个相邻操作之间空闲连接的超时时间。如果客户端与Redis之间没有任何数据交互超过这个时间Nginx会主动断开连接。Redis服务端默认的空闲超时是0也就是不主动断开所以很多人在实际使用中会把这个参数忽略。但我的建议是不要设成0一个长时间挂着的空闲TCP连接对两端都没好处白白占着文件描述符。300秒是一个比较常见的折中值既不会频繁断开正常应用的空闲连接又能及时回收废弃连接。配置完成后执行nginx -t nginx -s reloadnginx -t是检查配置文件语法的这一步必须养成习惯别直接reload。语法检查通过后reloadNginx会平滑加载新配置不会中断现有连接。验证代理是否生效用Redis自带的命令行工具redis-cli -p 16379 ping返回PONG说明链路已经通了。4. 进阶加固TLS终止、访问控制和连接数限制基础转发跑通这只是第一步。把Redis代理放到生产环境至少还要做三件事TLS加密、IP访问控制、连接数限制。这三件事在安全水位比较高的内网环境里几乎都是默认要求。4.1 用TLS终止给Redis链路加一把锁Redis原生协议本身是明文设计Redis自带的TLS支持需要从6.0版本开始而且需要在服务端配置证书客户端也要跟着适配。如果你有很多历史客户端逐个改起来成本很高。通过Nginx做TLS终止可以把“加密”这件事收敛到一个点上客户端与Nginx之间走TLSNginx与后端Redis之间走明文。这样客户端只需要支持TLS连接服务端Redis完全不用动。先用OpenSSL生成一张自签证书mkdir -p /etc/nginx/ssl openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout /etc/nginx/ssl/redis.key \ -out /etc/nginx/ssl/redis.crt \ -subj /CNredis.internal然后在stream配置里加上SSL相关指令server { listen 16379 ssl; ssl_protocols TLSv1.2 TLSv1.3; ssl_certificate /etc/nginx/ssl/redis.crt; ssl_certificate_key /etc/nginx/ssl/redis.key; proxy_pass redis_backend; proxy_connect_timeout 5s; proxy_timeout 300s; }这里listen 16379 ssl的语法和HTTP配置是一样的但注意这是在stream块里Nginx编译时需要带--with-stream_ssl_module。配置完善后客户端连接方式要跟着调整。如果你的客户端是redis-cli6.0以上版本支持TLSredis-cli --tls -p 16379 -a yourpassword pingJava的Lettuce客户端连接串加上rediss://前缀并在客户端侧信任这张自签证书。这里有个比较容易踩的坑自签证书在Java环境里默认不被信任如果只是把rediss://的host和port改掉客户端会直接报SSLHandshakeException。解决方法是把redis.crt导入客户端的truststore或者配置证书信任策略。TLS终止放Nginx层意味着Nginx与Redis之间的明文链路只存在于可信网络内部。如果是跨机房、跨安全域的网络这条明文链路同样暴露在你不可控的网络上那就需要在Nginx到Redis这一段也启用TLS。stream模块同样支持proxy_ssl等指令配置思路上是对称的只是需要Redis服务端也配置证书。实际生产环境里我自己更倾向于把TLS端点放在离Redis足够近的位置确保明文链路不出安全边界。4.2 用allow/deny做IP白名单Redis默认绑定内网网卡还好如果绑定地址是0.0.0.0且没有开密码认证那几乎就是在内网裸奔。通过在Nginx的stream配置里做IP白名单可以把风险挡在第一道门外。server { listen 16379 ssl; allow 192.168.1.0/24; allow 10.0.0.1; deny all; proxy_pass redis_backend; }allow和deny在stream模块里是逐条匹配、顺序敏感的。先匹配到的规则优先生效。上面的配置里192.168.1.0这个网段和10.0.0.1这个具体IP被允许其他所有客户端连接都会被Nginx拒绝甚至不会转发到后端Redis。这个控制粒度对大多数场景够用了。如果要做更细粒度的基于用户身份的鉴权那是另一个层面的事情Nginx四层代理做不了需要在应用层或Redis本身解决。4.3 连接数限制防止单客户端打满Redis另外一个容易被忽视的安全风险是连接数过多。Redis虽然是单线程模型处理命令极快但每多一个TCP连接Redis就要多维护一个客户端对象连接数一多照样能把Redis拖垮。在Nginx这层做连接数限制配置方式和HTTP模块类似stream { limit_conn_zone $binary_remote_addr zoneredis_conn:10m; server { listen 16379 ssl; limit_conn redis_conn 50; proxy_pass redis_backend; } }这段配置的含义是同一个客户端IP与Nginx之间的并发连接数最多50个超出部分会被拒绝。limit_conn_zone里的10m是共享内存的大小按每个IP状态占几十字节估算10M足够容纳几十万个IP的记录普通内网场景绰绰有余。连接数限制的实际意义在于万一某个应用因为Bug疯狂重连Redis或者某个IP段的客户端异常耗尽了文件描述符Nginx会先一步把恶意流量挡下来不会让异常直接传导到Redis。这对Redis的保护作用非常明显我在实际运维中断言很多Redis连接数打满的事故都能在Nginx这一层被化解。5. 真实环境踩坑keepalive、主从切换与健康检查的边界配置文档不会告诉你的是跑了一段时间之后你会遇到一些只有在真实流量下才会暴露的问题。我把踩过的坑整理成三条基本覆盖了Nginx代理Redis最常见的问题面。5.1 keepalive连接池Redis重启后客户端报错先说一个让我印象深刻的场景。某天线上突然有一批应用报Redis连接异常错误信息指向连接被重置。Redis服务本身没挂监控面板一切正常。后来排查发现问题出在Nginx的keepalive 32这个配置上。原理是这样的Nginx会维护一批到后端Redis的空闲连接客户端来了就复用。Redis一旦重启它维护的所有TCP连接都会失效。这时候Nginx连接池里缓存的空闲连接其实是已经断开的“僵尸连接”复用这些连接去发Redis命令Redis内核直接返回RST客户端就收到连接重置异常。这个问题本身不大但排查起来隐蔽性很强。我的处理办法是能不用keepalive就先不用或者把keepalive调到一个比较小的值。对于Redis这种高频短连接的场景TCP握手的开销远小于业务请求本身的开销省掉一次握手带来的收益相比连接失效带来的故障复杂度在我这里是不划算的。如果业务场景确实需要高并发短连接复用那么前提是你有完善的客户端重连机制以及运维层面的连接巡检而不是丢给keepalive自动处理。顺便说一句Redis服务端自身的空闲超时配置也值得关注。很多Redis实例的timeout参数保持默认的0也就是空闲连接永不超时。如果你同时设置了Nginx的keepalive和Redis的timeout 0一条空闲连接会一直存在一旦Redis重启大量僵尸连接会让Nginx的日志瞬间刷屏。把Redis的timeout设成一个较小的值比如300秒能自动清理空闲连接降低僵尸连接带来的影响。5.2 Sentinel主从切换后Nginx还在往旧master转发这是个更大的坑也是最容易被忽略的架构性矛盾。Redis Sentinel负责监控Redis主从状态在master宕机后自动选举新的master。Sentinel的故障转移机制本身很成熟但Nginx的upstream完全不感知这个变化。你的upstream里写着server 192.168.1.10:6379Sentinel把master切到了192.168.1.11Nginx仍然按照旧配置把客户端流量转发到192.168.1.10。此时旧master已经降级为从库读写命令的行为就变得非常诡异写命令直接失败。这个问题的根源在于Sentinel的故障转移是Redis生态内的机制Nginx作为一个纯四层代理既看不懂Redis协议也不参与Sentinel选主两边是割裂的。我见过的可行处理方案有三种。第一种在Sentinel完成切换后手动修改Nginx的upstream配置并reload。这个方案要求运维响应及时适合故障频率极低、有专人盯着的环境。第二种把Nginx的upstream指向一个固定的域名域名解析由内部的DNS系统维护。Sentinel切换后DNS记录自动更新Nginx在解析域名时就能拿到新的master地址。这个方案要求你的DNS系统支持自动化更新而且Nginx每次建立新连接都要做DNS解析连接性能会有一些损耗。第三种也是最符合直觉的如果应用本身就在用Sentinel不如让客户端直接对接Sentinel获取master地址不要在这个链路里强行插入Nginx。Nginx适合的是“应用不关心后端Redis拓扑只认固定入口”的场景不适合“后端已经引入了Sentinel这种故障转移机制”的场景。这两种架构思路在本质上是冲突的非要把它们叠加在一起只会增加维护成本。从这个角度回头看Nginx代理Redis的价值你会发现它的适用范围其实很明确后端拓扑相对稳定不需要自动故障转移机制的场景Nginx代理能带来很好的入口管理和安全加固如果后端已经开始用Sentinel或Cluster那说明你的架构复杂度已经超过了四层代理能够承载的范围还是让客户端直连或者使用更专业的中间件产品更靠谱。5.3 健康检查的“看似有、实际无”很多人会以为Nginx配置了多个后端Redis当一个不可用时Nginx会自动把流量切换到另一个健康的后端上。这个想法在四层转发的语境下是个很大的误区。开源版的stream模块没有主动健康检查能力。所谓主动健康检查是Nginx周期性地向后端发送探测协议确认后端是否存活这是Nginx Plus商业版才有的能力。开源版默认的“健康检查”只能做到这一步Nginx在建立到后端的连接时如果发现连接失败会尝试下一个后端。但问题在于TCP连接建立成功并不代表Redis进程就真的健康。Redis进程可以正常接受TCP连接但内部状态已经异常比如OOM、阻塞、主从数据差异过大这些情况在四层转发层面完全看不出来。Nginx只知道连接建立成功了然后把字节流丢过去Redis返回什么它就转什么客户端能不能用取决于Redis自身的状态。这意味着什么如果你指望Nginx能在Redis宕机或者主从切换时自动做流量切换那大概率会失望。Redis的高可用保障要靠Redis自己的机制而不是Nginx。Nginx在这套架构里更适合当“流量入口的看门人”而不是“Redis状态的裁判”。把这些坑汇总一下方便大家对照问题根因处理方向Redis重启后客户端连接报错keepalive连接池缓存的僵尸连接被复用调小或关闭keepaliveRedis侧设置空闲超时Redis主从切换后写失败Nginx不感知Sentinel选主结果手动reload、DNS动态解析或客户端直连后端Redis状态异常但Nginx不摘除stream模块无主动健康检查依赖Redis主从/哨兵机制保障Nginx只做转发6. 可观测性验证从redis-cli到tcpdump的完整核对配置全部写完不能只是“能ping通”就算完工。要确认流量真的是按你设想的路径在走必须做完整的链路核对。这一节我按自己的排查习惯从外到内把验证过程整理一遍。6.1 先把stream访问日志打开默认情况下stream模块的access_log是关闭的你需要在配置里显式打开。前面我的示例配置里已经写了一段log_format proxy可以按照自己的需要调整字段。常用的几个变量是$remote_addr客户端IP$protocol使用的协议TCP或UDP$status会话状态码200表示正常$bytes_sentNginx发送给客户端的字节数$bytes_receivedNginx从客户端接收的字节数$session_time会话持续时间单位秒然后指定日志路径access_log /var/log/nginx/redis_access.log proxy;打开日志后每次客户端通过Nginx访问Redis都会在日志里留下一条记录。这在平时看起来只是多了一行日志到了排查问题时就是救命稻草你能准确地知道哪些客户端在什么时候访问了Redis、实际传输了多大的流量、一个连接维持了多久。相比在Redis端抓客户端连接Nginx日志的语义更清晰因为它是真正的入口记录。6.2 用redis-cli验证代理转发验证命令本身很简单redis-cli -p 16379 ping返回PONG之后立刻去看Nginx访问日志确认记录生成。这条记录中有客户端IP、会话时长以及200的会话状态。如果你配置了TLS记得在redis-cli命令里加上--tls参数。如果你的Redis设置了密码认证客户端需要通过代理做AUTHredis-cli -p 16379 -a yourpassword ping这里有个重要的细节Nginx只是做字节流转发它不会替你去掉或者处理AUTH指令。AUTH命令会原样透传给后端Redis后端Redis校验通过才返回PONG。所以如果代理配置没问题但客户端一直认证失败那么问题大概率出在Redis本身的密码配置上跟Nginx无关。6.3 用tcpdump确认完整转发路径redis-cli ping通了只证明客户端能连上Nginx并且拿到PONG响应但中间到底发生了什么用抓包看得最清楚。在Nginx服务器上执行tcpdump -i any -nn port 6379这条命令抓取所有经过Nginx、目标端口为6379的流量。然后再开一个终端执行redis-cli -p 16379 ping观察抓包结果。你会看到两个连接的完整数据包一个是客户端与Nginx之间的TLS加密流量如果配了TLS这里看到的是加密后的数据另一个是Nginx在空闲连接池里取出连接或者新建连接与后端Redis之间的明文TCP流量。这两个连接的存在从包层面证明了Nginx确实做了四层转发并且在你启用了TLS时确认明文流量只存在于Nginx与Redis之间。这种验证方式在排障时特别有用。比如客户端报“连接超时”你一看tcpdump发现数据包根本没到Nginx那就说明是网络链路或者防火墙的问题而不是Nginx和Redis配置的问题。把问题边界分清楚排障速度会快很多。6.4 顺带看一眼性能影响最后一个大家都会关心的问题Nginx代理Redis到底会带来多少性能损耗从原理上讲四层转发就三件事内核收到数据包、Nginx在用户态拷贝一次、内核再发给另一端的Socket。相比七层HTTP反向代理要做完整的HTTP协议解析四层转发的开销非常小。我在一台2核4G的虚拟机上做过一次简单的压力验证客户端使用redis-benchmark开启100个并发连接每个连接连续执行GET命令Nginx的CPU占用率大概在5%到8%之间波动延迟比直连Redis增加了不到1毫秒。这个量级对于绝大多数业务场景完全可以忽略。但性能不是只看CPU。连接数才是四层代理最容易撞到的资源瓶颈。每个TCP连接都要占用文件描述符Nginx的worker_connections参数直接决定了可以维护的连接数上限。如果客户端特别多比如上千个应用实例同时连过来你需要提前把这些参数调大同时检查系统的ulimit -n限制。否则不是CPU扛不住而是文件描述符耗尽导致的新连接无法建立。worker_processes auto; worker_rlimit_nofile 65535; events { worker_connections 2048; }worker_rlimit_nofile 65535提高worker进程能打开的文件描述符上限worker_connections 2048表示每个worker能同时维护2048个连接。在高连接数场景下这两个参数几乎必须调大否则服务会半死不活地卡在那里。我在实际使用中最深刻的体会是Nginx做Redis代理技术上难点不多真正拉开差距的是对边界条件的理解。你知道它最多只是做字节流转发就不会指望它能智能分流Redis协议你知道它不参与Sentinel选主就会提前想好主从切换时的应对预案。想清楚这些边界Nginx代理Redis这套方案就是一套又轻又稳的基础设施能安静地帮你把入口管好不添乱。