跳转到主要内容

使用说明

通过交互菜单、命令行、配置文件或 GUI 运行客户端，并管理系统服务

启动方式选择

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

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

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

./npc -config=/etc/nps/npc.conf

快捷连接码与交互菜单

在 Web 管理的客户端列表中展开客户端，可以复制【快捷连接码】或【TLS 快捷连接码】。当前格式是下列明文的 Base64 编码：

nps:<备注>|<服务端地址:桥接端口>|<vkey>|<是否启用 TLS>

新版 TLS 连接码在末尾增加第五段 |<服务端公钥指纹>。旧四段格式仍可读取，但自签名证书需要额外配置信任；建议重新复制新版 TLS 连接码。证书校验方式见桥接证书与身份验证 。

Base64 只是编码，不是加密；快捷连接码包含 vkey，应当按凭据保护，不要公开到日志、截图或聊天群。

无默认配置文件时，直接运行 npc/npc.exe 会进入菜单：

操作输入内容
直接连接快捷连接码；多个连接码使用英文逗号分隔
注册系统服务快捷连接码；多个连接码使用英文逗号分隔
卸载服务客户端 vkey；多个 vkey 使用英文逗号分隔
启动服务客户端 vkey；多个 vkey 使用英文逗号分隔
停止服务客户端 vkey；多个 vkey 使用英文逗号分隔

每个系统服务以 nps-client-<vkey> 命名，因此同一台机器可以注册多个客户端实例。

image

命令行连接

# TCP 桥接
./npc -server=nps.example.com:8024 -vkey=客户端验证密钥

# TLS 桥接：服务端使用受系统 CA 信任且域名匹配的证书
./npc -server=nps.example.com:8025 -vkey=客户端验证密钥 -tls_enable=true

# 使用同一组连接参数启动两个客户端实例
./npc -server=nps.example.com:8024 -vkey=客户端密钥1,客户端密钥2

逗号分隔的是多个客户端验证密钥，不是隧道 ID。每个客户端连接断开后，命令行模式会等待 5 秒再连接。

常用选项：

选项默认值说明
-server空NPS 地址和桥接端口，例如 nps.example.com:8024
-vkey空Web 中客户端的验证密钥；可用英文逗号连接多个密钥
-typetcpNPC 到 NPS 的桥接类型：tcp 或 kcp
-tls_enablefalse启用 TCP TLS 桥接；必须连接 tls_bridge_port，不适用于 KCP
-tls_ca_file空私有 CA PEM 文件；默认使用系统信任根
-tls_server_name空证书校验名称；默认取服务端地址的主机部分，DNS 名称同时用于 SNI
-tls_server_fingerprint空服务端公钥 SHA-256 指纹（64 位十六进制），与 CA 文件二选一
-tls_insecure_skip_verifyfalse显式跳过证书验证，仅兼容旧部署；不能与上述信任选项同时使用
-proxy空TCP 桥接的 HTTP 或 SOCKS5 出站代理 URL；KCP 不使用该选项
-disconnect_timeout60连续未收到 5 秒心跳的次数；默认约 5 分钟，不是秒数
-debugtruetrue 输出到终端；false 输出到日志文件
-log_path自动-debug=false 时的日志路径
-log_level7Beego 日志等级 0 到 7
-pprof空pprof 监听地址，例如 127.0.0.1:9999；不要直接暴露到公网
-versionfalse输出版本信息后退出

-log 参数虽然仍能被命令行解析，但当前实现不读取它来决定日志输出，请使用 -debug 和 -log_path。

KCP、TLS 和出站代理的约束分别见 KCP 传输 、TLS 加密 NPC 连接 和出站代理 。私密代理与 P2P 的访问端命令见配置示例 。

配置文件模式

npc.conf 可以同时声明客户端连接和由该客户端创建的隧道：

[common]
server_addr=nps.example.com:8024
conn_type=tcp
vkey=客户端验证密钥
auto_reconnection=true
disconnect_timeout=60

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

使用已有客户端的 vkey 时，管理员必须在 Web 客户端编辑页启用“允许客户端通过配置文件连接”。另一种方式是使用服务端 public_vkey 动态创建临时客户端，但它是共享凭据，首次自动生成配置中的示例值 123 不应继续用于生产环境。

auto_reconnection=true 表示配置连接退出后等待 5 秒重连。修改 npc.conf 后应重启或重连 NPC；可用 npc status -config=/实际路径/npc.conf 查询其中各隧道在服务端的运行状态，详见配置文件隧道状态 。

仓库中的 conf/npc.conf 包含 HTTP(S)、TCP、UDP、SOCKS5、HTTP 正向代理、私密代理、P2P 和健康检查示例。复制前应删除不需要的示例段和示例凭据。

TLS 校验选项也可直接写入 npc.conf 的 [common] 段，名称与命令行一致、去掉 - 前缀。CA 相对路径以 npc.conf 所在目录为基准。默认自签名服务端需要配置 tls_server_fingerprint；完整示例见桥接证书与身份验证 。

GUI 客户端

桌面 GUI 基于 Wails v3，支持：

  1. 粘贴 Web 管理界面的快捷连接码。
  2. 手动填写名称、服务端地址、vkey 和 TLS 开关；启用 TLS 后可填写 CA 文件、公钥指纹和证书域名。

请从当前版本的 Release 中选择与操作系统和 CPU 架构匹配的包。详细说明见仓库中的 cmd/npc/npc-gui/README.md。

img

注册到系统服务

以管理员权限启动无配置文件的 NPC，在菜单中选择“注册系统服务”并粘贴快捷连接码。安装完成后会立即尝试启动服务，服务名为 nps-client-<vkey>。

sudo ./npc   # Linux/macOS
npc.exe      # Windows 管理员终端

Windows 如需在 NPC 异常退出后由服务管理器自动重启，可配置服务恢复策略：

img

日志

通过交互菜单注册的服务会强制使用文件日志，每个 vkey 对应一个 npc-<vkey>.log：

  • Windows：npc.exe 所在目录。
  • Linux/macOS：/var/log/。

直接运行命令行时默认输出到终端。要写入指定文件，可传入 -debug=false -log_path=/path/to/npc.log，并确保运行用户对目标目录有写权限。

更新客户端

在无默认配置文件的交互菜单中选择“更新客户端”，会下载并替换当前 NPC 二进制。更新后应重启已注册的客户端服务。

如果菜单更新失败，请停止相关服务，从当前 Release 下载与系统架构匹配的客户端，替换二进制后再启动服务；不要覆盖或删除自己的 npc.conf。

最后修改 2026-10-02