OpenCecs API 接口文档

文档版本: v3 | 更新日期: 2026-03-19

📌 接口说明（重要）

Base URL:https://www.opencecs.com/api/v1。

认证方式:大多数接口需要JWT Token（登录后获得）。再请求头中添加：Authorization: Bearer {token}。

统一响应格式: 所有接口返回JSON对象，包含以下字段：

{
  "code": 0,          // 0 表示成功，非0表示失败
  "message": "成功",   // 提示信息
  "data": { ... }      // 具体数据，可能为 null
}

以下文档中，成功返回仅展示data字段，失败返回展示message字段。

{
  "code": 500,
  "message": "错误信息",
  "data": null
}

📚 接口目录

AUTH 认证
USER 用户
CECS 实例
CECSDISK 磁盘管理
ORDER 订单
FINANCE 财务
PORTMAPPING 端口映射
SHAREDSTORAGE 共享存储
TASKLOG 定时任务
STORAGE 对象存储
STORAGEADMIN 存储管理
METRICS 流量上报

一、AUTH 认证

1.1 发送短信验证码

功能说明：发送短信验证码，用于登录。

请求方式：POST

请求URL：

{base_url}/auth/sms/send

请求参数：

参数名	必选	类型	说明
phone	是	string	手机号，11位数字
scene	是	string	场景：register（注册）/ login（登录）/ reset（重置密码）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/sms/send" \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000", "scene": "login"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "expire_time": 300
  }
}

返回字段说明：

字段	类型	说明
expire_time	int	验证码有效期（秒），通常300秒

1.2 发送邮箱验证码

功能说明：发送邮箱验证码

请求方式：POST

请求 URL：

{base_url}/auth/email/send

请求参数：

参数名	必选	类型	说明
email	是	string	邮箱地址
scene	是	string	场景：login（登录）/ reset（重置密码）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/email/send" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "scene": "login"}'

返回示例：

{
  "code":0,
  "message":"Success",
  "data":
    {
      "expire_time": 300
    }
}

1.3 用户注册

功能说明：用户注册

请求方式：POST

请求 URL：

{base_url}/auth/register

请求参数：

参数名	必选	类型	说明
phone	是	string	手机号，11位
code	是	string	6位短信验证码
agreements	是	string	同意的协议列表，必须同时包含全部3项：terms（用户协议）、privacy（隐私政策）、service（产品服务协议）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "13800138000",
  "code": "123456",
  "agreements": ["terms", "privacy", "service"]}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "user_id": "usr_abc123",
    "username": "user_123",
    "phone": "13800138000",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
user_id	string	用户唯一标识
username	string	系统生成的用户名
phone	string	手机号
token	string	JWT Token，后续请求放入 Authorization 头
expire_time	int64	Token过期时间（Unix时间戳）

1.4 手机号验证码登录

功能说明：手机号验证码登录

请求方式：POST

请求 URL：

{base_url}/auth/login/phone

请求参数：

参数名	必选	类型	说明
phone	是	string	手机号，11位
code	是	string	6位短信验证码
remember_me	否	bool	true=长期Token(30天)，false=短期Token(2小时)

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/login/phone" \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000", "code": "123456", "remember_me": false}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "user_id": "usr_abc123",
    "username": "user_123",
    "phone": "13800138000",
    "email": "",
    "user_type": "beginner",
    "is_verified": false,
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
user_id	string	用户ID
username	string	系统生成的用户名
phone	string	手机号
email	string	邮箱
user_type	string	用户类型：beginner / professional
is_verified	bool	是否已实名认证
token	string	JWT Token
expire_time	int64	Token过期时间（Unix时间戳）

1.5 邮箱密码登录

功能说明：邮箱密码登录

请求方式：POST

请求 URL：

{base_url}/auth/login/email

请求参数：

参数名	必选	类型	说明
email	是	string	邮箱地址
password	是	string	密码，6-20位
remember_me	否	bool	是否长期登录

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/login/email" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword", "remember_me": false}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "user_id": "usr_abc123",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
user_id	string	用户ID
token	string	JWT Token
expire_time	int64	过期时间（Unix时间戳）

1.6 账号密码登录

功能说明：账号密码登录（账号可以是用户名/手机号/邮箱）

请求方式：POST

请求 URL：

{base_url}/auth/login/account

请求参数：

参数名	类型	必填	说明
account	string	必填	账号（用户名/手机号/邮箱均可）
password	string	必填	密码，6-20位
remember_me	bool	可选	是否长期登录

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/login/account" \
  -H "Content-Type: application/json" \
  -d '{"account": "admin", "password": "yourpassword", "remember_me": false}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "user_id": "user_abc123",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
user_id	string	用户ID
token	string	JWT Token
expire_time	int64	过期时间（Unix时间戳）

1.7 验证身份（重置密码第一步）

功能说明：验证身份（重置密码第一步）

请求方式：POST

请求 URL：

{base_url}/auth/reset/verify

请求参数：

参数名	类型	必填	说明
verify_type	string	必填	验证类型：phone / email / account
phone	string	可选	手机号（verify_type=phone时填写）
phone_code	string	可选	手机验证码
email	string	可选	邮箱（verify_type=email时填写）
email_code	string	可选	邮箱验证码

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/reset/verify" \
  -H "Content-Type: application/json" \
  -d '{"verify_type": "phone", "phone": "13800138000", "phone_code": "123456"}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "reset_token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
reset_token	string	重置密码临时Token，第二步使用
expire_time	int64	Token过期时间（10分钟有效）

1.8 重置密码（第二步）

功能说明：重置密码（第二步）

请求方式：POST

请求 URL：

{base_url}/auth/reset/password

请求参数：

参数名	类型	必填	说明
reset_token	string	必填	第一步返回的reset_token
new_password	string	必填	新密码，6-20位
confirm_password	string	必填	确认密码，需与new_password一致

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/auth/reset/password" \
  -H "Content-Type: application/json" \
  -d '{"reset_token": "eyJhbGciOiJIUzI1NiIs...", "new_password": "newpass123", "confirm_password": "newpass123"}'

返回示例：

成功：

{
  "code": 0,
  "message": "重置成功",
  "data": null
}

二、USER 用户

2.1 获取当前用户信息

功能说明：获取当前用户信息

请求方式：GET

请求 URL：

{base_url}/user/info

请求参数：无

请求示例：

GET "https://www.opencecs.com/api/v1/user/info"

curl -X GET "https://www.opencecs.com/api/v1/user/info" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "user_id": "usr_abc123",
    "username": "user_123",
    "phone": "138****8000",
    "email": "user@example.com",
    "avatar": "https://...",
    "user_type": "beginner",
    "is_verified": false,
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
user_id	string	用户唯一标识
username	string	用户名
phone	string	手机号（脱敏）
email	string	邮箱
avatar	string	头像URL
user_type	string	用户类型：beginner / professional
is_verified	bool	是否已实名认证
created_at	string	注册时间

2.2 退出登录

功能说明：退出登录

请求方式：POST

请求 URL：

{base_url}/user/logout

请求参数：无

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/user/logout" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "退出成功",
  "data": null
}

2.3 刷新 Token

功能说明：刷新 Token

请求方式：POST

请求 URL：

{base_url}/token/refresh

请求参数：无

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/user/token/refresh" \
  -H "Authorization: Bearer {oldToken}"

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_time": 1712345678
  }
}

返回字段说明：

字段	类型	说明
token	string	新的JWT Token
expire_time	int64	新Token过期时间（Unix时间戳）

三、CECS 实例

3.1 获取CECS产品列表

功能说明：获取CECS产品列表

请求方式：GET

请求 URL：

{base_url}/cecs/products

请求参数：

参数名	类型	必填	说明
board_type	string	可选	核心板类型，如 RK3588，不填返回全部
in_stock	int	可选	0=全部，1=仅有货

请求示例：

GET "https://www.opencecs.com/api/v1/cecs/products?in_stock=1"

返回示例：

成功：

