NPSNPS
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
  • 文档首页
  • 快速上手

    • 安装与部署
    • 快速开始
    • 运行命令速查
    • 完整部署参考
    • 隧道模式
    • 使用示例
  • 服务端

    • 服务端使用
    • 使用说明页面配置
    • 配置文件参考
    • 服务端增强功能
    • 服务端介绍
    • 部署安全与参数速查
    • Docker 部署
    • 宝塔面板部署
  • 客户端

    • 客户端使用
    • 客户端增强功能
    • NPC SDK
    • 客户端配置与启动
    • 配置文件参考
    • NPC Docker 部署
    • 飞牛 fnOS 原生包
    • NPC GUI 客户端
    • 客户端更新与远程升级
  • 扩展功能

    • 功能概览
    • 域名代理与路由
    • 平台域名与证书诊断
    • 访问控制与配额
    • 运行说明
    • 对外 API v1
    • API 鉴权与兼容
    • 历史 Web API
    • 使用示例
  • 项目与社区

    • 用户体系
    • 系统架构
    • 升级迁移
    • 功能与兼容矩阵
    • 构建发布
    • 本项目更新日志
    • 上游更新日志
    • FAQ
    • 贡献
    • 交流
    • 捐助
    • 致谢

客户端配置

客户端程序为 npc。它运行在内网设备上,主动连接公网 NPS 服务端。推荐使用无配置文件模式:客户端、隧道和域名规则都在服务端 Web 面板管理,npc 只负责连接。

运行方式

方式适合场景特点
无配置文件模式常规部署、Web 面板集中管理命令只需要 -server 和 -vkey
配置文件模式旧版配置、批量静态配置、不依赖 Web 面板读取本地 npc.conf
交互式菜单Windows 双击、手动注册服务可粘贴快捷启动命令
系统服务需要长期在线、开机自启后台运行,日志写入文件
Docker容器化客户端注意容器网络和内网目标地址

无配置文件模式

普通 Bridge:

./npc -server=<服务器IP>:8024 -vkey=<VerifyKey>

其他 Bridge 入口:

入口示例命令注意事项
TCP + TLS./npc -server=<服务器IP>:8025 -vkey=<VerifyKey> -tls_enable=true服务端需启用 tls_enable
KCP./npc -server=<服务器IP>:8026 -vkey=<VerifyKey> -type=kcp需放行 UDP
WS./npc -server=<服务器IP>:8027 -vkey=<VerifyKey> -type=ws -bridge_path=/ws路径需与服务端 bridge_path 一致
WSS./npc -server=<服务器IP>:8028 -vkey=<VerifyKey> -type=wss -bridge_path=/ws需放行 TCP,路径与服务端一致
QUIC./npc -server=<服务器IP>:8029 -vkey=<VerifyKey> -type=quic -quic_alpn=nps -tls_server_name=<证书域名>需放行 UDP,ALPN 与服务端一致
HTTP/3 Bridge./npc -server=<Bridge域名>:<http3端口> -vkey=<VerifyKey> -type=quic -quic_alpn=nps -tls_server_name=<bridge_host>仅在 HTTPS 入口、HTTP/3 反代和 bridge_http3=true 均已启用时可用

Web 面板只展示实际启用且能够监听的入口。bridge_*_show=false 可隐藏某一入口的命令,但不会关闭对应监听。

TLS 系列 Bridge:

./npc -server=<服务器IP>:8025 -vkey=<VerifyKey> -tls_enable=true

TLS 客户端默认校验证书。NPS 首次启动会在日志中打印服务端证书的 SHA-256 指纹;服务端使用自签名证书时,建议固定该指纹:

./npc -server=<服务器IP>:8025 -vkey=<VerifyKey> \
  -tls_enable=true -tls_fingerprint=<SHA-256指纹>

也可以通过 -tls_ca_file=<CA文件> 使用 CA 链校验,并按需设置 -tls_server_name=<证书名称>。-tls_insecure_skip_verify=true 仅用于兼容旧部署,生产环境不要启用。

