VMOS Edge Container API - AI快速参考
版本: 2026-02-04
语言: zh-CN

========================
1. 基础信息
========================

Base URL:
- http://{主机IP}:18182

数据格式:
- 请求/响应: JSON
- 文件上传: multipart/form-data

通用响应结构:
{
  "code": 200,        // 状态码,200为成功
  "data": {...},      // 业务数据
  "msg": "OK"         // 状态描述
}

常见错误码:
- 0: 操作失败
- 1: 参数错误
- 2: 状态错误
- 200: 成功
- 201/202: 资源不存在或特殊参数错误
- 203: 运行实例数量即将超限
- 460: 操作冲突
- 500: 服务器错误
- 1001: 实例不存在
- 1004: 模式不匹配

实例状态:
- creating: 创建中
- starting: 启动中
- running: 运行中
- stopping: 停止中
- stopped: 已停止
- rebooting: 重启中
- rebuilding: 重建中
- renewing: 一键新机中
- deleting: 删除中

异步接口列表:
- create, run, stop, reboot, reset, delete
- upgrade_image, replace_devinfo, clone

轮询方式:
- POST /container_api/v1/get_db 查询实例详情
- GET /container_api/v1/list_names 查询实例列表

========================
2. 主机管理 (Host)
========================

## 获取主机配置信息
GET /v1/get_hardware_cfg

返回示例:
{
  "code": 200,
  "message": "success",
  "data": {
    "cpuload": "0%",
    "cputemp": 33,
    "device_id": "93508a1ed52c4e1dee17320ec78f806a",
    "hwaddr": "82:C1:32:C6:E4:34",
    "ip": "192.168.10.20",
    "mem_total": "15943",
    "mem_use": "689",
    "mmc_total": "239281",
    "mmc_use": "20691",
    "ssd_total": "",
    "ssd_use": "",
    "model": "c1_10",
    "version": "QL-c1-2025.v0.3.0.202503311512"
  }
}

## 获取主机系统信息
GET /v1/systeminfo

返回示例:
{
  "code": 200,
  "msg": {
    "cpu": 5.4,
    "disk_percent": 39.3,
    "disk_total": 250903556096,
    "mem_percent": 63.9,
    "mem_total": 16720510976,
    "temperatures": 29.615,
    "swap_total": 0,
    "swap_percent": 0
  }
}

## 获取主机网络配置
GET /v1/net_info

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "gateway": "192.168.10.1",
    "netmask": "255.255.254.0",
    "subnet": "192.168.10.0/23"
  }
}

## 主机心跳检查
GET /v1/heartbeat

返回示例:
{
  "code": 200,
  "message": "主机正常",
  "data": {
    "docker_status": true,
    "http_status": true,
    "ping_status": true
  }
}

## 获取主机镜像列表
GET /v1/get_img_list

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "repository": "armcloud/demo:latest",
      "image_id": "sha256:..."
    }
  ]
}

## 清理未使用镜像
GET /v1/prune_images

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "freed_mb": "542.15",
    "images": [
      "vcloud_android13_edge_20250925011125",
      "vcloud_android12_edge_20250920010230"
    ]
  }
}

## 导入镜像
POST /v1/import_image
Content-Type: multipart/form-data

参数:
- file (必填): 镜像文件(.tar.gz或.tar格式)

流式返回(NDJSON格式):
- Uploading: upload_progress=100%, load_progress=0%
- Loading: upload_progress=100%, load_progress=1-99%
- Success: upload_progress=100%, load_progress=100%
- Failed: upload_progress=100%, load_progress=0%

## 设置Swap开关
GET /v1/swap/{enable}

参数:
- enable: 1=开启, 0=关闭

返回示例:
{
  "code": 200,
  "msg": {
    "swap_total": 2147483648,
    "swap_percent": 0
  }
}

## 重启主机
GET /v1/reboot_for_arm

返回示例:
{
  "code": 200,
  "msg": "rebooting"
}

## 主机关机
GET /v1/shutdown

返回示例:
{
  "code": 200,
  "msg": "正在关机",
  "data": {
    "host_ip": "192.168.1.100"
  }
}

## 重置主机
GET /v1/reset

说明: 销毁容器、清理映射、格式化并挂载数据盘、清理根分区后重启

返回示例:
{
  "code": 200,
  "msg": "resetting and rebooting"
}

## 导入机型模板
POST /v1/import_adi
Content-Type: multipart/form-data

参数:
- adiZip (必填): ADI模板文件(.zip格式)

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "filename": "template.zip"
  }
}