{
  "code": 0,
  "message": "重置成功",
  "data": {
    "list": [
      {
        "product_id": "prod_rk3588_8g",
        "board_type": "RK3588",
        "board_name": "Rockchip RK3588",
        "cpu_spec": "8核 2.4GHz",
        "gpu_spec": "Mali-G610 MP4",
        "memory": 8,
        "monthly_price": 299.0,
        "hourly_price": 0.45,
        "stock": 10,
        "in_stock": true,
        "is_new": true
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
list[].product_id	string	产品ID
list[].board_type	string	核心板类型
list[].board_name	string	核心板名称
list[].cpu_spec	string	CPU规格描述
list[].gpu_spec	string	GPU规格描述
list[].memory	int	内存（GB）
list[].monthly_price	float64	包月单价（元）
list[].hourly_price	float64	按时单价（元）
list[].stock	int	库存数量
list[].in_stock	bool	是否有货
list[].is_new	bool	是否新品

3.2 获取CECS产品详情

功能说明：获取CECS产品详情

请求方式：GET

请求 URL：

{base_url}/cecs/products/:product_id

请求参数：

参数名	类型	必填	说明
product_id	string	必填	产品ID

请求示例：

GET "https://www.opencecs.com/api/v1/cecs/products/prod_rk3588_8g"

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "product": {
      "product_id": "prod_rk3588_8g",
      "board_name": "Rockchip RK3588",
      "cpu_spec": "8核 2.4GHz",
      "gpu_spec": "Mali-G610 MP4",
      "codec_spec": "H.264/H.265",
      "memory": 8,
      "monthly_price": 299.0,
      "stock": 10
    }
  }
}

返回字段说明：

字段	类型	说明
reset_token	string	重置密码临时Token，第二步使用
expire_time	int64	Token过期时间（10分钟有效）

3.3 获取可用地域列表

功能说明：获取可用地域列表

请求方式：GET

请求 URL：

{base_url}/cecs/regions

请求参数：无

请求示例：

GET "https://www.opencecs.com/api/v1/cecs/regions"

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "list": [
      {
        "region_id": "cn-wuhan",
        "country": "中国",
        "country_code": "CN",
        "city": "武汉",
        "zone_count": 3
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
list[].region_id	string	地域ID，下单时使用
list[].country	string	国家名称
list[].country_code	string	ISO国家代码
list[].city	string	城市名称
list[].zone_count	int	可用区数量

3.4 获取系统镜像列表

功能说明：获取系统镜像列表

请求方式：GET

请求 URL：

{base_url}/cecs/systems

请求参数：

参数名	类型	必填	说明
image_type	string	可选	镜像类型：public / private，不填返回全部

请求示例：

GET "https://www.opencecs.com/api/v1/cecs/systems?image_type=public"

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "list": [
      {
        "image_id": "img_ubuntu22",
        "image_type": "public",
        "image_name": "Ubuntu 22.04 LTS",
        "os_version": "Ubuntu 22.04",
        "arch": "arm64",
        "description": "官方 Ubuntu 22.04 镜像"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
list[].image_id	string	镜像ID，创建实例时使用
list[].image_type	string	镜像类型：public / private
list[].image_name	string	镜像名称
list[].os_version	string	操作系统版本，如 Ubuntu 22.04
list[].arch	string	CPU架构，如 arm64
list[].description	string	镜像描述

3.5 获取CECS实例列表

功能说明：获取CECS实例列表

请求方式：GET

请求 URL：

{base_url}/cecs/instances

请求参数：

参数名	类型	必填	说明
status	string	可选	状态过滤：running / stopped / expired / pending
region_id	string	可选	地域ID过滤
page	int	可选	页码，默认1
page_size	int	可选	每页数量，默认10

请求示例：

GET "https://www.opencecs.com/api/v1/cecs/instances?status=running&page=1"
或
curl -X GET "https://www.opencecs.com/api/v1/cecs/instances?status=running&page=1" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 5,
    "list": [
      {
        "instance_id": "ins-abc123",
        "instance_name": "my-instance",
        "board_type": "RK3588",
        "ip_address": "192.168.1.100",
        "status": "running",
        "billing_mode": "monthly",
        "expire_at": "2026-04-01 12:00:00",
        "created_at": "2026-03-01 12:00:00"
      }
    ],
    "stats": {
      "running": 2,
      "stopped": 1,
      "expired": 2
    }
  }
}

返回字段说明：

字段	类型	说明
total	int	实例总数
list[].instance_id	string	实例ID
list[].instance_name	string	实例名称
list[].board_type	string	核心板类型
list[].ip_address	string	内网IP地址
list[].status	string	状态：running / stopped / expired
list[].billing_mode	string	计费模式：monthly / hourly
list[].expire_at	string	到期时间
list[].created_at	string	创建时间
stats.running	int	运行中数量
stats.stopped	int	已停止数量
stats.expired	int	已过期数量

3.6 获取CECS实例详情

功能说明：获取CECS实例详情

请求方式：GET

请求 URL：

{base_url}/cecs/instances/{instance_id}

请求参数：

参数名	类型	必填	说明
instance_id	string	是	实例ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token"

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance": {
      "instance_id": "ins-abc123",
      "instance_name": "my-instance",
      "ip_address": "192.168.1.100",
      "mac_address": "52:54:00:ab:cd:ef",
      "status": "running",
      "order_id": "ORD-20260301-001",
      "region_name": "武汉",
      "monthly_price": "299.00",
      "expire_at": "2026-04-01 12:00:00",
      "created_at": "2026-03-01 12:00:00",
      "updated_at": "2026-03-01 12:00:00"
    }
  }
}

返回字段说明：

字段	类型	说明
instance.instance_id	string	实例ID
instance.instance_name	string	实例名称
instance.ip_address	string	内网IP地址
instance.mac_address	string	MAC
instance.status	string	实例状态
instance.order_id	string	关联订单号
instance.region_name	string	地域名称
instance.status	string	实例状态
instance.order_id	string	关联订单号
instance.region_name	string	地域名称
instance.monthly_price	string	月费（元）
instance.expire_at	string	到期时间
instance.created_at	string	创建时间
instance.updated_at	string	最后更新时间

3.7 启动CECS实例

功能说明：启动CECS实例

请求方式：POST

请求 URL：

{base_url}/cecs/instances/:instance_id/start

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/start" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "status": "running",
    "message": "启动成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
status	string	操作后状态
message	string	操作结果说明

3.8 停止CECS实例

功能说明：停止CECS实例

请求方式：POST

请求 URL：

{base_url}/cecs/instances/:instance_id/stop

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/stop" \
  -H "Authorization: Bearer eyJ...”
    #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "status": "stopped",
    "message": "停止成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
status	string	操作后状态
message	string	操作结果说明

3.9 重启CECS实例

功能说明：重启CECS实例

请求方式：POST

请求 URL：

{base_url}/cecs/instances/:instance_id/reboot

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/reboot" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "status": "running",
    "message": "重启成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
status	string	操作后状态
message	string	操作结果说明

3.10 获取实例控制台URL

功能说明：获取实例控制台URL

请求方式：GET

请求 URL：

{base_url}/cecs/instances/:instance_id/console

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/console" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "console_url": "https://console.opencecs.com/vnc?token=abc123",
    "expire_at": "2026-03-12 12:30:00"
  }
}

返回字段说明：

字段	类型	说明
console_url	string	VNC控制台URL（含临时Token）
expire_at	string	URL过期时间（通常15分钟）

3.11 删除CECS实例

功能说明：删除CECS实例

请求方式：DELETE

请求 URL：

{base_url}/cecs/instances/:instance_id/delete

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID，需已过期状态

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/delete" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	被删除的实例ID
message	string	删除结果说明

3.12 续费CECS实例

功能说明：续费CECS实例

请求方式：POST

请求 URL：

{base_url}/cecs/instances/:instance_id/renew

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID
duration	int	必填	续费时长（月），最小1

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/renew" \
  -H "Authorization: Bearer eyJ...” \
   #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"duration": 3}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260312-001",
    "total_price": "897.00",
    "new_expire_at": "2026-06-12 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
order_id	string	续费订单号
total_price	string	续费金额（元）
new_expire_at	string	续费后新到期时间

3.13 获取可用节点列表

功能说明：获取可用节点列表

请求方式：GET

请求 URL：

{base_url}/cecs/zones

请求参数：

参数名	类型	必填	说明
region_id	string	必填	地域ID，如 cn-wuhan

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/zones?region_id=cn-wuhan" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "list": [
      {
        "zone_id": "ZONE-CN-WH-1",
        "zone_name": "武汉1",
        "status": 1
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
list[].zone_id	string	节点ID，如 ZONE-CN-WH-1
list[].zone_name	string	节点名称，如武汉1
list[].status	int	状态：1=可用，0=不可用

3.14 切换系统镜像

功能说明：切换系统镜像（会清空所有挂载磁盘数据）

请求方式：POST

请求 URL：

{base_url}/cecs/instances/:instance_id/switch-os

请求参数：

参数名	类型	必填	说明
instance_id	string	必填	实例ID
new_image_id	string	必填	目标镜像ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/switch-os" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"new_image_id": "img_ubuntu22"}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "new_image_id": "img_ubuntu22",
    "disk_results": [
      {
        "disk_id": "disk-abc123",
        "success": true,
        "err_msg": ""
      }
    ],
    "message": "镜像切换成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
new_image_id	string	新镜像ID
disk_results[].disk_id	string	磁盘ID
disk_results[].success	bool	磁盘重建是否成功
disk_results[].err_msg	string	失败原因（成功时为空）
message	string	操作信息

四、CECSDISK 磁盘管理

4.1 磁盘列表（含统计）

功能说明：磁盘列表（含统计）

请求方式：GET

请求 URL：

{base_url}/cecs/disks

请求参数：

参数名	类型	必填	说明
status	string	可选	状态筛选：available / in_use / overdue / expired
region_id	string	可选	地域筛选
page	int	可选	页码，默认1
page_size	int	可选	每页数量，默认10，最大50

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/disks?status=in_use&page=1" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "stats": {
      "total": 5,
      "attached": 3,
      "unattached": 2,
      "total_gb": 500
    },
    "total": 3,
    "list": [
      {
        "disk_id": "disk-abc123",
        "disk_name": "my-disk",
        "size_gb": 100,
        "billing_mode": "monthly",
        "status": "in_use",
        "instance_id": "ins-xyz456",
        "expire_at": "2026-04-01 12:00:00",
        "days_remain": 20
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
stats.total	int	磁盘总数
stats.attached	int	已挂载数量
stats.unattached	int	未挂载数量
stats.total_gb	int	总容量（GB）
total	int	当前筛选总数
list[].disk_id	string	磁盘ID
list[].disk_name	string	磁盘名称
list[].size_gb	int	容量（GB）
list[].billing_mode	string	计费模式：monthly / hourly
list[].status	string	磁盘状态
list[].instance_id	string	已挂载的实例ID（未挂载为空）
list[].expire_at	string	到期时间（包月）
list[].days_remain	int	剩余天数（-1表示按量）

4.2 磁盘详情

功能说明：磁盘详情

请求方式：GET

请求 URL：

{base_url}/cecs/disks/:id

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "disk_name": "my-disk",
    "size_gb": 100,
    "used_gb": 50,
    "used_percent": 50,
    "billing_mode": "monthly",
    "status": "in_use",
    "instance_id": "ins-xyz456",
    "region_id": "cn-wuhan",
    "expire_at": "2026-04-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
disk_name	string	磁盘名称
size_gb	int	容量（GB）
used_gb	int	已用（GB），-1表示不可获取
used_percent	int	使用率（%），-1表示不可获取
billing_mode	string	计费模式
status	string	磁盘状态
instance_id	string	已挂载实例ID
region_id	string	地域ID
expire_at	string	到期时间

4.3 购买磁盘价格预估

功能说明：购买磁盘价格预估

请求方式：POST

请求 URL：

{base_url}/cecs/disks/calculate

请求参数：

参数名	类型	必填	说明
billing_mode	string	必填	计费模式：monthly / hourly
region_id	string	必填	地域ID
size_gb	int	必填	容量（GB），50-10240
duration	int	必填	包月时为月数(1/2/3/6/12)；按量固定传1
quantity	int	必填	购买数量，1-100

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/calculate" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "billing_mode": "monthly",
    "region_id": "cn-wuhan",
    "size_gb": 100,
    "duration": 1,
    "quantity": 1
  }'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "unit_price": "50.00",
    "total_price": "50.00",
    "price_detail": "100GB 包月磁盘，单价50元/月",
    "billing_mode": "monthly",
    "unit": "月"
  }
}

