Nginx Stream模块实现数据库端口转发：原理、配置与生产实践

Nginx Stream模块实现数据库端口转发：原理、配置与生产实践

发布时间：2026/8/22 3:16:45
Nginx Stream模块实现数据库端口转发：原理、配置与生产实践 1. 项目概述为什么用Nginx做数据库端口转发最近在搞一个内部系统的架构调整遇到一个挺典型的场景开发、测试、运维团队都需要访问同一个MySQL数据库但出于安全考虑数据库服务器本身只允许内网特定IP段访问。直接开放公网端口风险太大用传统的堡垒机跳转又觉得太重每次操作都麻烦。这时候一个轻量、稳定、配置灵活的端口转发方案就成了刚需。我第一时间就想到了Nginx。很多人对Nginx的印象还停留在“高性能Web服务器”或“反向代理”其实它的stream模块从1.9.0版本开始就支持四层TCP/UDP的代理和负载均衡用来做数据库端口转发简直是“杀鸡用牛刀”——大材小用但异常顺手。相比于直接用iptables做DNAT或者写个简单的socat脚本Nginx的方案有几个无法拒绝的优势配置集中管理、支持负载均衡和健康检查对于读写分离或集群场景、能集成SSL/TLS加密虽然数据库通常自带加密但Nginx可以额外做一层SSL终端或透传最关键的是Nginx本身的高并发、低内存占用特性让它作为流量中转层非常可靠几乎不会成为瓶颈。这个方案特别适合哪些人呢如果你正在处理以下问题那这篇笔记可能就是为你写的需要安全地对外暴露数据库服务如从公网访问内网RDS、想对数据库连接做统一的入口管理和访问控制、需要在数据库前做简单的流量分发、或者只是想找一个比iptables更易维护的端口转发工具。接下来我会拆解整个配置过程从原理到实操再到踩坑记录手把手带你走一遍。2. 核心思路与方案选型考量2.1 为什么是Nginx而不是其他方案在做技术选型时我们通常会对比几种常见方案。针对“数据库端口转发”这个需求我简单列了个对比方案优点缺点适用场景Nginx (stream模块)配置灵活、支持负载均衡与健康检查、性能极高、日志完善、可与HTTP服务共存需要编译或确认包含stream模块、配置语法需要学习生产环境首选尤其需要高并发、负载均衡或复杂路由时iptables (DNAT)Linux内核自带无需额外安装、零额外进程开销、性能极佳配置分散不易管理、无负载均衡能力、调试复杂、规则多时影响性能简单的、临时的端口映射对运维人员Linux网络知识要求高socat单一二进制文件极度轻量、配置简单一行命令功能单一仅转发、无负载均衡、进程监控需额外配置如systemd快速测试、临时调试或资源极度受限的环境HAProxy专为代理和负载均衡设计功能强大如精细的健康检查、ACL专门用途若只为端口转发则稍显重量需要极其复杂的四层/七层代理规则和监控的场景SSH隧道无需在服务器端安装额外软件、加密隧道天然安全连接稳定性依赖SSH会话、性能开销较大、不适合高并发生产流量开发人员临时从本地连接内网数据库进行调试对于大多数生产环境尤其是已经部署了Nginx作为Web服务器的场景启用其stream模块来做数据库端口转发是性价比最高的选择。它复用现有基础设施统一了运维监控界面日志、进程管理并且其事件驱动模型处理大量持久化的数据库长连接如MySQL游刃有余。2.2 Nginx Stream模块工作原理浅析理解原理能帮你更好地配置和排错。Nginx的HTTP反向代理处理的是应用层七层协议它需要解析HTTP头部能根据Host、URL等做复杂的路由。而stream模块工作在传输层四层它不解析应用层协议内容只是单纯地在客户端和后端服务器之间转发TCP或UDP数据包。你可以把它想象成一个高效的“数据搬运工”客户端向Nginx服务器的某个端口如13306发起TCP连接Nginx的stream模块接受这个连接然后根据配置代表客户端向真正的数据库服务器如192.168.1.100:3306建立另一个TCP连接。此后所有来自客户端的数据包都会被Nginx原封不动地转发给后端数据库反之数据库的响应包也通过Nginx传回客户端。对于客户端和数据库来说它们都只感知到在和Nginx通信实现了网络的隔离和转发。注意正因为是四层转发Nginx无法像HTTP代理那样根据数据库协议内容如SQL语句做路由或过滤。它转发的是原始的TCP流。这也意味着如果你需要基于数据库用户名或库名做路由需要在Nginx这一层之上使用能解析MySQL或PostgreSQL协议的特殊代理如ProxySQL或者使用Nginx的七层代理需要对应的协议模块但通常不推荐用于生产数据库流量。3. 环境准备与Nginx配置要点3.1 确认与安装Nginx Stream模块首先你需要一个支持stream模块的Nginx。大多数现代Linux发行版的官方仓库或EPEL仓库中的Nginx包都默认包含了此模块。你可以通过以下命令验证nginx -V 21 | grep -o with-stream如果输出with-stream则说明已支持。如果没有你可能需要从源码编译。这里以CentOS/RHEL系列通过官方仓库安装为例# 添加Nginx官方仓库如果尚未添加 sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://nginx.org/packages/centos/$releasever/$basearch/ # 安装Nginx sudo yum install -y nginx # 验证stream模块 nginx -V 21 | grep stream对于Ubuntu/Debian系列过程类似使用apt命令即可。安装后关键的配置文件有两个主配置文件/etc/nginx/nginx.conf和流配置/etc/nginx/stream.conf或者包含在conf.d/目录下的*.conf文件。3.2 核心配置解析与编写Nginx的stream配置与http配置块是平级的。我建议在/etc/nginx/nginx.conf的http块之外单独配置stream块。这样逻辑更清晰。打开/etc/nginx/nginx.conf在文件末尾http块之后或文件内合适位置添加如下配置# /etc/nginx/nginx.conf # ... 其他全局配置 ... events { worker_connections 1024; # 根据需要调整处理数据库长连接可以设高些 } http { # ... 你的HTTP服务配置 ... } # 关键Stream模块配置块 stream { # 定义一个上游服务器组名为 mysql_backend upstream mysql_backend { # 如果有多台数据库服务器可以在这里配置负载均衡 server 192.168.1.100:3306 weight1 max_fails3 fail_timeout30s; # server 192.168.1.101:3306 weight1; # 第二台示例 } # 定义一个TCP服务器监听13306端口并代理到上游组 server { listen 13306 so_keepaliveon; # 监听端口开启TCP keepalive proxy_pass mysql_backend; # 转发到上游组 proxy_connect_timeout 10s; # 连接后端超时时间 proxy_timeout 24h; # 非常重要数据库连接通常是长连接超时时间要设得非常长 # 可选的缓冲设置对于大查询结果可能有用但通常数据库连接不建议开缓冲 # proxy_buffer_size 16k; # 日志配置可选但强烈建议开启用于排错 access_log /var/log/nginx/mysql-access.log stream_log; error_log /var/log/nginx/mysql-error.log; } # 你可以配置多个server块转发不同的端口到不同的后端服务 # server { # listen 15432; # proxy_pass 192.168.1.200:5432; # 直接转发到PostgreSQL # proxy_timeout 24h; # } }配置逐行解读与避坑指南upstream块定义后端服务器池。即使你只有一台数据库用upstream定义也是一个好习惯为未来扩展留有余地。max_fails和fail_timeout参数用于简单的健康检查如果Nginx在fail_timeout时间内连接该服务器失败max_fails次则会暂时将其标记为不可用。server块中的listen13306是Nginx对外暴露的端口。so_keepaliveon启用了TCP层的keepalive有助于保持连接活性减少因网络空闲断开导致的问题。proxy_timeout 24h;这是最关键的参数之一数据库连接如MySQL一旦建立可能会持续数小时甚至数天。如果这个值设置过小比如默认的10分钟Nginx会在超时后主动断开与客户端的连接导致应用端报“连接丢失”错误。根据你的业务场景可以设置为24h24小时甚至更长。如果知道连接池最大空闲时间可以设置得比那个时间稍长。proxy_buffer_size对于数据库流量通常不建议开启或设置很大的缓冲。因为Nginx的缓冲会引入额外的内存拷贝和延迟。数据库协议通常是“一问一答”的让数据尽快透传是最佳实践。除非你遇到特定的内存或流量整形问题否则可以忽略此配置。日志单独指定stream模块的访问日志和错误日志便于排查问题。stream_log是一个预定义的日志格式你也可以用log_format在stream块外自定义格式。3.3 权限、SELinux与防火墙配置配置写好了启动前还有三道“安全门”需要检查。第一道Nginx用户权限。Nginx进程通常是nginx或www-data用户需要有权限绑定到你所监听的端口如13306。1024以下的端口需要root权限我们用的13306没问题。确保Nginx进程用户存在。第二道SELinux仅限RHEL/CentOS。SELinux可能会阻止Nginx绑定非标准HTTP端口或发起网络连接。你可以选择临时关闭SELinux生产环境不推荐或者为其添加正确的策略# 查看SELinux是否阻止 sudo tail -f /var/log/audit/audit.log | grep nginx # 如果看到avc denied错误需要添加策略 # 允许Nginx连接到任何网络端口 sudo setsebool -P nginx_can_network_connect 1 # 允许Nginx绑定到非标准端口如13306 sudo semanage port -a -t http_port_t -p tcp 13306第三道防火墙。确保你的系统防火墙如firewalld或iptables开放了13306端口的入站流量。# 使用firewalld (CentOS 7/8, RHEL) sudo firewall-cmd --permanent --add-port13306/tcp sudo firewall-cmd --reload # 使用ufw (Ubuntu) sudo ufw allow 13306/tcp sudo ufw reload4. 完整实操流程与验证4.1 启动服务与加载配置完成所有配置和系统设置后按顺序执行以下命令# 1. 测试配置文件语法是否正确 sudo nginx -t -c /etc/nginx/nginx.conf # 你应该看到类似输出nginx: configuration file /etc/nginx/nginx.conf test is successful # 2. 重新加载或启动Nginx # 如果Nginx已在运行重新加载配置平滑重启不影响现有连接 sudo systemctl reload nginx # 或者 sudo nginx -s reload # 如果Nginx未运行则启动它 sudo systemctl start nginx sudo systemctl enable nginx # 设置开机自启 # 3. 检查Nginx进程和端口监听状态 sudo systemctl status nginx sudo ss -tlnp | grep nginx # 你应该能看到nginx进程正在监听13306端口4.2 多维度连接测试配置是否生效需要用多种方式测试。测试1从服务器本地测试端口连通性# 使用telnet或nc测试端口是否开放 telnet 127.0.0.1 13306 # 或者 nc -zv 127.0.0.1 13306 # 如果成功你会看到“Connected to 127.0.0.1”或“succeeded!”的提示。 # 对于MySQL端口开放后连接会立刻建立然后等待客户端发送握手包。如果很快断开可能是后端数据库连接有问题。测试2使用MySQL客户端通过Nginx连接这是最直接的验证。在另一台可以访问Nginx服务器的机器上比如你的开发电脑使用MySQL客户端连接。mysql -h [Nginx服务器的IP地址] -P 13306 -u [数据库用户名] -p连接成功后执行一个简单查询SHOW DATABASES; SELECT hostname; -- 如果你后端是数据库集群这个命令可以帮你确认连接到了哪台具体的服务器测试3验证负载均衡如果配置了多个后端如果你在upstream中配置了多台数据库服务器可以通过多次连接并查询hostname或服务器唯一标识来观察Nginx是否按预期分发连接。默认是轮询round-robin算法。4.3 监控与日志分析运行起来后监控是保证稳定性的关键。查看Stream专属日志sudo tail -f /var/log/nginx/mysql-access.log sudo tail -f /var/log/nginx/mysql-error.log访问日志会记录每个连接的建立和关闭时间、客户端IP、后端服务器IP等信息。错误日志会记录连接失败等异常。监控Nginx状态可以使用nginx-module-vts等第三方模块来监控stream模块的连接数、流量等指标集成到PrometheusGrafana中。监控系统资源使用top、htop或nmon工具观察Nginx进程的CPU和内存占用。对于纯转发开销通常极低。5. 高级配置与性能调优基础转发搞定后我们可以看一些能提升安全性、可靠性和性能的高级配置。5.1 访问控制与安全增强默认配置下任何能连接到Nginx服务器13306端口的客户端都能尝试转发到数据库。我们可以通过allow和deny指令进行简单的IP过滤。stream { upstream mysql_backend { server 192.168.1.100:3306; } server { listen 13306; # 只允许特定IP段访问 allow 10.0.0.0/8; allow 172.16.0.0/12; deny all; # 拒绝所有其他IP proxy_pass mysql_backend; proxy_timeout 24h; } }注意stream模块的访问控制是连接级别的即在TCP握手阶段进行判断。它比应用层如MySQL的权限系统更早可以作为第一道安全防线。但对于更复杂的安全需求如基于证书的认证需要结合SSL代理或使用专门的数据库防火墙。5.2 SSL/TLS终端与透传如果你的客户端到Nginx或者Nginx到数据库的链路需要加密可以配置SSL。场景A客户端到Nginx加密SSL Termination。客户端使用SSL连接NginxNginx解密后以明文方式连接后端数据库。这减轻了数据库的加密计算压力。stream { upstream mysql_backend { server 192.168.1.100:3306; } server { listen 13307 ssl; # 监听SSL端口 ssl_certificate /etc/nginx/ssl/nginx.crt; ssl_certificate_key /etc/nginx/ssl/nginx.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; proxy_pass mysql_backend; proxy_timeout 24h; } }客户端连接时需要使用mysql --ssl-modeREQUIRED -h ... -P 13307。场景BNginx到数据库加密SSL Passthrough。Nginx不解密只是将加密的TCP流原样转发给支持SSL的后端数据库。这种配置在Nginx中比较复杂通常需要将proxy_ssl参数设置为on并配置相关证书。但更常见的做法是在数据库端强制SSL然后Nginx只做纯四层转发让客户端和数据库直接完成SSL握手前提是客户端支持并配置了SSL。stream模块本身对SSL透传的支持是有限的。5.3 连接池与超时参数精细调优数据库连接对超时非常敏感。以下是一些关键参数的经验值stream { server { listen 13306 so_keepaliveon; proxy_pass mysql_backend; # 连接后端服务器的超时时间网络不好可适当延长 proxy_connect_timeout 15s; # 客户端与Nginx之间连接的超时时间必须设置得足够长 proxy_timeout 7d; # 例如设置为一周覆盖连接池长期空闲的场景 # 以下参数控制Nginx与后端之间的连接行为 proxy_socket_keepalive on; # 启用TCP keepalive探测后端连接是否存活 # 缓冲相关一般保持默认或关闭 # proxy_buffer_size 0; # 设置为0禁用缓冲减少延迟 # proxy_upload_rate 0; # 上传限速0为不限速 # proxy_download_rate 0; # 下载限速0为不限速 } }实操心得proxy_timeout的值最好比你应用服务器数据库连接池中设置的“最大空闲时间”或“连接存活检测间隔”要长。例如你的Java应用连接池设置了testWhileIdletrue和timeBetweenEvictionRunsMillis600001分钟检测一次那么proxy_timeout至少应该设置为2分钟以上避免Nginx在应用层健康检查的间隙把连接断掉。6. 常见问题排查与修复实录即使配置看似正确在实际部署中也难免会遇到问题。这里记录几个我踩过的坑和解决方案。6.1 连接建立失败Connection refused现象客户端连接13306端口时迅速收到“Connection refused”错误。排查思路检查Nginx是否监听端口在Nginx服务器上执行sudo ss -tlnp | grep :13306。如果没有输出说明Nginx没有成功绑定端口。可能原因A配置文件语法错误Nginx加载失败。用nginx -t仔细检查。可能原因B端口被其他进程占用。用sudo ss -tlpn | grep :13306查看占用进程。可能原因CSELinux或防火墙阻止绑定。检查SELinux日志和firewalld规则。检查Nginx到后端数据库的网络连通性在Nginx服务器上尝试直接连接后端数据库telnet 192.168.1.100 3306。如果连不上说明网络或数据库服务有问题。可能原因数据库防火墙未放行Nginx服务器的IP数据库服务未启动数据库监听的地址不是0.0.0.0只绑定了127.0.0.1。6.2 连接超时或随机断开Connection timed out / Lost connection现象连接建立成功但执行查询时很慢或者空闲一段时间后连接自动断开。排查思路首要怀疑proxy_timeout这是最常见的原因。检查Nginx配置中的proxy_timeout值。将其设置为一个非常大的值如24h或7d进行测试。检查中间网络设备客户端-Nginx-数据库整条链路上的防火墙、负载均衡器等设备是否有独立的TCP空闲超时设置这些设备的超时时间必须大于proxy_timeout和应用连接池的超时设置。启用并分析日志在Nginx的streamserver块中将日志级别调为info或debug临时观察连接断开时的日志信息。error_log /var/log/nginx/mysql-error.log debug;数据库服务端配置检查数据库服务器自身的wait_timeout、interactive_timeoutMySQL或tcp_keepalive参数。确保数据库不会先于Nginx断开空闲连接。6.3 性能问题吞吐量低或延迟高现象通过Nginx转发后数据库查询性能明显下降。排查思路禁用缓冲尝试在Nginx配置中设置proxy_buffer_size 0;让数据直接透传避免额外的内存拷贝。检查系统资源使用vmstat 1、iostat -x 1等命令查看Nginx服务器的CPU、内存、磁盘I/O和网络带宽是否成为瓶颈。数据库查询本身是重I/O操作如果Nginx服务器磁盘IOPS不足如果用了swap也会影响整体表现。Nginx工作进程数在nginx.conf的全局部分调整worker_processes通常设置为CPU核心数和worker_connections每个进程可处理连接数。对于大量数据库长连接可能需要调高worker_connections。内核参数调优对于高并发长连接可能需要调整Linux内核网络参数如net.core.somaxconn监听队列长度、net.ipv4.tcp_tw_reuseTIME_WAIT端口重用等。但这属于高级调优需谨慎。6.4 负载均衡不生效或状态检查失败现象配置了多个后端但流量没有按预期分发或者某台后端宕机后Nginx仍然尝试转发导致失败。排查思路检查upstream配置确保upstream块中所有server的IP和端口正确并且后端服务确实在运行。理解健康检查机制Nginxstream模块的被动健康检查max_fails,fail_timeout只在尝试连接失败时触发。如果后端数据库进程存活但已经无法响应SQL例如数据库僵死Nginx可能无法感知。此时需要考虑使用Nginx Plus商业版的主动健康检查功能。或者在应用层实现更完善的健康检查并结合动态的Nginx配置管理如使用Consul Template。会话保持stream模块是四层转发默认的轮询负载均衡对于数据库连接是有效的因为每个连接都是独立的。但需要注意如果客户端使用了连接池并保持长连接那么这些长连接会一直固定在某个后端服务器上直到连接断开。这不是Nginx的问题而是TCP长连接的特性。7. 生产环境部署建议与演进思考将Nginx用于数据库端口转发在中小型生产环境中已经足够稳健。但当你面对更大规模、更复杂的场景时可以考虑以下演进方向高可用架构单点Nginx存在故障风险。可以采用Keepalived VIP实现主备高可用或者使用DNS轮询、LVS在前端做负载均衡后面挂多个Nginx实例。配置管理自动化当后端数据库服务器IP变更或扩缩容时手动修改Nginx配置并重载容易出错。可以结合Consul、etcd等服务发现工具使用confd或Consul Template自动生成Nginx的upstream配置并触发重载。监控告警体系化除了看日志应将Nginx的stream状态指标如活跃连接数、吞吐量纳入监控系统如Prometheus。为连接失败、后端服务器下线等关键事件设置告警。向专业数据库中间件演进如果需求变得复杂例如需要基于SQL语句进行读写分离。查询结果缓存。连接池复用Nginx是连接转发不是连接池。复杂的故障切换Failover。 那么就应该考虑引入专业的数据库中间件如ProxySQL、MaxScale或HAProxy配合更精细的检查脚本。这些工具是专门为数据库流量管理而设计的功能更强大。回过头看用Nginx做数据库端口转发本质上是在网络的传输层搭建了一座坚固、可控的桥梁。它可能不是功能最强大的那个但在简单、直接、高性能的需求面前它往往是最快、最稳的选择。我在好几个项目中用它来统一数据库访问入口隔离内外网运维同事再也不用去每台服务器上改iptables了所有的访问日志集中在一处查问题也方便得多。技术选型没有银弹关键是弄清楚你的核心需求是什么然后选择那个“恰好够用”又“留有余地”的工具。