# 管理计算实例

计算实例为 SQL、工作流和数据处理任务提供运行容量。本页说明如何选择规格、创建实例、观察运行状态，以及在确认依赖后暂停、启动或删除实例。

## 前提条件

- 已准备 Product API Base URL、个人访问令牌和工作区 ID。
- 当前身份具有计算实例的读取或管理权限。
- 已了解将要运行的任务类型和容量需求。

计算规格由平台统一提供。普通开发者应从规格列表选择 `spec_id`，不应自行创建或修改规格。

## 计算实例生命周期

```text
读取可用规格和 Worker 镜像
→ 创建计算实例并保存 resource_id
→ 查询详情、运行时或指标
→ 按需暂停、恢复或重试
→ 删除预检
→ 删除计算实例
```

创建、暂停、启动、重试和删除可能需要后台完成。HTTP 请求成功表示操作已经受理，不表示计算实例已经达到目标状态；继续读取实例详情中的 `status` 和 `status_message`。

## 相关接口

| 方法与路径 | 用途 |
| --- | --- |
| `GET /compute-resource-specs` | 列出当前工作区可选择的计算规格。 |
| `GET /compute-resources/worker-images` | 列出可选 Worker 镜像。 |
| `POST /compute-resources` | 创建计算实例。 |
| `GET /compute-resources` | 列出计算实例。 |
| `GET /compute-resources/{resource_id}` | 读取实例详情和状态。 |
| `PUT /compute-resources/{resource_id}` | 更新实例配置。 |
| `GET /compute-resources/{resource_id}/runtime` | 读取各 Worker 的运行时状态。 |
| `GET /compute-resources/{resource_id}/metrics` | 读取实例用量指标。 |
| `POST /compute-resources/{resource_id}/suspend` | 暂停实例。 |
| `POST /compute-resources/{resource_id}/resume` | 启动实例。 |
| `POST /compute-resources/{resource_id}/retry` | 重试失败的生命周期操作。 |
| `GET /compute-resources/{resource_id}/preflight-delete` | 检查删除依赖。 |
| `DELETE /compute-resources/{resource_id}` | 删除实例。 |

## 选择规格

先读取当前可用的规格：

```bash
curl "$PRODUCT_API_BASE_URL/compute-resource-specs" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

从响应中选择已启用并满足任务需求的规格，保存其 `id`。规格可能包含 `kind`、CPU、内存、GPU 和每小时 Credit 等信息；可选值以本次响应为准。

如果需要指定 Worker 镜像，再读取镜像列表：

```bash
curl "$PRODUCT_API_BASE_URL/compute-resources/worker-images" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

不要把镜像地址直接写入创建请求。需要自定义镜像时，使用列表返回的镜像 ID、Worker 类型和平台信息。

## 创建计算实例

下面的请求创建一个最小计算实例。`cpu` 和 `memory_gib` 应与所选规格的容量保持一致：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/compute-resources" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-processing",
    "description": "用于数据处理任务",
    "spec_id": "<SPEC_ID>",
    "cpu": 2,
    "memory_gib": 4,
    "min_replicas": 1,
    "max_replicas": 2
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 工作区内便于识别的实例名称。 |
| `spec_id` | string | 是 | 从规格列表取得的规格 ID。实例类型和标准容量以该规格为准。 |
| `cpu` | integer | 是 | CPU 数量。使用所选规格对应的值。 |
| `memory_gib` | integer | 是 | 内存容量，单位为 GiB。使用所选规格对应的值。 |
| `description` | string | 否 | 实例用途说明。 |
| `min_replicas` | integer | 否 | 最小副本数。不得大于 `max_replicas`。 |
| `max_replicas` | integer | 否 | 最大副本数。 |
| `auto_suspend_minutes` | integer | 否 | 无活动后自动暂停的等待时间。 |
| `worker_images` | object[] | 否 | Worker 镜像选择。使用镜像列表返回的标识和类型。 |

成功响应返回计算实例对象：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<RESOURCE_ID>",
    "workspace_id": "<WORKSPACE_ID>",
    "name": "data-processing",
    "spec_id": "<SPEC_ID>",
    "status": "DEPLOYING",
    "status_message": "",
    "current_replicas": 0,
    "desired_replicas": 1
  }
}
```

保存 `data.id`。随后读取 `GET /compute-resources/{resource_id}`，而不是根据创建请求耗时推断实例是否可用。

## 读取运行状态和指标

实例详情给出整体状态；运行时接口进一步按 Worker 类型返回目标副本数、当前副本数和运行状态：

```bash
curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/runtime" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

指标接口返回计算实例 ID、累计 Credit 和分类明细：

```bash
curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/metrics" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

`breakdown` 的维度可能随实例类型不同而变化。读取前应允许未知字段，不要依赖固定的明细键集合。

## 暂停、启动和重试

以下操作不需要请求体：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/suspend" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

将路径末尾改为 `resume` 可启动实例；只有实例处于可重试的失败状态时才使用 `retry`。每次操作后重新读取详情，直到 `status` 达到预期状态或进入失败终态。

暂停会影响依赖该计算实例的新任务和正在运行的任务。操作前先确认关联工作负载，并让调用方能够处理实例启动带来的等待时间。

## 删除前检查依赖

删除前先调用预检：

```bash
curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/preflight-delete" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "active_tasks": 1,
    "active_task_ids": ["<TASK_ID>"],
    "bound_workflows": 1,
    "bound_workflow_details": []
  }
}
```

当 `active_tasks` 或 `bound_workflows` 大于 `0` 时，先停止任务或把工作流迁移到其他计算实例。依赖处理完成后重新预检，再发送删除请求。删除不可恢复，也可能被默认计算实例或权限规则阻止。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 创建请求被拒绝 | `spec_id` 是否存在并启用，CPU 和内存是否匹配规格 | 重新读取规格，不沿用其他环境保存的 ID。 |
| 长时间处于部署中或扩缩容中 | `status_message`、运行时副本和 Worker 镜像 | 保留计算实例 ID，查询详情；不要重复创建同名实例。 |
| 暂停后任务调用变慢 | 实例是否正在启动 | 延长调用等待时间，并在实例可用后再判断任务是否失败。 |
| 无法删除 | 删除预检、默认计算实例限制和权限 | 先解除任务及工作流依赖，再重新预检。 |
| 指标明细为空 | 实例是否刚创建或尚未产生工作负载 | 结合实例状态和任务记录判断，不把空明细直接当作接口失败。 |

## 下一步

- [运行 SQL 并读取结果](sql/execute-results.md)
- [运行并查询工作流](workflows-workitems-lineage/run-query-cancel.md)
- [查看状态码和错误码](../common/status-error-codes.md)