返回字段说明：

字段	类型	说明
unit_price	string	单块磁盘单价（元）
total_price	string	订单总价（元）
price_detail	string	价格明细说明
billing_mode	string	计费模式
unit	string	计费单位：月/小时

4.4 购买磁盘

功能说明：购买磁盘

请求方式：POST

请求 URL：

{base_url}/cecs/disks/buy

请求参数：

参数名	类型	必填	说明
billing_mode	string	必填	计费模式：monthly / hourly
region_id	string	必填	地域ID
zone_id	string	必填	节点ID
size_gb	int	必填	容量（GB），50-10240
duration	int	必填	包月时为月数；按量固定传1
quantity	int	必填	购买数量，1-100
idempotent_token	string	可选	客户端生成UUID，防重复提交

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/buy" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "billing_mode": "monthly",
    "region_id": "cn-wuhan",
    "zone_id": "ZONE-CN-WH-1",
    "size_gb": 100,
    "duration": 1,
    "quantity": 1
  }'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260312-002",
    "disk_ids": ["disk-abc123"],
    "total_price": "50.00",
    "message": "购买成功"
  }
}

返回字段说明：

字段	类型	说明
order_id	string	订单ID
disk_ids	[]string	购买的磁盘ID列表
total_price	string	订单总价（元）
message	string	提示信息

4.5 挂载磁盘到CECS实例

功能说明：挂载磁盘到CECS实例

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/attach

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID
instance_id	string	必填	目标CECS实例ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/attach" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ins-xyz456"}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "instance_id": "ins-xyz456",
    "category": "data",
    "status": "in_use"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
instance_id	string	实例ID
category	string	iSCSI镜像分类
status	string	磁盘状态

4.6 从实例卸载磁盘

功能说明：从实例卸载磁盘

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/detach

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/detach" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "status": "available"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
status	string	卸载后磁盘状态

4.7 扩容磁盘

功能说明：扩容磁盘

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/expand

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID
new_size_gb	int	必填	扩容后容量（GB），必须大于当前容量，50-10240

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/expand" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"new_size_gb": 200}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "old_size_gb": 100,
    "new_size_gb": 200,
    "extra_charge": "50.00",
    "status": "in_use"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
old_size_gb	int	原容量（GB）
new_size_gb	int	新容量（GB）
extra_charge	string	补差价（元），按量磁盘为0
status	string	磁盘状态

4.8 续费磁盘（仅包月）

功能说明：续费磁盘（仅包月）

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/renew

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID
duration	int	必填	续费月数：1/2/3/6/12

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/renew" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"duration": 3}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "order_id": "ORD-20260312-003",
    "total_price": "150.00",
    "new_expire_at": "2026-07-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
order_id	string	续费订单ID
total_price	string	续费价格（元）
new_expire_at	string	新到期时间

4.9 创建备份（功能开发中）

功能说明：创建备份（功能开发中）

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/backup

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID
remark	string	可选	备注（可选）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/backup" \
  -H "Authorization: Bearer eyJ...” \
  #需将 eyJ... 替换为实际的 JWT Token \
  -H "Content-Type: application/json" \
  -d '{"remark": "手动备份"}'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "backup_id": "bak-abc123",
    "disk_id": "disk-abc123",
    "status": "pending"
  }
}

返回字段说明：

字段	类型	说明
backup_id	string	备份ID
disk_id	string	磁盘ID
status	string	备份状态

4.10 格式化磁盘（清空数据，不可撤销）

功能说明：格式化磁盘（清空数据，不可撤销）

请求方式：POST

请求 URL：

{base_url}/cecs/disks/:id/format

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID，⚠️ 将清空所有数据

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/format" \
  -H "Authorization: Bearer eyJ...”
  # 需将 eyJ... 替换为实际的 JWT Toke

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "status": "available"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
status	string	磁盘状态

4.11 释放磁盘

功能说明：释放磁盘

请求方式：DELETE

请求 URL：

{base_url}/cecs/disks/:id

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID，需未挂载状态

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "disk_id": "disk-abc123",
    "message": "释放成功"
  }
}

返回字段说明：

字段	类型	说明
disk_id	string	磁盘ID
message	string	提示信息

4.12 备份列表（功能开发中）

功能说明：备份列表（功能开发中）

请求方式：GET

请求 URL：

{base_url}/cecs/disks/:id/backups

请求参数：

参数名	类型	必填	说明
id	string	必填	磁盘ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/disks/disk-abc123/backups" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "list": [
      {
        "backup_id": "bak-abc123",
        "disk_id": "disk-abc123",
        "size_gb": 100,
        "status": "completed",
        "remark": "手动备份",
        "created_at": "2026-03-12 12:00:00"
      }
    ],
    "total": 1
  }
}

返回字段说明：

字段	类型	说明
list[].backup_id	string	备份ID
list[].disk_id	string	磁盘ID
list[].size_gb	int	备份时磁盘容量（GB）
list[].status	string	备份状态
list[].remark	string	备注
list[].created_at	string	创建时间
total	int	总数量

4.13 删除备份（功能开发中）

功能说明：删除备份（功能开发中）

请求方式：DELETE

请求 URL：

{base_url}/cecs/disks/backups/:backup_id

请求参数：

参数名	类型	必填	说明
backup_id	string	必填	备份ID

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/cecs/disks/backups/bak-abc123" \
  -H "Authorization: Bearer eyJ...”
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": null
}

返回字段说明：

字段	类型	说明
（空响应）	-	删除成功返回 HTTP 200

五、ORDER 订单

5.1 计算订单价格

功能说明：计算订单价格

请求方式：POST

请求 URL：

{base_url}/orders/calculate

请求参数：

参数名	类型	必填	说明
resource_type	string	必填	资源类型，填 cecs_instance
billing_mode	string	必填	计费模式：monthly / hourly
duration	int	必填	购买时长（月），最小1
quantity	int	必填	购买数量，1-100
config	string	必填	配置JSON字符串，含 product_id / image_id 等字段

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/orders/calculate" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "cecs_instance",
    "billing_mode": "monthly",
    "duration": 1,
    "quantity": 1,
    "config": "{\"product_id\":\"prod_rk3588_8g\",\"image_id\":\"img_ubuntu22\"}"
  }'

返回示例：

成功：

{
  "code": 0,
  "message": "Success",
  "data": {
    "cecs_price": "299.00",
    "disk_price": "0.00",
    "bandwidth_price": "0.00",
    "total_price": "299.00",
    "price_detail": "CECS实例: 299元/月"
  }
}

返回字段说明：

字段	类型	说明
cecs_price	string	CECS设备价格（元）
disk_price	string	磁盘价格（元）
bandwidth_price	string	带宽价格（元）
total_price	string	订单总价（元）
price_detail	string	价格明细描述

5.2 创建订单

功能说明：创建订单

请求方式：POST

请求URL：{base_url}/orders/create

请求参数：

参数名	必选	类型	说明
order_type	是	string	订单类型，填 purchase
resource_type	是	string	资源类型，填 cecs_instance
billing_mode	是	string	计费模式：monthly / hourly
region_id	是	string	地域ID
duration	是	int	购买时长（月），最小1
quantity	是	int	购买数量，1-100
config	是	string	配置JSON字符串
idempotent_token	否	string	幂等Token，防止重复提单（可选）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/orders/create" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "purchase",
    "resource_type": "cecs_instance",
    "billing_mode": "monthly",
    "region_id": "cn-shenzhen",
    "duration": 1,
    "quantity": 1,
    "config": "{\"product_id\":\"prod_rk3588_8g\",\"image_id\":\"img_ubuntu22\"}"
  }'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260227-001",
    "total_price": "299.00",
    "status": "pending_payment",
    "expired_at": "2026-03-02 12:00:00",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
order_id	string	订单号（如 ORD-20260227-001）
total_price	string	订单总价（元）
status	string	状态：pending_payment
expired_at	string	支付截止时间（超时自动取消）
created_at	string	创建时间

5.3 获取订单列表

功能说明：获取订单列表

请求方式：GET

请求URL：{base_url}/orders/list

请求参数：

参数名	必选	类型	说明
order_type	否	string	订单类型过滤
status	否	string	状态过滤
page	否	int	页码，默认1
page_size	否	int	每页数量，默认10

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/orders/list?status=paid&page=1" \
  -H "Authorization: Bearer eyJ..."
  # 需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 10,
    "list": [
      {
        "order_id": "ORD-20260227-001",
        "resource_type": "cecs_instance",
        "total_price": "299.00",
        "status": "paid",
        "created_at": "2026-03-01 12:00:00",
        "paid_at": "2026-03-01 12:05:00"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	订单总数
list[].order_id	string	订单号
list[].resource_type	string	资源类型
list[].total_price	string	订单总价
list[].status	string	状态：pending_payment / paid / cancelled
list[].created_at	string	创建时间
list[].paid_at	string	支付时间（未支付为空）

5.4 获取订单详情

功能说明：获取订单详情

请求方式：GET

请求URL：{base_url}/orders/{order_id}

请求参数：

参数名	必选	类型	说明
order_id	是	string	订单号

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/orders/ORD-20260227-001" \
  -H "Authorization: Bearer eyJ..."
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order": {
      "order_id": "ORD-20260227-001",
      "resource_type": "cecs_instance",
      "region_name": "深圳",
      "quantity": 1,
      "total_price": "299.00",
      "config": "{\"product_id\":\"prod_rk3588_8g\",\"image_id\":\"img_ubuntu22\"}",
      "status": "paid",
      "paid_at": "2026-03-01 12:05:00",
      "completed_at": "2026-03-01 12:06:00"
    }
  }
}

