运行说明

本页解释 NPS 在运行时常见的行为边界：请求来自哪里、统计数值代表什么、哪些修改会立即生效，以及出现连接问题时应先检查什么。

获取访问者真实 IP

HTTP(S) 域名代理可在转发到后端时附加真实来源地址。服务端配置：

# conf/nps.conf
http_add_origin_header=true

启用后，后端应用可从请求头读取：

请求头含义
X-Forwarded-For访问链路中的来源地址；NPS 会保留已有链路并追加它直接看到的来源
X-Real-IPNPS 看到的直接访问者 IP

该能力只适用于 NPS 可以解析的 HTTP 请求，以及由 NPS 终结 TLS 后的 HTTPS 请求；TCP、UDP、SOCKS5 和纯 TLS 透传没有 HTTP Header 可写入。后端必须只信任由 NPS 或受控反向代理写入的这两个请求头。若后端直接暴露在公网，客户端可以伪造同名 Header，不能把它们作为唯一的身份凭据。

修改配置后的生效范围

在 Web 管理面板中新增、编辑、启用或停用客户端、隧道和域名规则后，保存成功的规则会用于后续连接。它不等于完整的配置热重载。

下列项目修改后请重启 NPS，避免监听状态与配置文件不一致：

  • bridge_ip、bridge_port、bridge_type、tls_bridge_port
  • http_proxy_ip、http_proxy_port、https_proxy_port
  • web_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、移动网络、容器和上游代理都会影响这个地址。

状态含义
在线客户端主控制连接和心跳正常
离线未建立控制连接、网络中断、验证失败或客户端已退出
暂停客户端被手动停用或已到期；其名下规则不会继续提供服务

客户端可上报局域网地址，用于管理页面辅助排查；它仅供显示，不是公网可直接访问的地址。

流量、带宽和连接数

指标含义
入流量 / 出流量经过 NPS 代理的两个方向累计字节数
当前带宽当前采样窗口内的传输速率，适合观察趋势，不是计费级精确值
当前连接数当前客户端名下正在处理的连接数
最大连接数客户端级上限；需要服务端启用 allow_connection_num_limit=true
流量限制客户端级累计流量上限，单位为 MiB；入口与出口字节数相加后超过上限时，新的代理连接会被拒绝。需要 allow_flow_limit=true。
带宽限制客户端级速率上限，单位为 KiB/s；同一客户端的代理流量共享限速器。需要 allow_rate_limit=true。

当前连接数与最大连接数是数据连接配额，不是隧道条目数；长连接、慢请求和 WebSocket 会持续占用配额。压缩、加密、协议头以及采样时机都会使显示数值与操作系统网卡计数存在差异。请用 NPS 指标进行容量观察，用云厂商或网卡计费数据进行账单核对。

仪表盘运行状态

首页的“运行状态”是一个轻量级概览，默认每 15 秒局部刷新一次；浏览器切换到后台时会暂停轮询，点击刷新按钮可立即更新。刷新只请求 /index/dashboarddata，不会重新加载页面或触发全屏遮罩。

管理员看到服务器级客户端、隧道、域名主机、代理连接和 NPS 入/出站速率，并可查看宿主机 CPU、内存、系统连接和网卡采样。普通用户只看到自己名下客户端、隧道、Host、流量和配额，接口也不会返回管理员的监听配置或宿主机指标。

状态含义如下：

区域状态或指标说明
客户端在线、离线、已停用、即将到期依据控制连接、启用状态和到期时间汇总。
隧道运行中、已停止、等待客户端连接“等待客户端连接”表示规则已启用但对应 NPC 尚未建立控制连接。
当前代理速率入站 / 出站仅统计经过 NPS 代理的字节速率，不是宿主机网卡总速率；首次采样建立基线，可能显示为 0。
待处理事项配额或健康告警客户端连接数、隧道数或流量达到约 80% 时提示；健康检查失败或客户端即将到期也会提示。
最后更新时间本地时间用于确认这次概览数据的采样时间。

资源状态图只区分隧道的运行中、已停止和等待连接，不再把协议类型误当作运行状态。流量、连接和配额数值仍以服务端数据层为准，页面刷新失败时不会覆盖上一次成功的结果。

管理员首页的“配额使用”区域会列出每个可见客户端的连接、隧道和流量限制；普通用户只会看到自己名下的客户端。未设置限制的项目显示为“未设置限制”，不会凭空生成配额。

版本兼容

NPS 和 NPC 应使用同一正式发布版本。Bridge 握手会交换版本信息，但它不是跨版本兼容性的保证；协议、TLS、配置字段和更新方式变化时，混用二进制仍可能导致连接或转发异常。

升级顺序建议为：

  1. 备份服务端 conf/ 目录和现有二进制。
  2. 先升级 NPS 服务端，确认管理面板和现有客户端正常。
  3. 分批升级 NPC 客户端；同一台机器多实例时逐个升级。
  4. 确认 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。

排查顺序

出现“域名能解析但访问失败”或“客户端在线但隧道不可用”时，按以下顺序检查：

  1. 确认 NPS 对应监听端口已经启动，且云安全组、系统防火墙、Docker 端口策略允许访问。
  2. 在 NPS 主机本地验证监听和目标服务，再从外网验证。
  3. 确认客户端在线、未到期、隧道已启用，并检查目标地址属于 NPC 所在网络命名空间。
  4. 域名代理确认 DNS 指向 NPS 公网 IP，访问时携带正确 Host；非标准端口也必须写在 URL 中。
  5. 查看 NPS 与 NPC 同一时段日志，定位验证失败、端口占用、目标连接失败或超时。

具体的域名、非 80/443 端口和服务端本地转发配置请阅读隧道模式与服务端增强功能。