扩展功能配置指南 on NPS Plus

向 HTTP 后端传递访问者真实 IP

Mon, 01 Jan 0001 00:00:00 +0000

HTTP(S) 隧道默认由 NPC 连接内网服务，因此后端看到的 TCP 来源通常是 NPC 所在主机，而不是公网访问者。开启来源头后，NPS 会把访问者地址写入 HTTP 请求头，供后端应用或反向代理恢复真实 IP。

Web 配置何时生效

Mon, 01 Jan 0001 00:00:00 +0000

NPS 将 Web 管理数据与进程启动配置分开处理。客户端、HTTP(S) 隧道和普通隧道的大多数 Web 修改会直接更新运行时数据，不需要重启整个 NPS。

生效范围

操作	生效方式	对现有连接的影响
修改 HTTP(S) 隧道的目标、Host、请求头或 URL 路径	保存后供后续请求读取	已进入转发的请求不变
修改普通隧道	NPS 停止并重新启动该隧道监听	新连接使用新配置；应按业务类型验证长连接
启用/停用隧道	打开或关闭对应监听	停用后不再接受新连接
修改客户端限速、认证和访问名单	保存后更新客户端运行数据	新请求/后续传输按相应功能执行
修改 NPC 配置文件创建的隧道	修改 `npc.conf` 后重新连接	Web 不是这类配置的持久化来源
修改 `nps.conf` / `npc.conf`	重启对应进程	取决于被重启的进程和隧道

查看客户端的出口与内网地址

Mon, 01 Jan 0001 00:00:00 +0000

客户端列表提供“出口地址”和“内网地址”，两者用于判断 NPC 从哪里接入以及它在内网使用了哪块网卡。

字段	数据来源	常见值
出口地址	NPS 接受桥接连接时实际看到的远端 IP	公网 IP、NAT 网关地址或上游代理地址
内网地址	NPS 上线后向 NPC 请求，NPC 优先上报当前桥接连接使用的本地 IPv4	`192.168.1.20`、`10.0.0.8`

使用方法

进入 Web 管理的“客户端列表”，展开或查看对应客户端。地址可用于：

查看和保存隧道流量统计

Mon, 01 Jan 0001 00:00:00 +0000

Web 管理会显示客户端以及各隧道的“入站流量”和“出站流量”，适合比较隧道用量、判断异常增长，并为流量限制设置基线。

统计口径

统计发生在 NPS 的转发读写路径中，记录应用数据经过隧道时的字节数。它不是操作系统网卡计数，也不是云厂商账单，因此以下内容会造成差异：

查看客户端当前传输速度

Mon, 01 Jan 0001 00:00:00 +0000

客户端列表中的“网速”显示该客户端最近一个采样周期内经过 NPS 限速器的聚合吞吐量，用于快速发现突发流量或验证带宽限制是否生效。

如何读取

统计对象是单个客户端下的汇总流量，不是单条隧道。
采样约每秒更新一次，短请求可能在刷新页面时已经回落到零。
页面按字节速率自动换算显示；它不是 bit/s，和网络运营商常用的 Mbps 口径不同。
上传、下载、协议开销以及压缩/加密会使其与操作系统或云监控数值不同。

如需稳定验证，可通过该客户端的一条 TCP 或 HTTP(S) 隧道持续传输较大文件，同时观察客户端列表。限制值的精确单位和换算见带宽限制。容量规划应以主机网卡、云监控或专业监控系统为准，本页面数据用于运行观察。

查看 NPC 版本与兼容性

Mon, 01 Jan 0001 00:00:00 +0000

NPC 在握手时会向 NPS 上报发行版本，NPS 也会返回核心协议版本摘要。Web 管理的客户端列表会显示在线 NPC 的版本，便于发现混用版本。

当前兼容行为

当前产品的核心版本基线为 0.26.0。握手会完成版本交换，但核心版本不一致时仍会兼容放行；版本不同不会单独导致连接被拒绝。连接失败应先检查客户端验证密钥、桥接地址、协议、TLS 设置和网络连通性。

提高 Linux 并发连接容量

Mon, 01 Jan 0001 00:00:00 +0000

