帮助中心

## 云服务器API接口文档

2026-02-05 15:29:31 云助数据 www.zhuip.com

### 认证方式

所有API接口都需要提供认证信息，支持两种方式：

#### 方式一：请求头（推荐）

| 请求头 | 说明 | 示例 |
|--------|------|------|
| `X-User-ID` | 用户名 | `your_username` |
| `X-API-Key` | API密钥 | `your_apikey` |

#### 方式二：查询参数

| 参数名 | 说明 | 示例 |
|--------|------|------|
| `userid` | 用户名 | `your_username` |
| `apikey` | API密钥 | `your_apikey` |

---

### 1. 查询云服务器列表

#### 接口信息

| 项目 | 说明 |
|------|------|
| **请求方法** | `GET` |
| **请求路径** | `/api/v1/vm/list` |
| **Content-Type** | `application/json` |

#### 请求示例

**使用请求头认证：**

```bash
curl -X GET "http://your-domain.com/api/v1/vm/list" \
  -H "X-User-ID: your_username" \
  -H "X-API-Key: your_apikey"
```

**使用查询参数认证：**

```bash
curl -X GET "http://your-domain.com/api/v1/vm/list?userid=your_username&apikey=your_apikey"
```

#### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "vmname": "vm001",
      "userid": "user001",
      "vmprdid": 10,
      "vmprdName": "标准型VPS",
      "vmnodeid": 1,
      "ipinfo": "192.168.1.100",
      "adslinfo": "账号:adsl001 密码:123456",
      "createtime": "2024-01-01 10:00:00",
      "expiretime": "2024-12-31 23:59:59",
      "runstatus": 1,
      "vmstatus": 0,
      "vmstatus2": "正常",
      "conninfo": "192.168.1.1:3389"
    }
  ]
}
```

#### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `code` | `int` | 响应码，0表示成功 |
| `message` | `string` | 响应消息 |
| `data` | `array` | 云服务器列表 |
| `data[].id` | `int` | 服务器ID |
| `data[].vmname` | `string` | 服务器名称 |
| `data[].userid` | `string` | 用户ID |
| `data[].vmprdid` | `int` | 产品ID |
| `data[].vmprdName` | `string` | 产品名称 |
| `data[].vmnodeid` | `int` | 节点ID |
| `data[].ipinfo` | `string` | IP信息 |
| `data[].adslinfo` | `string` | ADSL拨号信息 |
| `data[].createtime` | `string` | 开通时间 |
| `data[].expiretime` | `string` | 到期时间 |
| `data[].runstatus` | `int` | 运行状态：0=未知, 1=运行中, 2=关机 |
| `data[].vmstatus` | `int` | 业务状态码 |
| `data[].vmstatus2` | `string` | 业务状态描述 |
| `data[].conninfo` | `string` | 连接信息 |

---

### 2. 批量操作

#### 接口信息

| 项目 | 说明 |
|------|------|
| **请求方法** | `POST` |
| **请求路径** | `/api/v1/vm/batch` |
| **Content-Type** | `application/json` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 可选值 |
|--------|------|------|------|--------|
| `action` | `string` | 是 | 操作类型 | `start`（开机）、`reboot`（重启）、`shutdown`（关机） |
| `vmnames` | `array` | 是 | 云服务器名称列表 | 字符串数组 |

#### 请求示例

```bash
curl -X POST "http://your-domain.com/api/v1/vm/batch" \
  -H "X-User-ID: your_username" \
  -H "X-API-Key: your_apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reboot",
    "vmnames": ["vm001", "vm002", "vm003"]
  }'
```

#### 响应示例

```json
{
  "code": 0,
  "message": "操作完成",
  "data": [
    {
      "node_id": 1,
      "status": "success",
      "message": "操作成功",
      "vmnames": ["vm001", "vm002"]
    }
  ]
}
```

#### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `code` | `int` | 响应码，0表示成功 |
| `message` | `string` | 响应消息 |
| `data` | `array` | 操作结果列表（按节点分组） |
| `data[].node_id` | `int` | 节点ID |
| `data[].status` | `string` | 操作状态：`success`（成功）、`failed`（失败） |
| `data[].message` | `string` | 操作消息 |
| `data[].vmnames` | `array` | 该节点下操作的服务器名称列表 |

---

### 3. 单个操作

#### 接口信息

| 项目 | 说明 |
|------|------|
| **请求方法** | `POST` |
| **请求路径** | `/api/v1/vm/operation` |
| **Content-Type** | `application/json` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 可选值 |
|--------|------|------|------|--------|
| `action` | `string` | 是 | 操作类型 | `start`（开机）、`reboot`（重启）、`shutdown`（关机） |
| `vmname` | `string` | 是 | 云服务器名称 | 字符串 |

#### 请求示例

```bash
curl -X POST "http://your-domain.com/api/v1/vm/operation" \
  -H "X-User-ID: your_username" \
  -H "X-API-Key: your_apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "start",
    "vmname": "vm001"
  }'
```

#### 响应示例

```json
{
  "code": 0,
  "message": "操作成功",
  "data": {
    "vmname": "vm001",
    "action": "start"
  }
}
```

#### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `code` | `int` | 响应码，0表示成功 |
| `message` | `string` | 响应消息 |
| `data.vmname` | `string` | 操作的服务器名称 |
| `data.action` | `string` | 执行的操作类型 |

## 错误码说明

| 错误码 | 说明 | 可能原因 |
|--------|------|----------|
| `0` | 成功 | 请求处理成功 |
| `400` | 请求参数错误 | 缺少必填参数、参数格式错误、参数值无效 |
| `401` | 认证失败 | 用户名或API密钥错误 |
| `403` | 权限不足 | IP未在白名单中、API未启用、用户未实名 |
| `404` | 资源不存在 | 指定的云服务器不存在或不属于当前用户 |
| `500` | 服务器内部错误 | 服务器异常、数据库连接失败等 |

### 错误响应示例

```json
{
  "code": 401,
  "message": "认证失败：用户名或API密钥错误",
  "data": null
}
```

## 注意事项

1. 确保数据库用户有足够的权限访问 `m_member`、`m_vmname`、`m_vmprd`、`m_vmip`、`m_vmnode` 等表
2. IP白名单配置：在 `m_member` 表的 `apiAllowIP` 字段中配置，`0.0.0.0` 表示允许所有IP
3. 用户必须已实名（`realname=1`）且API已启用（`apiEnable=1`）才能使用API
4. 所有操作都会验证用户权限，用户只能操作自己名下的云服务器

返回列表

帮助中心

分类导航

热门关键词

需要帮助？

## 云服务器API接口文档

产品与服务

帮助与支持

其他