VilaNet CLI
VilaNet CLI 是適用於 Linux、macOS 與 Windows 的官方命令列用戶端。它適合無螢幕電腦、伺服器，或偏好使用終端機指令而非圖形化應用程式的使用者。
若需要一般桌面介面，請改用 macOS 版 VilaNet、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 Service 屬於進階選項，首次連線並不需要。
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 Proxy：
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。Windows 版 1.2.9 的 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 檢查。本指南現已加入官方發布頁面的真實截圖；各作業系統的乾淨環境完整往返測試仍待完成。