返回字段说明：

字段	类型	说明
order.order_id	string	订单号
order.resource_type	string	资源类型
order.region_name	string	地域名称
order.quantity	int	购买数量
order.total_price	string	总价（元）
order.config	string	配置详情JSON
order.status	string	订单状态
order.paid_at	string	支付时间
order.completed_at	string	完成时间

5.5 支付订单

功能说明：支付订单

请求方式：POST

请求URL：{base_url}/orders/{order_id}/pay

请求参数：

参数名	必选	类型	说明
order_id	是	string	订单号
payment_method	是	string	支付方式：balance（余额）/ alipay / wechat

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/orders/ORD-20260227-001/pay" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"payment_method": "balance"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260227-001",
    "status": "paid",
    "paid_at": "2026-03-01 12:05:00",
    "instance_ids": ["ins-abc123"]
  }
}

返回字段说明：

字段	类型	说明
order_id	string	订单号
status	string	支付后状态：paid
paid_at	string	支付完成时间
instance_ids	[]string	创建的实例ID列表

5.6 取消订单

功能说明：取消订单

请求方式：POST

请求URL：{base_url}/orders/{order_id}/cancel

请求参数：

参数名	必选	类型	说明
order_id	是	string	订单号，仅 pending_payment 状态可取消

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/orders/ORD-20260227-001/cancel" \
  -H "Authorization: Bearer eyJ..."
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260227-001",
    "status": "cancelled",
    "message": "取消成功"
  }
}

返回字段说明：

字段	类型	说明
order_id	string	订单号
status	string	取消后状态：cancelled
message	string	取消说明

六、FINANCE 财务

6.1 获取费用概览

功能说明：获取费用概览

请求方式：GET

请求URL：{base_url}/finance/overview

请求参数：无

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/finance/overview" \
  -H "Authorization: Bearer eyJ..."
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "available_balance": 1000.0,
    "month_consumption": 299.0,
    "month_over_month_ratio": 2.5,
    "month_over_month_direction": "up",
    "expiring_resource_count": 3,
    "invoiceable_amount": 1000.0
  }
}

返回字段说明：

字段	类型	说明
available_balance	float64	账户可用余额（元）
month_consumption	float64	本月消费金额（元）
month_over_month_ratio	float64	环比上月变化百分点（2.5表示增长12.5%）
month_over_month_direction	string	涨跌方向：up / down / flat
expiring_resource_count	int	30天内即将到期资源数量
invoiceable_amount	float64	可申请开票金额（元）

6.2 统一账单列表

功能说明：统一账单列表

请求方式：GET

请求URL：{base_url}/finance/orders

请求参数：