高并发隧道同时受进程文件描述符、监听队列、临时端口、连接跟踪和内存限制。只有监控或日志表明达到系统上限时才应调整；单纯增大参数不能弥补 CPU、内存或带宽不足。

防止 Web 管理登录被暴力破解

Mon, 01 Jan 0001 00:00:00 +0000

Web 管理登录内置按来源 IP 的失败次数保护。某个 IP 在 60 秒内累计失败达到 10 次后，后续登录会被拒绝；距离最近一次失败满 60 秒后计数重置，登录成功也会清除该 IP 的记录。

加密 NPC 与 NPS 之间的连接

Mon, 01 Jan 0001 00:00:00 +0000

TLS 桥接用于加密 NPC 与 NPS 之间的控制和多路复用链路，避免桥接流量以明文形式经过网络。它不等同于 HTTP(S) 隧道的站点证书配置。

服务端配置

在 nps.conf 中设置：

为 NPC 连接 NPS 配置证书

Mon, 01 Jan 0001 00:00:00 +0000

本页介绍如何为 NPC（客户端）与 NPS（服务端）之间的连接配置证书（用于证明服务端身份的电子文件）。这些设置用于桥接连接（NPC 与 NPS 之间传送连接管理信息和转发数据的连接）。

为 HTTP(S) 站点设置访问密码

Mon, 01 Jan 0001 00:00:00 +0000

HTTP(S) 隧道共用服务端入口。对于开发预览、临时管理页等不应公开访问的站点，可以使用客户端的“代理认证用户名”和“代理认证密码”启用 HTTP Basic Auth。

配置方式

在 Web 管理中编辑站点所属的客户端，同时填写：

改写 HTTP 后端收到的 Host

Mon, 01 Jan 0001 00:00:00 +0000

公网域名与内网站点绑定的虚拟主机名不一致时，可使用“改写 Host 请求头”让后端命中正确站点。例如访问者请求 preview.example.com，但内网 Nginx 只接受 app.internal.example。

新增或覆盖 HTTP 后端请求头

Mon, 01 Jan 0001 00:00:00 +0000

HTTP(S) 隧道的“改写请求头”可以在转发前新增请求头，或覆盖后端将收到的同名请求头。常见用途包括给内网应用传递固定环境标识、关闭上游缓存或补充反向代理约定字段。

自定义 HTTP 隧道的 404 页面

Mon, 01 Jan 0001 00:00:00 +0000

HTTP 隧道已经匹配域名规则，但客户端不可用、流量超限或目标连接失败时，会以 404 Not Found 返回内置错误页。自定义模板位于项目目录：

web/static/page/error.html

自定义方法

该模板会编译进 NPS 二进制。修改已安装程序运行目录中的同名文件不会生效，必须在项目中修改模板后重新构建并替换 NPS：

限制客户端可累计使用的流量

Mon, 01 Jan 0001 00:00:00 +0000

流量限制按客户端累计“入站流量 + 出站流量”，适合给租户或设备设置总用量配额。它不是按月自动重置的计费系统。

开启并配置

先在服务端 nps.conf 开放 Web 配置项并重启 NPS：

限制客户端的传输速度

Mon, 01 Jan 0001 00:00:00 +0000

带宽限制为客户端级共享限速器，客户端下所有隧道的读写流量共同消耗额度。它适合防止单个客户端占满 NPS 出口，不用于保证最低带宽或按隧道分配权重。

开启并配置

在服务端 nps.conf 中开放 Web 配置项并重启：

将新连接轮询到多个后端

Mon, 01 Jan 0001 00:00:00 +0000

HTTP(S) 隧道和 TCP 隧道可配置多个“目标地址（IP:端口）”。NPS 按轮询顺序为新连接选择目标，适合把无状态服务分散到多台内网主机。

Web 配置

新增或编辑隧道，在目标地址中每行填写一个目标：

自动分配服务端监听端口

Mon, 01 Jan 0001 00:00:00 +0000

在 Web 管理中新增需要监听端口的隧道时，“服务端监听端口（留空自动分配）”可以不填。NPS 会选择当时可绑定的端口，并在保存成功后显示实际端口。

分配规则

