服务端

• 1: 使用说明
• 2: 服务端配置
• 3: 增强功能

1 - 使用说明

Web 管理

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

仅当运行目录中不存在 conf/nps.conf 时，NPS 才会生成默认配置。管理员用户名固定为 admin，web_password、auth_key 和 auth_crypt_key 会随机生成并打印到终端。已有配置文件不会被改写。

修改 nps.conf 后请重启 NPS。Web 中保存的客户端和隧道设置通常会直接生效，二者的区别见 Web 配置何时生效 。

服务端管理脚本

./nps -server         # linux/darwin（操作系统服务时需 sudo）
nps.exe -server       # windows（操作系统服务时需管理员）

交互菜单提供安装、卸载、状态查询、启停、重启和更新操作。

工作目录与配置文件位置

配置位置取决于启动方式：

运行目录结构如下：

nps_dir/
├── conf/
│   ├── nps.conf     # NPS 主配置文件
│   ├── clients.json # 客户端列表
│   ├── tasks.json   # 普通隧道列表
│   ├── hosts.json   # HTTP(S) 隧道列表
│   └── global.json  # Web 全局设置
└── nps              # Windows 下为 nps.exe

启动日志中的 the config path is: 会显示当前实际运行目录。排查“修改配置不生效”时，应先确认编辑的是该目录下的文件。

更新

./nps -server   # 选择 “更新” 菜单项

菜单更新只替换当前目录中的 nps 二进制文件，不改写 conf。更新完成后需要重新启动服务。

如果无法成功更新，可直接下载 releases 压缩包覆盖原有的 nps 二进制文件。

数据迁移

先停止旧服务，再完整复制实际运行目录中的 conf 目录。目标端直接运行二进制时，可把 conf 放在 nps/nps.exe 同级目录；安装为服务或使用自定义目录时，应放到目标实例的 -conf_path 下。Web 静态资源已经嵌入二进制，不需要迁移单独的 web 目录。

迁移后先核对 nps.conf 中的监听地址、端口、证书路径和凭据，再启动目标服务；不要同时运行两个使用同一组客户端验证密钥的实例。

2 - 服务端配置

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

首次启动时若 conf/nps.conf 不存在会自动生成默认配置。web_username 固定为 admin，web_password、auth_key 和 auth_crypt_key 会生成随机值并打印到终端，请在启动日志或配置文件中查看。

下表“默认值”以代码首次自动生成的 nps.conf 为准。标为“未配置”的参数不会写入自动生成的文件，需要时再手动添加。修改 nps.conf 后应重启 NPS；监听端口、桥接协议等启动参数不会通过 Web 保存而重新创建。

通用配置

自动生成的 public_vkey=123 是公开配置客户端的共享凭据。无需通过 NPC 配置文件创建隧道时应将其留空；需要使用时应改为独立的随机值，不能继续使用示例值 123。

桥接证书的信任配置、持久化和名称模式切换详见桥接证书与身份验证 。桥接证书启动时加载，更新后需要重启 NPS；路径不完整或证书无效时启动失败，不会回退生成另一张证书。

HTTP(S) 隧道

当前版本的缓存实现边界和替代方案见 HTTP 响应缓存（未实现） 。

Web 管理

API 鉴权

P2P 连接

限制开关

这些参数控制 Web 管理是否显示或允许设置对应能力。首次生成的配置中，除 allow_local_proxy 外均按下表启用；改为 false 不会自动清除已经保存的客户端或隧道参数。

TCP 新连接限频默认值

这些参数只作用于 mode=tcp 的普通 TCP 隧道，是尚未在 Web 全局设置中保存对应配置时的后备值。单条隧道还可以继承、覆盖或关闭限频，详见 TCP 白名单与连接限频 。

debug / pprof

3 - 增强功能

使用 HTTPS

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

自动跳转 HTTPS（301）

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

