AZ TUTORIALS · 接口参考

VBox · API 文档

VBox（虚拟盒子）通过本地 HTTP 接口调用，格式为 /cmd?fun=指令名&参数。VBox 中的「实例」即一条记录。

AZ 教程汇总站内阅读更新于 2026-11-01

项目	值
HTTP 基址	`http://127.0.0.1:8080`
请求方式	`GET`
结果文件	`/var/mobile/VBoxResult.txt`
导出目录	`/var/mobile/VBox_export`

调用前准备

调用期间保持 VBox 主界面在前台，不要切到后台。

返回值

调用后读取 /var/mobile/VBoxResult.txt：

值	含义
`1`	成功
`0`	失败
`2`	正在执行

推荐的等待方式

每次调用后等 1 秒再读结果；如果是 2，再等 1 秒继续读。这样最多只多等 1 秒。

接口一览

功能	指令	参数
新建实例	`newRecord`	—
原始实例	`originRecord`	—
下一个实例	`nextRecord`	—
第一个实例	`firstRecord`	—
切换到指定实例	`setRecord`	`recordName`
删除指定实例	`deleteRecord`	`recordName`
删除所有实例	`deleteAllRecords`	—
获取当前实例名称	`getCurrentRecordName`	—
获取所有实例名称	`getAllRecordNames`	`saveFilePath`
修改实例名称	`setRecordName`	`oldName` `newName`
获取指定实例参数	`getRecordParam`	`recordName` `saveFilePath`
获取当前实例参数	`getCurrentRecordParam`	`saveFilePath`
设置指定实例参数	`setRecordParam`	`recordName` `filePath`
设置当前实例参数	`setCurrentRecordParam`	`filePath`
导出实例	`exportData`	`exportKeychain`
导入实例	`importData`	`importKeychain`

接口详情

实例名称默认是创建时间，例如 2020-07-03-21-24-13-52。

新建实例

GET http://127.0.0.1:8080/cmd?fun=newRecord

原始实例

GET http://127.0.0.1:8080/cmd?fun=originRecord

切回原始设备环境。

下一个实例

GET http://127.0.0.1:8080/cmd?fun=nextRecord

第一个实例

GET http://127.0.0.1:8080/cmd?fun=firstRecord

切换到指定实例

GET http://127.0.0.1:8080/cmd?fun=setRecord&recordName=2020-07-03-21-24-13-52

参数	必填	说明
`recordName`	是	实例名称

以下情况无法切换

当前正在使用的实例、已被禁用的实例、不存在的实例。

删除指定实例

GET http://127.0.0.1:8080/cmd?fun=deleteRecord&recordName=2020-07-03-21-24-13-52

参数	必填	说明
`recordName`	是	实例名称

删除所有实例

GET http://127.0.0.1:8080/cmd?fun=deleteAllRecords

获取当前实例名称

GET http://127.0.0.1:8080/cmd?fun=getCurrentRecordName

获取所有实例名称

GET http://127.0.0.1:8080/cmd?fun=getAllRecordNames&saveFilePath=/var/mobile/record.txt

参数	必填	说明
`saveFilePath`	是	名称列表保存路径

修改实例名称

GET http://127.0.0.1:8080/cmd?fun=setRecordName&oldName=2020-07-03-21-24-13-52&newName=2020

参数	必填	说明
`oldName`	是	原名称
`newName`	是	新名称

WARNING

已禁用的实例和原始实例不能改名。

获取指定实例参数

GET http://127.0.0.1:8080/cmd?fun=getRecordParam&recordName=2020-07-03-21-24-13-52&saveFilePath=/var/mobile/test.plist

参数	必填	说明
`recordName`	是	实例名称
`saveFilePath`	是	参数保存路径（plist）

获取当前实例参数

GET http://127.0.0.1:8080/cmd?fun=getCurrentRecordParam&saveFilePath=/var/mobile/test.plist

参数	必填	说明
`saveFilePath`	是	参数保存路径（plist）

设置指定实例参数

GET http://127.0.0.1:8080/cmd?fun=setRecordParam&recordName=2020-07-03-21-24-13-52&filePath=/var/mobile/test.plist

参数	必填	说明
`recordName`	是	实例名称
`filePath`	是	修改后的参数文件路径

设置当前实例参数

GET http://127.0.0.1:8080/cmd?fun=setCurrentRecordParam&filePath=/var/mobile/test.plist

参数	必填	说明
`filePath`	是	修改后的参数文件路径

正确流程：先用获取接口导出 plist → 修改字段 → 用设置接口写回。

导出实例

GET http://127.0.0.1:8080/cmd?fun=exportData&exportKeychain=0

参数	必填	说明
`exportKeychain`	是	`1` 同时导出 Keychain，`0` 不导出

导出到 /var/mobile/VBox_export，每个 tar 包对应一个实例。

Keychain 不能跨机器

Keychain 跨设备、跨系统不通用，带过去容易导致系统出现跳激活。数据要放到其他机器使用时，必须用 exportKeychain=0。只在本机备份恢复时，可以用 exportKeychain=1，数据更完整。

导入实例

GET http://127.0.0.1:8080/cmd?fun=importData&importKeychain=0

参数	必填	说明
`importKeychain`	是	规则同导出：跨机器用 `0`

导入前把 tar 包放到 /var/mobile/VBox_export。

Lua 示例（触动精灵）

lua

local http = require("szocket.http")

local BASE = "http://127.0.0.1:8080/cmd?fun="
local RESULT = "/var/mobile/VBoxResult.txt"

-- 调用并等待结果：true 成功 / false 失败
function VBox(query)
    local res, code = http.request(BASE .. query)
    if code ~= 200 then return false end
    while true do
        mSleep(1000)
        if isFileExist(RESULT) then
            local r = readFileString(RESULT)
            if r == "1" then return true, res end
            if r == "0" then return false, res end
            -- "2" 继续等待
        end
    end
end

-- 新建实例
if VBox("newRecord") then toast("新建实例成功", 2) end

-- 当前实例名称
local ok, name = VBox("getCurrentRecordName")

-- 切换到指定实例
VBox("setRecord&recordName=2020-07-03-21-24-13-52")

-- 导出全部实例（不带 Keychain，可放到其他机器）
VBox("exportData&exportKeychain=0")

TIP

getCurrentRecordName 的名称返回位置以实际为准：若响应体为空，可改用 getAllRecordNames 写入文件后读取。

使用教程见 VBox 使用教程。

提示