# VilaNet CLI

VilaNet CLI 是適用於 Linux、macOS 與 Windows 的官方命令列用戶端。它適合無螢幕電腦、伺服器，或偏好使用終端機指令而非圖形化應用程式的使用者。

若需要一般桌面介面，請改用 [macOS 版 VilaNet](/zh-tw/official-apps/macos/)、[Windows 版](/zh-tw/official-apps/windows/)或 [Linux 版](/zh-tw/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 Service 屬於進階選項，首次連線並不需要。

## 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 Proxy：

```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`。Windows 版 1.2.9 的 `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 檢查。本指南現已加入官方發布頁面的真實截圖；各作業系統的乾淨環境完整往返測試仍待完成。