扩展功能配置指南

• 1: 向 HTTP 后端传递访问者真实 IP
• 2: Web 配置何时生效
• 3: 查看客户端的出口与内网地址
• 4: 查看和保存隧道流量统计
• 5: 查看客户端当前传输速度
• 6: 查看 NPC 版本与兼容性
• 7: 提高 Linux 并发连接容量
• 8: 防止 Web 管理登录被暴力破解
• 9: 加密 NPC 与 NPS 之间的连接
• 10: 为 NPC 连接 NPS 配置证书
• 11: 为 HTTP(S) 站点设置访问密码
• 12: 改写 HTTP 后端收到的 Host
• 13: 新增或覆盖 HTTP 后端请求头
• 14: 自定义 HTTP 隧道的 404 页面
• 15: 限制客户端可累计使用的流量
• 16: 限制客户端的传输速度
• 17: 将新连接轮询到多个后端
• 18: 自动分配服务端监听端口
• 19: 复制普通隧道配置
• 20: 向 TCP 后端传递访问者真实 IP
• 21: 限制隧道可使用的服务端端口
• 22: 批量映射 TCP 或 UDP 端口
• 23: 批量映射到其他内网主机
• 24: 使用 UDP/KCP 连接 NPS
• 25: 用泛域名转发多个子域名
• 26: 按 URL 路径选择不同后端
• 27: 限制客户端的并发连接数
• 28: 限制客户端可创建的隧道数
• 29: 让桥接、站点与管理端共用一个端口
• 30: 用一条桥接连接承载多个隧道
• 31: 用环境变量启动 NPC
• 32: 采集 NPS 与 NPC 性能分析数据
• 33: 调整 NPC 断线检测时间
• 34: 检测 NAT 类型并评估 P2P 直连条件
• 35: 检查 npc.conf 中的隧道是否在运行
• 36: 让 NPC 通过 HTTP 或 SOCKS5 代理连接 NPS
• 37: 在群晖 NAS 上运行 NPC
• 38: 用白名单和限频保护 TCP 隧道
• 39: HTTP 响应缓存（未实现）

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

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

开启来源头

在服务端 nps.conf 中设置：

http_add_origin_header=true

重启 NPS 后生效。NPS 会在转发请求时设置：

• X-Forwarded-For：保留已有链路并在末尾追加 NPS 实际看到的来源地址。
• X-Real-IP：设置为 NPS 生成的来源地址内容。

该功能只适用于 NPS 能解析 HTTP 的流量。HTTPS 隧道必须在 NPS 上配置证书并由 NPS 终止 TLS；未配置证书时是 TLS 透传，NPS 无法插入请求头。原始 TCP 服务请使用 PROXY 协议 。

配置后端反向代理

不要无条件信任公网传入的 X-Forwarded-For。下面的 127.0.0.1 应替换为后端实际看到的直接上游地址：目标服务与 NPC 同机时通常是回环地址，目标在另一台内网主机时通常是 NPC 的内网地址。

Nginx

确保 Nginx 包含 http_realip_module，在 http、server 或对应 location 中配置：

set_real_ip_from 127.0.0.1; # 只信任 NPC 到后端的来源地址
real_ip_header X-Forwarded-For;
real_ip_recursive on;

log_format with_real_ip '$remote_addr proxy=$realip_remote_addr "$request"';
access_log /var/log/nginx/access.log with_real_ip;

应用读取 $remote_addr 即可得到解析后的访问者地址，$realip_remote_addr 保留直接上游地址。检查并重载配置：

nginx -t && nginx -s reload

Apache HTTP Server

启用 mod_remoteip，然后在虚拟主机中配置：

RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxy 127.0.0.1

LogFormat "%a proxy=%{c}a %l %u %t \"%r\" %>s %b" nps_real_ip
CustomLog logs/access_log nps_real_ip

Debian/Ubuntu 可先执行 a2enmod remoteip。检查并平滑重载：

apachectl configtest && apachectl graceful

%a 是处理后的访问者地址，%{c}a 是连接到 Apache 的直接上游地址。

Caddy

Caddy 需要把 NPC 的地址声明为可信代理，并严格从右向左解析转发链：

{
    servers {
        trusted_proxies static 127.0.0.1/32
        trusted_proxies_strict
    }
}

internal.example.com {
    reverse_proxy 127.0.0.1:8080
}

检查并平滑加载：

caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfile

应用或日志可使用 Caddy 的 {client_ip} 占位符取得解析后的地址。

验证与排障

先让后端临时输出请求头，再从另一网络发起请求：

curl -H 'X-Forwarded-For: 198.51.100.123' https://your-domain.example/

正确配置时，后端识别出的地址应是实际访问端，而不是伪造的 198.51.100.123、NPC 地址或回环地址。若仍看到 NPC 地址，请依次检查：NPS 是否已重启、HTTPS 是否在 NPS 终止、可信代理地址是否填写为后端实际看到的直接上游，以及前方 CDN/负载均衡器是否另有可信代理链配置。

2 - Web 配置何时生效

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

生效范围

推荐操作

1. 修改前记录原值和隧道 ID。
2. 保存后从新的连接验证，不要只观察已有 SSH、WebSocket 或数据库长连接。
3. 涉及监听端口、协议或客户端连接参数时安排维护窗口。
4. 修改 nps.conf 后重启 NPS；修改 npc.conf 后重启或重连 NPC。

“热更新”不表示所有配置都无损切换。尤其是普通隧道编辑会重新创建监听，启动失败时应检查端口占用、端口白名单 和 NPS 日志。

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

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

使用方法

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

• 确认多个 NPC 是否从预期网络接入。
• 选择后端反向代理的可信上游地址，参见获取用户真实 IP 。
• 排查双网卡、VPN、容器网络导致的路由选择问题。

出口地址是 NPS 视角的连接来源，不等于 NPC 主机的公网查询结果；经过 NAT、四层代理或负载均衡时，显示的可能是中间设备地址。内网地址只展示 NPC 选出的一个 IPv4；旧版 NPC 不支持上报时该字段可能为空，升级并重新连接即可再次采集。

4 - 查看和保存隧道流量统计

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

统计口径

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

• TCP/IP、TLS、KCP 等协议开销。
• 客户端压缩或加密前后的大小变化。
• 重传、握手、探测包以及未进入正常转发的数据。
• 部署在 NPS 前方的 CDN 或反向代理缓存直接返回的数据，因为请求没有进入 NPS。

做容量或计费核对时，应同时查看主机网卡和云平台监控。

持久化

流量计数默认只在内存中维护。需要在服务端重启后保留时，在 nps.conf 设置保存间隔，单位为分钟：

flow_store_interval=1

设置为正整数并重启 NPS 后生效；留空、无效值或 0 不启动定时持久化。通过公共验证密钥临时连接的客户端不会持久化。

验证

选择一条空闲隧道传输一个已知大小的文件，刷新客户端列表和隧道列表，确认计数持续增加。不要期望页面值与文件大小或网卡字节数完全一致；若完全不变化，请确认请求确实命中了该隧道，并检查隧道运行状态和 NPS 日志。

5 - 查看客户端当前传输速度

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

如何读取

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

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

6 - 查看 NPC 版本与兼容性

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

当前兼容行为

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

兼容放行不代表所有新字段都能被旧版识别。例如旧版 NPC 不会上报内网地址，也可能不支持后来增加的配置字段。服务端与客户端跨较大版本运行时，常见表现是部分功能缺失，而不是握手立即失败。

升级建议

1. 在客户端列表记录在线 NPC 的版本和客户端验证密钥。
2. 阅读目标版本更新日志，先升级一台非关键 NPC 验证。
3. 优先让 NPS 与 NPC 使用同一发行版本；需要分批升级时，缩短混用周期。
4. 升级后检查客户端在线状态，并逐项验证 TCP、UDP、HTTP(S)、P2P 等实际使用的隧道。

命令行可查看本机二进制版本：

./nps -version
./npc -version

如果 Web 显示的版本未更新，确认旧 NPC 进程已经退出，系统服务实际指向了新二进制，然后重新连接。

7 - 提高 Linux 并发连接容量

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

先检查现状

ulimit -n
sysctl net.core.somaxconn net.ipv4.tcp_max_syn_backlog
ss -s
cat /proc/sys/fs/file-nr

常见日志包括 too many open files、监听队列溢出或大量连接停留在异常状态。先估算 NPS、NPC、目标服务以及监控进程共同需要的文件描述符数量。

文件描述符

使用 systemd 运行 NPS 时，在服务覆盖配置中设置，而不是只修改当前终端的 ulimit：

# systemctl edit nps
[Service]
LimitNOFILE=1048576

应用并重启服务：

systemctl daemon-reload
systemctl restart nps
cat /proc/$(pidof nps)/limits | grep 'open files'

