Nginx Proxy Manager Streams 指南：使用 Nginx 流代理转发 TCP/UDP 流量

Nginx Proxy Manager Streams 指南：使用 Nginx 流代理转发 TCP/UDP 流量

【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager

导读

Streams（流）是 Nginx Proxy Manager（NPM）中用于转发 TCP/UDP 流量的核心功能：它不关心 HTTP 层协议，而是直接把四层网络连接原样转发到局域网内的另一台计算机。本文以 Nginx Proxy Manager 官方帮助文档中关于 Streams 的说明为骨架，结合本仓库的源码、Nginx 配置模板与前端表单实现，系统讲解 Stream 的定义、适用场景、Web 界面配置、底层 Nginx 配置生成原理、SSL 支持以及 API 操作方式，帮助你真正掌握如何用 NPM 托管游戏服务器、FTP、SSH 等非 HTTP 服务。

Stream 是什么

What is a Stream? A relatively new feature for Nginx, a Stream will serve to forward TCP/UDP traffic directly to another computer on the network.

Stream 是 Nginx 相对较新的一个特性（对应 Nginx 的ngx_stream_core_module模块）。与常规的 HTTP 反向代理（Proxy Host）不同，Stream 工作在传输层（四层），它将进入 NPM 指定端口的 TCP/UDP 流量，原样转发给网络中的另一台计算机，而不解析、修改或缓存应用层内容。

如果你在运行游戏服务器、FTP 或 SSH 服务器，这一功能会非常实用——因为这些服务并不使用 HTTP 协议，普通的域名反代（如 80/443 端口）无法处理它们，而 Stream 可以：

核心配置参数

在 NPM 中，一个 Stream 对象由以下核心参数组成（数据模型见 stream.js，接口 Schema 见 stream-object.json）：

其中forwarding_host在 stream-object.json 中支持三种形式：域名、IPv4 地址、IPv6 地址。

注意tcp_forwarding与udp_forwarding为布尔值，但数据库中以整型存储，模型在读写时通过convertBoolFieldsToInt/convertIntFieldsToBool自动转换（见 stream.js）。

一个 Stream 可以同时监听 TCP 和 UDP

从配置模板可以看出，tcp_forwarding与udp_forwarding可以同时开启：此时模板会生成两个独立的server块，分别监听 TCP 和 UDP（见 stream.conf）。前端表单中也通过两个开关控制，且保证至少开启其中一个（见 StreamModal.tsx）。

如何创建一个 Stream

在 NPM 管理界面中，进入Streams页面，点击Add Stream按钮（对应前端页面 Streams/index.tsx 与表单 StreamModal.tsx）。

表单包含两个页签：

Details（详情）页签：

• Incoming Port（入站端口）：1–65535 的整数，例如8080；
• Forward Host（转发主机）：目标服务器地址（域名或 IP），例如192.168.1.10；
• Forward Port（转发端口）：目标端口，例如8081；
• TCP / UDP 开关：选择转发的协议类型。

SSL 页签：

• 选择已有的 SSL 证书，或新建证书（allowNew，对应 SSLCertificateField）；
• 配置 SSL 选项（对应 SSLOptionsFields）。

提示：由于 Stream 不按域名路由，后端在创建时会将domain_names字段从数据中移除（见 stream.js 注释 "streams aren't routed by domain name so don't store domain names in the DB"），因此 Stream 不支持按域名区分流量。

表单校验规则

前端表单使用validateNumber(1, 65535)和validateString(1, 255)进行校验（见 StreamModal.tsx），端口必须落在 1–65535 之间，转发主机为 1–255 个字符。后端 API 在 stream-object.json 中同样对端口与主机格式做了严格校验。

底层 Nginx 配置生成原理

当创建、更新或启用一个 Stream 时，后端会调用internalNginx.configure(streamModel, "stream", row)生成对应的 Nginx 配置文件（见 stream.js），最终渲染自模板 stream.conf。

以 TCP 转发为例，生成的 Nginx 配置结构如下：

# ------------------------------------------------------------ # 8080 TCP: 1 UDP: 0 # ------------------------------------------------------------ server { listen 8080 reuseport; listen [::]:8080 reuseport; # 若配置了 SSL 证书，此处会 include 证书模板 proxy_pass 192.168.1.10:8081; access_log /data/logs/stream-1_access.log stream; error_log /data/logs/stream-1_error.log warn; # Custom include /data/nginx/custom/server_stream[.]conf; include /data/nginx/custom/server_stream_tcp[.]conf; }