配置了 allow_ports 时，只在允许列表中随机选择并逐个检查。
未配置 allow_ports 时，最多尝试 1000 次随机端口，自动范围从 1024 开始。
TCP、HTTP 正向代理和 SOCKS5 等模式检查 TCP 端口；UDP 隧道检查 UDP 端口。
私密代理和 P2P 不依赖独立公网监听端口，不需要用此功能规划端口。

如果找不到可用端口，新增会失败并提示端口可能已占用或不在允许范围。端口检测与真正启动监听之间存在很短的竞争窗口，极端并发创建时仍可能启动失败。

复制普通隧道配置

Mon, 01 Jan 0001 00:00:00 +0000

隧道列表页的“复制”适合快速创建目标、客户端和访问策略相同，但公网监听端口不同的普通隧道。

复制内容

复制后会创建新的隧道 ID 并立即启用，包含原隧道的：

向 TCP 后端传递访问者真实 IP

Mon, 01 Jan 0001 00:00:00 +0000

普通 TCP 转发会由 NPC 连接目标服务，因此后端默认只能看到 NPC 的地址。需要保留公网访问者地址时，应根据业务协议选择 PROXY 协议或 HTTP 请求头。

方案选择

场景	推荐方式
数据库、自定义 TCP 协议、TCP 模式承载的 HTTP	PROXY v1 或 v2
NPS 的 HTTP(S) 域名隧道	`X-Forwarded-For` / `X-Real-IP`，参见获取用户真实 IP
SSH、RDP 等后端不支持 PROXY 协议	不要开启；改由应用审计、VPN 或支持该协议的前置代理处理

在 NPS 中启用

新增或编辑 TCP 隧道，在“PROXY 协议版本”中选择：

限制隧道可使用的服务端端口

Mon, 01 Jan 0001 00:00:00 +0000

为了防止用户任意占用服务端端口，可在 nps.conf 中配置 allow_ports，把普通隧道的“服务端监听端口”限制在指定集合内：

allow_ports=9001-9009,10001,11000-12000

修改后重启 NPS。忽略或留空表示不限制；配置项使用英文逗号分隔单个端口或闭区间，不要加入空格。

批量映射 TCP 或 UDP 端口

Mon, 01 Jan 0001 00:00:00 +0000

NPC 配置文件可用一段配置批量创建多个 TCP 或 UDP 隧道，适合映射连续服务端口。Web 管理不接受端口范围，需要逐条创建。

配置示例

[tcp]
mode=tcp
server_port=9001-9009,10001,11000-12000
target_port=8001-8009,10002,13000-14000

展开后的端口按位置一一对应：9001 -> 8001、9002 -> 8002，依此类推。UDP 只需将 mode 改为 udp。

批量映射到其他内网主机

Mon, 01 Jan 0001 00:00:00 +0000

端口范围默认映射到 NPC 本机。需要转发到 NPC 可访问的另一台内网主机时，在范围映射中增加 target_ip：

[tcp]
mode=tcp
server_port=9001-9009,10001,11000-12000
target_port=8001-8009,10002,13000-14000
target_ip=10.1.50.2

展开后例如 9001 -> 10.1.50.2:8001。忽略 target_ip 时目标为 NPC 本机 127.0.0.1。

使用 UDP/KCP 连接 NPS

Mon, 01 Jan 0001 00:00:00 +0000

KCP 使用 UDP 承载 NPC 与 NPS 之间的桥接连接。在低丢包、低抖动且 UDP 畅通的专线或内网中，它可能降低部分交互延迟；公网、移动网络或受限网络不一定更快。

服务端配置

在 nps.conf 中设置并重启 NPS：

用泛域名转发多个子域名

Mon, 01 Jan 0001 00:00:00 +0000

泛域名规则用一条 HTTP(S) 隧道接收同一后缀下的多个子域名。例如 *.proxy.com 可让 a.proxy.com、b.proxy.com 等转发到同一目标。

配置步骤

在 DNS 服务商添加 *.proxy.com 的 A/AAAA 记录，指向 NPS 服务端。
在 Web 管理新增 HTTP(S) 隧道，把“域名”填写为 *.proxy.com。
填写目标地址；如使用 HTTPS，配置覆盖这些子域名的通配符证书和私钥。
另行创建 proxy.com 规则，因为 *.proxy.com 不包含根域名本身。