参数名	必选	类型	说明
tab_type	是	string	Tab分类：all / purchase / renewal / expansion / package / recharge
billing_mode	否	string	计费模式过滤：monthly / hourly
status	否	string	状态过滤
start_time	否	string	开始日期，格式 2006-01-02
end_time	否	string	结束日期，格式 2006-01-02
page	否	int	页码，默认1
page_size	否	int	每页数量，默认10，最大100

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/finance/orders?tab_type=all&page=1" \
  -H "Authorization: Bearer eyJ..."
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 10,
    "list": [
      {
        "order_id": "ORD-20260301-005",
        "amount": 299.0,
        "status": "paid",
        "order_type": "purchase",
        "resource_name": "CECS实例",
        "billing_mode": "monthly",
        "created_at": "2026-03-01 12:00:00"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总记录数
list[].order_id	string	订单号/充值单号
list[].amount	float64	金额（元）
list[].status	string	状态
list[].order_type	string	订单类型（充值记录无此字段）
list[].resource_name	string	资源名称
list[].billing_mode	string	计费模式
list[].created_at	string	创建时间

6.3 即将到期资源列表

功能说明：即将到期资源列表

请求方式：GET

请求URL：{base_url}/finance/expiring-resources

请求参数：

参数名	必选	类型	说明
days	否	int	查询多少天内到期，默认30天
page	否	int	页码，默认1
page_size	否	int	每页数量，默认10

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/finance/expiring-resources?days=7" \
  -H "Authorization: Bearer eyJ..."
  #需将 eyJ... 替换为实际的 JWT Token

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "list": [
      {
        "resource_id": "ins-abc123",
        "resource_name": "my-instance",
        "resource_type": "cecs_instance",
        "expire_at": "2026-03-08 12:00:00",
        "remaining_days": 7
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总记录数
list[].resource_id	string	资源ID
list[].resource_name	string	资源名称
list[].resource_type	string	资源类型：cecs_instance / cecs_disk
list[].expire_at	string	到期时间
list[].remaining_days	int	剩余天数

6.4 发起充值

功能说明：发起充值

请求方式：POST

请求URL：{base_url}/finance/recharges

请求参数：

参数名	必选	类型	说明
amount	是	float64	充值金额（元），最小1，最大100000
payment_method	是	string	支付方式：wechat / alipay / bank_card

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/finance/recharges" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00, "payment_method": "alipay"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "recharge_id": "REC-20260301-001",
    "status": "pending",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
recharge_id	string	充值单号
status	string	初始状态：pending
created_at	string	创建时间

6.5 申请开票

功能说明：申请开票

请求方式：POST

请求URL：{base_url}/finance/invoices

请求参数：

参数名	必选	类型	说明
amount	是	float64	开票金额（元），最小1
invoice_type	是	string	发票类型：vat_general / vat_special
title_type	是	string	抬头类型：personal / enterprise
title	是	string	发票抬头，1-100字符
tax_number	否	string	税号（企业抬头必填）
email	是	string	发票接收邮箱

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/finance/invoices" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "invoice_type": "vat_general",
    "title_type": "enterprise",
    "title": "某某科技有限公司",
    "tax_number": "91440300XXXXXXXX",
    "email": "finance@example.com"
  }'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "invoice_id": "INV-20260301-001",
    "status": "applying",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
invoice_id	string	开票申请ID
status	string	初始状态：applying
created_at	string	申请时间

七、PORTMAPPING 端口映射

7.1 获取端口映射概览

功能说明：获取端口映射概览

请求方式：GET

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings/overview

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings/overview" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "ins-abc123",
    "instance_name": "my-instance",
    "private_ip": "192.168.1.100",
    "nat_public_ip": "203.0.113.1",
    "tcp": {
      "used": 2,
      "quota": 10,
      "active_count": 2,
      "failed_count": 0
    },
    "udp": {
      "used": 1,
      "quota": 5,
      "active_count": 1,
      "failed_count": 0
    }
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
instance_name	string	实例名称
private_ip	string	实例内网IP
nat_public_ip	string	端口映射公网IP（NAT分配）
tcp.used	int	TCP已使用映射数
tcp.quota	int	TCP映射配额上限
tcp.active_count	int	TCP代理正常数量
tcp.failed_count	int	TCP代理异常数量
udp.used	int	UDP已使用映射数
udp.quota	int	UDP映射配额上限
udp.active_count	int	UDP代理正常数量
udp.failed_count	int	UDP代理异常数量

7.2 查询端口映射规则列表

功能说明：查询端口映射规则列表

请求方式：GET

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
protocol	否	string	协议过滤：TCP / UDP，不填返回全部
page	否	int	页码，默认1
page_size	否	int	每页数量，默认10，最大50

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings?protocol=TCP&page=1" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 3,
    "list": [
      {
        "mapping_id": "pm-001",
        "protocol": "TCP",
        "public_port": 10022,
        "private_port": 22,
        "remark": "SSH",
        "proxy_status": "ok",
        "fail_reason": "",
        "created_at": "2026-03-01 12:00:00"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	规则总数
list[].mapping_id	string	映射规则ID
list[].protocol	string	协议：TCP / UDP
list[].public_port	int	公网端口（系统自动分配，不可修改）
list[].private_port	int	内网端口（用户配置）
list[].remark	string	备注
list[].proxy_status	string	NAT代理状态：ok / failed
list[].fail_reason	string	代理失败原因（proxy_status=ok 时为空）
list[].created_at	string	规则创建时间

7.3 创建端口映射规则

功能说明：创建端口映射规则

请求方式：POST

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
protocol	是	string	协议：TCP / UDP
private_port	是	int	内网端口，1-65535
remark	否	string	备注，最多50字符

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"protocol": "TCP", "private_port": 22, "remark": "SSH"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "mapping_id": "pm-001",
    "protocol": "TCP",
    "public_port": 10022,
    "private_port": 22,
    "remark": "SSH",
    "proxy_status": "ok",
    "fail_reason": "",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
mapping_id	string	新建映射规则ID
protocol	string	协议：TCP / UDP
public_port	int	系统自动分配的公网端口（固定，不可修改）
private_port	int	内网端口
remark	string	备注
proxy_status	string	NAT代理状态：ok（生效）/ failed（端口监听失败）
fail_reason	string	代理失败原因（proxy_status=ok 时为空）
created_at	string	创建时间

7.4 修改端口映射规则

功能说明：修改端口映射规则（内网端口或备注）

请求方式：PATCH

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings/{mapping_id}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
mapping_id	是	string	映射规则ID
private_port	否	int	新内网端口（1-65535），至少传一个字段
remark	否	string	新备注，最多50字符

请求示例：

curl -X PATCH "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings/pm-001" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"private_port": 8080, "remark": "HTTP"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "mapping_id": "pm-002",
    "protocol": "TCP",
    "public_port": 10022,
    "private_port": 8080,
    "remark": "HTTP",
    "proxy_status": "ok",
    "fail_reason": "",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
mapping_id	string	映射规则ID（仅修改备注时ID不变；修改内网端口会删旧建新，ID随之更新）
protocol	string	协议：TCP / UDP
public_port	int	公网端口（始终保持不变）
private_port	int	更新后的内网端口
remark	string	更新后的备注
proxy_status	string	NAT代理状态：ok / failed
fail_reason	string	代理失败原因
created_at	string	规则创建时间

7.5 删除端口映射规则

功能说明：删除端口映射规则

请求方式：DELETE

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings/{mapping_id}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
mapping_id	是	string	映射规则ID

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings/pm-001" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {}
}

返回字段说明：无（空对象）

7.6 批量创建端口映射规则

功能说明：批量创建端口映射规则

请求方式：POST

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings/batch

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
rules	是	array	规则列表，至少1条
rules[].protocol	是	string	协议：TCP / UDP（大小写均可）
rules[].private_port	是	int	内网端口，1-65535
rules[].remark	否	string	备注，最多50字符

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings/batch" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {"protocol": "TCP", "private_port": 22, "remark": "SSH"},
      {"protocol": "TCP", "private_port": 8080, "remark": "HTTP"}
    ]
  }'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "succeeded": 2,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "success": true,
        "data": {
          "mapping_id": "pm-001",
          "protocol": "TCP",
          "public_port": 10022,
          "private_port": 22,
          "remark": "SSH",
          "proxy_status": "ok",
          "created_at": "2026-03-01 12:00:00"
        },
        "reason": ""
      },
      {
        "index": 1,
        "success": true,
        "data": {
          "mapping_id": "pm-002",
          "protocol": "TCP",
          "public_port": 10023,
          "private_port": 8080,
          "remark": "HTTP",
          "proxy_status": "ok",
          "created_at": "2026-03-01 12:00:00"
        },
        "reason": ""
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	提交的规则总数
succeeded	int	成功创建数量
failed	int	失败数量
results[].index	int	对应请求 rules 数组的下标
results[].success	bool	该条是否成功
results[].data	object	成功时返回的映射规则详情
results[].reason	string	失败原因（success=true 时为空）

7.7 批量删除端口映射规则

功能说明：批量删除端口映射规则

请求方式：DELETE

请求URL：{base_url}/cecs/instances/{instance_id}/port-mappings/batch

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
mapping_ids	是	[]string	要删除的规则ID列表，至少1个

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/cecs/instances/ins-abc123/port-mappings/batch" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"mapping_ids": ["pm-001", "pm-002"]}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "succeeded": 2,
    "failed": 0,
    "results": [
      {
        "mapping_id": "pm-001",
        "success": true,
        "reason": ""
      },
      {
        "mapping_id": "pm-002",
        "success": true,
        "reason": ""
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	提交的ID总数
succeeded	int	成功删除数量
failed	int	失败数量
results[].mapping_id	string	规则ID
results[].success	bool	该条是否成功
results[].reason	string	失败原因（success=true 时为空）

八、SHAREDSTORAGE 共享存储

8.1 购买共享存储资源包

功能说明：购买共享存储资源包

请求方式：POST

请求URL：{base_url}/shared-storage/packages/buy

请求参数：

参数名	必选	类型	说明
region_id	是	string	地域ID
capacity_gb	是	int	购买容量（GB），100-20480
duration	是	int	购买时长（月）：1/2/3/6/12
quantity	是	int	购买数量，1-10
idempotent_key	否	string	幂等键，防止重复下单

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/packages/buy" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"region_id": "cn-shenzhen", "capacity_gb": 100, "duration": 1, "quantity": 1}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "ORD-20260301-006",
    "total_price": "500.00",
    "status": "pending",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
order_id	string	订单号
total_price	string	订单总价（元）
status	string	状态：pending
created_at	string	创建时间

8.2 查询共享存储资源包列表

功能说明：查询共享存储资源包列表

请求方式：GET

请求URL：{base_url}/shared-storage/packages

请求参数：

参数名	必选	类型	说明
region_id	否	string	按地域过滤
status	否	string	状态：active / expired / grace
page	否	int	页码，默认1
page_size	否	int	每页数量，默认20

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/packages?status=active" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "list": [
      {
        "package_id": "pkg-001",
        "region_name": "深圳",
        "capacity_gb": 100,
        "status": "active",
        "expired_at": "2026-04-01 12:00:00",
        "days_left": 13
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总数量
list[].package_id	string	资源包ID
list[].region_name	string	地域名称
list[].capacity_gb	int	容量（GB）
list[].status	string	状态：active / expired / grace
list[].expired_at	string	到期时间
list[].days_left	int	剩余天数（已过期为0）

8.3 共享存储概览

功能说明：共享存储概览

请求方式：GET

请求URL：{base_url}/shared-storage/overview

请求参数：无

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/overview" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total_gb": 200.0,
    "used_gb": 45.5,
    "available_gb": 154.5,
    "usage_percent": 22.75,
    "package_count": 2,
    "instance_count": 1,
    "instances": [
      {
        "instance_id": "si-001",
        "display_name": "my-storage",
        "capacity_gb": 100,
        "used_percent": 45,
        "access_mode": "private"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total_gb	float64	总配额（GB）
used_gb	float64	已使用（GB）
available_gb	float64	可用配额（GB）
usage_percent	float64	使用率（%）
package_count	int	有效资源包数量
instance_count	int	存储实例数量
instances[].instance_id	string	实例ID
instances[].display_name	string	存储名称
instances[].capacity_gb	int	分配容量（GB）
instances[].used_percent	float64	使用率（%）
instances[].access_mode	string	访问模式：public / private

8.4 创建共享存储实例

功能说明：创建共享存储实例

请求方式：POST

请求URL：{base_url}/shared-storage/instances

请求参数：

参数名	必选	类型	说明
region_id	是	string	地域ID
name	是	string	存储名称，3-63字符，小写字母/数字/连字符
capacity_gb	是	int	初始容量（GB），10-500
access_mode	是	string	访问模式：public / private
description	否	string	描述，最多200字符

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/instances" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"region_id": "cn-shenzhen", "name": "my-storage", "capacity_gb": 50, "access_mode": "private"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "bucket_name": "userid_my-storage",
    "display_name": "my-storage",
    "intranet_addr": "http://10.0.0.1:9000/userid_my-storage",
    "access_key": "abc123def456",
    "created_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
bucket_name	string	实际Bucket名称（userid_name格式）
display_name	string	用户输入的存储名称
intranet_addr	string	内网访问地址（如`http://10.x.x.x:9000/bucket`）
access_key	string	访问密钥（private模式时返回，请保存）
created_at	string	创建时间

8.5 获取存储实例列表

功能说明：获取存储实例列表

请求方式：GET

请求URL：{base_url}/shared-storage/instances

请求参数：

参数名	必选	类型	说明
region_id	是	string	地域ID（必填）
name	否	string	按存储名称模糊搜索
page	否	int	页码，默认1
page_size	否	int	每页数量，默认20

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/instances?region_id=cn-shenzhen" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 1,
    "list": [
      {
        "instance_id": "si-001",
        "display_name": "my-storage",
        "intranet_addr": "http://10.0.0.1:9000/userid_my-storage",
        "capacity_gb": 50,
        "used_gb": 22.5,
        "access_mode": "private",
        "created_at": "2026-03-01 12:00:00"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总数量
list[].instance_id	string	实例ID
list[].display_name	string	存储名称
list[].intranet_addr	string	内网访问地址
list[].capacity_gb	int	分配容量（GB）
list[].used_gb	float64	已使用（GB）
list[].access_mode	string	访问模式
list[].created_at	string	创建时间

8.6 列举目录内容

功能说明：列举目录内容

请求方式：GET

请求URL：{base_url}/shared-storage/instances/{instance_id}/files

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
path	否	string	目录路径，默认 /
max_keys	否	int	最大返回条数，默认200
marker	否	string	分页标记，上一页返回的 next_marker

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/files?path=/data/" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "current_path": "/data/",
    "dirs": [
      {
        "name": "images",
        "full_path": "/data/images/"
      }
    ],
    "files": [
      {
        "name": "file.txt",
        "size": 1024,
        "size_readable": "1.00 KB",
        "last_modified": "2026-03-01 12:00:00"
      }
    ],
    "is_truncated": false,
    "next_marker": "",
    "used_gb": 22.5,
    "capacity_gb": 50
  }
}

返回字段说明：

字段	类型	说明
current_path	string	当前目录路径
dirs[].name	string	子目录名称
dirs[].full_path	string	子目录完整路径
files[].name	string	文件名
files[].size	int64	文件大小（字节）
files[].size_readable	string	可读大小，如 1.23 MB
files[].last_modified	string	最后修改时间
is_truncated	bool	是否还有更多数据
next_marker	string	下一页分页标记
used_gb	float64	实例已用容量（GB）
capacity_gb	int	实例总容量（GB）

8.7 新建文件夹

功能说明：新建文件夹

请求方式：POST

请求URL：{base_url}/shared-storage/instances/{instance_id}/folders

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
path	是	string	文件夹路径，必须以 / 结尾，如 /data/images/

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/folders" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"path": "/data/images/"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "path": "/data/images/",
    "message": "创建成功"
  }
}

返回字段说明：

字段	类型	说明
path	string	创建的文件夹路径
message	string	操作结果

8.8 上传文件

功能说明：上传文件

请求方式：PUT

请求URL：{base_url}/shared-storage/instances/{instance_id}/files/{key}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
key	是	string	文件路径，如 /data/image.png

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/files/data/image.png" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: image/png" \
  --data-binary @image.png

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "bucket_name": "userid_my-storage",
    "key": "data/image.png",
    "size": 123456,
    "etag": "abc123def456"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
bucket_name	string	Bucket名称
key	string	文件路径
size	int64	文件大小（字节）
etag	string	MD5

8.9 查看文件详情

功能说明：查看文件详情

请求方式：GET

请求URL：{base_url}/shared-storage/instances/{instance_id}/files/{key}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
key	是	string	文件路径

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/files/data/image.png" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "key": "data/image.png",
    "size": 123456,
    "size_readable": "120.56 KB",
    "content_type": "image/png",
    "etag": "abc123def456",
    "last_modified": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
key	string	文件路径
size	int64	文件大小（字节）
size_readable	string	可读大小
content_type	string	Content-Type
etag	string	ETag校验值
last_modified	string	最后修改时间

8.10 删除文件或文件夹

功能说明：删除文件或文件夹

请求方式：DELETE

请求URL：{base_url}/shared-storage/instances/{instance_id}/files/{key}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
key	是	string	文件路径；删除文件夹时路径以 / 结尾

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/files/data/image.png" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "key": "data/image.png",
    "message": "删除成功",
    "deleted": 1
  }
}

返回字段说明：

字段	类型	说明
key	string	删除的路径
message	string	操作结果
deleted	int	实际删除的对象数量（文件夹时为递归删除数量）

8.11 重置访问密钥

功能说明：重置访问密钥

请求方式：POST

请求URL：{base_url}/shared-storage/instances/{instance_id}/access-key/reset

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/access-key/reset" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "access_key": "newkey123",
    "message": "重置成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
access_key	string	新的访问密钥（请保存，只显示一次）
message	string	操作结果

8.12 切换访问模式

功能说明：切换访问模式

请求方式：PUT

请求URL：{base_url}/shared-storage/instances/{instance_id}/access-mode

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
access_mode	是	string	目标访问模式：public / private

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/access-mode" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"access_mode": "private"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "access_mode": "private",
    "access_key": "newkey456",
    "message": "切换成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
access_mode	string	切换后的访问模式
access_key	string	切换至 private 时返回新密钥
message	string	操作结果

8.13 扩容存储实例

功能说明：扩容存储实例

请求方式：POST

请求URL：{base_url}/shared-storage/instances/{instance_id}/expand

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
additional_gb	是	int	扩容大小（GB），1-500

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/expand" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  -H "Content-Type: application/json" \
  -d '{"additional_gb": 50}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "capacity_gb": 100,
    "message": "扩容成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
capacity_gb	int	扩容后总容量（GB）
message	string	操作结果

8.14 格式化存储实例

功能说明：格式化存储实例

请求方式：POST

请求URL：{base_url}/shared-storage/instances/{instance_id}/format

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID，⚠️ 会清空所有数据，不可恢复

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/format" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "message": "格式化成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	实例ID
message	string	格式化结果

8.15 删除存储实例

功能说明：删除存储实例

请求方式：DELETE

请求URL：{base_url}/shared-storage/instances/{instance_id}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID，⚠️ 实例需为空才可删除

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/shared-storage/instances/si-001" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "instance_id": "si-001",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
instance_id	string	被删除的实例ID
message	string	删除结果

8.16 下载文件

功能说明：下载文件

请求方式：GET

请求URL：{base_url}/shared-storage/instances/{instance_id}/download/{key}

请求参数：

参数名	必选	类型	说明
instance_id	是	string	存储实例ID
key	是	string	文件路径

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/shared-storage/instances/si-001/download/data/image.png" \
  -H "Authorization:   Bearer eyJ..." \
  #需将 eyJ... 替换为实际的 JWT Token
  --output image.png

成功返回：直接返回文件内容流，响应头含 Content-Type / Content-Length。

九、TASKLOG 定时任务

9.1 查询定时任务日志列表

功能说明：查询定时任务日志列表

请求方式：GET

请求URL：{base_url}/task/logs

请求参数：

参数名	必选	类型	说明
task_name	否	string	任务名称过滤，如 release-expired-stock
status	否	string	状态过滤：running / success / failed / skipped
page	否	int	页码，默认1
page_size	否	int	每页条数，默认20，最大100

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/task/logs?status=failed&page=1" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 5,
    "page": 1,
    "list": [
      {
        "id": 42,
        "task_name": "release-expired-stock",
        "task_desc": "释放过期库存",
        "status": "failed",
        "started_at": "2026-03-01 00:00:00",
        "finished_at": "2026-03-01 00:01:00",
        "duration_ms": 60000,
        "result": "{\"released\":0}",
        "error_msg": "库存服务异常"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总条数
page	int	当前页
list[].id	uint64	日志ID
list[].task_name	string	任务名称
list[].task_desc	string	任务描述
list[].status	string	执行状态：running/success/failed/skipped
list[].started_at	string	开始时间
list[].finished_at	string	结束时间
list[].duration_ms	int	耗时（毫秒）
list[].result	string	结果摘要（JSON）
list[].error_msg	string	错误信息

9.2 查询定时任务日志详情

功能说明：查询定时任务日志详情

请求方式：GET

请求URL：{base_url}/task/logs/{id}

请求参数：

参数名	必选	类型	说明
id	是	int	日志ID

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/task/logs/42" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "id": 42,
    "task_name": "release-expired-stock",
    "task_desc": "释放过期库存",
    "status": "failed",
    "started_at": "2026-03-01 00:00:00",
    "finished_at": "2026-03-01 00:01:00",
    "duration_ms": 60000,
    "result": "{\"released\":0}",
    "error_msg": "库存服务异常",
    "created_at": "2026-03-01 00:01:00"
  }
}

返回字段说明：

字段	类型	说明
id	uint64	日志ID
task_name	string	任务名称
task_desc	string	任务描述
status	string	执行状态
started_at	string	开始时间
finished_at	string	结束时间
duration_ms	int	耗时（毫秒）
result	string	结果摘要（JSON）
error_msg	string	错误信息
created_at	string	记录创建时间

9.3 查询定时任务执行统计

功能说明：查询定时任务执行统计

请求方式：GET

请求URL：{base_url}/task/logs/stats

请求参数：无

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/task/logs/stats" \
  -H "Authorization: Bearer {token}"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "stats": [
      {
        "task_name": "release-expired-stock",
        "task_desc": "释放过期库存",
        "total_runs": 30,
        "success_count": 28,
        "failed_count": 2,
        "skipped_count": 0,
        "avg_duration_ms": 55000.5,
        "last_run_at": "2026-03-01 00:00:00",
        "last_status": "success"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
stats[].task_name	string	任务名称
stats[].task_desc	string	任务描述
stats[].total_runs	int	总执行次数
stats[].success_count	int	成功次数
stats[].failed_count	int	失败次数
stats[].skipped_count	int	跳过次数
stats[].avg_duration_ms	float64	平均耗时（毫秒）
stats[].last_run_at	string	最近执行时间
stats[].last_status	string	最近执行状态

十、STORAGE 对象存储

10.1 列举Bucket内对象

功能说明：列举Bucket内对象

请求方式：GET

请求URL：{base_url}/storage/{bucket}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
prefix	否	string	前缀过滤，如 data/
delimiter	否	string	分隔符，通常为 / 实现目录浏览
max_keys	否	int	最大返回数量，默认1000
marker	否	string	分页标记
access_key	否	string	访问密钥（private Bucket必填）

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage/my-bucket?prefix=data/&delimiter=/"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "objects": [
      {
        "key": "data/file1.txt",
        "size": 1024,
        "last_modified": "2026-03-01 12:00:00",
        "etag": "abc123"
      }
    ],
    "common_prefixes": ["data/images/"],
    "is_truncated": false,
    "next_marker": ""
  }
}

返回字段说明：

字段	类型	说明
objects[].key	string	对象路径
objects[].size	int64	对象大小（字节）
objects[].last_modified	string	最后修改时间
objects[].etag	string	ETag校验值
common_prefixes	[]string	公共前缀列表（目录）
is_truncated	bool	是否还有更多
next_marker	string	下一页标记

10.2 获取树形目录

功能说明：获取树形目录

请求方式：GET

请求URL：{base_url}/storage/{bucket}/tree

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
prefix	否	string	起始子路径

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage/my-bucket/tree"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "tree": [
      {
        "name": "data",
        "path": "data/",
        "type": "dir",
        "children": [
          {
            "name": "file.txt",
            "path": "data/file.txt",
            "type": "file",
            "size": 1024
          }
        ]
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
tree[].name	string	节点名称
tree[].path	string	完整路径
tree[].type	string	类型：file / dir
tree[].size	int64	文件大小（文件节点才有）
tree[].children	[]TreeNode	子节点（目录节点才有）

10.3 下载文件（流式）

功能说明：下载文件（流式）

请求方式：GET

请求URL：{base_url}/storage/{bucket}/{key}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
key	是	string	文件路径
access_key	否	string	访问密钥（private Bucket必填）

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage/my-bucket/data/image.png" --output image.png

成功返回：直接返回文件内容流，响应头含 Content-Type / Content-Length。

10.4 删除文件

功能说明：删除文件

请求方式：DELETE

请求URL：{base_url}/storage/{bucket}/{key}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
key	是	string	文件路径

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/storage/my-bucket/data/image.png"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "key": "data/image.png",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
key	string	删除的文件路径
message	string	操作结果

10.5 批量删除文件

功能说明：批量删除文件

请求方式：POST

请求URL：{base_url}/storage/{bucket}/batch-delete

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
keys	是	[]string	文件路径列表

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage/my-bucket/batch-delete" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["data/a.txt", "data/b.png"]}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "success": 2,
    "failed": 0
  }
}

