# 使用说明

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

---

LLMS 索引： [llms.txt](/llms.txt)

---

## 启动方式选择

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

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

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

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

## 快捷连接码与交互菜单

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

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

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

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

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

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

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

![image](/image/new/cmd.png)

## 命令行连接

```shell
# 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 传输](/extend/feature/kcp.html)、[TLS 加密 NPC 连接](/extend/feature/encrypted-transport.html)和[出站代理](/extend/feature/outbound-proxy.html)。私密代理与 P2P 的访问端命令见[配置示例](/extend/example.html)。

## 配置文件模式

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

```ini
[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` 查询其中各隧道在服务端的运行状态，详见[配置文件隧道状态](/extend/feature/config-status.html)。

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

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

## GUI 客户端

桌面 GUI 基于 Wails v3，支持：

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

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

![img](/image/new/gui.png)

## 注册到系统服务

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

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

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

![img](/image/windows_client_service_configuration.png)

## 日志

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

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

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

## 更新客户端

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

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