当前重定向目标不会保留原请求的路径和查询参数。如果业务依赖完整 URL，请在 Nginx、Caddy 或应用层完成 HTTP 到 HTTPS 的跳转。

HTTPS 证书来源

Web 中的“HTTPS 证书（内容或文件路径）”和“HTTPS 私钥（内容或文件路径）”支持两种填写方式：

• 分别粘贴完整的 PEM 证书和私钥内容。
• 分别填写 NPS 服务端可读取的文件路径，例如 /etc/letsencrypt/live/proxy.com/fullchain.pem 和 /etc/letsencrypt/live/proxy.com/privkey.pem。

证书和私钥必须使用同一种方式。只要任一字段包含 -----BEGIN，NPS 就会把两个字段都当作 PEM 内容，而不会再把另一个字段当作路径。

使用文件路径时，NPS 会在新的 TLS 连接到来时读取文件。证书续期并原位替换文件后，后续连接通常无需重启即可使用新内容；应同时确认 NPS 进程对两个文件及其父目录有读取权限。

TLS 桥接加密

TLS 桥接会加密 NPC 与 NPS 之间的控制和隧道流量。它只支持 TCP 桥接，并使用独立的监听端口：

# nps.conf
bridge_type=tcp
tls_enable=true
tls_bridge_port=8025

修改后重启 NPS，客户端连接 TLS 端口并同时启用 TLS：

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

NPS 默认生成并持久化自签名证书，也支持自定义证书文件。NPC 默认校验服务端身份；默认自签名部署可从可信的服务端启动日志或新版 Web TLS 连接码获取公钥指纹。公共 CA、私有 CA、名称模式及迁移方法见桥接证书与身份验证 。

全局设置

Web 管理界面的“全局设置”保存在 conf/global.json：

全局 IP 黑名单不是主机防火墙，也不保护 Web 管理端口或 NPC 桥接端口。公网部署仍应使用安全组或防火墙限制这些管理入口。

客户端 IP 黑名单

客户端编辑页中的 IP 黑名单作用于该客户端下的普通 TCP、HTTP(S) 和 UDP 隧道。每行填写一个精确的 IPv4 或 IPv6 地址，不支持 CIDR；命中后连接或数据包会被丢弃。

客户端 IP 白名单与授权

客户端编辑页中的旧版“IP 白名单”只有在启用白名单且填写授权密码时才会执行。未在名单中的 HTTP(S) 请求会收到 401 授权页面，密码正确后，来源 IP 会加入该客户端的白名单。

这一功能按精确 IP 匹配，不支持 CIDR。普通 TCP 隧道会尝试向未授权连接返回同一套 HTTP 授权页面，因此只适用于 TCP 隧道内承载 HTTP 的场景；SSH、数据库等非 HTTP 协议无法通过该页面授权。UDP 隧道不执行这套白名单授权。

如果要保护 SSH、数据库等普通 TCP 隧道，请使用 TCP 白名单与连接限频 。该功能在单条 TCP 隧道上直接支持 IPv4、IPv6 和 CIDR，不依赖授权页面。

PROXY 协议

在 Web 的 TCP 隧道编辑页选择“PROXY 协议版本”后，NPS 会在转发数据前向后端发送 PROXY v1 或 v2 头。只有正确解析相应 PROXY 协议的后端（如 Nginx、HAProxy）才能据此取得原始来源 IP；不支持该协议的后端会把头部当作业务数据。

Web 登录验证码

在 nps.conf 中设置：

open_captcha=true

重启 NPS 后，Web 登录页会要求图形验证码。结合“Web 管理保护”（连续 10 次失败封禁 1 分钟，见说明 ），可以缓解密码暴力尝试。

关闭 HTTP(S) 隧道入口

将 http_proxy_port 留空可关闭 HTTP 入口，将 https_proxy_port 留空可关闭 HTTPS 入口。修改 nps.conf 后需要重启 NPS。

流量数据持久化