实际服务名可能不同，请以安装时注册的 unit 为准。

监听队列

可按压测结果建立 /etc/sysctl.d/99-nps.conf：

net.core.somaxconn = 4096
net.ipv4.tcp_max_syn_backlog = 8192

然后执行：

sysctl --system

somaxconn 限制已完成握手的监听队列，tcp_max_syn_backlog 影响尚未完成握手的 SYN 队列。数值应结合内存、连接速率和攻击面压测确定，不建议照搬极端配置。

排障边界

• 大量出站连接失败时检查本机临时端口范围和 TIME_WAIT，不要先启用危险的连接复用参数。
• 使用容器时还要检查容器的 nofile 限制、宿主机 conntrack 和端口发布规则。
• SYN flood 应由防火墙、云安全组或专业防护处理，内核队列调大不是访问控制。
• NPS 的客户端最大连接数 是应用级保护，不能替代系统容量限制。

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

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

开启验证码

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

open_captcha=true

开启后，登录请求必须先通过图形验证码，再校验用户名和密码。验证码和失败次数限制应同时使用。

部署建议

• 不要把管理端直接暴露给整个公网；优先使用防火墙白名单、VPN 或反向代理访问控制。
• 首次启动会生成随机管理密码，应妥善保存并替换历史弱口令。
• 使用反向代理时确认 NPS 看到的来源地址符合预期。当前登录限制按 TCP 连接来源计数；若所有用户都经同一代理地址访问，他们会共享失败计数。
• 为 Web 管理启用 HTTPS，避免凭据和会话在网络中明文传输。

被临时限制时

停止重复尝试并等待最后一次失败后至少 60 秒，再使用正确凭据登录。若合法用户经共享出口频繁触发限制，应修复错误保存的密码或自动探测任务，而不是关闭验证码或扩大公网暴露范围。

9 - 加密 NPC 与 NPS 之间的连接

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

服务端配置

在 nps.conf 中设置：

bridge_type=tcp
bridge_port=8024
tls_enable=true
tls_bridge_port=8025

重启 NPS，并在防火墙放通 tls_bridge_port 的 TCP 入站流量。TLS 监听与普通 bridge_port 并存；确认所有 NPC 已迁移后，如不需要明文桥接，可在防火墙关闭普通桥接端口。

TLS 桥接只用于 TCP 桥接模式。bridge_type=kcp 时不会启动独立 TLS 监听。

客户端连接

使用默认自签名证书时，先从可信的 NPS 启动日志获取 64 位公钥指纹，或直接复制 Web 管理中新生成的 TLS 连接命令。无配置文件模式：

./npc -server=nps.example.com:8025 -vkey=客户端验证密钥 \
  -tls_enable=true -tls_server_fingerprint=替换为服务端实际公钥指纹

配置文件模式：

[common]
server_addr=nps.example.com:8025
conn_type=tcp
vkey=客户端验证密钥
tls_enable=true
tls_server_fingerprint=替换为服务端实际公钥指纹

服务端和客户端必须成对使用 TLS 端口与 tls_enable=true。把 TLS 客户端连到普通桥接端口，或把明文客户端连到 TLS 端口，都会在握手阶段失败。

安全边界

NPS 默认生成并持久化自签名证书，重启复用身份。NPC 默认校验服务端证书，可选择系统 CA、指定私有 CA 或固定公钥指纹。公共 CA 证书且域名匹配时可省略指纹参数；自签名名称模式、证书文件路径、GUI 和旧版迁移详见桥接证书与身份验证 。

显式启用 tls_insecure_skip_verify=true 会恢复旧版只加密、不验证身份的行为。TLS 桥接与普通明文桥接同时监听，TLS 本身不会关闭明文入口。最低支持 TLS 1.2，双方支持时协商 TLS 1.3。

连接后可在客户端列表确认 NPC 在线，并检查 NPS 日志中的 TLS 监听端口。若连接失败，依次核对 TCP 连通性、两端 TLS 开关、端口以及 bridge_type。

10 - 为 NPC 连接 NPS 配置证书

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

开启 TLS（保护网络通信的加密协议）后，NPC 默认会验证服务端身份，也就是确认连到的是你信任的 NPS。这里最低支持 TLS 1.2；NPC 和 NPS 都支持 TLS 1.3 时，会使用 TLS 1.3。

如果还没开启加密连接，请先看加密 NPC 与 NPS 之间的连接 。本页配置的是 TLS 桥接端口（NPS 专门接收 NPC 加密连接的入口，通常为 8025）使用的证书。网页管理页面的 web_cert_file、web_key_file，以及按域名转发的网站所用的证书，需要在各自的设置中配置。

先选择适合你的方式

公钥（证书中可以公开的密钥）与私钥（需要由服务端保密的配套密钥）配合使用，让服务端证明自己的身份。公钥指纹（根据公钥计算出的一串识别码）用于核对服务端出示的公钥是否与你预先保存的一致。

没有准备证书时，可以按“让 NPS 自动生成并保存证书 ”和“使用公钥指纹确认服务端 ”两节配置。相关名词也可查阅术语表 。

在 NPS 中配置证书

使用已有证书

在服务端的 nps.conf 中填写证书文件和私钥文件的路径。下面使用 TCP（按顺序可靠传送数据的网络协议）连接，路径仅为示例，请替换为实际文件的位置：

bridge_type=tcp
tls_enable=true
tls_bridge_port=8025
tls_cert_file=/etc/letsencrypt/live/nps.example.com/fullchain.pem
tls_key_file=/etc/letsencrypt/live/nps.example.com/privkey.pem

文件需要使用 PEM（用文本保存证书或密钥的格式）。证书文件应包含证书链（一组前后关联、用于证明证书来源的证书）：第一张是签发给 NPS 的证书，后面依次放中间证书（连接服务端证书与受信任 CA 的证书）。证书提供方通常会给出合并好的文件，例如 fullchain.pem。

证书的 SAN（记录证书适用于哪些域名或 IP 地址的字段）应包含 NPC 要验证的地址。例如，用 nps.example.com 验证时，证书需要包含这个域名（便于记忆的网络名称）；用 203.0.113.10 验证时，则需要包含这个 IP 地址（设备在网络上的地址）。

填写路径时，建议使用绝对路径（完整写出文件位置的路径），例如上面的 /etc/letsencrypt/...。如果使用相对路径（从某个目录开始查找文件的路径），例如 conf/tls/bridge.pem，NPS 会从它的运行目录（存放 conf 文件夹的目录）开始查找。启动日志中 the config path is: 后面的路径就是这个目录，详情见配置文件位置 。

tls_cert_file 和 tls_key_file 必须一起填写。如果文件找不到、内容无法读取为证书或私钥、证书与私钥不配套，NPS 会报错并退出。服务端证书尚未生效、已经过期，或证书限定的用途不允许用于证明服务端身份时，也会报错退出。

NPS 在启动时读取证书。 更新或替换证书文件后，需要重启 NPS。读取失败时，NPS 会保留文件供你检查，不会改用临时生成的证书。

让 NPS 自动生成并保存证书

在 nps.conf 中开启 TLS，并让 tls_cert_file 和 tls_key_file 都留空：

bridge_type=tcp
tls_enable=true
tls_bridge_port=8025
tls_cert_file=
tls_key_file=

首次启动时，NPS 会在运行目录中创建这两个文件：

conf/tls/bridge.pem
conf/tls/bridge.key

bridge.pem 保存证书，bridge.key 保存私钥。以后重启时会继续使用这两个文件，公钥指纹也保持不变。请备份这两个文件，并妥善保管私钥。

如果使用 Docker（将应用放在称为“容器”的独立环境中运行的工具），需要为整个 conf 目录设置挂载（把容器中的目录对应到容器外的存储位置）。这样替换容器后，原来的证书和私钥仍然可用。

自动生成的证书有以下设置：

• 使用 RSA（一种生成和使用公钥、私钥的算法），密钥长度为 2048 位，证书有效期为 365 天。
• CN（证书中的通用名称）填写 localhost（表示本机的名称）；O（组织名称）和 C（国家）留空。
• SAN 包含 localhost、127.0.0.1 和 ::1。这些名称和地址都表示本机，不包含你实际使用的远程服务端地址，因此建议按下文的公钥指纹方式验证。
• 文件权限为 0600（普通账号中只有文件所有者可以读写），新建目录权限为 0700（普通账号中只有目录所有者可以进入、读取和修改）。Windows 上需要另行检查文件和目录的访问权限。

如果文件损坏，或两个文件只剩下一个，NPS 会报错并保留现有文件，等待你处理。证书到期后，也需要你更新或替换证书；NPS 不会自动更换密钥，以免 NPC 中保存的指纹突然失效。

