计算资产模板管理 API

管理 Docker 镜像模板的 CRUD、镜像拉取和启用/禁用操作。

基础路径

/admin/assets-templates

认证方式

使用 combinedAuth + adminAudit 中间件。仅支持 JWT Bearer Token 认证，且需要 site:admin 权限。

Authorization: Bearer <jwt_token>

---

端点列表

GET /admin/assets-templates

获取所有模板列表（排除已软删除），按 sort_order 升序排列。

响应 200

{
  "templates": [
    {
      "id": "uuid",
      "slug": "ubuntu-terminal",
      "type": "docker",
      "label": "Ubuntu 终端",
      "label_en": "Ubuntu Terminal",
      "description": "...",
      "image": "ubuntu:22.04",
      "memory_mb": 512,
      "cpu_cores": 1,
      "protocol": "ssh",
      "port": 22,
      "enabled": true,
      "image_pull_status": "ready",
      "sort_order": 0
    }
  ]
}

---

POST /admin/assets-templates

创建新的镜像模板。

请求体

参数	类型	必填	说明
slug	string	是	唯一标识，小写字母、数字和连字符，长度 2-64
type	string	是	模板类型：docker / browser / desktop
label	string	是	中文显示名称
label_en	string	是	英文显示名称
image	string	是	Docker 镜像地址
protocol	string	是	连接协议：vnc / ssh（docker 仅支持 ssh，browser/desktop 仅支持 vnc）
description	string	否	中文描述
description_en	string	否	英文描述
memory_mb	number	否	内存限制 MB（64-16384），默认 512
cpu_cores	number	否	CPU 核心数（0.25-16），默认 1
port	number	否	连接端口（1-65535），默认 ssh=22 / vnc=5900
username	string	否	默认用户名
env	object	否	环境变量 Record<string, string>
sort_order	number	否	排序序号，默认 0

响应 201

{
  "template": { ... }
}

错误响应

状态码	说明
400	输入校验失败（slug 格式、type/protocol 组合不合法等）
409	slug 已存在

---

PUT /admin/assets-templates/:id

更新模板信息。所有字段均为可选，仅更新传入的字段。

Path 参数

参数	类型	说明
id	string	模板 ID

请求体

与创建接口相同的字段，均为可选。

特殊行为

• 镜像变更：当 image 字段变更时，自动重置 enabled=false、image_pull_status='none'，需重新拉取镜像后才能启用

错误响应

状态码	说明
400	没有需要更新的字段 / 输入校验失败 / type+protocol 组合不合法
404	模板不存在
409	slug 已存在

---

DELETE /admin/assets-templates/:id

软删除模板。

Path 参数

参数	类型	说明
id	string	模板 ID

前置检查

• 检查是否有未删除的 managed 资产引用该模板（直接引用 + 遗留默认映射）
• 有引用时返回 409 拒绝删除

响应 200

{
  "success": true
}

错误响应

状态码	说明
404	模板不存在
409	模板正在被资产引用，无法删除

---

POST /admin/assets-templates/:id/pull

触发 Docker 镜像拉取。

Path 参数

参数	类型	说明
id	string	模板 ID

响应 200

{
  "success": true,
  "message": "镜像拉取已启动"
}

错误响应

状态码	说明
409	拉取已在进行中或其他冲突

---

GET /admin/assets-templates/:id/pull-status

查询镜像拉取进度。

Path 参数

参数	类型	说明
id	string	模板 ID

响应 200

返回拉取状态对象，包含进度信息。

---

POST /admin/assets-templates/:id/toggle

切换模板的启用/禁用状态。

Path 参数

参数	类型	说明
id	string	模板 ID

前置检查

• 启用时要求 image_pull_status = 'ready'，镜像未就绪时返回 400

响应 200

{
  "success": true,
  "enabled": true
}

错误响应

状态码	说明
400	镜像未就绪，无法启用
404	模板不存在