KiwiVM API 自動化入門指南
更多語言
更多操作
一、前言
KiwiVM 控制面板的大多數功能，其實都可以通過 API 接口來實現。搬瓦工官方對此的說法是：「Whether you want to automatically create nightly snapshots, query status of your VPS, or develop a complete replacement for the KiwiVM panel, this page is for you.」 簡單來說，不管你是想定時自動備份、查詢 VPS 狀態，還是想自己寫一套管理程序來替代 KiwiVM 面板，都可以通過 API 實現。
對於有一定編程基礎的朋友，搬瓦工的 API 使用起來其實很簡單——本質上就是發送一個 HTTP 請求，然後收到一個 JSON 格式的返回結果。沒有複雜的 OAuth 認證流程，也不需要 SDK，用 curl、wget、Python、PHP 甚至瀏覽器都能調用。本文就從零開始，介紹 KiwiVM API 的獲取方法、調用方式、常用接口以及實用自動化場景。
| ℹ️ 提示：KiwiVM API 適合有一定編程基礎的用戶。如果你平時只是用 KiwiVM 面板做一些簡單操作（重啟、重裝系統等），不需要專門研究 API，直接用面板就行。 |
二、獲取 API KEY 和 VEID
調用 KiwiVM API 需要兩個參數：VEID 和 API KEY。這兩個參數是每台 VPS 獨立的，也就是說如果你有多台搬瓦工 VPS，每台的 VEID 和 API KEY 都不一樣。
2.1 通過 KiwiVM 面板獲取
第一步：登錄搬瓦工官網（bwh81.net），進入 Services → My Services，點擊對應 VPS 的 KiwiVM Control Panel 按鈕進入面板。
第二步：在 KiwiVM 面板左側菜單找到 API 選項，點擊進入。
第三步：點擊 Show API Key 按鈕，即可查看該 VPS 的 API KEY（一個以 private_ 開頭的隨機字符串）。頁面上同時會顯示 VEID（一個 7 位數的數字）。
如果需要重置 API KEY（比如懷疑密鑰泄露），可以點擊 Reset API Key 按鈕，重置後舊的 API KEY 立即失效。
2.2 批量導出所有 VPS 的 API KEY
如果你有多台搬瓦工 VPS，逐個登錄 KiwiVM 面板查看 API KEY 比較麻煩。搬瓦工官網後台提供了一個批量導出功能：在搬瓦工官網後台的 Services → My Services 頁面，找到 Export all services with private API keys 選項，可以導出一個 CSV 文件，裡面包含了你所有 VPS 的 VEID 和 API KEY。
| ⚠️ 注意：API KEY 相當於你 VPS 的管理密碼，擁有 API KEY 的人可以通過 API 對你的 VPS 進行重啟、重裝系統、執行命令等操作。請妥善保管，不要泄露給不信任的人。 |
三、API 調用基礎
3.1 請求格式
KiwiVM API 的調用方式非常直接：向指定 URL 發送 HTTP 請求，帶上 VEID 和 API KEY 作為參數即可。支持 GET 和 POST 兩種方式傳參。
API 基礎地址如下：
| https://api.64clouds.com/v1/{API接口名称}?veid={VEID}&api_key={API_KEY} |
舉個例子，如果要查詢 VPS 的基本信息，完整的請求 URL 是這樣的：
| https://api.64clouds.com/v1/getServiceInfo?veid=1234567&api_key=private_xxxxxxxxxxxx |
3.2 返回格式
所有 API 調用的返回結果都是 JSON 格式。每個返回結果都包含一個 error 字段，如果 error 為 0 表示調用成功，否則請查看 message 字段了解具體錯誤原因。示例：
| // 成功返回示例（getServiceInfo）
{ "error": 0, "hostname": "my-vps", "node_datacenter": "USCA_6", "ip_addresses": ["1.2.3.4"], "plan_monthly_data": 1000000000000, "data_counter": 52428800, "os": "ubuntu-24.04-x86_64", "ve_status": "Running", ... }
{ "error": 700005, "message": "Authentication failure" } |
3.3 常見錯誤碼
| 錯誤碼 | 含義 | 解決方法 |
| 700005 | Authentication failure（認證失敗） | VEID 或 API KEY 不正確，核對參數 |
| 700000 | VPS is not running / stopped | VPS 未運行，需先啟動 |
| 700003 | VPS is already running | 已在運行中，無需重複啟動 |
| rate limit | 請求過於頻繁，被限流 | 等待幾分鐘後重試，減少調用頻率 |
| ℹ️ 提示：KiwiVM API 有限流機制，短時間內調用太頻繁會被臨時屏蔽。可以通過 getRateLimitStatus 接口查詢當前限流狀態。建議調用間隔不要低於 1 秒。 |
四、常用 API 接口整理
下面按功能分類整理 KiwiVM API 的主要接口。這些接口基本覆蓋了 KiwiVM 面板上能做的所有操作。
4.1 VPS 信息查詢
| 接口名稱 | 說明 |
| getServiceInfo | 獲取 VPS 基本信息：IP、端口、操作系統、流量使用、機房位置等 |
| getLiveServiceInfo | 獲取 VPS 實時狀態（含 getServiceInfo 全部字段），返回磁盤使用、運行狀態等實時數據（調用可能需 15 秒） |
| getRawUsageStats | 獲取詳細統計數據，對應 KiwiVM 面板的 Detailed Statistics 頁面 |
| getAvailableOS | 獲取當前可用的操作系統列表（用於重裝系統） |
| getSuspensionDetails | 查詢當前是否有暫停情況及具體原因 |
| getAuditLog | 獲取 KiwiVM 操作日誌，對應面板的 Audit log 功能 |
4.2 電源管理
| 接口名稱 | 說明 |
| start | 啟動 VPS |
| stop | 正常停止 VPS |
| restart | 重啟 VPS |
| kill | 強制停止 VPS（用於 VPS 卡死無法正常停止的情況，未保存數據會丟失） |
4.3 備份與快照
| 接口名稱 | 說明 |
| snapshot/create | 創建快照，參數 description 為快照描述 |
| snapshot/list | 獲取快照列表（包含文件名、大小、MD5、下載鏈接等） |
| snapshot/delete | 刪除指定快照，參數 snapshot 為文件名 |
| snapshot/restore | 恢復指定快照，參數 snapshot 為文件名 |
| backup/list | 獲取自動備份列表（系統定期自動備份） |
| backup/copyToSnapshot | 將自動備份轉換為快照（方便手動管理） |
4.4 系統與網絡管理
| 接口名稱 | 說明 |
| reinstallOS | 重裝操作系統，參數 os 為系統模板名稱 |
| resetRootPassword | 重置 root 密碼，新密碼通過返回結果獲取 |
| setHostname | 設置主機名，參數 newHostname |
| setPTR | 設置反向 DNS 記錄，參數 ip 和 ptr |
| ipv6/add | 分配新的 IPv6 地址 |
| migrate/getLocations | 獲取可遷移的機房列表 |
| migrate/start | 開始遷移機房，參數 location 為目標機房 ID |
4.5 Shell 命令執行
| 接口名稱 | 說明 |
| basicShell/exec | 在 VPS 上同步執行 Shell 命令，參數 command，返回執行結果 |
| shellScript/exec | 在 VPS 上異步執行 Shell 腳本，參數 script，返回日誌文件名 |
| ⚠️ 注意：basicShell/exec 和 shellScript/exec 這兩個接口的權限非常高，可以直接在你的 VPS 上執行任意命令。這也是為什麼必須保護好 API KEY 的原因。 |
五、實戰調用示例
5.1 使用 curl / wget 調用
最簡單的調用方式，在終端直接運行一條命令即可：
| # 使用 wget 查詢 VPS 信息
wget -qO- "https://api.64clouds.com/v1/getServiceInfo?veid=YOUR_VEID&api_key=YOUR_API_KEY"
curl "https://api.64clouds.com/v1/restart?veid=YOUR_VEID&api_key=YOUR_API_KEY"
curl "https://api.64clouds.com/v1/snapshot/create?veid=YOUR_VEID&api_key=YOUR_API_KEY&description=manual_backup" |
5.2 使用 Python 調用
用 Python 調用也很簡單，使用標準庫或第三方 requests 庫都可以：
| import requests
import json
API_KEY = 'YOUR_API_KEY' BASE_URL = 'https://api.64clouds.com/v1'
url = f'{BASE_URL}/{action}' data = {'veid': VEID, 'api_key': API_KEY} if params: data.update(params) r = requests.get(url, params=data) return r.json()
info = call_api('getServiceInfo') print(json.dumps(info, indent=2))
result = call_api('restart') print(result)
result = call_api('snapshot/create', {'description': 'nightly_backup'}) print(result) |
5.3 使用 PHP 調用
搬瓦工官方給出的示例是 PHP 代碼，以下是最基本的調用方式：
| <?php
$veid = 'YOUR_VEID'; $api_key = 'YOUR_API_KEY';
$url = "https://api.64clouds.com/v1/getServiceInfo?veid={$veid}&api_key={$api_key}"; $info = json_decode(file_get_contents($url)); print_r($info);
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.64clouds.com/v1/restart'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, ['veid' => $veid, 'api_key' => $api_key]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $result = json_decode(curl_exec($ch)); curl_close($ch); print_r($result); ?> |
六、實用自動化場景
光會調用 API 還不夠，關鍵是要知道拿它來做什麼。下面介紹幾個實用的自動化場景。
6.1 定時自動快照備份
KiwiVM 面板本身有自動備份功能（Backups），但備份周期是系統自動計算的，用戶無法自定義。如果你希望每天晚上自動創建一個快照，可以用 crontab + API 來實現：
| #!/bin/bash
# 文件名: auto_snapshot.sh # 功能: 自動創建 KiwiVM 快照
API_KEY="YOUR_API_KEY" DATE=$(date +%Y%m%d_%H%M%S) DESC="auto_backup_${DATE}"
echo "[$(date)] Snapshot result: ${RESULT}" >> /var/log/bwg_snapshot.log |
然後添加到 crontab 中，每天凌晨 3 點執行：
| # 編輯 crontab
crontab -e
0 3 * * * /root/auto_snapshot.sh |
||
| ℹ️ 提示：搬瓦工快照有數量限制，建議配合 snapshot/list 和 snapshot/delete 接口實現自動輪轉，保留最近 N 個快照，刪除更早的。 | ||
6.2 VPS 狀態監控與告警
通過定期調用 getLiveServiceInfo 接口，可以監控 VPS 的運行狀態，當 VPS 異常停止時自動發送通知或嘗試自動重啟：
| #!/bin/bash
# 文件名: monitor_vps.sh # 功能: 監控 VPS 狀態，停止時自動重啟
API_KEY="YOUR_API_KEY"
STATUS=$(curl -s "https://api.64clouds.com/v1/getLiveServiceInfo?veid=${VEID}&api_key=${API_KEY}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('ve_status','Unknown'))")
echo "[$(date)] VPS status: ${STATUS}, attempting restart..." >> /var/log/bwg_monitor.log curl -s "https://api.64clouds.com/v1/start?veid=${VEID}&api_key=${API_KEY}" >> /var/log/bwg_monitor.log # 可以在這裡加上郵件/Telegram 通知 fi |
配合 crontab 每 5 分鐘執行一次即可實現基本的健康監控。當然，更完善的方案可以結合 Python 腳本和郵件通知來做。
6.3 流量使用監控
getServiceInfo 接口返回的數據中包含 plan_monthly_data（套餐月流量）和 data_counter（已用流量）兩個字段，單位是字節。可以用這兩個字段計算流量使用百分比，當超過閾值時發出告警，避免因流量耗盡導致 VPS 被暫停。
| import requests
API_KEY = 'YOUR_API_KEY' THRESHOLD = 0.85 # 流量使用超過 85% 時告警
f'https://api.64clouds.com/v1/getServiceInfo?veid={VEID}&api_key={API_KEY}' ).json()
used = info['data_counter'] usage = used / monthly
print(f'警告: 流量已使用 {usage:.1%}，請注意控制用量!') # 發送郵件或 Telegram 消息通知 |
6.4 批量管理多台 VPS
如果你有多台搬瓦工 VPS，可以將所有 VPS 的 VEID 和 API KEY 保存在一個配置文件中（或直接用導出的 CSV），然後寫一個腳本遍歷所有 VPS，批量查詢狀態、批量創建快照等。實現了開頭提到的 「develop a complete replacement for the KiwiVM panel」。
社區也有一些現成的工具可以直接使用，比如 iOS 上的「瓦工助手」、安卓上的「Bandwagon 控制台」等 APP，原理都是調用 KiwiVM API 實現的。當然，第三方 APP 的安全性需要自行評估。
七、API 與 KiwiVM 面板功能對照
下表整理了 KiwiVM 面板主要功能與對應 API 接口的關係，方便大家查找。
| KiwiVM 面板功能 | 對應 API 接口 | 備註 |
| Main Controls | getServiceInfo | 查看 IP、端口、狀態、流量等 |
| Detailed Statistics | getRawUsageStats | CPU、網絡、磁盤統計數據 |
| Root shell – basic | basicShell/exec | 同步執行命令 |
| Install new OS | reinstallOS | 需先調用 getAvailableOS |
| Root password modification | resetRootPassword | 返回新密碼 |
| Snapshots | snapshot/* | create/list/delete/restore |
| Backups | backup/* | list / copyToSnapshot |
| Migrate to another DC | migrate/* | getLocations / start |
| Audit log | getAuditLog | 操作日誌審計 |
八、常見問題與注意事項
8.1 調用報 Authentication failure
最常見的問題。通常是 VEID 或 API KEY 填錯了，檢查以下幾點：VEID 是一串純數字，API KEY 以 private_ 開頭；確認沒有多餘的空格或換行符；如果最近重置過 API KEY，需要更新為新的 KEY。
8.2 調用無響應或超時
可能是網絡問題導致無法訪問 api.64clouds.com。可以嘗試更換 DNS，或者在其他網絡環境下重試。另外，getLiveServiceInfo 接口本身就比較慢，可能需要 15 秒才返回結果，這是正常的。
8.3 被限流了怎麼辦
短時間內調用 API 太頻繁會觸發限流，API 會丟棄你的請求。解決方法很簡單：等待幾分鐘後重試，並降低調用頻率。可以通過 getRateLimitStatus 接口查詢當前的限流狀態。建議在腳本中加上適當的 sleep 間隔。
8.4 API KEY 安全問題
幾個安全建議：不要將 API KEY 硬編碼在公開的代碼倉庫中（比如 GitHub）；可以使用環境變量或配置文件來存儲 API KEY；如果懷疑密鑰泄露，立即在 KiwiVM 面板點擊 Reset API Key 重置密鑰；所有通過 API 進行的操作都會記錄在 KiwiVM 面板的 Audit log 中，定期查看審計日誌可以發現異常操作。
九、總結
KiwiVM API 的設計很簡潔，認證方式直接，調用方法簡單，不需要額外的 SDK 或庫，用 curl 一行命令就能完成大多數操作。對於有編程基礎的用戶來說，利用 API 可以實現很多自動化場景：定時備份、狀態監控、流量告警、批量管理等。
對於普通用戶，日常管理 VPS 用 KiwiVM 面板就完全足夠了，不需要專門研究 API。但如果你有自動化的需求，或者單純想折騰寫點代碼，搬瓦工的 API 接口是很好的練手素材。
搬瓦工中文網 — 專業的搬瓦工中文教程站