# VilaNet CLI

VilaNet CLI 是适用于 Linux、macOS 和 Windows 的官方命令行客户端。您可以在无显示器的计算机、服务器上使用它，或在偏好终端命令而非图形应用时使用它。

如果您希望使用常规桌面界面，请改用 [VilaNet for macOS](/zh-cn/official-apps/macos/)、[Windows](/zh-cn/official-apps/windows/) 或 [Linux](/zh-cn/official-apps/linux/)。

> **需要完整技术参考？** 请打开[内容更丰富的 VilaNet CLI 指南](https://cli.vilavpn.com/)，查看各平台安装方式、命令参考、配置、故障排除和交互式示例。本页继续作为多语言安全入门指南。

## 开始之前

您需要：

- 有效的 VilaVPN 账户；
- 建立全设备 TUN 连接所需的管理员权限；
- 与您的操作系统和处理器匹配的软件包。

当前已验证的版本是 **1.2.9**。请从 [VilaNet CLI 官方发布页面](https://github.com/vilavpn/vilanet-cli/releases/tag/v1.2.9)下载。

{% hint style="warning" %}
切勿将密码粘贴到命令、截图或支持消息中。`login` 命令会提示您输入密码，而不会将密码写入 shell 历史记录。
{% endhint %}

## 1. 选择正确的软件包

| 系统 | 处理器 | 软件包后缀 |
|---|---|---|
| Linux | Intel/AMD 64 位 | `linux_amd64.tar.gz` |
| Linux | ARM 64 位 | `linux_arm64.tar.gz` |
| Linux | ARMv7 | `linux_armv7.tar.gz` |
| macOS | Apple 芯片 | `darwin_arm64.tar.gz` |
| macOS | Intel | `darwin_amd64.tar.gz` |
| Windows | Intel/AMD 64 位 | `windows_amd64.zip` |
| Windows | ARM 64 位 | `windows_arm64.zip` |

在 Linux 或 macOS 上，如果不确定，请运行 `uname -m`。`x86_64` 表示 AMD64；`arm64` 或 `aarch64` 表示 ARM64。

## 2. 安装

### Linux

解压下载的归档文件，然后安装二进制文件：

```bash
tar -xzf vilanet-cli_1.2.9_linux_amd64.tar.gz
sudo install -m 0755 vilanet-cli /usr/local/bin/
sudo setcap 'cap_net_admin,cap_net_bind_service+eip' /usr/local/bin/vilanet-cli
```

如果您下载的是相应软件包，请将 `amd64` 替换为 `arm64` 或 `armv7`。

### macOS

解压归档文件并安装二进制文件：

```bash
tar -xzf vilanet-cli_1.2.9_darwin_arm64.tar.gz
sudo install -m 0755 vilanet-cli /usr/local/bin/
```

在 Intel Mac 上，请将 `arm64` 替换为 `amd64`。全设备 TUN 模式需要使用 `sudo`；仅限本地 SOCKS 的连接不需要。

### Windows

1. 解压 ZIP 文件。
2. 仅从 [Wintun 官方网站](https://www.wintun.net/)下载 Wintun。
3. 将匹配的 `wintun.dll` 复制到 `vilanet-cli.exe` 所在目录。
4. 以管理员身份打开 PowerShell。
5. 切换到解压后的文件夹。

首次设置时，请保持简单，直接在前台运行 VilaNet。安装 Windows 服务属于高级选项，首次连接并不需要。

## 3. 确认安装成功

在 Linux 或 macOS 上：

```bash
vilanet-cli version
```

在 Windows PowerShell 上：

```powershell
.\vilanet-cli.exe version
```

该命令应输出版本号，而不是错误。

## 4. 登录

运行：

```bash
vilanet-cli login --email you@example.com
```

出现提示时输入您的 VilaVPN 密码。登录成功后，凭据会加密存储在此设备上。日常使用时请勿使用 `--insecure-store`。

任何截图都不会重现包含真实密码的密码提示。

## 5. 查看可用套餐和服务器

```bash
vilanet-cli list packages
vilanet-cli list servers
```

您可以按国家/地区筛选服务器列表，例如：

```bash
vilanet-cli list servers --country HK
```

服务器可用性取决于您的有效套餐。不要将内部服务器标识符复制到公开截图中。

## 6. 连接

要建立全设备连接，请在具有所需权限的终端中运行：

```bash
vilanet-cli connect --country HK
```

在 macOS 上，如果需要 TUN 权限，请添加 `sudo`。在 Windows 上，请从已提权的 PowerShell 窗口运行。让前台命令保持运行；按 `Ctrl+C` 可停止。

要在 Linux 或 macOS 上建立不使用 TUN 的本地 SOCKS/HTTP 代理：

```bash
vilanet-cli connect --no-tun --mixed 127.0.0.1:1080
```

## 7. 确认 VilaVPN 正常工作

在 Linux、macOS 和 Windows 上，保持前台终端打开，并确认连接进程仍在运行。然后打开 IP 检测网站，确认公网 IP 与您平时使用的 ISP IP 不同。前台进程不会公开 CLI 控制通道，因此 `status --json` 不是此首次运行流程的验证命令。

有意启动了受支持后台守护进程的 Linux 和 macOS 用户，可以从另一个终端运行 `vilanet-cli status --json` 来检查该守护进程。Windows 版 1.2.9 没有对应的后台 IPC 控制平面。

## 断开连接和退出登录

在 Linux 或 macOS 上，使用以下命令停止托管/后台连接：

```bash
vilanet-cli disconnect
```

在 Windows 上，返回前台 PowerShell 窗口并按 `Ctrl+C`。在 1.2.9 版本中，Windows 的 `disconnect`、`status` 和 `switch` 无法控制该前台进程。

连接停止后，要删除已存储的凭据，请运行：

```bash
vilanet-cli logout
```

`logout` 会删除已存储的凭据和缓存的账户数据。仅仅为了断开连接，无需退出登录。

## 如果出现问题

| 症状 | 处理方法 |
|---|---|
| `command not found` | 确认二进制文件已安装到 `PATH` 中的目录，或从解压后的文件夹运行。 |
| 退出代码 `2` | 检查电子邮件地址和密码，然后再次运行 `login`。 |
| 退出代码 `4` | 先登录；如果服务因重复请求而限流，请稍后再试。 |
| 退出代码 `5` | 使用所需的管理员权限运行；在 Linux 上，请重复执行 `setcap` 步骤。 |
| Windows 报告 Wintun 错误 | 确认正确的官方 `wintun.dll` 位于 `vilanet-cli.exe` 旁边。 |
| 显示已连接但流量无法正常工作 | 运行 `vilanet-cli logs --follow`，保留错误，安全断开连接，然后将经过编辑、已移除敏感信息的摘录发送给支持团队。 |

请勿发布整个配置目录。它可能包含加密凭据、标识符和连接元数据。

## 指南验证状态

上述命令、软件包和受支持架构已根据 VilaNet CLI 1.2.9 完成核对。本指南现已加入官方发布页的真实截图；仍需在每个操作系统的干净环境中完成一次完整往返验证。