可选：更改自动生成证书中的名称

这个设置决定新生成的自签名证书填写什么名称。通常保持默认值即可。在 nps.conf 中设置：

# 默认设置：通用名称 CN 填写 localhost，组织名称 O 留空
tls_self_signed_name_mode=standard

如果希望 CN 和 O 使用随机名称，可以改为：

tls_self_signed_name_mode=random

random 会用适合安全用途的随机数，分别生成 CN 和 O。两个名称各有 32 个十六进制字符（由数字 0–9 和字母 a–f 组成），各自独立生成。两种设置都不会填写 NPS Org 或 My Company Name LTD.。如果你使用的是已有证书，NPS 会保留证书原有的名称和其他内容。

此设置只在生成新证书时生效。如果证书已经存在，只修改设置并重启，名称不会改变。要更改已有自签名证书中的名称，请按顺序操作：

1. 选择允许暂时断开连接的时间，停止 NPS。
2. 备份 conf/tls/bridge.pem 和 conf/tls/bridge.key，再把原文件移到其他目录。
3. 在 nps.conf 中填写需要的名称设置，然后启动 NPS。
4. 从 NPS 启动日志获取新指纹，并更新使用指纹验证的 NPC。

重新生成时会同时更换公钥和私钥，原来的指纹将失效。更改名称只能去掉证书中的默认产品名称，不能保证别人认不出这是 NPS。任何能连接这个 TLS 端口的人，都可以在建立连接时取得服务端证书；使用 TLS 1.3 也一样。

在 NPC 中选择验证方式

下列设置可以写在 npc.conf 的 [common] 下方，也可以作为命令行参数（启动程序时附加的设置）使用。命令行写法需要在名称前加 -，例如 -tls_enable=true。true 表示开启，false 表示关闭。

请留意以下填写规则：

• 使用这些验证设置前，需要先设置 tls_enable=true。
• tls_ca_file 和 tls_server_fingerprint 不能同时填写。
• 设置 tls_insecure_skip_verify=true 时，tls_ca_file、tls_server_name 和 tls_server_fingerprint 都必须留空。

指纹格式错误、CA 文件无法读取或不含可用证书、同时填写了不能一起使用的选项，都会报错。开关值填写错误也会报错，请按示例使用 true 或 false。遇到这些错误时，NPC 会停止连接，等待你修正设置。

下面示例中的域名、IP 地址和文件路径都需要换成你自己的值。vkey 填客户端验证密钥（NPC 接入 NPS 时使用的连接凭据，可在网页管理的客户端列表中查看）。

使用公共 CA 证书

如果 NPS 使用的证书由操作系统信任的公共 CA 签发，并且证书包含 nps.example.com，可直接使用该域名连接：

./npc -server=nps.example.com:8025 -vkey=客户端验证密钥 -tls_enable=true

如果通过 IP 地址连接，而证书只包含域名，则用 tls_server_name 填写证书上的域名：

./npc -server=203.0.113.10:8025 -vkey=客户端验证密钥 \
  -tls_enable=true -tls_server_name=nps.example.com

上面的命令仍然连接 203.0.113.10:8025，只是检查证书是否适用于 nps.example.com。

验证名称是域名时，NPC 还会发送 SNI（建立加密连接时，告诉服务端自己要访问哪个域名的信息），方便服务端选择对应证书。名称是 IP 地址时，不发送 SNI。如果没有填写 tls_server_name，就使用连接地址中的域名或 IP 地址。

使用私有 CA 证书

如果证书由你自己或组织内部的 CA 签发，需要把该 CA 的证书文件放到 NPC 所在设备上，再填写 tls_ca_file。例如，在 npc.conf 中配置：

[common]
server_addr=203.0.113.10:8025
conn_type=tcp
vkey=客户端验证密钥
tls_enable=true
tls_ca_file=certs/root-ca.pem
tls_server_name=nps.example.com

这里的 certs/root-ca.pem 是 CA 证书文件的相对路径。NPC 会从 npc.conf 所在目录开始查找。例如，配置文件在 /etc/nps/npc.conf 时，就会读取 /etc/nps/certs/root-ca.pem。

如果从命令行或 GUI（通过窗口和按钮操作的图形客户端）填写路径，则从程序的当前工作目录（程序查找相对路径时使用的目录）开始查找。建议填写完整的绝对路径，避免因启动方式不同而找不到文件。

NPC 会检查证书是否由所信任的 CA 签发、是否在有效期内、是否允许用于证明服务端身份，以及 SAN 是否包含需要验证的域名或 IP 地址。

使用公钥指纹确认服务端

使用 NPS 自动生成的自签名证书时，建议选择这种方式。NPC 会计算收到的证书的公钥指纹，并与事先保存的指纹比较。

先登录你自己的 NPS 服务器，查看启动日志，找到下面这一行：

bridge TLS public-key SHA-256 fingerprint: <64个十六进制字符组成的指纹>

复制冒号后面的完整指纹，填入 NPC 配置。也可以从你确认可信的 NPS 管理页面获取。指纹必须来自你自己的服务端或管理员，否则就失去了核对身份的意义。

[common]
server_addr=nps.example.com:8025
conn_type=tcp
vkey=客户端验证密钥
tls_enable=true
tls_server_fingerprint=替换为服务端实际输出的64个字符的指纹

使用指纹验证时，可以通过域名或 IP 地址连接，也可以使用自签名证书。NPC 仍会检查证书有效期，以及证书是否允许用于证明服务端身份。

默认只核对公钥和上述证书条件。如果还希望检查证书适用的域名或 IP 地址，可以再填写 tls_server_name；此时 SAN 中必须包含填写的名称或地址。指纹不匹配时，NPC 会拒绝连接。

证书到期后，如果用原来的公钥重新签发，指纹保持不变；如果更换了公钥和私钥，就需要更新 NPC 中保存的指纹。

如果前置代理（放在 NPS 前面、代为接收连接的服务器）负责与 NPC 建立 TLS 加密连接，那么 NPC 收到的是代理提供的证书。此时应填写代理证书的公钥指纹。

可选：从证书文件计算指纹

通常直接复制 NPS 启动日志中的指纹即可。如果需要自己计算，可以使用 OpenSSL（处理证书和加密连接的命令行工具），在服务端执行：

openssl x509 -in conf/tls/bridge.pem -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256

请把命令中的路径替换为实际证书路径。三行命令需要一起执行：先提取公钥，再转换格式，最后计算指纹。取最后输出中的 64 个十六进制字符，填入 tls_server_fingerprint。

这里的计算方式写作 SHA-256(DER SubjectPublicKeyInfo)：SHA-256（将数据计算成固定长度识别值的算法）处理的是 DER（二进制数据编码格式）保存的 SubjectPublicKeyInfo（证书中记录公钥及其算法的部分）。需要计算的是这部分公钥信息的指纹，不是整张证书的指纹。

使用快捷连接码或图形客户端

在网页管理的客户端列表中，可以复制 TLS 连接命令或快捷连接码（将地址、验证密钥等设置打包成一段文字，供 NPC 导入）。新生成的命令和连接码都包含当前桥接证书的公钥指纹。

直接复制管理页面提供的完整连接码即可。它使用 Base64（把数据转换成一段便于复制的文字的编码方式）保存以下内容，各项用 | 分隔：

nps:<备注>|<地址:端口>|<vkey>|true|<公钥指纹>

其中 vkey 是客户端验证密钥，true 表示开启 TLS。Base64 不会对这些内容加密，连接码中包含验证密钥，请妥善保管。

新版命令行客户端、通过交互菜单注册的系统服务（由操作系统管理、在后台运行的程序），以及图形客户端，都会保留导入的指纹。

旧连接码只有备注、地址、验证密钥和 TLS 开关四项，没有公钥指纹。新版 NPC 仍能读取，但使用自签名证书时需要补充验证设置。最方便的做法是从自己的管理页面重新复制 TLS 连接码。如果使用公共 CA 证书，也可以按前面的命令行示例连接，无需填写指纹。

在图形客户端中手工添加连接时，先启用 TLS，再根据所选方式填写公钥指纹或 CA 文件，需要时填写证书域名。每个连接分别保存自己的验证设置。已有连接需要更换指纹或 CA 文件时，可以删除该连接，再用新的连接码或设置重新添加。

通过代理连接及其他连接方式

使用出站代理（NPC 借助另一台服务器连接 NPS）时，可以选择 HTTP CONNECT（让 HTTP 代理建立到目标地址的转发连接）或 SOCKS5（通过代理转发网络连接的协议）。代理连通目标后，NPC 仍会与 NPS 进行 TLS 握手（建立加密连接前，交换证书并确定加密方式的过程），并按你配置的方式验证证书。SNI 中填写的域名也仍然是 NPS 的域名。具体设置见让 NPC 通过代理连接 NPS 。