## 获取主机机型模板列表
GET /v1/get_adi_list
GET /v1/get_adi_list?brand=vivo
GET /v1/get_adi_list?aosp_version=13

参数:
- brand (可选): 过滤品牌(如vivo、google、samsung)
- aosp_version (可选): 过滤AOSP版本(如13、14)

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "list": [
      {
        "adiID": 2001,
        "brand": "google",
        "model": "Pixel 7 Pro(12G)",
        "model_name": "Pixel 7 Pro",
        "aosp_version": "13",
        "layout": "1440x3120x560",
        "adiName": "59ddfc6374723e2bea36a84792238063.zip",
        "adiPass": ""
      }
    ]
  }
}

========================
3. 实例管理 (Instance)
========================

## 创建实例
POST /container_api/v1/create

参数:
- user_name (必填): 实例用户名,长度>2,支持数字/字母/下划线/点/横线
- count (可选): 批量创建数量,默认1,最大12
- bool_start (可选): 是否立即启动,默认false
- bool_macvlan (可选): 是否启用macvlan双网卡模式,默认false
- macvlan_network (可选): macvlan网络名称,默认macvlan100
- macvlan_start_ip (可选): macvlan起始IP地址
- image_repository (可选): 本地镜像名称(不含tag),默认vcloud_android13_edge_20250925011125
- bool_gms_disabled (可选): 是否禁用GMS,默认false
- bool_gms_upgrade_enable (可选): 是否允许GMS升级,默认false
- resolution (可选): 分辨率配置{dpi, fps, height, width}
- selinux (可选): 是否启用SELinux
- dns (可选): DNS服务器列表
- adiID (可选): ADI模板ID(优先级最高)
- adiName (可选): ADI模板文件名
- adiPass (可选): ADI解压密码
- lon (可选): 经度
- lat (可选): 纬度
- locale (可选): 语言(如zh-CN)
- timezone (可选): 时区(如Asia/Shanghai)
- country (可选): 国家代码(如CN)
- userProp (可选): 自定义安卓属性(JSON格式字符串)
- cert_hash (可选): 证书文件哈希值
- cert_content (可选): 证书内容base64编码
- device_type (可选): 设备类型(virtual/real),默认real
- remark (可选): 实例备注

请求示例:
{
  "user_name": "test-001",
  "bool_start": false,
  "image_repository": "vcloud_android13_edge_20250925011125",
  "adiID": 1039,
  "resolution": {
    "dpi": 560,
    "fps": 60,
    "height": 3040,
    "width": 1440
  },
  "selinux": false,
  "dns": ["8.8.8.8", "1.1.1.1"],
  "bool_gms_disabled": false,
  "bool_gms_upgrade_enable": false
}

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "db_ids": ["EDGE0A1B2C3D4E5"]
  }
}

## 批量启动实例(异步)
POST /container_api/v1/run

参数:
- db_ids (必填): 实例ID数组

返回值说明:
- 200: 成功,任务已入队
- 460: 存在其他启动任务进行中
- 203: 运行实例数量即将超限
- 1: db_id不存在
- 2: 实例不在stopped状态

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9I0J1"]
}

## 批量停止实例(异步)
POST /container_api/v1/stop

参数:
- db_ids (必填): 实例ID数组

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5"]
}

## 批量重启实例(异步)
POST /container_api/v1/reboot

参数:
- db_ids (必填): 实例ID数组

## 批量重置实例(异步)
POST /container_api/v1/reset

参数:
- db_ids (必填): 实例ID数组

## 批量删除实例(异步)
POST /container_api/v1/delete

参数:
- db_ids (必填): 实例ID数组

## 升级实例镜像
POST /container_api/v1/upgrade_image

说明: 停止容器→删除容器→使用新镜像重建→启动容器,数据保留

参数:
- db_ids (必填): db_id数组
- repository (必填): 镜像仓库名(不含tag)
- adiID (可选): ADI模板ID
- adiName (可选): ADI模板文件名
- adiPass (可选): ADI解压密码

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5"],
  "repository": "vcloud_android13_edge_20260120",
  "adiID": 1039
}

## 重命名实例
GET /container_api/v1/rename/{db_id}/{new_user_name}

说明: 仅修改user_name,不修改db_id/容器名

参数:
- db_id (必填): 实例唯一标识
- new_user_name (必填): 新的user_name,长度>2

## 更新证书配置
POST /container_api/v1/update_cert

参数:
- db_id (必填): 实例唯一标识
- cert_hash (可选): 证书文件哈希值(优先使用)
- cert_content (可选): 证书内容base64编码

说明: cert_hash和cert_content必须提供其中一个