返回字段说明：

字段	类型	说明
total	int	提交删除总数
success	int	删除成功数
failed	int	删除失败数

10.6 创建文件夹

功能说明：创建文件夹

请求方式：PUT

请求URL：{base_url}/storage/{bucket}/folders/{path}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
path	是	string	文件夹路径，支持多级

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/storage/my-bucket/folders/data/images"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "path": "data/images/",
    "message": "创建成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
path	string	创建的路径
message	string	操作结果

10.7 删除文件夹

功能说明：删除文件夹

请求方式：DELETE

请求URL：{base_url}/storage/{bucket}/folders/{path}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
path	是	string	文件夹路径

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/storage/my-bucket/folders/data/images"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "path": "data/images/",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
path	string	删除的路径
message	string	操作结果

10.8 移动文件或文件夹

功能说明：移动文件或文件夹

请求方式：POST

请求URL：{base_url}/storage/{bucket}/move

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
src	是	string	源路径
dst	是	string	目标路径（不能已存在）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage/my-bucket/move" \
  -H "Content-Type: application/json" \
  -d '{"src": "old/path/file.txt", "dst": "new/path/file.txt"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "src": "old/path/file.txt",
    "dst": "new/path/file.txt",
    "message": "移动成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
src	string	源路径
dst	string	目标路径
message	string	操作结果