本页的 TLS 加密连接只支持 TCP。KCP（另一种网络传输协议，NPS 可用它连接客户端和服务端）不支持这种连接方式。NPC 同时启用 KCP 和这里的 TLS 设置时，会报错。

crypt=true 是隧道（把外部访问转发到目标服务的规则）原有的数据加密选项，它不会单独验证 NPS 身份。要确认连到的是自己的 NPS，需要开启本页介绍的 TLS 桥接。

从旧版本升级

旧版 NPC 默认不检查服务端证书，新版默认会检查。如果之前使用的是 NPS 临时生成的自签名证书，建议按顺序操作：

1. 升级 NPS，启动后确认 conf/tls/ 下已经生成证书和私钥，并备份这两个文件。
2. 从 NPS 启动日志获取公钥指纹。
3. 升级 NPC，填写 tls_enable=true 和 tls_server_fingerprint，重新连接。

旧版 NPC 可以连接新版 NPS，但只升级 NPS 不会让旧版 NPC 开始验证证书。

升级过程中，如果确实需要暂时沿用旧版的连接方式，可以设置 tls_insecure_skip_verify=true，并将 CA 文件、证书名称和指纹三项留空。此时连接仍然加密，但 NPC 无法确认对方是不是你的 NPS。完成升级后，应改回 false，再按所选方式配置 CA 验证或指纹验证。

检查是否配置成功

先使用正确的配置连接，在网页管理的客户端列表中确认 NPC 在线。再根据所选验证方式检查以下情况；需要更换证书的测试，请在测试环境中进行：

如果需要查看服务端实际发来了什么证书，可以使用 OpenSSL：

openssl s_client -connect nps.example.com:8025 -servername nps.example.com -showcerts

把命令中的地址、端口和域名换成实际值。这个命令用于查看建立 TLS 连接时收到的证书，不会提交 NPS 要求的客户端验证密钥，因此不能用它判断 NPC 是否能完整登录。

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

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

配置方式

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

• 代理认证用户名
• 代理认证密码

两项均留空时不使用这组凭据；只有用户名和密码都非空时才启用认证。配置属于客户端，因此该客户端下的 HTTP(S) 隧道以及 HTTP 正向代理会共用同一组凭据，而不是每个域名单独设置。

使用公共验证密钥、由 npc.conf 注册临时客户端时，可在 [common] 中设置：

[common]
basic_username=preview
basic_password=请替换为高强度随机密码

修改配置文件后重新连接 NPC。对于已经在 Web 管理中创建的客户端，以 Web 保存的代理认证用户名和密码为准，npc.conf 中的同名字段不会覆盖服务端客户端设置。

访问和验证

未认证访问会收到 401 Unauthorized 和 Basic challenge；HTTP 正向代理使用同一凭据时返回的是 407 Proxy Authentication Required。测试站点：

curl -i https://preview.example.com/
curl -i -u 'preview:实际密码' https://preview.example.com/

第一次应为 401，第二次应到达后端。HTTPS 必须在 NPS 上终止 TLS 才能读取认证头；未配置站点证书的 TLS 透传流量无法使用这项 HTTP 认证。

Basic Auth 只编码、不加密凭据，必须配合 HTTPS。它适合低风险临时保护，不代替应用自身的账号、权限、审计和多因素认证。

12 - 改写 HTTP 后端收到的 Host

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

配置

在 Web 管理中新增或编辑 HTTP(S) 隧道：

保存后，新请求转发到后端时将使用：

Host: app.internal.example

留空会保留访问者原始的 Host。只填写主机名；后端确实按非标准端口区分虚拟主机时才加入 :端口。

配置文件模式可使用：

[preview]
host=preview.example.com
target_addr=192.168.1.20:8080
host_change=app.internal.example

验证与限制

可在后端访问日志中加入 $host / %v，或临时运行回显服务检查 Host。该设置只修改转发的 HTTP 请求头，不修改公网 DNS、TLS SNI 或浏览器地址栏；TLS 透传时 NPS 无法解析和改写 HTTP Host。若后端仍返回默认站点，检查站点规则的协议、证书终止方式以及后端虚拟主机配置。

13 - 新增或覆盖 HTTP 后端请求头

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

Web 配置

新增或编辑 HTTP(S) 隧道，在“改写请求头”中每行填写一个 名称: 值：

X-Environment: preview
Cache-Control: no-cache
X-Forwarded-Proto: https

保存后对新请求生效。配置使用覆盖语义，同名的访客请求头会被替换。

NPC 配置文件

配置文件使用 header_ 前缀：

[preview]
host=preview.example.com
target_addr=127.0.0.1:8080
header_X-Environment=preview
header_Cache-Control=no-cache

修改后重新连接 NPC。

限制与安全

• 只改写请求头，不改写后端响应头。
• 每行必须恰好包含一个冒号；值中还需要冒号的复杂字段不适合在这里配置。
• HTTPS 必须在 NPS 终止 TLS；透传流量不可改写。
• 不要把用户可控内容写入 Authorization、Cookie 等安全敏感字段，也不要用固定请求头代替真正的身份认证。
• 真实来源地址应使用专门的获取用户真实 IP 配置，不要手工写死。

可让后端临时输出收到的请求头，或使用访问日志验证。若未生效，检查是否命中了预期的域名和 URL 路径规则。

14 - 自定义 HTTP 隧道的 404 页面

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

web/static/page/error.html

自定义方法

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

go build -o nps ./cmd/nps

然后重启 NPS。建议保持页面为自包含 HTML，例如：

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>服务暂不可用</title>
  </head>
  <body>
    <h1>服务暂不可用</h1>
    <p>请稍后重试。</p>
  </body>
</html>

注意事项

• 错误页是全局资源，所有 HTTP 隧道共用，不能按域名单独设置。
• 不要依赖相对路径 CSS、图片或脚本；这些请求仍需经过域名路由，故障时可能同样不可用。
• 不要在页面中暴露内网地址、客户端验证密钥或具体堆栈信息。
• 未匹配到域名规则的请求不保证返回该模板；应由前置反向代理提供默认站点或兜底响应。
• HTTPS 入口目前不能可靠返回这份自定义正文；TLS 透传失败时通常只能关闭连接。

部署后使用一个存在的 HTTP 域名规则，临时停止其 NPC 或填写不可达目标，确认状态码、正文和字符集符合前端监控预期。

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

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

开启并配置

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

allow_flow_limit=true

然后在 Web 管理中新增或编辑客户端，填写“流量限制”，单位为 MiB：

1024 MiB = 1 GiB = 1,073,741,824 字节

留空或填 0 表示不限制。使用公共验证密钥、由 npc.conf 注册临时客户端时，可在 [common] 中写入：

flow_limit=1024

对于已经在 Web 管理中创建的客户端，以 Web 保存的限制为准，npc.conf 中的值不会覆盖它。

达到限制后

NPS 在建立新连接及转发数据时检查客户端累计值。超过配额后，HTTP 隧道返回 404，其他隧道拒绝新连接或关闭失败的连接；正在传输的连接会在后续检查中终止。HTTPS 的具体表现取决于是否由 NPS 终止 TLS。该客户端下所有隧道共享同一配额。

计数来自 NPS 转发层，不等同于云厂商流量账单，详见流量统计 。当前没有周期和自动清零机制，Web 页面也没有一键清零操作。开始新周期时，管理员可通过 Web API 的“编辑客户端”接口 将 flow_inlet 和 flow_export 设为 0。该接口同时保存其他客户端字段，调用前应先读取完整配置并留存审计数据，避免用空值覆盖原配置。

建议先设置较高阈值并观察正常峰值，再逐步收紧。达到限制后，检查客户端列表中的累计流量和 NPS 日志。HTTP 隧道可能返回 404，其他类型的连接可能被拒绝或关闭，不要误判为后端服务故障。

16 - 限制客户端的传输速度

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

开启并配置

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

allow_rate_limit=true

进入 Web 管理，新增或编辑客户端，在“带宽限制”中填写整数。单位以管理端说明为准，是 KiB/s：

1024 KiB/s = 1 MiB/s = 8 Mib/s

留空或填 0 表示不限制。使用公共验证密钥、由 npc.conf 注册临时客户端时可写：

[common]
rate_limit=1024

对于已经在 Web 管理中创建的客户端，以 Web 保存的限制为准，npc.conf 中的值不会覆盖它。

生效行为

限速在 NPS 到 NPC 的转发读写路径上执行，入站和出站共享一个令牌桶。修改 Web 设置后会替换当前客户端的限速器，后续传输立即使用新值，无需重启 NPS。

