这是本节的多页打印视图。 .

客户端

连接 NPC 客户端，了解运行方式与 SDK

1: 使用说明
2: NPC SDK 文档

1 - 使用说明

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

启动方式选择

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

同时传入 -server 和 -vkey 时，按命令行参数连接。
传入 -config=/path/to/npc.conf 时，按指定配置文件连接。
无参数启动时，如果默认位置存在 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> 命名，因此同一台机器可以注册多个客户端实例。

命令行连接

# 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 中客户端的验证密钥；可用英文逗号连接多个密钥
`-type`	`tcp`	NPC 到 NPS 的桥接类型：`tcp` 或 `kcp`
`-tls_enable`	`false`	启用 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_verify`	`false`	显式跳过证书验证，仅兼容旧部署；不能与上述信任选项同时使用
`-proxy`	空	TCP 桥接的 HTTP 或 SOCKS5 出站代理 URL；KCP 不使用该选项
`-disconnect_timeout`	`60`	连续未收到 5 秒心跳的次数；默认约 5 分钟，不是秒数
`-debug`	`true`	`true` 输出到终端；`false` 输出到日志文件
`-log_path`	自动	`-debug=false` 时的日志路径
`-log_level`	`7`	Beego 日志等级 `0` 到 `7`
`-pprof`	空	pprof 监听地址，例如 `127.0.0.1:9999`；不要直接暴露到公网
`-version`	`false`	输出版本信息后退出

-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，支持：

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

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

注册到系统服务

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

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

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

日志

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

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

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

更新客户端

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

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

2 - NPC SDK 文档

查阅客户端 SDK 的启动、状态查询、日志与关闭接口

命令行模式启动客户端
从 v0.26.10 开始，此函数会阻塞，直到客户端退出返回，请自行管理是否重连
p0->服务端地址
p1->客户端验证密钥（vkey）
p2->连接类型（tcp or udp）
p3->连接代理

extern GoInt StartClientByVerifyKey(char* p0, char* p1, char* p2, char* p3);

查看当前启动的客户端状态，在线为1，离线为0
extern GoInt GetClientStatus();

关闭客户端
extern void CloseClient();

获取当前客户端版本
extern char* Version();

获取日志，实时更新
extern char* Logs();