10.9 批量下载文件（ZIP）

功能说明：批量下载文件（ZIP）

请求方式：POST

请求URL：{base_url}/storage/{bucket}/batch-download

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
keys	是	[]string	文件路径列表

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage/my-bucket/batch-download" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["data/a.txt", "data/b.png"]}' \
  --output files.zip

成功返回：返回 ZIP 文件流，浏览器直接下载。

十一、STORAGEADMIN 存储管理

11.1 创建Bucket

功能说明：创建Bucket

请求方式：POST

请求URL：{base_url}/storage-admin/buckets

请求参数：

参数名	必选	类型	说明
bucket_name	是	string	3-63字符，小写字母/数字/连字符/下划线
quota_gb	是	int	配额大小（GB），最小1
access_mode	是	string	访问模式：public / private
access_key	否	string	访问密钥，留空自动生成

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets" \
  -H "Content-Type: application/json" \
  -d '{"bucket_name": "my-bucket", "quota_gb": 10, "access_mode": "private"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "lv_name": "lv-my-bucket",
    "mount_point": "/mnt/lv-my-bucket",
    "quota_gb": 10,
    "access_mode": "private",
    "access_key": "abc123def456"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
lv_name	string	逻辑卷名称
mount_point	string	挂载点路径
quota_gb	int	配额大小（GB）
access_mode	string	访问模式
access_key	string	访问密钥

11.2 列出所有Bucket

功能说明：列出所有Bucket

请求方式：GET

请求URL：{base_url}/storage-admin/buckets

请求参数：

参数名	必选	类型	说明
page	否	int	页码，默认1
page_size	否	int	每页数量，默认20，最大100
access_mode	否	string	过滤访问模式
sort	否	string	排序字段：name / created_at / used_gb
order	否	string	排序方向：asc / desc

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/buckets?page=1&page_size=20"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "buckets": [
      {
        "bucket_name": "my-bucket",
        "access_mode": "private",
        "quota_gb": 10.0,
        "used_gb": 2.3,
        "usage_percent": 23.0,
        "file_count": 15,
        "created_at": "2026-03-01 12:00:00"
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
total	int	总数量
buckets[].bucket_name	string	Bucket名称
buckets[].access_mode	string	访问模式
buckets[].quota_gb	float64	配额（GB）
buckets[].used_gb	float64	已用（GB）
buckets[].usage_percent	float64	使用率（%）
buckets[].file_count	int	文件数量
buckets[].created_at	string	创建时间

11.3 查询Bucket详情

功能说明：查询Bucket详情

请求方式：GET

请求URL：{base_url}/storage-admin/buckets/{bucket}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket_name": "my-bucket",
    "lv_name": "lv-my-bucket",
    "access_mode": "private",
    "access_key": "abc123def456",
    "quota_gb": 10.0,
    "used_gb": 2.3,
    "usage_percent": 23.0,
    "file_count": 15,
    "created_at": "2026-03-01 12:00:00",
    "updated_at": "2026-03-01 12:00:00"
  }
}

返回字段说明：

字段	类型	说明
bucket_name	string	Bucket名称
lv_name	string	逻辑卷名称
access_mode	string	访问模式
access_key	string	访问密钥明文（管理员可见）
quota_gb	float64	配额（GB）
used_gb	float64	已用（GB）
usage_percent	float64	使用率（%）
file_count	int	文件数量
created_at	string	创建时间
updated_at	string	最后更新时间

11.4 删除Bucket

功能说明：删除Bucket

请求方式：DELETE

请求URL：{base_url}/storage-admin/buckets/{bucket}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": null
}

返回字段说明：无（空响应）

11.5 扩容Bucket

功能说明：扩容Bucket

请求方式：POST

请求URL：{base_url}/storage-admin/buckets/{bucket}/expand

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
additional_gb	是	int	扩容大小（GB），最小1

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/expand" \
  -H "Content-Type: application/json" \
  -d '{"additional_gb": 10}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "additional_gb": 10,
    "quota_bytes": 21474836480
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
additional_gb	int	本次扩容量（GB）
quota_bytes	uint64	扩容后总配额（字节）

11.6 格式化Bucket

功能说明：格式化Bucket

请求方式：POST

请求URL：{base_url}/storage-admin/buckets/{bucket}/format

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称，⚠️ 会清空所有数据

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/format"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": null
}

返回字段说明：无（空响应）

11.7 更新访问密钥

功能说明：更新访问密钥

请求方式：PUT

请求URL：{base_url}/storage-admin/buckets/{bucket}/access-key

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
access_key	否	string	新密钥，留空自动生成

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/access-key" \
  -H "Content-Type: application/json" \
  -d '{"access_key": ""}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "access_key": "newkey789",
    "message": "更新成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
access_key	string	新的访问密钥
message	string	操作结果

11.8 更新访问模式

功能说明：更新访问模式

请求方式：PUT

请求URL：{base_url}/storage-admin/buckets/{bucket}/access-mode

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
access_mode	是	string	public / private

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/access-mode" \
  -H "Content-Type: application/json" \
  -d '{"access_mode": "private"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "access_mode": "private",
    "message": "更新成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
access_mode	string	更新后访问模式
message	string	操作结果

11.9 获取Bucket使用量

功能说明：获取Bucket使用量

请求方式：GET

请求URL：{base_url}/storage-admin/buckets/{bucket}/usage

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/usage"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "quota_bytes": 10737418240,
    "used_bytes": 2474631168,
    "avail_bytes": 8262787072,
    "usage_percent": 23.05
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
quota_bytes	uint64	配额（字节）
used_bytes	uint64	已用（字节）
avail_bytes	uint64	可用（字节）
usage_percent	float64	使用率（%）

11.10 列举对象（管理员）

功能说明：列举对象（管理员）

请求方式：GET

请求URL：{base_url}/storage-admin/buckets/{bucket}/objects

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
prefix	否	string	前缀过滤
delimiter	否	string	分隔符
max_keys	否	int	最大返回数量，默认1000
marker	否	string	分页标记

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/objects?delimiter=/"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "objects": [
      {
        "key": "data/file.txt",
        "size": 1024,
        "last_modified": "2026-03-01 12:00:00"
      }
    ],
    "common_prefixes": ["data/images/"],
    "is_truncated": false
  }
}

返回字段说明：

字段	类型	说明
objects[].key	string	对象路径
objects[].size	int64	大小（字节）
objects[].last_modified	string	修改时间
common_prefixes	[]string	目录前缀列表
is_truncated	bool	是否还有更多

11.11 删除文件（管理员）

功能说明：删除文件（管理员）

请求方式：DELETE

请求URL：{base_url}/storage-admin/buckets/{bucket}/objects/{key}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
key	是	string	文件路径

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/objects/data/file.txt"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "key": "data/file.txt",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
key	string	删除的路径
message	string	操作结果

11.12 批量删除（管理员）

功能说明：批量删除（管理员）

请求方式：POST

请求URL：{base_url}/storage-admin/buckets/{bucket}/objects/batch-delete

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
keys	是	[]string	文件路径列表

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/objects/batch-delete" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["data/a.txt", "data/b.png"]}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 2,
    "success": 2,
    "failed": 0
  }
}

返回字段说明：

字段	类型	说明
total	int	提交删除总数
success	int	删除成功数
failed	int	删除失败数

11.13 获取树形目录（管理员）

功能说明：获取树形目录（管理员）

请求方式：GET

请求URL：{base_url}/storage-admin/buckets/{bucket}/tree

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
prefix	否	string	起始子路径

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/tree"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "tree": [
      {
        "name": "data",
        "path": "data/",
        "type": "dir",
        "children": [
          {
            "name": "file.txt",
            "path": "data/file.txt",
            "type": "file",
            "size": 1024
          }
        ]
      }
    ]
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
tree[].name	string	节点名称
tree[].path	string	完整路径
tree[].type	string	类型：file / dir
tree[].children	[]TreeNode	子节点

11.14 创建文件夹（管理员）

功能说明：创建文件夹（管理员）

请求方式：PUT

请求URL：{base_url}/storage-admin/buckets/{bucket}/folders/{path}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
path	是	string	文件夹路径

请求示例：

curl -X PUT "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/folders/data/images"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "path": "data/images/",
    "message": "创建成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
path	string	创建的路径
message	string	操作结果

11.15 删除文件夹（管理员）

功能说明：删除文件夹（管理员）

请求方式：DELETE

请求URL：{base_url}/storage-admin/buckets/{bucket}/folders/{path}

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
path	是	string	文件夹路径

请求示例：

curl -X DELETE "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/folders/data/images"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "path": "data/images/",
    "message": "删除成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
path	string	删除的路径
message	string	操作结果