一个进程可连接多个客户端配置:

./npc -server=<服务器IP>:8024 -vkey=key1,key2,key3

也可以同时连接多个 NPS 服务端。各列表按位置对应;vkey、type、local_ip 列表较短时会复用最后一项,type=tls 等价于 TCP Bridge 并启用 TLS:

./npc -server=nps-a.example.com:8024,nps-b.example.com:8025 \
  -vkey=key-a,key-b -type=tcp,tls

Windows:

npc.exe -server=<服务器IP>:8024 -vkey=<VerifyKey>

VerifyKey 在 NPS Web 面板的「客户端」页面创建,必须和对应客户端匹配。

环境变量

如果命令行未传 -server 或 -vkey,客户端会尝试读取:

环境变量说明
NPC_SERVER_ADDR服务端地址,例如 1.1.1.1:8024
NPC_SERVER_VKEY客户端连接密钥

常用命令行参数

参数说明默认值
-server服务端地址,格式 ip:port空
-vkey客户端连接密钥,多个用英文逗号分隔空
-config配置文件路径默认配置路径
-time执行 npc register 时请求的临时 IP 登记时长,单位小时2
-service_name通过 install 注册的系统服务名;交互菜单创建的独立服务不使用这一默认名Npc
-typeBridge 类型,tcp、kcp、ws、wss 或 quic;tls 等价于 TCP 并启用 TLStcp
-bridge_pathWS/WSS Bridge URL 路径,需与服务端配置相同/ws
-quic_alpnQUIC Bridge 的 ALPN,需与服务端配置相同nps
-tls_enable启用 TLS Bridgefalse
-tls_ca_fileTLS CA 证书文件空
-tls_server_nameTLS SNI/证书名称服务端地址
-tls_fingerprint服务端证书 SHA-256 指纹空
-tls_insecure_skip_verify显式关闭 TLS 证书校验(不推荐)false
-proxy通过 HTTP/HTTPS CONNECT、SOCKS4/4a、SOCKS5/SOCKS5H 代理连接服务端空
-local_ip指定 NPC 对 NPS 的本地出站地址空
-local_ip_forward将本地出站地址用于公网目标的 TCP/UDP/SOCKS5 UDP 转发false
-dns_server自定义 DNS 服务器,多个地址用逗号分隔系统解析器
-disable_remote_update忽略服务端下发的远程更新指令false
-disconnect_timeout心跳超时倍数,单位为 5 秒60
-log日志输出方式,stdout 或 filestdout
-log_level日志级别,0 到 77
-log_path日志文件路径自动选择
-debug是否输出到控制台;作为系统服务时会自动追加 -debug=falsetrue
-pprofpprof 地址,格式 ip:port空
-version输出版本号false

代理示例:

./npc -server=1.1.1.1:8024 -vkey=key \
  -proxy=socks5://user:pass@127.0.0.1:9007

配置文件模式

./npc -config=npc.conf

需要同时运行多份相互独立的配置时,可传入逗号分隔的文件路径:

./npc -config=/etc/nps/npc-a.conf,/etc/nps/npc-b.conf

未指定 -config 时,源码默认查找:

  • Windows:程序目录下的 conf/npc.conf
  • Linux/macOS:当前工作目录下的 conf/npc.conf

示例:

[common]
server_addr=1.1.1.1:8024
conn_type=tcp
vkey=your-key
auto_reconnection=true
compress=true
crypt=true

[ssh]
mode=tcp
target_addr=127.0.0.1:22
server_port=9001

配置文件模式适合旧版用法或不使用 Web 面板管理的场景。常规部署建议继续使用无配置文件模式。

完整的所有模式、配置项、健康检查、端口范围和环境变量模板请查阅 NPC 配置文件参考。

common 传输选项