限速值是客户端聚合上限，不保证每条隧道公平分配；一个大流量连接可能占用大部分额度。TCP 拥塞控制、请求大小和采样窗口也会让瞬时“网速”上下波动。

验证

通过该客户端持续传输足够大的文件，观察当前客户端带宽 ，并在访问端使用 curl、iperf3 或应用自身统计交叉验证。若结果约为预期的八分之一，通常是把 bit/s 与 Byte/s 混淆；若完全未限速，确认修改的是实际承载隧道的客户端，并检查值是否为 0。

17 - 将新连接轮询到多个后端

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

Web 配置

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

192.168.1.21:8080
192.168.1.22:8080
192.168.1.23:8080

HTTP(S) 和 TCP 均使用相同格式。配置文件模式用逗号分隔：

[app]
host=app.example.com
target_addr=192.168.1.21:8080,192.168.1.22:8080,192.168.1.23:8080

[tcp_app]
mode=tcp
server_port=9000
target_addr=192.168.1.21:9000,192.168.1.22:9000

调度边界

• 算法是顺序轮询，不按响应时间、连接数或权重调度。
• TCP 每个新连接选择一次目标；HTTP keep-alive 上的多个请求可能继续使用同一后端，并非严格逐请求平均。
• 选中的目标连接失败时，当前请求不会自动重试下一个目标。
• Web 配置本身不提供主动健康检查。NPC 配置文件支持另行定义健康检查，并在目标失效时暂停向它转发新连接。
• 会话保存在单机内存的应用需要共享会话、无状态令牌或应用层粘性策略，否则登录状态可能在后端间丢失。

NPC 健康检查

配置文件模式可以为 target_addr 中的同一批地址增加 TCP 或 HTTP 检查。例如：

[app]
mode=tcp
server_port=9000
target_addr=192.168.1.21:8080,192.168.1.22:8080

[health_app]
health_check_type=http
health_check_target=192.168.1.21:8080,192.168.1.22:8080
health_http_url=/healthz
health_check_timeout=2
health_check_interval=10
health_check_max_failed=3

HTTP 检查要求返回状态码 200。使用 health_check_type=tcp 时不需要 health_http_url，只验证能否建立 TCP 连接。health_check_target 必须与隧道目标地址保持一致，恢复后目标会重新加入轮询。

验证

让各后端返回不同实例标识，连续建立多个新连接观察是否轮询。测试故障时主动停止一个后端，确认客户端能接受单次连接失败，或在 NPS 前后增加具备健康检查和重试能力的专业负载均衡器。

18 - 自动分配服务端监听端口

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

分配规则

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

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

使用建议

自动分配不会修改云安全组或主机防火墙。保存后复制实际端口，按协议放通入站规则，再从外部网络验证：

# TCP 示例
nc -vz nps.example.com 实际端口

# 查看 NPS 是否监听
ss -lntup | grep ':实际端口'

生产环境需要稳定访问地址时，应记录分配结果，或使用端口白名单 限定专用范围，避免重建隧道后端口变化。

19 - 复制普通隧道配置

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

复制内容

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

• 所属客户端、隧道类型和备注。
• 目标地址、服务端监听 IP 和“由 NPS 服务端连接目标”设置。
• 本地路径、移除的 URL 路径前缀和 PROXY 协议版本。
• TCP 访问控制策略，但不复制运行中的连接计数和自动封禁。

服务端监听端口会按端口自动生成 规则重新分配，流量计数从零开始。

操作后检查

1. 在对应隧道列表点击“复制”。
2. 确认提示复制成功并记录新 ID、实际监听端口。
3. 编辑新隧道的备注或目标，避免后续混淆。
4. 放通新端口的防火墙/安全组，并从外部建立新连接验证。

客户端“最大隧道数”和服务端“端口白名单”仍会校验，达到上限或无可用端口时复制失败。私密代理和 P2P 的“隧道访问密钥”必须全局唯一，而复制会沿用原密钥，因此应改用“新增”并填写新密钥。HTTP(S) 域名规则位于单独列表，不使用普通隧道复制按钮。

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

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

方案选择

在 NPS 中启用

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

• V1：可读文本头，便于抓包排障。
• V2：紧凑二进制头，适合支持 v2 的后端。
• 留空：不发送 PROXY 头，保持普通 TCP 字节流。

NPS 会让 NPC 在连接目标成功后、业务数据之前写入 PROXY 头。目标服务必须从连接的第一个字节开始解析所选版本；不支持时通常会把它当作错误业务数据并断开。启用“由 NPS 服务端连接目标”时不要依赖此功能，应由 NPC 连接后端。

常见后端配置

Nginx HTTP 后端：

