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 接口是很好的练手素材。
搬瓦工中文网 — 专业的搬瓦工中文教程站