11.16 移动文件或文件夹（管理员）

功能说明：移动文件或文件夹（管理员）

请求方式：POST

请求URL：{base_url}/storage-admin/buckets/{bucket}/move

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
src	是	string	源路径
dst	是	string	目标路径（不能已存在）

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/move" \
  -H "Content-Type: application/json" \
  -d '{"src": "old/file.txt", "dst": "new/file.txt"}'

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "bucket": "my-bucket",
    "src": "old/file.txt",
    "dst": "new/file.txt",
    "message": "移动成功"
  }
}

返回字段说明：

字段	类型	说明
bucket	string	Bucket名称
src	string	源路径
dst	string	目标路径
message	string	操作结果

11.17 卷组统计

功能说明：卷组统计

请求方式：GET

请求URL：{base_url}/storage-admin/stats/vg

请求参数：无

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/stats/vg"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "vg_name": "vg_storage",
    "total_bytes": 1099511627776,
    "free_bytes": 549755813888,
    "used_bytes": 549755813888,
    "lv_count": 10,
    "usage_percent": 50.0,
    "bucket_count": 8
  }
}

返回字段说明：

字段	类型	说明
vg_name	string	卷组名称
total_bytes	int64	总容量（字节）
free_bytes	int64	空闲容量（字节）
used_bytes	int64	已用容量（字节）
lv_count	int	逻辑卷数量
usage_percent	float64	使用率（%）
bucket_count	int	Bucket数量

11.18 健康检查（含CPU/内存/网络）

功能说明：健康检查（含CPU/内存/网络）

请求方式：GET

请求URL：{base_url}/storage-admin/health

请求参数：无

请求示例：

curl -X GET "https://www.opencecs.com/api/v1/storage-admin/health"

返回示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "status": "healthy",
    "message": "all systems operational",
    "storage": {
      "status": "healthy",
      "usage_percent": 45.2
    },
    "cpu": {
      "usage_percent": 12.5,
      "load_avg_1m": 0.8
    },
    "memory": {
      "usage_percent": 30.1
    },
    "network": {
      "tcp_established": 120
    }
  }
}

返回字段说明：

字段	类型	说明
status	string	总体健康状态：healthy / degraded / unhealthy
message	string	状态描述
storage.status	string	存储层状态
storage.usage_percent	float64	存储使用率（%）
cpu.usage_percent	float64	CPU使用率（%）
cpu.load_avg_1m	float64	1分钟平均负载
memory.usage_percent	float64	内存使用率（%）
network.tcp_established	int	TCP ESTABLISHED连接数

11.19 磁盘空间预检

功能说明：磁盘空间预检

请求方式：HEAD

请求URL：{base_url}/storage-admin/buckets/{bucket}/check

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
size	否	int	待上传文件字节数

请求示例：

curl -I "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/check?size=1048576"

成功返回：HTTP 200 表示空间充足，响应头包含可用空间信息。

响应头示例：

X-Available-Bytes: 10737418240
X-Available: true

11.20 批量下载ZIP（管理员）

功能说明：批量下载ZIP（管理员）

请求方式：POST

请求URL：{base_url}/storage-admin/buckets/{bucket}/objects/batch-download

请求参数：

参数名	必选	类型	说明
bucket	是	string	Bucket名称
keys	是	[]string	文件路径列表

请求示例：

curl -X POST "https://www.opencecs.com/api/v1/storage-admin/buckets/my-bucket/objects/batch-download" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["data/a.txt", "data/b.png"]}' \
  --output files.zip

成功返回：返回 ZIP 文件流，浏览器直接下载。

十二、METRICS 流量上报

12.1 宿主机Agent上报带宽流量

功能说明：宿主机Agent上报带宽流量

请求方式：POST

请求URL：{base_url}/metrics/report

请求参数：

参数名	必选	类型	说明
instance_id	是	string	CECS实例ID
private_ip	是	string	实例内网IP
mac	是	string	实例网卡MAC地址
rx_bytes	是	int64	自上次上报的接收字节增量
tx_bytes	是	int64	自上次上报的发送字节增量
timestamp	否	int64	Unix毫秒时间戳，不传则用服务器时间

请求示例：

curl -X POST "{base_url}/metrics/report" \
 -H "Authorization: Bearer {agent_api_key}" \
 -H "Content-Type: application/json" \
 -d '{
"instance_id": "CECS-XXXXXXXX",
"private_ip": "192.168.1.100",
"mac": "52:54:00:ab:cd:ef",
"rx_bytes": 1234567890,
"tx_bytes": 9876543210,
"timestamp": 1735689900000
}'

返回示例：

成功返回：

json
{
"code": 0,
"message": "上报成功",
"data": null
}

📌 接口说明（重要）​

📚 接口目录​

一、AUTH 认证​

1.1 发送短信验证码​

1.2 发送邮箱验证码​

1.3 用户注册​

1.4 手机号验证码登录​

1.5 邮箱密码登录​

1.6 账号密码登录​

1.7 验证身份（重置密码第一步）​

1.8 重置密码（第二步）​

二、USER 用户​

2.1 获取当前用户信息​

2.2 退出登录​

2.3 刷新 Token​

三、CECS 实例​

3.1 获取CECS产品列表​

3.2 获取CECS产品详情​

3.3 获取可用地域列表​

3.4 获取系统镜像列表​

3.5 获取CECS实例列表​

3.6 获取CECS实例详情​

3.7 启动CECS实例​

3.8 停止CECS实例​

3.9 重启CECS实例​

3.10 获取实例控制台URL​

3.11 删除CECS实例​

3.12 续费CECS实例​

3.13 获取可用节点列表​

3.14 切换系统镜像​

四、CECSDISK 磁盘管理​

4.1 磁盘列表（含统计）​

4.2 磁盘详情​

4.3 购买磁盘价格预估​

4.4 购买磁盘​

4.5 挂载磁盘到CECS实例​

4.6 从实例卸载磁盘​

4.7 扩容磁盘​

4.8 续费磁盘（仅包月）​

4.9 创建备份（功能开发中）​

4.10 格式化磁盘（清空数据，不可撤销）​

4.11 释放磁盘​

4.12 备份列表（功能开发中）​

4.13 删除备份（功能开发中）​

五、ORDER 订单​

5.1 计算订单价格​

5.2 创建订单​

5.3 获取订单列表​

5.4 获取订单详情​

5.5 支付订单​

5.6 取消订单​

六、FINANCE 财务​

6.1 获取费用概览​

6.2 统一账单列表​

6.3 即将到期资源列表​

6.4 发起充值​

6.5 申请开票​

七、PORTMAPPING 端口映射​

7.1 获取端口映射概览​

7.2 查询端口映射规则列表​

7.3 创建端口映射规则​

7.4 修改端口映射规则​

7.5 删除端口映射规则​

7.6 批量创建端口映射规则​

7.7 批量删除端口映射规则​

八、SHAREDSTORAGE 共享存储​

8.1 购买共享存储资源包​

8.2 查询共享存储资源包列表​

8.3 共享存储概览​

8.4 创建共享存储实例​

8.5 获取存储实例列表​

8.6 列举目录内容​

8.7 新建文件夹​

8.8 上传文件​

8.9 查看文件详情​

8.10 删除文件或文件夹​

8.11 重置访问密钥​

8.12 切换访问模式​

8.13 扩容存储实例​

8.14 格式化存储实例​

📌 接口说明（重要）

📚 接口目录

一、AUTH 认证

1.1 发送短信验证码

1.2 发送邮箱验证码

1.3 用户注册

1.4 手机号验证码登录

1.5 邮箱密码登录

1.6 账号密码登录

1.7 验证身份（重置密码第一步）

1.8 重置密码（第二步）

二、USER 用户

2.1 获取当前用户信息

2.2 退出登录

2.3 刷新 Token

三、CECS 实例

3.1 获取CECS产品列表

3.2 获取CECS产品详情

3.3 获取可用地域列表

3.4 获取系统镜像列表

3.5 获取CECS实例列表

3.6 获取CECS实例详情

3.7 启动CECS实例

3.8 停止CECS实例

3.9 重启CECS实例

3.10 获取实例控制台URL

3.11 删除CECS实例

3.12 续费CECS实例

3.13 获取可用节点列表

3.14 切换系统镜像

四、CECSDISK 磁盘管理

4.1 磁盘列表（含统计）

4.2 磁盘详情

4.3 购买磁盘价格预估

4.4 购买磁盘

4.5 挂载磁盘到CECS实例

4.6 从实例卸载磁盘

4.7 扩容磁盘

4.8 续费磁盘（仅包月）

4.9 创建备份（功能开发中）

4.10 格式化磁盘（清空数据，不可撤销）

4.11 释放磁盘

4.12 备份列表（功能开发中）

4.13 删除备份（功能开发中）

五、ORDER 订单

5.1 计算订单价格

5.2 创建订单

5.3 获取订单列表

5.4 获取订单详情

5.5 支付订单

5.6 取消订单

六、FINANCE 财务

6.1 获取费用概览

6.2 统一账单列表

6.3 即将到期资源列表

6.4 发起充值

6.5 申请开票

七、PORTMAPPING 端口映射

7.1 获取端口映射概览

7.2 查询端口映射规则列表

7.3 创建端口映射规则

7.4 修改端口映射规则

7.5 删除端口映射规则

7.6 批量创建端口映射规则

7.7 批量删除端口映射规则

八、SHAREDSTORAGE 共享存储

8.1 购买共享存储资源包

8.2 查询共享存储资源包列表

8.3 共享存储概览

8.4 创建共享存储实例

8.5 获取存储实例列表

8.6 列举目录内容

8.7 新建文件夹

8.8 上传文件

8.9 查看文件详情

8.10 删除文件或文件夹

8.11 重置访问密钥

8.12 切换访问模式

8.13 扩容存储实例

8.14 格式化存储实例