NPS 内网穿透 on NPS Plus

v0.26.40

Thu, 01 Oct 2026 00:00:00 +0800

新增：
- TCP 独立端口隧道新增访问控制：支持公开访问和 IPv4、IPv6、CIDR 白名单；白名单为空时拒绝全部连接
- TCP 隧道新增按来源 IP 的滑动窗口连接限频和临时封禁，默认每 600 秒最多建立 600 个新连接并封禁 600 秒；支持在全局设置、单条隧道和 npc.conf 中配置，Web 修改后无需重启且不影响已有连接
- Web 管理端为客户端、各类隧道和全局设置页面新增中英文使用说明，并优化配置表单在桌面端和移动端的布局
- Web 服务会在响应时自动压缩未预压缩的 CSS、JavaScript 静态资源
修复：
- 修复 P2P over UDP 服务端握手状态并发读写问题；增加无效报文校验、待处理会话数量限制、20 秒超时清理和安全关闭，避免竞态、状态泄漏及异常报文造成资源耗尽
- 普通客户端登录会持续校验客户端是否存在、启用且允许显示；客户端被停用、删除或隐藏后，已有会话立即失效
- 限制普通客户端修改自身状态、到期时间、流量和连接配额等管理员字段，并将全局设置限制为管理员访问
- 验证码校验失败后立即终止登录，防止继续执行账号密码认证
- IP 白名单认证日志不再记录客户端密钥和授权密码等敏感信息
- 修复中英文界面的缺失或错误文案，批量删除确认提示按单条和多条分别显示，流量单位统一为 IEC 单位
- 修复 NPC、NPC SDK 和旧 GUI 构建目标相互冲突的问题，并将依赖 Docker 的 mux 测试隔离为集成测试
安全：
- 升级 github.com/ulikunitz/xz 至 v0.5.8，修复 CVE-2021-29482
- 升级 golang.org/x/net 至 v0.55.0，修复 CVE-2024-45338、CVE-2025-22870 和 CVE-2026-25681
- 升级 golang.org/x/crypto 至 v0.52.0、golang.org/x/image 至 v0.43.0、golang.org/x/text 至 v0.39.0，修复 CVE-2025-22869、CVE-2026-42508、CVE-2026-46602 和 CVE-2026-56852
- GUI 前端升级 Vite 至 v7.1.5、@vitejs/plugin-vue 至 v5.2.4，修复 CVE-2025-58752
优化：
- 精简登录页和管理端的过期链接及说明，更新版权年份和运行日志文案
- 外网 IPv4 查询服务切换到 v4.ipip.net
- Go 工具链和 Docker 构建环境升级至 1.25，GUI 发布流程升级至 Node.js 22

Docker 部署（推荐）

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

先拉取镜像：

docker pull yisier1/nps

启动容器，请把 <本机conf目录> 替换为实际路径（例如 /root/nps/conf）：

docker run -d \
 --restart=always \
 --name nps \
 --net=host \
 -v <本机conf目录>:/conf \
 -v /etc/localtime:/etc/localtime:ro \
 yisier1/nps

先拉取镜像：

docker pull yisier1/npc

启动容器，请把 <> 内的值替换为实际配置：

docker run -d \
 --restart=always \
 --name <自定义名称> \
 --net=host \
 yisier1/npc \
 -server=<服务端IP:端口> \
 -vkey=<客户端验证密钥>

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

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

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

v0.26.38

Mon, 24 Aug 2026 00:00:00 +0800

新增：
- GUI 客户端（npc-gui）迁移到 Wails v3
- GUI 客户端新增版本自动更新：启动时自动检查 GitHub 最新 release，支持一键下载并热替换当前可执行文件后自动重启
修复：
- 客户端内网地址为 192.169.x.x 等非标准私网段时，Web 面板客户端列表不显示本机 IP #348

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

从项目发布页下载对应系统版本。服务端 (nps) 和客户端 (npc) 使用单独的压缩包。

首次启动时 nps 会在可执行文件同级目录自动生成 conf/nps.conf，并随机生成 web_password、auth_key、auth_crypt_key。Web 管理界面的登录密码请在 conf/nps.conf 或启动日志中查看。

Linux 或 macOS：

./nps -server

Windows：

nps.exe -server

