Nginx Proxy Manager 端口转发Streams完全指南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端口转发Stream是 Nginx Proxy ManagerNPM中基于 Nginx stream 模块实现的核心能力之一用于将 TCP/UDP 流量直接转发到网络中的另一台主机适合游戏服务器、FTP、SSH 等非 HTTP 服务。本文以 Streams 帮助文档 为骨架结合 stream.conf 模板、internal/stream.js、stream 数据模型 与前端 StreamModal 等仓库源码系统讲解 Stream 的适用场景、配置字段、前端操作、后端生命周期与最终生成的 Nginx 配置帮助读者在 NPM 中正确、安全地搭建 TCP/UDP 转发规则。什么是 StreamNginx 的传输层流代理按照官方帮助文档的定义Stream 是 Nginx 的一项相对较新的功能它可以把 TCP/UDP 流量直接转发到网络中的另一台计算机对应俄语文档原文 поток позволяет напрямую проксировать TCP/UDP‑трафик на другой компьютер в сети。与 Proxy HostHTTP/HTTPS 反向代理不同Stream 工作在传输层L4不关心上层协议内容只负责把原始字节流在端口之间搬运。因此它非常适合承载那些不是 Web 服务的网络应用。NPM 中 Stream 的核心特征可以从源码中得到印证在 internal/stream.js 中有一句关键注释streams arent routed by domain name so dont store domain names in the DBStream 不按域名路由因此数据库中不存储域名。这正是它区别于 Proxy Host 的本质——Stream 只按端口寻址不按域名寻址。stream 列表接口 按incoming_port升序排序并支持按incoming_port模糊搜索再次印证端口是 Stream 的唯一标识维度。典型使用场景游戏服务器、FTP 与 SSH官方帮助文档明确指出如果你在运行游戏服务器、FTP 或 SSH 服务器这个功能就会很有用。从技术角度看这些场景的共性在于场景协议为什么需要 Stream游戏服务器TCP/UDP游戏流量通常是非 HTTP 的自定义协议且需要 UDP 支持FTP 服务器TCP控制连接与数据连接均为 TCP且可能占用多个端口SSH 服务器TCP需要把外部某个端口安全地透传到内网 SSH 服务其典型部署形态是Nginx Proxy Manager 运行在公网入口主机上监听一个公网端口把流量转发到内网某台机器或同一内网中的另一台服务器的对应端口实现无需暴露整台内网机器即可对外提供 TCP/UDP 服务。Stream 配置字段全解创建或编辑 Stream 时涉及的核心字段在 stream-object.json 接口定义 中有完整的类型约束同时 StreamModal.tsx 展示了前端表单的输入规则。汇总如下字段类型取值范围/说明来源incoming_portinteger165535NPM 监听的外部端口必填stream-object.json、StreamModalforwarding_hoststring目标主机支持域名、IPv4、IPv6 三种格式stream-object.jsonforwarding_portinteger165535目标端口必填stream-object.jsontcp_forwardingboolean是否启用 TCP 转发stream-object.jsonudp_forwardingboolean是否启用 UDP 转发stream-object.jsonenabledboolean是否启用该 Streamstream-object.jsoncertificate_idinteger关联的 SSL 证书 ID0 表示无证书stream-object.jsonmetaobject附加元数据默认{}stream-object.json前端表单 StreamModal.tsx 中对应的输入校验逻辑也完全一致Incoming Porttypenumbermin1、max65535校验函数validateNumber(1, 65535)占位符示例8080Forward HostvalidateString(1, 255)支持填域名或 IPForward Port同样限定 165535TCP/UDP 转发开关通过tcpForwarding、udpForwarding两个布尔字段控制。值得注意的是tcp_forwarding和udp_forwarding可以同时开启——模板会为同一incoming_port分别生成 TCP 与 UDP 两个server块实现同一端口同时支持 TCP 和 UDP的效果详见下文模板分析。前端操作创建与编辑 Stream在 NPM 管理界面中Streams 的入口位于左侧菜单的Streams页面页面组件见 Streams/TableWrapper.tsx。页面顶部提供了新增按钮调用showStreamModal(new)打开新建弹窗帮助按钮调用showHelpModal(Streams, ...)打开本文对应的帮助文档每行的编辑/删除/启停操作删除与启停分别调用 deleteStream / toggleStream 对应接口。弹窗内部StreamModal.tsx分为两个标签页Details详情填写 Incoming Port、Forward Host、Forward Port以及 TCP/UDP 转发开关SSL通过 SSLCertificateField 选择证书、SSLOptionsFields 配置 SSL 选项。提交后前端调用useSetStream()对应 useStream.ts hook最终命中后端的创建/更新接口。列表页在操作成功后还会失效[streams]与[stream, id]查询缓存保证界面即时刷新见 TableWrapper.tsx。后端生命周期从接口到 Nginx 配置Stream 的所有后端逻辑集中在 internal/stream.js其完整生命周期如下创建create流程为权限校验streams:create→ 设置owner_user_id→ 初始化meta→ 写入数据库此时特意剥离domain_names字段→ 若certificate_id new则先走createQuickCertificate快速签发证书并回填 → 调用internalNginx.configure(streamModel, stream, row)生成 Nginx 配置 → 写入审计日志action 为created。更新update先读取现有记录做一致性校验更新数据库后再次get并重新configure同时把变更写入审计日志action 为updated。启停enable / disableenable把enabled置 1重新调用configure生成配置disable把enabled置 0调用internalNginx.deleteConfig(stream, row)删除配置并reload()。两者都会在审计日志中记录enabled/disabled动作。删除delete采用软删除策略仅将is_deleted置 1然后删除 Nginx 配置并 reload审计日志记录deleted。整个链路表明NPM 对 Stream 的每一次增删改都会即时重写并重载 Nginx 配置这也是管理界面操作能够所见即所得的底层保证。模板解析生成的 Nginx 配置长什么样NPM 使用 Nunjucks 模板引擎渲染 Stream 配置核心模板是 backend/templates/stream.conf。渲染后 TCP 转发块大致如下# ------------------------------------------------------------ # 8080 TCP: 1 UDP: 0 # ------------------------------------------------------------ server { listen 8080 reuseport ssl; listen [::]:8080 reuseport ssl; # Lets Encrypt SSL include conf.d/include/ssl-cache-stream.conf; include conf.d/include/ssl-ciphers.conf; ssl_certificate /etc/letsencrypt/live/npm-3/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/npm-3/privkey.pem; proxy_pass 192.168.1.10:22; access_log /data/logs/stream-3_access.log stream; error_log /data/logs/stream-3_error.log warn; # Custom include /data/nginx/custom/server_stream[.]conf; include /data/nginx/custom/server_stream_tcp[.]conf; }模板的关键设计点全部有源码依据listen {{ incoming_port }} reuseport使用reuseport提升多 worker 下的端口分发性能当绑定了证书时追加ssl关键字IPv6 支持{% unless ipv6 -%} # {%- endunless -%} listen [::]:{{ incoming_port }}...——只有当ipv6开关开启时才会启用 IPv6 监听否则整行被注释proxy_pass {{ forwarding_host }}:{{ forwarding_port }}即目标主机与端口独立日志access_log /data/logs/stream-{{ id }}_access.log stream;和error_log /data/logs/stream-{{ id }}_error.log warn;每个 Stream 拥有独立的访问/错误日志便于排查自定义配置挂载点模板末尾会 include/data/nginx/custom/server_stream[.]conf与server_stream_tcp[.]confUDP 块则 includeserver_stream_udp[.]conf用户可以在不修改核心配置的前提下追加自定义指令如proxy_timeout、proxy_buffer_size等。注意这里的[.]写法是 Nginx 的 glob 语法用于避免与点号通配冲突。当 UDP 转发也开启时模板会再生成一个listen {{ incoming_port }} udp reuseport的server块逻辑与 TCP 块平行但监听的是 UDP 流量。SSL/TLS为 TCP 流加密Stream 同样支持 SSL 终止。SSL 配置由 _certificates_stream.conf 模板渲染若证书来自 Lets Encryptprovider letsencrypt证书路径为/etc/letsencrypt/live/npm-{{ certificate_id }}/fullchain.pem与对应的privkey.pem并 includessl-cache-stream.confSSL 会话缓存与ssl-ciphers.conf密码套件若是自定义证书则从/data/custom_ssl/npm-{{ certificate_id }}/目录读取。值得说明的是Stream 的证书支持是后来加入的能力数据库迁移 20240427161436_stream_ssl.js 为stream表新增了certificate_id列默认 0即无证书。因此在创建 Stream 时SSL 标签页中的证书是可选的。数据模型与权限控制数据模型models/stream.js 定义了stream表的 ORM 模型要点如下布尔字段is_deleted、enabled、tcp_forwarding、udp_forwarding在数据库中以 0/1 存储、在 API 层转换为 true/false与userowner 所有者和certificate证书建立关系映射defaultAllowGraph [owner,certificate]默认排序为incoming_port ASC。权限访问 Stream 相关接口需要对应权限从 streams-create.json 可见创建 Stream 需要管理员角色或拥有permission_streams管理权限的user角色其余操作streams:get、streams:update、streams:delete、streams:list在 internal/stream.js 中均通过access.can(...)校验。此外当权限可见性不是all时查询会自动加上owner_user_id过滤internal/stream.js即普通用户只能看到自己创建的 Stream。实战注意事项与排查建议端口冲突NPM 会在同一主机上为所有 Stream 分配监听端口如果两个 Stream 使用相同incoming_port会导致 Nginx 启动失败。从 internal/stream.js 的 TODO 注释At this point the existing ports should have been checked可以看出当前版本在创建阶段尚未对端口占用做强制校验因此配置前应先确认端口未被其他服务或 Stream 占用。TCP 与 UDP 可并行同一个incoming_port可以同时勾选 TCP 与 UDP模板会分别生成两个server块互不冲突但也意味着该端口上的 TCP 和 UDP 流量都会被接管请确认没有其他服务依赖该端口。查看日志每个 Stream 的日志独立存放在/data/logs/stream-{{ id }}_access.log与stream-{{ id }}_error.log排查连接失败问题时优先查看对应 ID 的错误日志。自定义配置需要调优如超时、缓冲区、proxy_protocol等时可在容器的/data/nginx/custom/目录放置server_stream_tcp[.]conf或server_stream_udp[.]conf文件模板会自动 include。域名不参与路由Stream 不按域名匹配domain_names不会被写入数据库internal/stream.js因此一个端口只能服务一个转发目标多目标分流需要占用多个端口。小结Nginx Proxy Manager 的 Stream 功能本质上是把 Nginx 的 stream 模块能力封装成了可视化的端口转发管理入口你在界面上填写监听端口、目标主机与端口、选择 TCP/UDP 与可选证书后端随即渲染出标准 Nginx stream 配置并热加载。对于游戏服务器、FTP、SSH 这类非 HTTP 服务它提供了一条比手动维护 Nginx 配置更直观、更可控的运维路径。理解 stream.conf 模板与 internal/stream.js 的生命周期逻辑是在生产环境中排障与深度定制的关键。【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考