请求示例:
{
  "db_id": "EDGE0A1B2C3D4E5",
  "cert_hash": "a1b2c3d4e5f6..."
}

## 更新用户属性
POST /container_api/v1/update_user_prop

参数:
- db_ids (必填): 实例唯一标识列表
- user_prop (必填): 用户自定义安卓属性(JSON格式字符串)
- isRestart (可选): 是否重启实例,默认false

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9I0J1"],
  "user_prop": "{\"ro.product.model\":\"CustomModel\",\"ro.build.version.sdk\":\"33\"}",
  "isRestart": false
}

## 设置IP(仅macvlan模式)
POST /container_api/v1/set_ip

参数:
- db_id (必填): 实例唯一标识
- ip (必填): 新的LAN IP

请求示例:
{
  "db_id": "EDGE0A1B2C3D4E5",
  "ip": "192.168.10.120"
}

## 获取实例详情
GET /container_api/v1/get_android_detail/{db_id}

参数:
- db_id (必填): 实例唯一标识

## 获取实例列表
GET /container_api/v1/get_db

## 获取ADB命令
GET /container_api/v1/adb_start/{db_id}

参数:
- db_id (必填): 实例唯一标识

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "adb_command": "adb connect 192.168.10.20:5555"
  }
}

## 截图
GET /container_api/v1/screenshots/{db_id}

说明: 返回JPEG二进制流

参数:
- db_id (必填): 实例唯一标识

## 克隆实例
POST /container_api/v1/clone

参数:
- user_name (必填): 克隆出来的实例名
- db_id (必填): 被克隆的容器db_id
- count (必填): 克隆数量,最大12
- update_prop (可选): 是否自动刷新安卓属性,默认false

请求示例:
{
  "user_name": "test-001",
  "db_id": "EDGE0A1B2C3D4E5",
  "count": 1,
  "update_prop": true
}

## 克隆实例任务状态
GET /container_api/v1/clone_status

## 获取ROM状态
GET /container_api/v1/rom_status/{db_id}

参数:
- db_id (必填): 实例唯一标识

返回值说明:
- code=0: 实例未启动
- code=1: ROM未就绪
- code=200: ROM已就绪

## 查询所有容器ID
GET /container_api/v1/list_names

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "db_id": "EDGE0A1B2C3D4E5",
      "user_name": "test-001",
      "adb": "adb connect 192.168.10.20:5555"
    }
  ]
}

## 同步实例状态
GET /container_api/v1/sync_status

## 批量一键新机(异步)
POST /container_api/v1/replace_devinfo

说明: 停机→清数据→启动,保留db_id与user_name

参数:
- db_ids (必填): 实例唯一标识列表
- adiID (可选): ADI模板ID
- adiName (可选): ADI模板文件名
- adiPass (可选): ADI解压密码
- country (可选): 国家代码(如CN)
- userProp (可选): 自定义安卓属性(JSON格式字符串)
- wipeData (可选): 是否清空数据盘,默认true
- lon (可选): 经度
- lat (可选): 纬度
- locale (可选): 语言
- timezone (可选): 时区
- cert_hash (可选): 证书文件哈希值
- cert_content (可选): 证书内容base64编码

请求示例:
{
  "db_ids": ["EDGE0A1...", "EDGE6F7..."],
  "adiID": 1039,
  "country": "CN",
  "wipeData": true,
  "userProp": "{\"persist.sys.country\":\"CN\"}",
  "lon": 121.5,
  "lat": 31.2,
  "locale": "zh-CN",
  "timezone": "Asia/Shanghai"
}

## 批量更新停止实例镜像信息
POST /container_api/v1/update_stopped_image

说明: 仅处理stopped/failed状态的实例

参数:
- db_ids (必填): db_id数组
- repository (必填): 镜像仓库名(不含tag)

请求示例:
{
  "db_ids": ["EDGE0A1...", "EDGE6F7..."],
  "repository": "vcloud_android13_edge_20250925011125"
}

## 更新投屏服务
POST /container_api/v1/refreshScreenService
Content-Type: multipart/form-data

参数:
- file (必填): 上传的文件(支持scd或scd.sh,可同时上传多个)
- db_id (可选): 实例ID(与user_name二选一)
- user_name (可选): 用户名(与db_id二选一)

## 启动GMS
GET /container_api/v1/gms_start

## 停用GMS
GET /container_api/v1/gms_stop

========================
4. 应用管理 (App)
========================

## 获取应用列表
GET /android_api/v1/app_get/{db_id}

参数:
- db_id (必填): 实例唯一标识

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "apps": ["com.example.app1", "com.example.app2"]
  }
}

## 启动应用(批量)
POST /android_api/v1/app_start