NPC 配置文件示例：

按 URL 路径选择不同后端

Mon, 01 Jan 0001 00:00:00 +0000

同一个域名可以创建多条 HTTP(S) 隧道规则，通过“URL 路径前缀”把请求分给不同内网服务。例如 API、静态资源和默认站点可以共用一个公网域名。

配置示例

为 app.example.com 创建三条规则：

限制客户端的并发连接数

Mon, 01 Jan 0001 00:00:00 +0000

“最大连接数”限制单个客户端同时占用的转发连接，避免一个客户端通过大量长连接耗尽 NPS 文件描述符或内存。限制对 SOCKS5、HTTP 正向代理、HTTP(S)、TCP、UDP 和私密代理生效。

限制客户端可创建的隧道数

Mon, 01 Jan 0001 00:00:00 +0000

“最大隧道数”限制单个客户端可以创建的隧道规则总数，适合多用户环境防止某个账号占用过多监听端口或域名规则。

开启并配置

在 nps.conf 中设置并重启 NPS：

让桥接、站点与管理端共用一个端口

Mon, 01 Jan 0001 00:00:00 +0000

端口复用可以让明文 TCP 桥接、HTTP(S) 隧道入口和 Web 管理共用一个 TCP 端口，适合公网只允许开放少量端口的环境。NPS 会根据连接开头的协议特征分流。

用一条桥接连接承载多个隧道

Mon, 01 Jan 0001 00:00:00 +0000

NPS 的业务转发默认使用多路复用，不需要在 Web 或配置文件中另行开启。NPC 与 NPS 建立数据桥接后，多个 TCP、HTTP(S)、SOCKS5 等业务连接会作为独立逻辑流共享这条连接。

用环境变量启动 NPC

Mon, 01 Jan 0001 00:00:00 +0000

无配置文件模式下，NPC 可从环境变量读取服务端地址和客户端验证密钥，适合容器、systemd EnvironmentFile 或密钥注入平台。

支持的变量

环境变量	含义	示例
`NPC_SERVER_ADDR`	NPS 桥接地址，包含端口	`nps.example.com:8024`
`NPC_SERVER_VKEY`	客户端验证密钥	Web 管理中该客户端的密钥

Shell 示例：

采集 NPS 与 NPC 性能分析数据

Mon, 01 Jan 0001 00:00:00 +0000

pprof 提供 CPU、堆内存、协程、锁等运行时数据，适合诊断 NPS/NPC CPU 异常、内存增长或协程阻塞。它默认关闭，接口没有登录认证，不能直接暴露到公网。

NPS 服务端

在 nps.conf 中只监听回环地址，然后重启 NPS：

调整 NPC 断线检测时间

Mon, 01 Jan 0001 00:00:00 +0000

NPS 与 NPC 的多路复用数据桥接每 5 秒发送一次探测包。disconnect_timeout 表示允许连续未收到探测响应的次数，不是秒数；默认 60，约 5 分钟后判定桥接失效。

检测 NAT 类型并评估 P2P 直连条件

Mon, 01 Jan 0001 00:00:00 +0000

NPC 可以通过 STUN 检测当前网络的 NAT 类型。这项结果适合在配置 P2P 连接前做初步判断，不代表两端一定能建立直连。

开始检测

在将要运行 NPC 的设备和网络中执行：

检查 npc.conf 中的隧道是否在运行

Mon, 01 Jan 0001 00:00:00 +0000

NPC 的 status 命令用本地 npc.conf 连接 NPS，然后逐项显示配置文件中的隧道是否已在 NPS 上创建或运行。它适合排查“NPC 已启动，但某条配置没有生效”的问题。

运行前提

NPC 使用 npc.conf 模式启动，而不是只传入 -server 和 -vkey。
配置文件中的 [common] 包含正确的 server_addr、vkey 和 conn_type。
运行中的配置模式 NPC 至少成功连接过一次，并写入状态命令所需的临时验证信息。

在 NPC 所在主机执行：

让 NPC 通过 HTTP 或 SOCKS5 代理连接 NPS