server {
    listen 8080 proxy_protocol;
    set_real_ip_from 127.0.0.1; # 后端实际看到的 NPC 地址
    real_ip_header proxy_protocol;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

HAProxy TCP 后端：

frontend from_nps
    bind :9000 accept-proxy
    mode tcp
    default_backend app_nodes

backend app_nodes
    mode tcp
    server app1 127.0.0.1:9001

若 HAProxy 还要把来源继续传给支持 PROXY 的下游，在 server 行增加 send-proxy 或 send-proxy-v2。

验证

先在非生产端口验证。Nginx 可记录 $proxy_protocol_addr，HAProxy 日志可查看客户端地址；也可用 tcpdump 抓取连接开头确认 v1 文本 PROXY ... 或 v2 签名。出现“开启后服务立即断开”时，优先检查后端监听端口是否真的启用了相同版本，而不是修改 NPS 网络参数。

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

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

allow_ports=9001-9009,10001,11000-12000

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

影响范围

• 新增、编辑、启动和复制 TCP、UDP、SOCKS5、HTTP 正向代理等监听型隧道时会检查。
• 端口自动生成 只会从允许集合中挑选空闲端口。
• 已保存但不在新范围内的隧道，在 NPS 重启或再次启动时可能无法监听。
• HTTP(S) 公共入口、Web 管理端口、桥接端口以及不单独监听的私密代理/P2P 不由此项分配。

规划示例

可为 NPS 预留一段专用端口，并在云安全组和主机防火墙中只放通同一范围：

allow_ports=20000-20999

配置后先创建一条自动端口隧道，确认实际端口落在范围内，再分别验证 TCP/UDP 防火墙规则。若提示端口被占用或不再允许，检查 ss -lntup、允许范围和协议；同一个数字的 TCP 与 UDP 端口可以分别监听，但安全组也要分别放通。

22 - 批量映射 TCP 或 UDP 端口

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。

配置规则

• 使用英文逗号分隔单个端口或闭区间，不要加入空格。
• server_port 与 target_port 展开后的数量必须完全相同，否则整组创建失败。
• 端口必须在 1-65535 内，范围起点不能大于终点。
• 此写法只支持 tcp 和 udp。
• 目标未指定主机时使用 NPC 本机 127.0.0.1；映射其他内网主机见跨机器端口范围映射 。

服务端必须允许该客户端“通过配置文件连接”，并且每个服务端端口都要满足端口白名单 、未被占用且已在防火墙放通。

上线与验证

使用配置启动 NPC，日志中每个展开隧道的备注会附加服务端端口。任选首、中、末三个端口从外网验证，不要只测试第一个：

nc -vz nps.example.com 9001
nc -vz nps.example.com 9005
nc -vz nps.example.com 12000

这些隧道由 NPC 配置维护，断开时会从服务端移除。修改范围后应重连 NPC，并检查旧端口是否已停止监听。

23 - 批量映射到其他内网主机

端口范围默认映射到 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。

前置检查

先在 NPC 主机上直接验证目标可达，避免把内网路由或防火墙问题误认为 NPS 故障：

nc -vz 10.1.50.2 8001

目标主机的防火墙应允许来自 NPC 的连接，服务也应监听可被 NPC 访问的地址，而不是只监听目标主机自己的 127.0.0.1。

限制

• target_ip 只在一次配置展开为多个端口时使用；单端口隧道请直接写 target_addr=10.1.50.2:8001。
• 一组范围只能使用同一个目标 IP；多个目标主机请拆成多个配置段。
• server_port 与 target_port 展开数量必须一致，其他格式规则见端口范围映射 。
• DNS 名称不适合作为这里的范围目标；需要名称解析时逐条使用 target_addr 并验证解析环境。

启动后分别测试范围两端，并在目标主机查看连接来源是否为 NPC 主机。

24 - 使用 UDP/KCP 连接 NPS

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

服务端配置

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

bridge_type=kcp
bridge_port=8024

bridge_port 此时是 UDP 端口。需要同时修改云安全组、主机防火墙和容器端口发布，例如 Docker 使用 8024:8024/udp。

客户端配置

无配置文件模式：

./npc -server=nps.example.com:8024 -vkey=客户端验证密钥 -type=kcp

配置文件模式：

[common]
server_addr=nps.example.com:8024
vkey=客户端验证密钥
conn_type=kcp

两端协议必须一致。服务端切换后，所有 NPC 都必须改为 KCP；TCP NPC 无法连接 KCP 监听。

不兼容与排障

• KCP 不能使用基于 TCP 的端口复用 。
• TLS 桥接监听只用于 TCP，不能叠加到 KCP。
• NPC 的 proxy_url 只用于 TCP 代理连接，不解决 UDP/KCP 被阻断的问题。
• 某些运营商、企业防火墙和云平台会限制 UDP，NAT 映射也可能更快失效。

切换前先从 NPC 所在网络测试服务端 UDP 可达，并保留回滚到 TCP 的维护窗口。上线后比较实际业务延迟、丢包、CPU 和重连次数；若日志持续出现 ping timeout，优先恢复 TCP，再排查 UDP 路径和 MTU。

25 - 用泛域名转发多个子域名

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

配置步骤

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

NPC 配置文件示例：

[wildcard_site]
host=*.proxy.com
target_addr=127.0.0.1:8080

泛域名只负责选择 NPS 转发规则。后端仍会收到访问者请求的具体 Host；如果后端只接受固定主机名，可配合改写后端 Host 。

安全边界

当前泛域名按配置中 * 之外的域名片段进行包含匹配，不是严格的 DNS 标签匹配。不要使用过短或过宽的规则，并在 NPS 前的反向代理、防火墙或后端再次限制允许的 Host。对需要隔离的站点，应使用精确域名规则。

通配符证书通常只覆盖一级子域名，例如 *.proxy.com 不覆盖 a.b.proxy.com。部署后至少验证一个预期子域名、根域名和一个不应命中的 Host，确认不会把未知域名转发到内网默认站点。

26 - 按 URL 路径选择不同后端

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

配置示例

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

留空按 / 匹配；多个规则同时匹配时使用最长前缀，所以 /api/admin/ 可以覆盖更宽的 /api/。

配置文件模式：

[api]
host=app.example.com
location=/api/
target_addr=192.168.1.20:8080

匹配规则

• 匹配是区分大小写的字面前缀，不是正则表达式。
• 建议目录规则以 / 结尾；/api 也会匹配 /apix。
• NPS 只按前缀选择目标，不会移除路径。后端仍收到完整的 /api/users。
• HTTP keep-alive 后续请求会再次检查 Host 和路径，必要时切换规则。
• HTTPS 必须在 NPS 上配置证书并终止 TLS。TLS 透传看不到 URL 路径，不能可靠地做路径分流。

为每个目标准备一个可识别的健康或版本响应，逐条请求边界路径，例如 /api/、/api2、/static/ 和 /。出现路由错误时，先检查是否缺少尾部斜杠，以及是否存在更长的前缀规则抢先匹配。

27 - 限制客户端的并发连接数

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

开启并配置

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

allow_connection_num_limit=true

然后在 Web 管理中新增或编辑客户端，填写“最大连接数”。留空或填 0 表示不限制。使用公共验证密钥、由 npc.conf 注册临时客户端时可写：

[common]
max_conn=500

对于已经在 Web 管理中创建的客户端，以 Web 保存的最大连接数为准，npc.conf 中的值不会覆盖它。

修改客户端限制后，新连接会立即按新值判断；已有连接不会因为把上限调低而主动断开，但在当前连接数降到新上限以下之前，新的连接会被拒绝。

如何选择数值

连接数是客户端下所有相关隧道共享的，不是每条隧道各自拥有额度。建议：

1. 先观察高峰期“当前连接数”，区分正常长连接与异常扫描。
2. 在正常峰值上保留重连和突发余量。
3. 同时检查 NPS 的文件描述符和内存容量，参见 Linux 系统限制 。
4. 对公开 TCP 服务再配置单隧道的访问白名单或新连接频率限制 ；最大连接数不能防御 SYN flood。

达到上限后，NPS 接受连接后会立即拒绝转发，客户端通常看到连接重置或超时。排障时比较当前连接数与上限，并检查是否存在未释放的长连接。

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

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

开启并配置

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

allow_tunnel_num_limit=true

管理员随后可在客户端新增/编辑页填写“最大隧道数”。留空或填 0 表示不限制。

计数包含该客户端当前存在的普通隧道和 HTTP(S) 域名规则；已停用但尚未删除的规则仍会计入。NPC 配置文件连接期间创建的临时隧道也会出现在这个计数中。

生效行为

• 通过 Web 创建、复制普通隧道或新增 HTTP(S) 隧道时检查上限。
• 达到上限后返回“隧道数量超过限制”，不会自动删除旧规则。
• 把上限调低到当前数量以下不会删除或停用现有隧道，但无法继续新增，直到删除规则或提高上限。
• NPC 配置文件提交隧道时不会执行最大隧道数校验。允许客户端通过配置文件连接或启用公共验证密钥时，不能依赖此项阻止批量创建。

该限制是 Web 管理配额，不是完整的安全边界。多用户环境还应谨慎开放“允许客户端通过配置文件连接”，避免公开 public_vkey，并使用端口允许列表 限制可占用范围。

排障时先统计普通隧道和 HTTP(S) 隧道两个列表，不要只查看当前页面。清理停用但不再需要的规则后再重试。

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

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

服务端配置

以下示例共用 443：

bridge_type=tcp
bridge_port=443
http_proxy_port=443
https_proxy_port=443
web_port=443
web_host=admin.nps.example.com

重启 NPS，并把以下 DNS 记录都解析到服务端：

• admin.nps.example.com：Web 管理。
• 业务域名：HTTP(S) 隧道。

Web 管理依赖 HTTP Host 与 web_host 精确区分。使用 IP 或其他 Host 访问会进入业务 HTTP 入口，而不是管理端。

客户端连接

普通 NPC 仍连接同一个桥接端口：

./npc -server=nps.example.com:443 -vkey=客户端验证密钥

端口复用只基于 TCP。KCP 使用 UDP，TLS 桥接使用独立的 tls_bridge_port，不能按以上方式合并到复用端口。

限制与验证

• Web 管理复用适用于明文 HTTP 识别；需要安全访问时，建议在受控网络/VPN 中使用，或让外层反向代理单独终止管理端 HTTPS。
• HTTP 识别支持常用的 GET、POST、HEAD、PUT、DELETE、CONNECT、OPTIONS 和 TRACE。依赖其他方法的首个请求应先实测。
• 复用监听会绑定所有地址，需使用防火墙限制管理域名对应入口的访问来源。
• 修改任一端口或 web_host 都需要重启 NPS。

重启后分别验证 NPC 上线、业务 HTTP、业务 HTTPS 和管理域名，不能只检查端口处于 LISTEN：

curl -I -H 'Host: admin.nps.example.com' http://127.0.0.1:443/
curl -I -H 'Host: app.example.com' http://127.0.0.1:443/

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

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

这样做的作用

• 减少每个业务连接都重新穿过 NAT、代理或防火墙建立控制通道的开销。
• 根据测得的延迟和传输速度动态调整逻辑流窗口。
• 每个逻辑连接仍可独立关闭，不需要为每条隧道建立常驻桥接。

故障影响

共享也意味着数据桥接断开时，其中承载的所有活动业务连接都会一起中断。NPS 与 NPC 每 5 秒交换一次探测包，连续未收到响应达到阈值后关闭数据桥接；NPC 随后重新连接，但 SSH、数据库、WebSocket 等原业务连接需要应用自行重建。

阈值配置见调整断线检测时间 。它不是单条业务连接的空闲超时，也不会仅关闭某一条隧道。

性能与排障

大带宽或高时延链路应先保持默认值，通过真实业务压测观察吞吐、延迟和重连。高并发时检查 Linux 并发连接调优 、CPU、内存、文件描述符和网络丢包。

不要在没有网络证据时随意降低 Linux 的 tcp_retries1、tcp_retries2 等全局重传参数，它们会影响主机上所有 TCP 应用。频繁出现整个客户端的连接同时中断时，检查 NPC/NPS 日志中的 ping timeout、桥接链路丢包、防火墙空闲超时和 NAT 映射，而不是逐条排查内网目标。

31 - 用环境变量启动 NPC

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

支持的变量

Shell 示例：

export NPC_SERVER_ADDR=nps.example.com:8024
export NPC_SERVER_VKEY='请替换为实际密钥'
./npc

只有在未指定配置文件时，这两个变量才会直接启动 NPC。命令行已提供 -server 或 -vkey 时，对应命令行值优先。连接协议、TLS、代理和超时没有对应环境变量，需要继续使用命令行参数，例如：

./npc -tls_enable=true -disconnect_timeout=60

systemd 示例

创建仅 root 可读的 /etc/nps/npc.env：

NPC_SERVER_ADDR=nps.example.com:8024
NPC_SERVER_VKEY=请替换为实际密钥

服务中引用：

[Service]
EnvironmentFile=/etc/nps/npc.env
ExecStart=/usr/local/bin/npc

设置权限并重启服务：

chmod 600 /etc/nps/npc.env
systemctl daemon-reload
systemctl restart npc

Docker Compose 示例

services:
  npc:
    image: your-npc-image
    restart: unless-stopped
    environment:
      NPC_SERVER_ADDR: nps.example.com:8024
      NPC_SERVER_VKEY: ${NPC_SERVER_VKEY}

不要把真实密钥提交到 Compose 文件或代码仓库；使用 .env、Docker Secret 或部署平台密钥管理。启动后从 NPC 日志和 Web 客户端列表确认连接的是预期地址与客户端。

32 - 采集 NPS 与 NPC 性能分析数据

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

NPS 服务端

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

pprof_ip=127.0.0.1
pprof_port=9999

两项必须同时有效；注释或留空即关闭。

NPC 客户端

命令行模式：

./npc -server=nps.example.com:8024 -vkey=客户端验证密钥 -pprof=127.0.0.1:9999

配置文件模式在 [common] 中设置：

[common]
pprof_addr=127.0.0.1:9999

采集数据

在同一台主机执行：

# 采集 30 秒 CPU profile，并进入交互分析
go tool pprof 'http://127.0.0.1:9999/debug/pprof/profile?seconds=30'

# 查看堆内存
go tool pprof http://127.0.0.1:9999/debug/pprof/heap

# 保存全部协程堆栈
curl -o goroutine.txt 'http://127.0.0.1:9999/debug/pprof/goroutine?debug=2'

远程分析应使用 SSH 端口转发，不要把监听改成公网地址：

ssh -L 9999:127.0.0.1:9999 user@nps.example.com

CPU profile 会增加少量运行开销，应限定采集时间。文件可能包含函数名、路径和运行状态，提交 Issue 前检查并清理敏感信息。采集完成后如不再使用，删除配置并重启对应进程。

33 - 调整 NPC 断线检测时间

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

配置两端

服务端 nps.conf：

disconnect_timeout=60

NPC 配置文件：

[common]
disconnect_timeout=60

无配置文件模式：

./npc -server=nps.example.com:8024 -vkey=客户端验证密钥 -disconnect_timeout=60

修改后重启对应进程。建议两端显式设置相同数值，避免一端已经放弃连接、另一端仍长时间等待。

如何选择

数值越小，故障切换越快，但瞬时拥塞可能让该客户端承载的所有活动连接一起中断。数值越大，误断更少，但黑洞连接恢复更慢。

重连行为与排障

只有 NPC 发现数据桥接 socket 已关闭，才会进入重连流程。正常情况下 NPS 主动关闭会通过 FIN/RST 传到 NPC；如果中间网络静默丢弃报文，NPC 必须等自己的阈值到达后才能关闭并重连，随后还会等待约 5 秒再尝试。

调整前先查明断线原因。若固定约 5 分钟断开，检查两端探测日志和防火墙/NAT 会话；若高峰时误断，检查丢包和拥塞。该参数不会让已经中断的 SSH、数据库或 WebSocket 会话自动恢复，应用仍需自行重连。

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

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

开始检测

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

./npc nat

NPC 默认访问 stun.stunprotocol.org:3478。需要使用自建或其他 STUN 服务时，传入完整的主机名和端口：

./npc nat -stun_addr=stun.example.com:3478

需要寻找候选地址时，可查看 always-online-stun 的 STUN 主机清单 ，选择一个 主机名:端口 传给 -stun_addr。该清单由第三方维护，文件记录的是 TCP 在线检测结果；NPC 的 NAT 检测需要 UDP，因此仍必须在 NPC 所在网络实际运行命令确认可用。公共服务的可用性和使用政策可能变化，不要将某一条地址视为固定依赖。

成功后会输出 NAT 类型和 STUN 观察到的公网映射地址，例如：

nat type: Full Cone NAT
public address: 203.0.113.20:54321

public address 是本次 UDP 检测得到的映射，不是可以长期固定使用的服务地址。路由器重启、运营商网络切换或映射超时后，地址和端口都可能变化。

理解结果

访问端和目标端应分别检测，并在实际网络中试连。检测成功只说明当前设备能通过 UDP 访问所选 STUN 服务；企业防火墙仍可能拦截 P2P 使用的其他 UDP 地址或端口。

检测失败时

1. 确认设备可解析 STUN 主机名，并能向其端口发送 UDP。
2. 更换可达的 STUN 服务后再次检测，不要根据单次超时判定 NAT 类型。
3. 在公司网络、家庭宽带和移动热点之间切换时重新检测，结果不能沿用。
4. 无法稳定直连时，改用由 NPS 中转的 TCP 隧道或私密代理。

公共 STUN 服务会看到检测设备的公网 IP。对外部服务有限制的环境，应使用组织自己管理的 STUN 服务。

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

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

运行前提

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

在 NPC 所在主机执行：

./npc status -config=/etc/nps/npc.conf

Windows 可以使用：

./npc.exe status -config=C:\nps\conf\npc.conf

-config 后必须是实际文件路径。命令读取配置、连接 NPS，输出结果后立即退出，不会启动一个新的常驻 NPC。

读取输出

每个条目使用 npc.conf 中的段名，例如：

web ok
ssh ok
dns not running

端口范围会展开为多个条目。例如 [database] 使用 server_port=6000-6002 时，输出名称为 database_6000、database_6001 和 database_6002。

ok 不等于业务端到端检查通过。对 HTTP(S) 规则，它只确认规则存在；对其他隧道，它也不会连接 target_addr 或从公网访问服务。状态检查后仍应使用 curl、nc 或业务客户端完成实际请求。

常见失败

• 连接或验证失败：检查 [common] 中的地址、端口、vkey、TCP/KCP 类型和防火墙。
• 找不到临时验证信息：先让配置模式 NPC 成功连接 NPS，再在同一主机上运行状态检查。
• 多个配置实例互相影响：当前状态命令共用一个临时验证文件，同一主机上多个 NPC 实例可能覆盖它。此时应优先根据 Web 管理中的隧道状态和 NPC 日志排查。
• 只有个别条目为 not running：查看 NPC 启动日志，重点检查端口占用、端口允许列表、重复域名或重复隧道密钥。

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

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

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

命令行启动

SOCKS5 代理：

./npc \
  -server=nps.example.com:8024 \
  -vkey=<客户端验证密钥> \
  -type=tcp \
  -proxy=socks5://proxy-user:proxy-password@127.0.0.1:1080

HTTP 代理：

./npc \
  -server=nps.example.com:8024 \
  -vkey=<客户端验证密钥> \
  -type=tcp \
  -proxy=http://proxy-user:proxy-password@127.0.0.1:3128

代理不需要认证时，可省略 proxy-user:proxy-password@。用户名或密码包含 @、:、/ 等 URL 保留字符时，必须先做百分号编码。命令行参数可能被同一主机的其他用户从进程列表看到，长期运行时建议改用权限受限的配置文件。

npc.conf 配置

在 [common] 中设置 proxy_url：

[common]
server_addr=nps.example.com:8024
vkey=<客户端验证密钥>
conn_type=tcp
proxy_url=socks5://proxy-user:proxy-password@127.0.0.1:1080

限制配置文件只能被运行 NPC 的账号读取。Linux 上可使用：

chmod 600 /etc/nps/npc.conf

代理端必须允许的连接

• HTTP 代理必须支持 CONNECT nps.example.com:8024 并返回 200。只允许浏览器访问 80/443 的代理可能拒绝 NPS 桥接端口。
• SOCKS5 代理必须允许连接 NPS 的主机名和 TCP 桥接端口。
• NPS 所在主机的安全组和防火墙仍需放通桥接端口，来源地址通常显示为上游代理的出口地址。

限制与安全边界

• 出站代理只用于 conn_type=tcp 或 -type=tcp。KCP 使用 UDP，不会经过这个 HTTP/SOCKS5 代理参数。
• 通过代理建立通道后，tls_enable=true 会继续执行到 NPS 的 TLS 握手和证书校验；应连接 TLS 桥接端口（通常为 8025），并按桥接证书与身份验证 配置 CA 或公钥指纹。
• HTTP CONNECT 和普通 SOCKS5 连接本身不提供端到端加密。未启用 TLS 桥接时，代理能够读取桥接数据。
• 不支持 PAC 脚本或自动读取操作系统代理，必须显式填写代理 URL。

验证与排障

1. 先在 NPC 主机上验证代理端口可达，再启动 NPC。
2. 检查 NPC 日志是否出现 Successful connection with server，并在 Web 管理中确认客户端在线。
3. HTTP 代理返回 proxy CONNECT failed: 403 或类似错误时，请检查 CONNECT 目标端口策略和代理认证信息。
4. 代理连接成功但验证失败时，检查 NPS 地址、桥接端口和客户端验证密钥，不要将上游代理密码与 NPS vkey 混淆。

37 - 在群晖 NAS 上运行 NPC

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

部署前准备

1. 在 NPS Web 管理中新增客户端，记录 NPS 桥接地址和客户端验证密钥。
2. 确认 NAS 能主动访问 NPS 桥接端口。NPC 不需要在路由器上做入站端口映射。
3. 在群晖套件中心安装 Container Manager，然后打开“项目”功能。

用 Compose 启动

新建项目并填入以下 Compose 内容，将占位值替换为真实配置：

services:
  npc:
    image: yisier1/npc:latest
    container_name: npc
    network_mode: host
    restart: unless-stopped
    command:
      - -server=nps.example.com:8024
      - -vkey=<客户端验证密钥>

network_mode: host 让 NPC 直接使用 NAS 的网络。因此隧道的 target_addr=127.0.0.1:<端口> 可以访问监听在 NAS 本机的服务，也可以填写其他局域网设备的 IP 和端口。

生产环境建议将 latest 改为已验证的具体版本标签，避免重建容器时自动跨版本升级。客户端验证密钥不应公开或提交到代码仓库。

使用 npc.conf

需要在 NAS 上声明多条隧道时，先创建例如 /volume1/docker/npc/conf/npc.conf 的配置文件，然后改用：

services:
  npc:
    image: yisier1/npc:latest
    container_name: npc
    network_mode: host
    restart: unless-stopped
    volumes:
      - /volume1/docker/npc/conf:/conf:ro
    command:
      - -config=/conf/npc.conf

挂载为只读可以防止容器修改 NAS 上的配置。请确认 Container Manager 能读取该目录；配置中含有 vkey 和其他凭据时，不要给普通 DSM 用户授予读取权限。

验证连接

1. 在 Container Manager 中查看 npc 容器日志，确认出现成功连接 NPS 的记录。
2. 在 NPS Web 管理的客户端列表中确认该客户端在线。
3. 从 NAS 上确认目标服务可达。如果目标在另一台局域网设备上，检查该设备的防火墙是否允许来自 NAS 的连接。
4. 从公网实际访问隧道，不要只以“客户端在线”判定后端服务可用。

第三方套件

不能使用 Container Manager 的机型，可自行评估“我不是矿神”套件源：https://spk7.imnks.com/ 。该套件源由第三方维护，不属于 NPS 项目的发布和更新链路。安装前应核对支持的 DSM 版本、CPU 架构、包签名和更新来源；对供应链有严格要求时，请使用官方镜像或发布页中与 NAS 架构匹配的 Linux 客户端。

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

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

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

在 Web 中配置 IP 白名单

1. 新增 TCP 隧道时，在“TCP 访问控制”中选择“仅白名单访问”。已有隧道可在 TCP 隧道列表中点击对应的“TCP 访问控制”编辑入口。
2. 在“允许的 IP / CIDR”中每行填一个条目，也可使用英文逗号分隔。
3. 保存后用新连接验证；策略立即应用，无需重启隧道，已建立的连接不会主动中断。

示例白名单：

203.0.113.10
198.51.100.0/24
2001:db8:1234::/48

支持单个 IPv4、IPv6 地址和 CIDR 网段，最多 1024 个去重后的条目。填写网段时应尽量缩小范围；例如 /24 会允许其中所有 IPv4 地址，不要为了省事填入过大网段。

选择“仅白名单访问”但留空名单时，NPS 会拒绝该隧道的所有新连接。无效 IP 或 CIDR 会导致保存失败，不会自动退回公开访问。

确认 NPS 看到的来源 IP

白名单匹配 NPS 接受 TCP 连接时看到的对端 IP，不信任 X-Forwarded-For，也不解析入站 PROXY 协议。NPS 前方有四层负载均衡、NAT 网关或反向代理时，它可能只看到中间设备的地址。

配置前先查看 NPS 日志或系统连接信息，确认实际来源。客户端经由家庭宽带、移动网络或企业共享出口时，公网 IP 可能变化或被多人共用；需要稳定身份边界时，应在白名单前搭配 VPN 或业务自身认证。

全局 IP 黑名单和客户端 IP 黑名单仍优先拒绝，即使同一地址也在 TCP 白名单中。客户端累计流量和并发连接配额也仍然生效。

限制公开隧道的新连接频率

公开访问模式按“单条隧道 + 来源 IP”独立计数。默认在 600 秒滑动窗口内允许 600 次新连接，第 601 次会触发 600 秒封禁。来源端口不参与区分，IPv4 与它的 IPv6 映射形式视为同一地址。

管理员可在 Web 管理的“全局设置 → TCP 新连接频率限制默认值”修改：

保存后，继承这些值的 TCP 隧道会对新连接实时应用，不中断已有连接。如果某条隧道的实际限频规则发生变化，它原有的连接计数和自动封禁会清空。

在新增 TCP 隧道或其“TCP 访问控制”页面中，可以选择继承全局开关、对该隧道强制启用，或对该隧道关闭限频。数值填 0 表示继承服务端默认值。单隧道显式设置的优先级高于全局设置。

在 nps.conf 中设置后备默认值

未通过 Web 保存全局 TCP 限频设置时，NPS 从 nps.conf 读取后备值：

tcp_conn_limit_enabled=true
tcp_conn_limit_max=600
tcp_conn_limit_window=600
tcp_conn_limit_ban=600

修改 nps.conf 后需要重启 NPS。实际优先级为：单隧道显式设置 → Web 中的全局设置 → nps.conf → 内置默认值。

在 npc.conf 中配置

仅允许固定管理地址访问 SSH：

[ssh]
mode=tcp
server_port=2222
target_addr=127.0.0.1:22
access_mode=whitelist
access_allowlist=203.0.113.10,2001:db8:1234::/48

为公开 Web 服务单独设置限频：

[public_web]
mode=tcp
server_port=8080
target_addr=127.0.0.1:80
access_mode=public
conn_limit_mode=enabled
conn_limit_max=600
conn_limit_window=600
conn_limit_ban=600

由 npc.conf 创建的隧道在 Web 中只能查看访问策略。修改配置文件并重连 NPC 才能持久生效。端口范围配置会给每条展开的隧道复制相同策略，但各自独立计数。

验证和排障

1. 白名单应分别从一个允许地址和一个未允许地址发起真实协议连接，例如 SSH 登录或 HTTPS 请求。
2. 被拒绝的连接在 TCP 握手后会立即关闭，而不是像防火墙 DROP 一样超时。只用端口扫描器可能仍然看到端口开放，应检查业务请求是否在建立后被关闭。
3. 限频触发时，NPS 在日志中记录新的自动封禁，并每分钟汇总拒绝次数。封禁期内继续重试不会延长封禁时间。
4. 重新保存某条隧道的访问策略会清空它的连接计数和自动封禁，可用于解除误封。重启 NPS 或重新启动隧道也会清空内存中的状态。

能力边界

• 新连接限频统计 TCP 连接，不能判断 SSH 是否登录成功，也不统计已建立连接中的 HTTP 请求数。
• 每条隧道最多跟踪 4096 个来源 IP 和 65536 个窗口内连接事件。达到容量时，NPS 拒绝无法继续跟踪的新连接，每分钟清理过期状态。
• 这是应用层的接入控制，不防御 SYN flood 或带宽耗尽攻击。公网服务仍应配置云安全组、主机防火墙和业务自身认证。

39 - HTTP 响应缓存（未实现）

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

http_cache=true
http_cache_length=100

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

当前版本状态

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

推荐方案

需要减少 NPC 链路流量时，在 NPS 的 HTTP 入口前部署 Nginx、Caddy、Varnish 或 CDN，并让它们按标准 HTTP 缓存语义处理 Cache-Control、Expires、Vary 和认证响应。例如 Nginx：

proxy_cache_path /var/cache/nginx/nps levels=1:2 keys_zone=nps_cache:10m max_size=1g inactive=60m;

server {
    listen 80;
    server_name static.example.com;

    location / {
        proxy_pass http://127.0.0.1:8010; # nps.conf 的 http_proxy_port
        proxy_set_header Host $host;
        proxy_cache nps_cache;
        proxy_cache_valid 200 10m;
        add_header X-Cache-Status $upstream_cache_status always;
    }
}

验证时连续请求同一静态资源，观察第二次是否返回 X-Cache-Status: HIT。不要缓存登录态、带 Authorization 的响应或包含用户隐私的动态内容，除非已经设计了正确的缓存键和绕过规则。