运行目录中没有 conf/npc.conf 时，客户端无参数启动会进入交互菜单；存在该文件时会直接按配置文件运行。需要强制使用其他配置文件时传入 -config=/实际路径/npc.conf。

Linux 或 macOS：

./npc

Windows：

npc.exe

通过 Web 管理界面的【快捷连接码】，或手动填写 -server、-vkey 等参数配置客户端。

v0.26.37

Sat, 08 Aug 2026 00:00:00 +0800

修复：
- NPC 安装到系统服务失败 BUG #338
- 隧道实际未运行但面板提示「启动成功」、运行状态始终为关闭的问题 #339
- 配置 allow_ports 后随机生成端口问题 #339
- Web 面板languages.xml使用 NPS 版本号作为缓存标识 #342
新增：
- 客户端、隧道、域名解析修改接口支持修改流量数据 #341

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

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

需要 Go 1.25.0 及以上，具体版本要求以仓库根目录的 go.mod 为准。

git clone https://github.com/yisier/nps.git
cd nps
go build -o nps cmd/nps/nps.go
go build -o npc cmd/npc/npc.go

v0.26.36

Sun, 12 Jul 2026 00:00:00 +0800

新增：
- 新增客户端内网地址上报功能,客户端列表展示 npc 内网地址 #333
- Web 管理端客户端/隧道/域名列表业务字段支持服务端排序（备注、状态、在线等）#254
优化：
- 不再依赖外部 web 目录的静态文件
修复：
- 客户端/服务端在线更新失败 BUG
- nps -server 安装成功后 web_port 未正常显示BUG #317
- Bridge 握手增加 10s 读超时，校验失败/读失败立即关闭连接，减轻端口扫描导致的连接与 goroutine 堆积 #281
- 解决私密代理和P2P连接的TLS启用问题 #143
- HTTP 正向代理 Basic 认证 BUG#133
- SOCKS5 用户名密码认证 BUG #133
- 客户端建连失败后半连接假死、需手动重启 npc BUG #115

查看和保存隧道流量统计

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

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

统计口径

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

v0.26.35

Sat, 04 Jul 2026 00:00:00 +0800

新增：
- 客户端列表、隧道列表、域名解析列表支持多选批量删除 #287
修复：
- HTTP 代理在 SVN 客户端无法正常检出 #336
- 新增/编辑隧道时无提示且不跳转，重复点击会产生多条记录 #334
- mips/mipsle 架构运行出现 Illegal instruction 错误 #331
优化：
- 隧道、域名解析编辑页的客户端 ID 改为下拉选择 #334

查看客户端当前传输速度

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

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

如何读取

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

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

v0.26.34

Thu, 04 Jun 2026 00:00:00 +0800

新增：
- nps -server 管理脚本欢迎语显示当前版本号,更新版本时比对版本，已是最新则直接退出，避免无谓覆盖 #328
- npc 管理脚本欢迎语显示当前版本号，新增 [5] 更新客户端 选项，更新并替换 npc 二进制
- 客户端新增到期时间字段，创建/修改客户端时可选填写，到期后自动暂停客户端 #322
修复：
- Dashboard IO 速率采集阻塞请求 500ms，改为后台采集缓存，消除 Sleep 等待
- ServerStatus 切片并发读写不安全，添加 RWMutex 保护
- flowSession goroutine 泄漏，改为仅在 StartNewServer 启动一次
- GetTunnel 双重遍历 sync.Map 性能问题，合并为单次 Range
- Bridge Client 字段并发读写不安全，添加 Mutex 保护
- TLS ClientHello recordLen 无上限，添加 16KB 限制防止内存耗尽
- SOCKS5 地址解析未检查 Read 返回值，改用 io.ReadFull
- 文件存储 panic 改为错误日志，defer 清理临时文件防止泄漏
- GenerateServerPort 可能无限循环，限制 1000 次重试
- P2P UDP 无超时永久阻塞，添加 30s ReadDeadline
- P2P goroutine 退出控制改用 context，修复潜在泄漏
- 客户端 UDP ReadFrom 错误后未退出，修复无效数据继续处理
- #324 隧道/域名解析/UDP 流量始终为 0
- muxPackager buffer pool 泄漏：UnPack() 错误路径未归还 windowBuff 导致内存持续增长
- bridge 客户端重连时旧 WORK_CHAN/WORK_FILE mux 未关闭，底层连接和 goroutine 永不释放
- pmux 连接超时泄漏：process() channel 发送超时后连接未关闭，且 ACCEPT_TIME_OUT 单位错误（10ns 应为 10s）
- pmux 关闭流程 panic：加 done channel + WaitGroup 保证 Close() 等所有 process() 退出后再 close conn channel；process() 入口设 ReadDeadline 防止阻塞读导致 wg.Wait() 死锁；PortListener 加 done channel 唤醒 Accept()
优化：ioutil.WriteFile → os.WriteFile、rand.Seed → rand.New 本地随机源

查看 NPC 版本与兼容性

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

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

当前兼容行为

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

v0.26.33

Sat, 23 May 2026 00:00:00 +0800

新增：
- 配置文件自动生成：启动时若 conf 目录或 nps.conf 不存在，自动创建并写入默认配置，方便 Docker 部署
- 首次启动默认 web_username/admin、web_password、auth_key、auth_crypt_key 均改为随机生成，并打印到终端，提升安全性
- Web 静态文件打包进可执行文件 + 静态文件 URL 加入版本号参数，升级后自动刷新缓存，部署无需单独拷贝 web 目录
- 精简发布包：去除打包时冗余的 conf/nps.conf、web 目录
- 清理失效配置项：移除 appname、runmode、https_default_cert_file、https_default_key_file、https_just_proxy
修复：
- #184 限速导致隧道中断：UpdateClient 在 RateLimit=0 时创建零速率令牌桶导致永久阻塞
- #159 关闭隧道端口仍可用：StopServer 错误时提前返回未更新状态 + 重复 OpenTask case 导致隧道被自动重启
- #170 TCP 负载均衡只有一个后端可达：GetRandomTarget 未处理 \r 换行符和尾部空行
- #319 客户端列表不显示实时网速：NowRate 计算逻辑错误，改为统计每秒实际消耗字节数
- #306 #316 TCP Basic 认证与域名解析冲突：移除 TCP 隧道 Basic 认证探测，域名解析继续使用客户端 Basic 认证

提高 Linux 并发连接容量

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

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

v0.26.32

Fri, 27 Mar 2026 00:00:00 +0800

修复：
- 客户端注册参数未正确处理[快捷启动命令]和[TLS快捷启动命令] #303
- 修复https反向代理bug，感谢okawao 的 PR

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

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

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

v0.26.31

Mon, 23 Mar 2026 00:00:00 +0800

新增：
- 域名解析记录开关功能 #314
- TCP隧道增加Basic认证 306
修复：
- 新增隧道出现secret mode keys must be unique 301

v0.26.30

Thu, 12 Mar 2026 00:00:00 +0800

修复：
- http 协议 websocket 错误，感谢xiaozonglong 提供的 home assistant 环境 ,#268 ,#296
- 域名解析中，主机url点击无法跳转非80端口 311
- 新增的主机配置页面，客户端ID异常 #310
- 自动 HTTPS(301) 按照 https_proxy_port 配置的端口号跳转

加密 NPC 与 NPS 之间的连接

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

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

服务端配置

在 nps.conf 中设置：

使用说明

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

启动方式选择

NPC 按以下顺序选择启动方式：

同时传入 -server 和 -vkey 时，按命令行参数连接。
传入 -config=/path/to/npc.conf 时，按指定配置文件连接。
无参数启动时，如果默认位置存在 conf/npc.conf，按该文件连接；否则进入交互菜单。

Windows 的默认配置位置相对于 npc.exe 所在目录；Linux 和 macOS 的默认位置相对于启动时的当前工作目录。为避免系统服务或脚本改变工作目录，配置文件模式建议使用绝对路径：

使用说明

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

Web 管理

访问 Web 管理界面：http://服务端 IP:Web 管理端口（默认端口为 8081）。启用 web_open_ssl 后改用 HTTPS；配置了 web_base_url 时还要附加该路径。

v0.26.29

Sat, 24 Jan 2026 00:00:00 +0800

新增：
- GUI 客户端，基于 Wails 开发，点击查看了解更多，需要 WebView2 运行时，可通过两种方式添加客户端。
  - 方式1：直接输入快捷启动命令即可
  - 方式2：手动添加客户端，输入-server -vkey等参数
修复：
- Android 包未构建到 Release 72

为 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 管理中编辑站点所属的客户端，同时填写：

v0.26.28

Sat, 06 Dec 2025 00:00:00 +0800

【全局参数】页面新增服务地址配置项，用于客户端命令地址显示、隧道访问地址显示 293
【IP授权功能优化】，通过穿透的端口去提交 IP 认证，感谢 Aqamoe 的建议 291
【重构限速器实现】提升性能和准确性

改写 HTTP 后端收到的 Host

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

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

v0.26.27

Wed, 05 Nov 2025 00:00:00 +0800

新增：
- 客户端新增【IP白名单】，可通过两种方式添加IP：
  - 方式1️⃣：在【客户端】新建/修改页面，配置IP授权密码，不在IP白名单的外网访问将被跳转到 IP 授权页面，输入正确的授权密码，即可完成添加 IP。
  - 方式2️⃣：在【客户端】新建/修改页面，直接添加IP到白名单中。
- 客户端配置移除【压缩】和【加密】功能，此功能会显著提高内存和CPU占用率，“利大于弊”。
- 客户端默认不再提供配置文件，强烈推荐使用无配置文件模式启动客户端

新增或覆盖 HTTP 后端请求头

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

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

v0.26.26

Fri, 15 Aug 2025 00:00:00 +0800

修复：
- windows注册服务使用tls无法连接 269
- 域名解析自动HTTPS逻辑bug 273

自定义 HTTP 隧道的 404 页面

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

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

web/static/page/error.html

自定义方法

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

v0.26.25

Wed, 28 May 2025 00:00:00 +0800

新增：
- nps增加nps(.exe) -server 命令，用于管理NPS服务，安装和卸载服务在 Linux 下需要有 sudo 权限，Windows 下需要有管理员权限。
- 增加【TLS快捷启动命令】，可用于在tls模式下，快速启动客户端。 257

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

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

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

开启并配置

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

v0.26.24

Wed, 16 Apr 2025 00:00:00 +0800

新增：
- 隧道支持复制功能，在隧道页面增加复制按钮，除了端口号为随机生成外，其他参数全部拷贝。251
修复：
- 私密代理连接时服务端会报错退出，250

限制客户端的传输速度

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

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

开启并配置

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

v0.26.23

Fri, 11 Apr 2025 00:00:00 +0800

新增：
- TCP 隧道支持 Proxy Protocol 协议来传递经过请求的真实 IP。
修复：
- 客户端较多时，协程增长过快，感谢 @huanglei288766 的PR

将新连接轮询到多个后端

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

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

Web 配置

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

v0.26.22

Thu, 23 Jan 2025 00:00:00 +0800

优化：
- 客户端注册系统服务时，（新版客户端注册方式，非 install 命令）将按照 npc-[vkey].log 格式保存日志，每个客户端VKEY单独一个日志文件，windows 日志位于 npc.exe 同级目录下，linux 位于 /var/log/目录。
- 域名模式，HTTPS证书支持上传文件和文件路径，系统将自动识别路径还是证书内容。 #175
修复：
- ipv6地址显示不全 #237

自动分配服务端监听端口

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

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

分配规则

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

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

v0.26.21

Tue, 07 Jan 2025 00:00:00 +0800

新增：
- 客户端列表页面新增【快捷启动命令】，此命令为连接地址+链接秘钥的base64编码，方便一键启动、一键安装客户端。
- 域名解析和隧道列表增加访问地址，可以点击隧道链接，直接网页打开。 #234
优化：
- 修改vkey生成方式，由16位缩短至10位，截取uuid前10位，避免重复。
- 优化客户端启动方式，当npc文件目录下无配置文件时，可直接双击运行客户端，输入命令完成启动、安装、卸载客户端，直接启动和安装服务时需要输入【快捷启动命令】，卸载服务、启动服务、停止服务时，只需输入隧道秘钥【vkey】即可。安装服务以 nps-client-vkey 方式命名，实现注册多个服务。

复制普通隧道配置

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

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

复制内容

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

v0.26.20

Thu, 07 Nov 2024 00:00:00 +0800

新增：
- 客户端增加创建时间
修复：
- 客户端限速单位不统一 #185
- 增加从下拉选择客户端,隧道列表排序,新增编辑后不会刷新界面 #183
- 隧道数量限制无法统计域名映射 #209

向 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/nps.conf 读取配置。直接运行二进制时，运行目录通常是 NPS 可执行文件所在目录；安装为系统服务后通常是 /etc/nps。使用 -conf_path=/path/to/nps 可以指定新的运行目录，此时配置文件路径为 /path/to/nps/conf/nps.conf。

使用示例

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

统一准备工作

开启 NPS 服务端，假设服务端公网 IP 为 1.1.1.1，配置文件中的 bridge_port 为 8024，web_port 为 8080。
访问 1.1.1.1:8080。
在客户端管理中新增一个客户端，记录客户端验证密钥。
在内网设备上运行 NPC（Windows 使用 CMD 运行 .exe 文件）。

./npc -server=1.1.1.1:8024 -vkey=客户端验证密钥

注意：运行服务端后，请确保客户端设备能正常访问配置文件中的 bridge_port 端口，可使用 Telnet、Netcat 等工具检查。

v0.26.19

Sat, 01 Jun 2024 00:00:00 +0800

golang 版本升级到 1.22。
增加自动https，自动将http 重定向（301）到 https。
客户端命令行方式启动支持多个隧道ID，使用逗号拼接，示例：npc -server=xxx:8024 -vkey=ytkpyr0er676m0r7,iwnbjfbvygvzyzzt。
移除 nps.conf 参数 https_just_proxy ，调整 https 处理逻辑，如果上传了 https 证书，则由nps负责SSL（此方式可以获取真实IP），否则走端口转发模式（使用本地证书，nps 获取不到真实IP），如下图所示。

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

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

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

allow_ports=9001-9009,10001,11000-12000

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

v0.26.18

Tue, 27 Feb 2024 00:00:00 +0800

新增：nps.conf 新增 tls_bridge_port=8025 参数，当 tls_enable=true 时，nps 会监听8025端口，作为 tls 的连接端口。客户端可以选择连接 tls 端口或者非 tls 端口：npc.exe -server=xxx:8024 -vkey=xxx 或 npc.exe -server=xxx:8025 -vkey=xxx -tls_enable=true

批量映射 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。

v0.26.17

Wed, 31 Jan 2024 00:00:00 +0800

说明：考虑到 npc 历史版本客户端众多，版本号不同旧版本客户端无法连接，为了兼容，仓库版本号将继续沿用 0.26.xx

批量映射到其他内网主机

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。

v0.27.01（已作废）

Tue, 02 Jan 2024 00:00:00 +0800

此版本已作废，功能移动到 v0.26.17。

新增：tls 流量加密，(客户端忽略证书校验，谨慎使用，客户端与服务端需要同时开启，或同时关闭)，使用方式：
- 服务端：nps.conf tls_enable=true；
- 客户端：npc.conf tls_enable=true 或者 npc.exe -server=xxx -vkey=xxx -tls_enable=true

使用 UDP/KCP 连接 NPS

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

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

服务端配置

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

v0.26.16

Thu, 01 Jun 2023 00:00:00 +0800

修复：https 流量不统计 Bug 修复。
新增：新增全局黑名单IP，用于防止被肉鸡扫描端口或被恶意攻击。
新增：新增客户端上次在线时间。

用泛域名转发多个子域名

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 配置文件示例：

v0.26.15

Fri, 24 Feb 2023 00:00:00 +0800

修复：更新程序 url 更改到当前仓库中
修复：nps 在外部路径启动时找不到配置文件
新增：增加 nps 启动参数，-conf_path=D:\test\nps，可用于加载指定nps配置文件和web文件目录。
window 使用示例：
- 直接启动：nps.exe -conf_path=D:\test\nps
- 安装：nps.exe install -conf_path=D:\test\nps
- 安装启动：nps.exe start
linux 使用示例：
- 直接启动：./nps -conf_path=/app/nps
- 安装：./nps install -conf_path=/app/nps
- 安装启动：nps start -conf_path=/app/nps

按 URL 路径选择不同后端

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

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

配置示例

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

v0.26.14

Fri, 30 Dec 2022 00:00:00 +0800

修复：API 鉴权漏洞修复

限制客户端的并发连接数

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

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

历史记录

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

2022-12-19
- 修复：某些场景下丢包导致服务端意外退出
- 优化：新增隧道时，不指定服务端口时，将自动生成端口号
- 优化：API返回ID，/client/add/, /index/addhost/, /index/add/
- 优化：域名解析、隧道页面，增加[唯一验证密钥]，方便搜查
2022-10-30
- 新增：在管理面板中新增客户端时，可以配置多个黑名单IP，用于防止被肉鸡扫描端口或被恶意攻击。
- 优化：0.26.12 版本还原了注册系统功能，使用方式和以前一样。无论是否注册了系统服务，直接执行 nps 时只会读取当前目录下的配置文件。
2022-10-27
- 新增：在管理面板登录时开启验证码校验，开启方式：nps.conf open_captcha=true，感谢 @dongFangTuring 提供的PR
2022-10-24
- 修复：HTTP协议支持WebSocket（稳定性待测试）
2022-10-21
- 修复：HTTP协议下实时统计流量，能够精准的限制住流量（上下行对等）
- 优化：删除HTTP隧道时，客户端已用流量不再清空
2022-10-19
- BUG：在TCP协议下，流量统计有问题，只有当连接断开时才会统计流量。例如，限制客户端流量20m,当传输100m的文件时，也能传输成功。
- 修复：TCP协议下实时统计流量，能够精准的限制住流量（上下行对等）
- 优化：删除TCP隧道时，客户端已用流量不再清空
2022-09-14
- 修改NPS工作目录为当前可执行文件目录（即配置文件和nps可执行文件放在同一目录下，直接执行nps文件即可），去除注册系统服务，启动、停止、升级等命令

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

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 会根据连接开头的协议特征分流。

Web API 鉴权

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

在 nps.conf 中配置 auth_key 即可启用 API 鉴权（首次启动自动生成）。

鉴权方式

每个请求需附带两个参数：

参数	说明
`auth_key`	`md5(配置文件中的 auth_key + 当前时间戳)`
`timestamp`	当前 unix 时间戳（秒）

时间戳有效范围为 20 秒，每次请求须重新生成。

NPC SDK 文档

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

命令行模式启动客户端
从 v0.26.10 开始，此函数会阻塞，直到客户端退出返回，请自行管理是否重连
p0->服务端地址
p1->客户端验证密钥（vkey）
p2->连接类型（tcp or udp）
p3->连接代理

extern GoInt StartClientByVerifyKey(char* p0, char* p1, char* p2, char* p3);

查看当前启动的客户端状态，在线为1，离线为0
extern GoInt GetClientStatus();

关闭客户端
extern void CloseClient();

获取当前客户端版本
extern char* Version();

获取日志，实时更新
extern char* Logs();

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

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

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

增强功能

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

使用 HTTPS

NPS 会根据 HTTP(S) 隧道是否同时配置证书和私钥选择处理方式：

证书和私钥	行为	NPS 能否获取 HTTP 层真实 IP
均已配置	NPS 终止 TLS，再把请求转发到内网服务	能
均未配置	NPS 透传 TLS，由内网服务终止 TLS	不能

自动跳转 HTTPS（301）

在 Web 的 HTTP(S) 隧道编辑页勾选“自动跳转 HTTPS（301）”后，NPS 会把该域名的 HTTP 请求重定向到 https://<隧道域名>:<https_proxy_port>。

用环境变量启动 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 管理都不在适用范围内。

Web API

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

除 AuthController 和 LoginController 外，所有接口均需通过鉴权，详见 API 鉴权说明。

通用响应格式

响应类型	格式
成功	`{"status": 1, "msg": "success"}`
成功（含 ID）	`{"status": 1, "msg": "success", "id": 123}`
失败	`{"status": 0, "msg": "error message"}`
列表	`{"rows": [...], "total": 100}`

单个查询接口（GetClient、GetOneTunnel、GetHost）返回 {"code": 1, "data": {...}} 或 {"code": 0}。

术语表

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

本页解释 NPS 管理界面和配置文档中的专有名词，以及容易混淆的字段。新增、编辑、保存等通用操作，以及版本、备注等含义明确的字段不再重复说明。

角色与对象