Mon, 01 Jan 0001 00:00:00 +0000

当 NPC 所在网络只允许通过企业代理访问外部地址时，可以让 NPC 先连接上游 HTTP 或 SOCKS5 代理，再由代理连接 NPS 的桥接端口。

这里配置的是 NPC 出站代理，不是对外提供 HTTP 正向代理或 SOCKS5 隧道。

在群晖 NAS 上运行 NPC

Mon, 01 Jan 0001 00:00:00 +0000

在支持 Container Manager 的群晖 NAS 上，建议使用 NPC 容器。官方镜像提供 linux/amd64、linux/arm 和 linux/arm64 平台；实际可用性仍取决于 NAS 型号、DSM 版本以及 Container Manager 支持范围。

用白名单和限频保护 TCP 隧道

Mon, 01 Jan 0001 00:00:00 +0000

NPS 可以在接收 TCP 隧道的新连接时，根据来源 IP 执行以下一种策略：

访问模式	适用场景	新连接处理
公开访问	必须对外公开的 SSH、数据库或其他 TCP 服务	允许所有来源，可按每个来源 IP 限制新连接频率
仅白名单访问	只允许办公网、VPN 出口或固定管理设备访问	只允许命中 IP/CIDR 白名单的来源，不再执行新连接限频

该功能只作用于 mode=tcp 的普通 TCP 隧道。隧道内可以承载 SSH、HTTP、HTTPS 或数据库协议，但 HTTP(S) 域名隧道、HTTP 正向代理、SOCKS5、UDP、P2P、私密代理、NPC 接入和 Web 管理都不在适用范围内。

HTTP 响应缓存（未实现）

Mon, 01 Jan 0001 00:00:00 +0000

nps.conf 保留了 HTTP(S) 隧道的内存缓存配置：

http_cache=true
http_cache_length=100

http_cache_length 表示最多保留的缓存条目数，使用 LRU 淘汰；0 表示不限制条目数。修改后需要重启 NPS。

当前版本状态

当前版本不会填充可供后续请求命中的响应缓存。因此即使开启以上参数，也不能把它作为可用的静态文件缓存功能部署。

扩展功能配置指南 on NPS Plus

向 HTTP 后端传递访问者真实 IP

Web 配置何时生效

生效范围

推荐操作

查看客户端的出口与内网地址

使用方法

查看和保存隧道流量统计

统计口径

查看客户端当前传输速度

如何读取

查看 NPC 版本与兼容性

当前兼容行为

提高 Linux 并发连接容量

防止 Web 管理登录被暴力破解

加密 NPC 与 NPS 之间的连接

服务端配置

为 NPC 连接 NPS 配置证书

为 HTTP(S) 站点设置访问密码

配置方式

改写 HTTP 后端收到的 Host

新增或覆盖 HTTP 后端请求头

自定义 HTTP 隧道的 404 页面

自定义方法

限制客户端可累计使用的流量

开启并配置

限制客户端的传输速度

开启并配置

将新连接轮询到多个后端

Web 配置

自动分配服务端监听端口

分配规则

复制普通隧道配置

复制内容

向 TCP 后端传递访问者真实 IP

方案选择

在 NPS 中启用

限制隧道可使用的服务端端口

批量映射 TCP 或 UDP 端口

配置示例

批量映射到其他内网主机

使用 UDP/KCP 连接 NPS

服务端配置

用泛域名转发多个子域名

配置步骤

按 URL 路径选择不同后端

配置示例

限制客户端的并发连接数

限制客户端可创建的隧道数

开启并配置

让桥接、站点与管理端共用一个端口

用一条桥接连接承载多个隧道

用环境变量启动 NPC

支持的变量

采集 NPS 与 NPC 性能分析数据

NPS 服务端

调整 NPC 断线检测时间

检测 NAT 类型并评估 P2P 直连条件

开始检测

检查 npc.conf 中的隧道是否在运行

运行前提

让 NPC 通过 HTTP 或 SOCKS5 代理连接 NPS

在群晖 NAS 上运行 NPC

用白名单和限频保护 TCP 隧道

HTTP 响应缓存（未实现）

当前版本状态