参数:
- db_ids (必填): 实例ID列表
- app (必填): 应用包名

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9J0K1"],
  "app": "com.chartcross.gpstest"
}

## 停止应用(批量)
POST /android_api/v1/app_stop

参数:
- db_ids (必填): 实例ID列表
- app (必填): 应用包名

请求示例:
{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9J0K1"],
  "app": "com.tencent.mm"
}

## 设置应用Root权限
POST /android_api/v1/root_app

说明: 操作完需重启应用才能生效

参数:
- db_ids (必填): 实例ID列表(支持中文/英文逗号分隔)
- app (必填): 应用包名

请求示例:
{
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1",
  "app": "com.chartcross.gpstest"
}

## 添加悬浮窗权限
POST /android_api/v1/add_show_other_app_over_permission

参数:
- db_id (必填): 实例ID
- app (必填): 应用包名

请求示例:
{
  "db_id": "EDGEH06HF5E52NQL",
  "app": "com.zhiliaoapp.musically"
}

========================
5. 文件操作 (File)
========================

## 批量安装APK
POST /android_api/v1/upload_file_android_batch
Content-Type: multipart/form-data

说明: 支持单包APK和Split APK(多包)

参数:
- db_ids (必填): 实例ID列表(逗号分隔)
- file (必填): 安装包文件(.apk/.zip/.xapk/.tar/.tar.gz/.tgz)

## 批量上传文件
POST /android_api/v1/upload_file_android_upload
Content-Type: multipart/form-data

参数:
- db_ids (必填): 实例ID列表(逗号分隔)
- file (必填): 要上传的文件
- path (可选): 目标目录,默认/storage/emulated/0/Download

## 从URL批量安装APK
POST /android_api/v1/install_apk_from_url_batch

参数:
- url (必填): APK文件下载URL
- db_ids (必填): 实例ID列表(逗号分隔)

请求示例:
{
  "url": "https://example.com/app.apk",
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1"
}

## 从URL批量上传文件
POST /android_api/v1/upload_file_from_url_batch

参数:
- url (必填): 文件下载URL
- db_ids (必填): 实例ID列表(逗号分隔)
- path (可选): 目标目录,默认/storage/emulated/0/Download

请求示例:
{
  "url": "https://example.com/file.zip",
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1",
  "path": "/storage/emulated/0/Download"
}

## 导出手机APK
POST /android_api/v1/export_phone_apk

参数:
- db_id (必填): 实例ID
- app (必填): 应用包名

说明:
- 单APK: 返回[app].apk
- Split APK: 返回[app]_apks.zip

请求示例:
{
  "db_id": "EDGEH06HF5E52NQL",
  "app": "com.zhiliaoapp.musically"
}

========================
6. 系统控制 (System)
========================

## 执行ADB命令
POST /android_api/v1/shell/{db_id}

参数:
- db_id (必填): 实例唯一标识
- cmd (必填): shell命令(请求体)

请求示例:
{
  "cmd": "ls -l /sdcard"
}

## 停止前台应用
GET /android_api/v1/stop_front_app/{db_id}

说明: 自动获取前台应用包名并强制关闭

参数:
- db_id (必填): 实例唯一标识

## GPS注入
POST /android_api/v1/gps_inject/{db_id}

参数:
- longitude (必填): 经度(-180.0~180.0)
- latitude (必填): 纬度(-90.0~90.0)
- altitude (可选): 海拔高度(米)
- speed (可选): 移动速度(m/s)
- bearing (可选): 方位角(0.0~360.0)
- horizontalAccuracyMeters (可选): 水平定位精度(米)

请求示例:
{
  "longitude": 116.397455,
  "latitude": 39.909187,
  "altitude": 43.5,
  "speed": 0,
  "bearing": 0,
  "horizontalAccuracyMeters": 5.0
}

## 视频注入
POST /android_api/v1/video_inject/{db_id}

参数:
- url (必填): 视频URL

请求示例:
{
  "url": "https://example.com/demo.mp4"
}

## 关闭视频注入
GET /android_api/v1/video_inject_off/{db_id}

参数:
- db_id (必填): 实例唯一标识

## 设置时区
POST /android_api/v1/timezone_set/{db_id}

参数:
- timeZone (必填): 时区(如Asia/Shanghai)

请求示例:
{
  "timeZone": "Asia/Shanghai"
}

## 设置国家
POST /android_api/v1/country_set/{db_id}

参数:
- country (必填): 国家代码(如CN、US、JP)