模板中值得注意的细节：

• listen ... reuseport：Nginx 使用reuseport参数以支持多进程共享同一端口的高效负载均衡；
• IPv6 支持：模板根据ipv6变量决定是否启用listen [::]:port，若未启用则整行被注释掉（stream.conf）；
• 协议独立监听：TCP 与 UDP 分别生成独立的server块，UDP 块使用listen ... udp reuseport（stream.conf）；
• 自定义扩展点：TCP 和 UDP 分别支持server_stream_tcp[.]conf与server_stream_udp[.]conf自定义配置文件，方便高级用户注入额外指令（stream.conf）；
• 独立日志：每个 Stream 有独立的stream-{{ id }}_access.log与stream-{{ id }}_error.log，便于排障。

Stream 的 SSL 支持

若为 Stream 关联了证书，stream.conf 会在listen指令后追加ssl参数，并通过 _certificates_stream.conf 引入证书配置：

# Let's Encrypt SSL include conf.d/include/ssl-cache-stream.conf; ssl_certificate /etc/letsencrypt/live/npm-1/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/npm-1/privkey.pem;

Let's Encrypt 证书与自定义证书的路径分别位于/etc/letsencrypt/live/npm-{{ certificate_id }}/与/data/custom_ssl/npm-{{ certificate_id }}/。这得益于迁移 20240427161436_stream_ssl.js 为stream表新增了certificate_id字段。注意：由于 Stream 不按域名路由，新建证书时需要通过 DNS 验证等方式签发（前端 SSL 表单中forceDNSForNew与requireDomainNames即为此设计）。

生命周期操作与 API

Stream 的完整生命周期由 stream.js 实现，对应 REST API 路由见 streams.js：

各操作的后端行为：

• 创建（create）：校验权限（streams:create，见 streams-create.json）、写入数据库（移除 domain_names）、可选新建证书、调用 Nginx 重新生成配置、写入审计日志；
• 更新（update）：校验streams:update权限，更新数据库后重新生成 Nginx 配置，并清理证书 meta（cleanRowCertificateMeta）；
• 启用（enable）：将enabled置 1 并重新生成 Nginx 配置，若已启用则抛出ValidationError("Stream is already enabled")；
• 禁用（disable）：将enabled置 0，删除 Nginx 配置文件并reloadNginx；
• 删除（delete）：软删除（is_deleted = 1），删除 Nginx 配置并 reload，同时写入审计日志。

权限说明：streams:list与streams:get受permission_visibility约束，非all可见性时仅能操作自己创建（owner_user_id）的 Stream（见 stream.js）。

创建示例（使用POST /api/nginx/streams）：

{ "incoming_port": 25565, "forwarding_host": "192.168.1.20", "forwarding_port": 25565, "tcp_forwarding": true, "udp_forwarding": false, "enabled": true, "certificate_id": 0 }

创建时的端口冲突提示

在 stream.js 与 stream.js 中可以看到// TODO: At this point the existing ports should have been checked注释，说明端口占用检查尚未在创建/更新流程中完整实现，配置重复入站端口时需自行留意。

在 Streams 页面查看与运维

Stream 列表页面（Table.tsx）展示以下列：所有者（头像）、入站端口、目标地址（forwardingHost:forwardingPort）、协议标识（TCP/UDP 徽章）、SSL 证书、状态（在线/离线），以及编辑、启用/禁用、删除等操作。列表默认按入站端口升序排列（对应后端orderBy("incoming_port", "ASC")，见 stream.js）。

小结

Nginx Proxy Manager 的 Streams 功能将 Nginx 强大的四层流代理能力封装成了可视化的管理界面：只需填写入站端口、目标主机与端口、选择 TCP/UDP 协议，即可完成游戏服务器、FTP、SSH 等非 HTTP 服务的端口转发与 TLS 加密。通过本文对 stream.conf、stream.js 与 StreamModal.tsx 等源码的分析，你可以清楚地了解每个配置项的作用、底层 Nginx 配置的生成方式，以及 Stream 的完整生命周期管理，从而在实际部署中高效使用这一功能。

【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager