运行说明
本页解释 NPS 在运行时常见的行为边界:请求来自哪里、统计数值代表什么、哪些修改会立即生效,以及出现连接问题时应先检查什么。
获取访问者真实 IP
HTTP(S) 域名代理可在转发到后端时附加真实来源地址。服务端配置:
# conf/nps.conf
http_add_origin_header=true
启用后,后端应用可从请求头读取:
| 请求头 | 含义 |
|---|---|
X-Forwarded-For | 来源地址链;默认覆盖客户端伪装的同名头,preserve 或可信代理模式会保留旧链路并追加 NPS 直接看到的来源 |
X-Real-IP | NPS 看到的直接访问者 IP |
X-Forwarded-Host | 访问者请求 NPS 时使用的原始域名 |
X-Forwarded-Proto | 访问者到 NPS 的协议,http 或 https |
X-Forwarded-Port | 访问者请求的原始端口 |
X-Real-Proto | 与 X-Forwarded-Proto 对应的兼容协议头 |
http_forwarded_header_mode=overwrite 是默认策略,会覆盖访问者传入的转发头; preserve 保留已有值并追加来源;trusted 只有 TCP 对端命中 trusted_proxy_ips 时才保留已有值。http_forwarded_trust_mode=strict 还会 限制 NPS 从 X-Real-IP/X-Forwarded-For 还原访问者地址时只信任这些代理。
该能力只适用于 NPS 可以解析的 HTTP 请求,以及由 NPS 终结 TLS 后的 HTTPS 请求;TCP、UDP、SOCKS5 和纯 TLS 透传没有 HTTP Header 可写入。后端必须只信任 由 NPS 或受控反向代理写入的这些请求头。若后端直接暴露在公网,客户端可以伪造 同名 Header,不能把它们作为唯一的身份凭据。
修改配置后的生效范围
在 Web 管理面板中新增、编辑、启用或停用客户端、隧道和域名规则后,保存成功的规则会用于后续连接。它不等于完整的配置热重载。
下列项目修改后请重启 NPS,避免监听状态与配置文件不一致:
bridge_ip、bridge_port、bridge_type、tls_bridge_porthttp_proxy_ip、http_proxy_port、https_proxy_portweb_ip、web_port、web_open_ssl及 Web 证书路径- 需要重新读取的全局行为开关,例如
allow_local_proxy
Linux/macOS 可先执行:
sudo nps reload
reload 只适合重新读取认证和管理面板相关配置,例如 web_username、web_password、auth_key、auth_crypt_key。监听端口、Bridge、代理协议和正在运行的代理仍应使用 nps restart。Windows 修改配置后直接执行 nps.exe restart。
证书文件是例外:用于域名 TLS 终结的证书/私钥路径在新的 TLS 连接建立时会重新校验。外部续期脚本以临时文件加 mv 替换有效文件后无需重启;如果新文件无效或成对更新的中间状态不匹配,NPS 会继续使用最近一次有效证书。现有 HTTPS 和 WebSocket 连接不会被主动中断,详见平台域名与证书热更新。
客户端地址与在线状态
客户端列表中的连接地址是 NPS 当前看到的客户端出口地址,不是其内网目标地址。NAT、移动网络、容器和上游代理都会影响这个地址。
公网出口地址下方按「国家 · 省/州 · 城市 · 区县」显示 IP 归属地,重复名称自动合并;接口缺少某一层信息时跳过该层。文字过长时可悬浮查看全文。支持 IPv4 和 IPv6,内网地址(包括 IPv4 映射的 IPv6 内网地址)只显示「内网地址」,不向第三方查询。
能够确认国家/地区时,在归属地文字前显示一个 4:3 小旗帜。旗帜使用随程序打包的 flag-icons 7.6.0 SVG,不依赖外部 CDN;接口只提供国家名称时在浏览器本地匹配,不增加查询请求。内网地址、未知国家或图片无法加载时只保留文字,不显示错误旗帜。
归属地完全由当前浏览器异步查询:优先使用 ip258,超时、跨域/网络失败、HTTP 错误或无有效位置时,自动尝试 GeoJS。每个接口最多等待 4 秒,同一地址去重查询,最多同时处理 4 个地址;两个接口均失败时显示「地域未知」。ip9、uapis 不在查询链中,因为它们当前无法在无 Key 的情况下由浏览器直接跨域读取;NPS 不新增服务端代查。
主接口结果在浏览器本地缓存 30 天;GeoJS 备用结果缓存 1 天,过期后会重新优先查询主接口;全部失败后的同一地址在当前页面暂停重试 5 分钟。ip258 的省市区通常返回中文;提供国家代码时国家名称随界面语言显示,其余位置名称保留接口原文,因此 GeoJS 备用结果的省市仍可能为英文。NPS 不代查或落盘,查询失败不影响列表和穿透连接。IP 归属地只代表公网出口的估算位置,不保证与设备实际所在城市一致。
| 状态 | 含义 |
|---|---|
| 在线 | 客户端主控制连接和心跳正常 |
| 离线 | 未建立控制连接、网络中断、验证失败或客户端已退出 |
| 暂停 | 客户端被手动停用或已到期;其名下规则不会继续提供服务 |
客户端可上报局域网地址,用于管理页面辅助排查;它仅供显示,不是公网可直接访问的地址。
新增、编辑隧道和域名规则时,客户端选择框与列表筛选使用相同的在线状态气泡,并显示客户端备注、ID 和所属用户(有用户备注时显示为 备注 (账号))。过长的名称会省略,悬浮可查看完整信息;在线状态以本次加载时的服务端信息为准,离线客户端仍可选择。选项仅包含当前登录账户有权访问的客户端;编辑页加载失败或返回结果缺少原客户端时保留原选中项,不会自动迁移到其他客户端。
流量、带宽和连接数
客户端列表把入口和出口累计量合并为「累计流量」一列,上下两行分别是 ↑ 入口:公网→内网、↓ 出口:内网→公网;旁边的「实时带宽」沿用相同的两行样式,并以 /s 区分实时速率。悬浮表头的信息图标可查看方向、单位和排序说明;点击表头仍按入口累计流量或入口实时带宽排序。桌面和窄屏卡片均显示两个方向,不改变底层统计与限速逻辑。
| 指标 | 含义 |
|---|---|
| 入口流量 | 公网访问者经 NPS 发往内网目标的累计字节数(公网 → 内网) |
| 出口流量 | 内网目标经 NPS 返回访问者的累计字节数(内网 → 公网) |
| 当前带宽 | 当前采样窗口内的传输速率,适合观察趋势,不是计费级精确值 |
| 当前连接数 | 当前客户端名下正在处理的连接数 |
| 当前 TCP 连接 | 单条 TCP 隧道当前建立的连接数;仅在 TCP 隧道列表显示 |
| 最大连接数 | 客户端级上限;需要服务端启用 allow_connection_num_limit=true |
| 流量限制 | 客户端级累计流量上限,单位为 MB;入口与出口字节数相加后超过上限时,新的代理连接会被拒绝。需要 allow_flow_limit=true。 |
| 带宽限制 | 客户端级双向总速率上限,单位为 KB/s;同一客户端下所有隧道共享一个令牌桶,允许短暂突发,不是单隧道或严格瞬时上限。需要 allow_rate_limit=true。 |
除了客户端级带宽外,普通隧道和 Host 规则还支持独立的 upload_limit / download_limit。它们的单位也是 KB/s:上行是访问者到内网服务,下行是内网服务到访问者;0 表示不限速,同一条资源的所有连接共享额度。资源级、客户端级和服务端全局限制会叠加,某一层更小就会成为实际瓶颈。面板显示的当前上行/下行速率是近似的一秒采样值,不是精确计费数据;P2P 成功直连时不经过 NPS,不受服务端资源限速约束。
当前连接数与最大连接数是数据连接配额,不是隧道条目数;长连接、慢请求和 WebSocket 会持续占用配额。压缩、加密、协议头以及采样时机都会使显示数值与操作系统网卡计数存在差异。请用 NPS 指标进行容量观察,用云厂商或网卡计费数据进行账单核对。
升级到 v1.1.12 时,旧版本中“两个方向同时累加”的历史流量会归并为“历史”总量,用于保留已消耗的流量配额;这部分无法倒推出真实方向,因此不会伪装成入口或出口。
仪表盘运行状态
首页的“运行状态”是一个轻量级概览,默认每 15 秒局部刷新一次;浏览器切换到后台时会暂停轮询,点击刷新按钮可立即更新。刷新只请求 /index/dashboarddata,不会重新加载页面或触发全屏遮罩。
管理员看到服务器级客户端、隧道、域名主机、代理连接和 NPS 入/出站速率,并可查看宿主机 CPU、内存、系统连接和网卡采样。普通用户只看到自己名下客户端、隧道、Host、流量和配额,接口也不会返回管理员的监听配置或宿主机指标。
状态含义如下:
| 区域 | 状态或指标 | 说明 |
|---|---|---|
| 客户端 | 在线、离线、已停用、即将到期 | 依据控制连接、启用状态和到期时间汇总。 |
| 隧道 | 运行中、已停止、等待客户端连接、启动失败 | 列表的“配置状态”表示规则是否启用;“监听状态”表示服务端是否实际持有监听。等待连接表示规则已启用但 NPC 尚未建立控制连接;启动失败会在展开行显示最后一次错误,例如端口冲突。 |
| 当前代理速率 | 入站 / 出站 | 仅统计经过 NPS 代理的字节速率,不是宿主机网卡总速率;首次采样建立基线,可能显示为 0。 |
| 待处理事项 | 配额或健康告警 | 客户端连接数、隧道数或流量达到约 80% 时提示;健康检查失败或客户端即将到期也会提示。 |
| 最后更新时间 | 本地时间 | 用于确认这次概览数据的采样时间。 |
资源状态图按运行中、已停止、等待连接和启动失败汇总,不会把协议类型误当作运行状态。流量、连接和配额数值仍以服务端数据层为准,页面刷新失败时不会覆盖上一次成功的结果。
管理员首页的“配额使用”区域会列出每个可见客户端的连接、隧道和流量限制;普通用户只会看到自己名下的客户端。未设置限制的项目显示为“未设置限制”,不会凭空生成配额。
首页的“用量趋势”卡片读取持久化的 NPS 代理历史,不依赖当前浏览器保持打开。 管理员默认查看全站汇总,普通用户查看自己的账号范围;可切换最近 24 小时、 7 天和 30 天。24 小时使用分钟精度,7 天和 30 天使用五分钟精度。卡片每 60 秒刷新,页面进入后台时暂停请求。采样默认每 60 秒一次,首次启动后需等待 一个采样周期才会出现第一个点;现存连接在服务启动时的首次采样只建立累计值 基线,不会被误算成一次爆发流量。原始数据默认写入 conf/usage_history.json,不包含 P2P 直连流量。
已有历史文件会自动兼容:旧记录缺失的用户/客户端范围标识在加载时补齐,仍在 保留期内的采样继续显示,不必删除历史重建。分钟精度默认保留 48 小时,五分钟 精度默认保留 90 天;启用采集时,启动和每次采样都会自动清理过期点,并在下次 写盘时更新历史文件。已删除资源的历史在两种精度全部过期后自动回收;客户端 仅离线不会导致历史被提前删除。可在「全局参数 → 服务端配置 → 日志与审计」 调整保留时长,重启后生效。
版本兼容
NPS 和 NPC 应使用同一正式发布版本。Bridge 握手会交换版本信息,但它不是跨版本兼容性的保证;协议、TLS、配置字段和更新方式变化时,混用二进制仍可能导致连接或转发异常。
升级顺序建议为:
- 备份服务端
conf/目录和现有二进制。 - 先升级 NPS 服务端,确认管理面板和现有客户端正常。
- 分批升级 NPC 客户端;同一台机器多实例时逐个升级。
- 确认 Bridge、HTTP(S) 代理和关键 TCP 隧道都可访问后再清理旧版本。
不要让同一个客户端启动命令混用来自不同大版本的 NPS/NPC 二进制。出现 Current client connection validation error 时,先检查 VerifyKey、客户端/用户状态和到期时间、Bridge 端口与 TLS 参数,再检查版本是否成对升级。
更新与回滚
CLI 和 GUI 客户端的自动更新会从本项目 GitHub Release 选择对应平台的发布包,并校验发布的 SHA-256 清单。网络受限或自动更新失败时,可从 Release 手动下载同一版本的压缩包后覆盖二进制。
服务端升级前必须备份完整 conf/ 目录;Docker 部署还必须确认 conf/ 通过宿主机目录或命名卷持久化。二进制或镜像更新本身不会替代配置备份。升级、检查和回滚步骤见升级迁移。
Linux 连接数限制
高并发场景中,系统文件描述符和 TCP 队列通常先成为瓶颈。启动前检查:
ulimit -n
sysctl net.core.somaxconn net.ipv4.tcp_max_syn_backlog
按机器性能、连接量和发行版规则调整服务账号的 nofile 限制,以及 somaxconn、tcp_max_syn_backlog 等内核队列参数。systemd 服务可通过覆盖配置设置 LimitNOFILE,例如:
# systemctl edit nps
[Service]
LimitNOFILE=1048576
调整后执行 systemctl daemon-reload 并重启服务,再观察日志;不要只提高数值而忽略 CPU、内存和带宽余量。
Web 管理保护
可通过验证码和登录失败保护降低后台暴力尝试风险:
open_captcha=true
同一 IP 在 1 分钟窗口内最多可进行 10 次显式登录尝试;连续失败达到上限后,会被临时拒绝直到窗口过期,成功登录会清除该 IP 的尝试记录。这个机制不能代替网络隔离。生产环境应优先让 web_ip 监听在 127.0.0.1 或管理网卡,再用 HTTPS 反向代理、VPN 或防火墙限制管理入口。
性能分析
NPS 可选开启 Go pprof:
pprof_ip=127.0.0.1
pprof_port=9999
pprof 会暴露运行时诊断信息,应只绑定回环或受控管理网段,不要将其直接公开到互联网。客户端配置文件也支持在 [common] 中使用 pprof_addr=127.0.0.1:9999。
排查顺序
出现“域名能解析但访问失败”或“客户端在线但隧道不可用”时,按以下顺序检查:
- 确认 NPS 对应监听端口已经启动,且云安全组、系统防火墙、Docker 端口策略允许访问。
- 在 NPS 主机本地验证监听和目标服务,再从外网验证。
- 确认客户端在线、未到期、隧道已启用,并检查目标地址属于 NPC 所在网络命名空间。
- 域名代理确认 DNS 指向 NPS 公网 IP,访问时携带正确 Host;非标准端口也必须写在 URL 中。
- 查看 NPS 与 NPC 同一时段日志,定位验证失败、端口占用、目标连接失败或超时。
