切換菜單
切換偏好設定選單
切換個人選單
尚未登入
若您做出任何編輯,會公開您的 IP 位址。
這是此頁面最近一次修訂;沒有已批准修訂。

一、前言

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 重啟 VPS

curl "https://api.64clouds.com/v1/restart?veid=YOUR_VEID&api_key=YOUR_API_KEY"


# 使用 curl 創建快照

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


VEID = 'YOUR_VEID'

API_KEY = 'YOUR_API_KEY'

BASE_URL = 'https://api.64clouds.com/v1'


def call_api(action, params=None):

   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()


# 查詢 VPS 信息

info = call_api('getServiceInfo')

print(json.dumps(info, indent=2))


# 重啟 VPS

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';


// 查詢 VPS 信息

$url = "https://api.64clouds.com/v1/getServiceInfo?veid={$veid}&api_key={$api_key}";

$info = json_decode(file_get_contents($url));

print_r($info);


// 使用 curl 進行 POST 請求(適合需要傳遞更多參數的場景)

$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 快照


VEID="YOUR_VEID"

API_KEY="YOUR_API_KEY"

DATE=$(date +%Y%m%d_%H%M%S)

DESC="auto_backup_${DATE}"


RESULT=$(curl -s "https://api.64clouds.com/v1/snapshot/create?veid=${VEID}&api_key=${API_KEY}&description=${DESC}")

echo "[$(date)] Snapshot result: ${RESULT}" >> /var/log/bwg_snapshot.log

然後添加到 crontab 中,每天凌晨 3 點執行:

# 編輯 crontab

crontab -e


# 添加以下行(每天 03:00 執行)

0 3 * * * /root/auto_snapshot.sh

ℹ️ 提示:搬瓦工快照有數量限制,建議配合 snapshot/list 和 snapshot/delete 接口實現自動輪轉,保留最近 N 個快照,刪除更早的。

6.2 VPS 狀態監控與告警

通過定期調用 getLiveServiceInfo 接口,可以監控 VPS 的運行狀態,當 VPS 異常停止時自動發送通知或嘗試自動重啟:

#!/bin/bash

# 文件名: monitor_vps.sh

# 功能: 監控 VPS 狀態,停止時自動重啟


VEID="YOUR_VEID"

API_KEY="YOUR_API_KEY"


# 查詢 VPS 狀態

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'))")


if [ "$STATUS" != "Running" ]; then

   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


VEID = 'YOUR_VEID'

API_KEY = 'YOUR_API_KEY'

THRESHOLD = 0.85  # 流量使用超過 85% 時告警


info = requests.get(

   f'https://api.64clouds.com/v1/getServiceInfo?veid={VEID}&api_key={API_KEY}'

).json()


monthly = info['plan_monthly_data']

used = info['data_counter']

usage = used / monthly


print(f'流量使用: {used/1e9:.2f} GB / {monthly/1e9:.0f} GB ({usage:.1%})')


if usage > THRESHOLD:

   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 接口是很好的練手素材。

搬瓦工中文網 — 專業的搬瓦工中文教程站