常见国家代码:
CN=中国, US=美国, JP=日本, GB=英国
DE=德国, IN=印度, FR=法国, IT=意大利
CA=加拿大, BR=巴西, AU=澳大利亚, ES=西班牙
KR=韩国, NL=荷兰

请求示例:
{
  "country": "CN"
}

## 设置语言
POST /android_api/v1/language_set/{db_id}

参数:
- country (必填): 国家代码(如CN)
- language (必填): 语言代码(如zh)

请求示例:
{
  "country": "CN",
  "language": "zh"
}

## 查询实例国家、语言、时区
GET /android_api/v1/get_timezone_locale/{db_id}

参数:
- db_id (必填): 实例唯一标识

返回示例:
{
  "code": 200,
  "msg": "success",
  "data": {
    "country": "CN",
    "language": "zh",
    "timezone": "Asia/Shanghai"
  }
}

## 根据IP获取经纬度
GET /android_api/v1/ip_geo/{db_id}

参数:
- db_id (必填): 容器ID
- ip (可选): 覆盖查询的IP

========================
7. 证书管理 (Certificate)
========================

## 从文件导入证书
POST /certificate_manage/file_import_cert
Content-Type: multipart/form-data

支持格式: .crt, .pem, .cer, .cert, .key, .prop, .xml

参数:
- file (必填): 证书文件(支持多个)
- filename (可选): 文件名(多个用逗号分隔)

## 从文本导入证书
POST /certificate_manage/content_import_cert

参数:
- content (必填): Base64编码的证书内容

请求示例:
{
  "content": "cm8uYnVpbGQuY2xvdWQuZ21zX3N1aXRlX2Rpc2FibGVkPTE="
}

========================
8. SSD管理 (SSD)
========================

## 存储状态
GET /storage/status

返回示例:
{
  "code": 200,
  "msg": "ssd",
  "data": {
    "status": "ssd",
    "device": "/dev/nvme0n1"
  }
}

说明:
- trial: 试用,无SSD
- new_ssd: 发现新SSD,需操作
- ssd: 已登记并挂载

## 格式化为数据盘并挂载
POST /storage/format

参数:
- device (必填): 设备路径(如/dev/nvme0n1)
- confirm (必填): 确认操作

请求示例:
{
  "device": "/dev/nvme0n1",
  "confirm": true
}

## 导入现有数据盘并挂载
POST /storage/import

参数:
- device (必填): 设备路径
- confirm (必填): 确认操作

请求示例:
{
  "device": "/dev/nvme0n1",
  "confirm": true
}

========================
9. 版本更新 (Update)
========================

## CBS版本更新
POST /v1/update_cbs
Content-Type: multipart/form-data

文件命名要求: cbs_go_edge_version格式,支持无后缀或.cbs

参数:
- file (必填): CBS可执行文件

## 内核版本更新
POST /v1/update_kernel
Content-Type: multipart/form-data

文件命名要求: .img格式

参数:
- file (必填): 内核镜像文件

说明: 更新后主机会自动重启

========================
10. 典型开发流程示例
========================

示例A: 创建并启动实例
1) POST /container_api/v1/create
   body: {"user_name": "test-001", "bool_start": false}
2) 记录返回的db_id
3) POST /container_api/v1/run
   body: {"db_ids": ["EDGE..."]}
4) 轮询 POST /container_api/v1/get_db 直到state=running
5) GET /container_api/v1/rom_status/{db_id} 确认ROM就绪(code=200)

示例B: 批量安装APK
1) POST /android_api/v1/upload_file_android_batch (multipart)
2) fields: db_ids=EDGE1,EDGE2 ; file=app.apk

示例C: 执行GPS注入
1) POST /android_api/v1/gps_inject/{db_id}
2) body: {"longitude": 116.397455, "latitude": 39.909187}

示例D: 一键新机
1) POST /container_api/v1/replace_devinfo
2) body: {"db_ids": ["EDGE..."], "adiID": 1039, "wipeData": true}
3) 轮询状态直到完成

注意事项:
- 异步接口必须轮询确认完成
- multipart接口必须带Content-Type: multipart/form-data
- 状态错误多因实例不在required state
- 镜像名称不含tag,默认使用latest
- macvlan模式需配置macvlan相关参数

========================
11. 错误处理建议
========================

1. 检查code字段判断成功/失败
2. code=460时等待当前任务完成后重试
3. code=2时检查实例状态是否符合要求
4. code=1时检查参数是否正确
5. 异步任务建议设置超时时间避免无限等待

========================
12. 性能优化建议
========================

1. 批量操作优先使用批量接口
2. 避免频繁轮询,建议间隔2-5秒
3. 大文件上传使用流式传输
4. 合理使用bool_start参数避免重复启动