flow_store_interval 控制流量统计的保存间隔，单位为分钟。首次自动生成配置时默认值为 1，即每分钟保存一次；设置为 0、负数或无效值会停用定时保存。

NPS 不会持久化通过 public_vkey 动态创建的临时客户端。

系统信息显示

system_info_display 控制 Web 首页是否显示服务端系统信息图表。首次自动生成配置时默认为 true；修改后重启 NPS。

关闭 Web 管理

将 web_port 留空或删除该项，然后重启 NPS。关闭前应确认仍有可用的配置和运维方式。

服务端多用户登录

首次自动生成配置时 allow_user_login=true。启用后，客户端可使用自己的 Web 凭据登录，并且只能管理自身资源：

• 客户端同时设置了 Web 用户名和 Web 密码时，使用这组凭据登录。
• 两者都为空时，用户名为 user，密码为该客户端的 vkey。

如不需要客户端登录，应设置 allow_user_login=false 并重启 NPS。vkey 本身是敏感凭据，不应通过不可信渠道发送。

用户注册功能

设置 allow_user_register=true 并重启 NPS 后，登录页会出现注册入口。公网部署前应同时设置端口范围、客户端配额和访问控制，避免匿名用户占用任意监听端口。

监听指定 IP

设置 allow_multi_ip=true 并重启 NPS 后，可在 Web 中为隧道选择服务端监听 IP。通过 npc.conf 创建隧道时也可在对应隧道段设置：

server_ip=192.0.2.10

客户端到期时间

在创建或修改客户端时可以填写到期时间，留空表示不过期。到期后该客户端会被自动停用，所有隧道停止服务，直到管理员延长或清空到期时间。

支持格式：2006-01-02 15:04:05、2006-01-02 15:04、2006-01-02T15:04:05、2006-01-02T15:04 或 2006-01-02。

首次启动凭据

仅当运行目录中不存在 conf/nps.conf 时，NPS 才会生成默认配置。web_username 固定为 admin，web_password、auth_key 和 auth_crypt_key 使用随机值。启动日志格式如下：

[CONFIG] Auto-generated default config file: <path>
[CONFIG] Web login username: admin, password: <xxxxxxxx>
[CONFIG] auth_key: <xxxxxxxx>
[CONFIG] auth_crypt_key: <xxxxxxxxxxxxxxxx>

已有配置文件不会被随机改写。请保护日志和配置文件中的凭据，修改 nps.conf 后重启 NPS。

与 Nginx 配合

如果由 Nginx 复用 80/443 端口，可让 NPS 的 HTTP 隧道入口监听本机非标准端口，例如：

http_proxy_ip=127.0.0.1
http_proxy_port=8010
https_proxy_port=

重启 NPS 后，让 Nginx 的 HTTP 和 HTTPS 虚拟主机都代理到同一个 NPS HTTP 入口。必须保留原始 Host，NPS 才能匹配域名隧道：

server {
    listen 80;
    server_name *.proxy.com;

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

server {
    listen 443 ssl;
    server_name *.proxy.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

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

此方案由 Nginx 终止公网 TLS，NPS 不再监听 https_proxy_port。修改后先运行 nginx -t，再重载 Nginx。

Web 管理使用 HTTPS

在 nps.conf 中设置 web_open_ssl=true，并配置 NPS 服务端可读取的 web_cert_file 和 web_key_file，然后重启 NPS。

使用 Caddy 代理 Web 管理

下面是 Caddy 2 的子路径代理示例。假设外部地址为 http://nps.example.com/nps，NPS Web 管理监听 127.0.0.1:8081：

http://nps.example.com {
    @nps path /nps /nps/*
    reverse_proxy @nps 127.0.0.1:8081
}

同时在 nps.conf 中设置：

web_base_url=/nps

重启 NPS，并执行 caddy reload --config /etc/caddy/Caddyfile。反向代理必须保留 /nps 路径，不能在转发前去掉该前缀。