CLICD/docs/features/api.md

API 集成

CLICD 对外推荐使用 /api/v1 接口。旧版未带版本号的接口主要用于 Web 面板和兼容场景，新接入请优先使用 /api/v1。

认证

API Key 可在“API 集成”页面创建和管理。请求时支持两种写法：

curl -H "X-API-Key: YOUR_API_KEY" https://panel.example.com/api/v1/containers

curl -H "Authorization: Bearer YOUR_API_KEY" https://panel.example.com/api/v1/dashboard

Python 示例

import requests

BASE_URL = "https://panel.example.com"
API_KEY = "YOUR_API_KEY"

session = requests.Session()
session.headers.update({
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
})

resp = session.get(f"{BASE_URL}/api/v1/containers", timeout=15)
resp.raise_for_status()
containers = resp.json()

print(containers)

创建端口映射：

import requests

BASE_URL = "https://panel.example.com"
API_KEY = "YOUR_API_KEY"
CONTAINER_ID = "example-vm"

payload = {
    "name": "web",
    "protocol": "tcp",
    "host_port": 18080,
    "container_port": 80,
}

resp = requests.post(
    f"{BASE_URL}/api/v1/containers/{CONTAINER_ID}/port-mappings",
    headers={"X-API-Key": API_KEY},
    json=payload,
    timeout=15,
)
resp.raise_for_status()
print(resp.json())

返回结构示例

容器列表：

{
  "success": true,
  "data": [
    {
      "id": 5,
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "example-vm",
      "status": "running",
      "ip": "10.0.3.25",
      "ipv6": "2001:db8:100::1005",
      "cpu_limit": 2,
      "memory_limit": 2048,
      "disk_limit": 20480,
      "traffic_limit": 107374182400,
      "expires_at": "2026-12-31 23:59:59"
    }
  ]
}

任务队列：

{
  "success": true,
  "data": [
    {
      "id": "task-13",
      "type": "restart",
      "status": "running",
      "created_at": "2026-06-09T10:00:00+08:00"
    }
  ]
}

WebSSH 票据：

{
  "success": true,
  "data": {
    "ticket": "***60秒有效票据***"
  }
}

常用接口

方法	路径	说明
GET	/api/v1/dashboard	控制面板统计
GET	/api/v1/host-info	主机资源
GET	/api/v1/containers	容器列表
POST	/api/v1/containers	创建容器
POST	/api/v1/containers/{id}/start	开机
POST	/api/v1/containers/{id}/stop	关机
POST	/api/v1/containers/{id}/restart	重启
DELETE	/api/v1/containers/{id}/delete	删除
GET	/api/v1/tasks	任务队列
GET	/api/v1/templates	模板列表
GET	/api/v1/images	镜像管理列表
GET	/api/v1/snapshots	快照总览
GET	/api/v1/security/alerts	安全告警
GET	/api/v1/audit-logs	操作日志
GET	/api/v1/api-keys	API Key 列表

完整接口清单请以面板内“API 集成”页面为准。