NPS 服务端：通常部署在有公网入口的设备上，负责接收 NPC 连接、监听隧道入口并转发流量。
NPC 客户端：运行在内网设备上的进程，主动连接 NPS，并从所在网络访问目标服务。
客户端：Web 管理中保存的一条逻辑记录，包含验证密钥、配额和所属隧道。NPC 使用对应密钥接入这条记录。
访问端：最终使用隧道的人或设备。私密代理和 P2P 模式下，访问端也要运行 NPC。
隧道：一条转发规则，描述入口、所属客户端、目标地址和转发方式。“隧道”本身不表示使用了 TLS 或端到端加密。
客户端 ID：NPS 为逻辑客户端分配的内部数字编号，用于关联隧道；连接 NPC 时使用的是客户端验证密钥。
客户端状态：NPC 是否已连接 NPS。在线表示控制连接可用，不代表每个目标服务都能访问。
运行状态：某条隧道是否启用并正在监听或等待连接。
允许客户端通过配置文件连接：允许该客户端通过 npc.conf 提交并创建隧道配置。关闭后，Web 中创建的隧道仍可使用。
管理员 / 用户：管理员管理全局配置和所有客户端；普通用户只管理分配给自己的客户端及隧道。

隧道类型

TCP 隧道：将 NPS 的一个 TCP 监听端口转发到 NPC 可访问的目标，适用于 SSH、远程桌面、数据库等。
UDP 隧道：将 NPS 收到的 UDP 数据转发到 NPC 可访问的目标。服务端防火墙需要放行对应 UDP 端口。
HTTP(S) 隧道：按域名和 URL 路径把请求反向代理到内网站点，多个站点可以共享 NPS 的 HTTP/HTTPS 端口。域名仍需自行解析到 NPS。
HTTP 正向代理：浏览器或应用显式配置代理后，通过 NPC 所在网络访问应用指定的 HTTP/HTTPS 资源。它与发布固定内网站点的 HTTP(S) 隧道方向不同。
SOCKS5 代理：支持 SOCKS5 的应用通过 NPC 所在网络连接应用指定的目标。只有配置了该代理的应用会经过 NPS。
私密代理：访问端运行 NPC，并用隧道访问密钥连接内网 TCP 服务。业务流量由 NPS 中转，但不必为每条隧道开放单独的公网端口。
P2P 连接：NPS 协调 NAT 穿透，尝试让访问端与提供服务的 NPC 直接传输业务流量。能否直连取决于双方网络和 NAT 类型。
文件服务：由 NPC 将本地路径中的文件通过 HTTP 提供出来，不提供文件同步或备份能力。
透明代理：P2P 访问端的一种本地接入方式，不是 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。

当前版本状态

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

NPS 内网穿透 on NPS Plus

v0.26.40

Docker 部署（推荐）

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

v0.26.38

Web 配置何时生效

生效范围

推荐操作

二进制安装

v0.26.37

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

使用方法

源码安装

v0.26.36

查看和保存隧道流量统计

统计口径

v0.26.35

查看客户端当前传输速度

如何读取

v0.26.34

查看 NPC 版本与兼容性

当前兼容行为

v0.26.33

提高 Linux 并发连接容量

v0.26.32

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

v0.26.31

v0.26.30

加密 NPC 与 NPS 之间的连接

服务端配置

使用说明

启动方式选择

使用说明

Web 管理

v0.26.29

为 NPC 连接 NPS 配置证书

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

配置方式

v0.26.28

改写 HTTP 后端收到的 Host

v0.26.27

新增或覆盖 HTTP 后端请求头

v0.26.26

自定义 HTTP 隧道的 404 页面

自定义方法

v0.26.25

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

开启并配置

v0.26.24

限制客户端的传输速度

开启并配置

v0.26.23

将新连接轮询到多个后端

Web 配置

v0.26.22

自动分配服务端监听端口

分配规则

v0.26.21

复制普通隧道配置

复制内容

v0.26.20

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

方案选择

在 NPS 中启用

服务端配置

使用示例

统一准备工作

v0.26.19

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

v0.26.18

批量映射 TCP 或 UDP 端口

配置示例

v0.26.17

批量映射到其他内网主机

v0.27.01（已作废）

使用 UDP/KCP 连接 NPS

服务端配置

v0.26.16

用泛域名转发多个子域名

配置步骤