VilaNet CLI
VilaNet CLI 是适用于 Linux、macOS 和 Windows 的官方命令行客户端。您可以在无显示器的计算机、服务器上使用它，或在偏好终端命令而非图形应用时使用它。
如果您希望使用常规桌面界面，请改用 VilaNet for macOS、Windows 或 Linux。
需要完整技术参考？ 请打开内容更丰富的 VilaNet CLI 指南，查看各平台安装方式、命令参考、配置、故障排除和交互式示例。本页继续作为多语言安全入门指南。
开始之前
您需要：
- 有效的 VilaVPN 账户；
- 建立全设备 TUN 连接所需的管理员权限；
- 与您的操作系统和处理器匹配的软件包。
当前已验证的版本是 1.2.9。请从 VilaNet CLI 官方发布页面下载。
{% 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
解压下载的归档文件，然后安装二进制文件：
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
解压归档文件并安装二进制文件：
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
- 解压 ZIP 文件。
- 仅从 Wintun 官方网站下载 Wintun。
- 将匹配的
wintun.dll复制到vilanet-cli.exe所在目录。 - 以管理员身份打开 PowerShell。
- 切换到解压后的文件夹。
首次设置时，请保持简单，直接在前台运行 VilaNet。安装 Windows 服务属于高级选项，首次连接并不需要。
3. 确认安装成功
在 Linux 或 macOS 上：
vilanet-cli version
在 Windows PowerShell 上：
.\vilanet-cli.exe version
该命令应输出版本号，而不是错误。
4. 登录
运行：
vilanet-cli login --email you@example.com
出现提示时输入您的 VilaVPN 密码。登录成功后，凭据会加密存储在此设备上。日常使用时请勿使用 --insecure-store。
任何截图都不会重现包含真实密码的密码提示。
5. 查看可用套餐和服务器
vilanet-cli list packages
vilanet-cli list servers
您可以按国家/地区筛选服务器列表，例如：
vilanet-cli list servers --country HK
服务器可用性取决于您的有效套餐。不要将内部服务器标识符复制到公开截图中。
6. 连接
要建立全设备连接，请在具有所需权限的终端中运行：
vilanet-cli connect --country HK
在 macOS 上，如果需要 TUN 权限，请添加 sudo。在 Windows 上，请从已提权的 PowerShell 窗口运行。让前台命令保持运行；按 Ctrl+C 可停止。
要在 Linux 或 macOS 上建立不使用 TUN 的本地 SOCKS/HTTP 代理：
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 上，使用以下命令停止托管/后台连接：
vilanet-cli disconnect
在 Windows 上，返回前台 PowerShell 窗口并按 Ctrl+C。在 1.2.9 版本中，Windows 的 disconnect、status 和 switch 无法控制该前台进程。
连接停止后，要删除已存储的凭据，请运行：
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 完成核对。本指南现已加入官方发布页的真实截图；仍需在每个操作系统的干净环境中完成一次完整往返验证。