配置项说明默认值
compress使用 Snappy 压缩 Bridge 数据,可降低带宽占用;CPU 较弱时可关闭false
crypt加密 Bridge 数据,需与服务端/客户端配置保持一致false
server_addr服务端地址;兼容旧配置别名 server空
conn_type连接类型 tcp、kcp、ws、wss 或 quic;兼容旧配置别名 tptcp
tls_ca_file服务端 CA 证书文件空
tls_server_nameTLS SNI/证书名称服务端地址
tls_fingerprint服务端证书 SHA-256 指纹空
tls_insecure_skip_verify显式关闭证书校验,仅兼容旧部署false

交互式菜单

直接运行 npc 或双击 npc.exe,如果没有 -server、-vkey,也没有找到配置文件,会进入交互式菜单。

菜单项:

输入操作
1注册系统服务,需要输入快捷启动命令;可一次输入多个,用英文逗号分隔
2删除/卸载系统服务,需要输入 vkey 或完整服务名;会先停止服务再卸载
3启动系统服务,需要输入 vkey 或完整服务名
4停止系统服务,需要输入 vkey 或完整服务名
5更新当前程序和已注册服务实际路径;可确认重启原本运行中的服务
6查看已注册的 nps-client-* 服务列表,并显示每个服务状态
7查看指定 vkey 对应服务的状态
8实时跟踪指定 NPC 服务日志(输入服务名或 vkey,按 Ctrl+C 返回)
9重启所有已注册 NPC 服务(需要输入 y 确认)
0退出
快捷启动命令不注册服务,直接启动连接;可一次输入多个,用英文逗号分隔

更新、回滚、旧 NPC 首次迁移及多 VKey 共用文件的注意事项见 客户端更新与远程升级。远程更新不会自动重启其他 VKey 服务。

也可以直接粘贴 Web 面板生成的「快捷启动命令」。多个快捷启动命令用英文逗号拼接。

快捷启动命令由 Web 面板按实际启用的 Bridge 入口生成,内容始终是 Base64。

TCP 和 TCP + TLS 继续使用永久兼容的 v1 格式:

nps:<名称>|<服务端地址:端口>|<VerifyKey>|<是否TLS>[|<TLS证书指纹>]

KCP、WS、WSS、QUIC 和 HTTP/3 使用 v2 JSON 格式,可携带协议、WS Path、QUIC ALPN、TLS Server Name 与证书指纹。Web 面板会在命令旁标记 v1 或 v2:

{
  "v": 2,
  "name": "测试客户端",
  "server": "nps.example.com:8027",
  "vkey": "a22c306c64",
  "endpoint": "ws",
  "transport": "ws",
  "bridge_path": "/ws",
  "tls": false
}

命令行 npc 与 NPC GUI 都兼容 v1 和 v2。v1 可由历史 NPC 继续读取;v2 需要升级到支持多协议快捷命令的 NPC/GUI(1.1.37 或更高)。无法识别 v2 的旧版程序不会错误地按 TCP 参数启动连接。

系统服务

命令行安装仍然可用:

sudo ./npc install -server=<服务器IP>:8024 -vkey=<VerifyKey>
sudo npc start

Windows 需要管理员 CMD 或 PowerShell:

npc.exe install -server=<服务器IP>:8024 -vkey=<VerifyKey>
npc.exe start

命令行安装会注册通用 Npc 服务,安装时带上的 -server、-vkey、-tls_enable 等参数会作为服务启动参数。

Linux 上请使用 sudo 执行安装。安装后服务会固定使用系统安装路径(通常为 /usr/bin/npc,无权限时为 /usr/local/bin/npc),不依赖解压目录;可以移动或删除下载的压缩包目录。

交互式菜单注册服务时,会按 vkey 和 Bridge 入口创建独立服务。普通 TCP 保留历史名称:

nps-client-<vkey>

其他入口使用协议后缀:

入口服务名
TCPnps-client-<vkey>
TCP + TLSnps-client-<vkey>-tls
KCPnps-client-<vkey>-kcp
WSnps-client-<vkey>-ws
WSSnps-client-<vkey>-wss
QUICnps-client-<vkey>-quic
HTTP/3 Bridgenps-client-<vkey>-http3

同一 VKey 安装多个入口时互不覆盖。启动、停止或删除时如果只填写 VKey 且存在多个后缀服务,程序会列出完整服务名并要求重新选择;直接输入完整服务名可精确操作。服务参数会完整保存协议、-bridge_path、-quic_alpn、TLS Server Name、证书指纹和 CA 文件,重启后不会退回普通 TCP。

交互式菜单里的「查看已注册服务列表」会扫描当前系统中已经注册的 nps-client-* 服务,适合一台机器绑定多个服务端或多个协议时排查。

日志默认位置:

系统日志路径
Linux/macOS/var/log/npc.log;独立服务按入口写成 /var/log/npc-<vkey>[-协议].log
Windowsnpc.exe 所在目录下的 npc.log 或 npc-<vkey>[-协议].log

HTTP/SOCKS5 代理认证

HTTP 正向代理和 SOCKS5 优先使用各自隧道上配置的独立认证;没有配置时才回退到所属客户端的公共 Basic 认证:

  1. 独立认证:编辑「HTTP / SOCKS 混合代理」规则,在「认证配置」中填写 用户名:密码,每行一个账号。该账号只作用于当前代理端口,设置后不会回退到客户端公共认证。
  2. 公共认证:如果没有配置独立认证,可在「客户端 → 编辑 → 认证配置」填写「Basic 认证用户名」和「Basic 认证密码」。该客户端下的混合代理和域名规则会复用这组认证。
  3. 文件访问本身不使用这组穿透入口认证;需要保护时应在反向代理或上游应用增加认证。

如果这两个字段都为空,SOCKS5 会允许无认证连接,知道服务端 IP 和端口的人都可以尝试连接。公网开放 SOCKS5 时,建议务必设置账号密码,并配合客户端黑名单、全局黑名单或防火墙限制来源 IP。

Docker 客户端

docker run -d --name npc wushuo98/npc \
  -server=<服务器IP>:8024 -vkey=<VerifyKey>

TLS:

docker run -d --name npc wushuo98/npc \
  -server=<服务器IP>:8025 -vkey=<VerifyKey> -tls_enable=true

容器里的 127.0.0.1 是容器自身,不是宿主机。如果隧道目标在宿主机上,Linux 可按需使用 --network host;Windows/macOS Docker Desktop 需要使用 Docker 提供的宿主机访问地址。

P2P 和 Secret 本地访问端

当传入 -password 时,客户端进入本地访问端模式,用于访问 P2P 或 Secret 隧道。

参数说明默认值
-passwordP2P/Secret 密钥空
-targetP2P 目标地址空
-local_type本地模式,p2p 或 secretp2p
-local_port本地监听端口2000
-target_type目标协议,tcp、udp 或 allall
-fallback_secretP2P 直连失败后是否回退 Secret 中继true

Secret 示例:

./npc -server=1.1.1.1:8024 -vkey=key \
  -password=secret-key -local_type=secret -local_port=2000

P2P 示例:

./npc -server=1.1.1.1:8024 -vkey=key \
  -password=p2p-key -target=10.0.0.2:22 -local_type=p2p -local_port=2000

NAT 类型检测:

./npc nat -stun_addr=stun.stunprotocol.org:3478

P2P 依赖双方 NAT 类型,不保证所有网络都能直连。-fallback_secret=true(默认)时直连失败会自动回退同任务 Secret 中继;关闭后直连失败直接报错,需要改用普通 TCP 或其他隧道方式。-target_type=udp 或 all 时,访问端本地端口同时提供 UDP 服务,UDP 数据报在转发链路上保持边界。

在 GitHub 上编辑此页
最后更新: 2026/11/7 20:51
Prev
NPC SDK
Next
配置文件参考