#Cloud SaaS 部署运行时

Cloud SaaS 部署通过 deployment API 命名空间提供运行时生命周期操作：暂停空闲的 Agent、按需恢复、创建和查看状态备份，以及从备份还原。

所有端点都在 /api/cloud-saas/deployments/:id 下。

#模板 Manifest

GET /manifest 返回部署关联的模板、manifest 版本、配置哈希和漂移状态（up-to-date、template-updated、missing-template、unlinked 或 unknown）。普通 deployment 列表仍保持脱敏；Dashboard 或 CLI 需要解释运行中部署来源时，应使用这个端点。

POST /template 会把已部署的配置快照保存为可编辑模板。用户拥有的 draft/rejected 社区模板会原地更新；官方、已发布或审核中的模板会自动 fork。

POST /redeploy 继续支持空 body，行为仍是按已部署快照重新部署。也可以传入：

const manifest = await client.getCloudDeploymentManifest('deployment-id')
await client.syncCloudDeploymentTemplate('deployment-id')
await client.redeployCloudDeployment('deployment-id', { mode: 'template' })

manifest = client.get_cloud_deployment_manifest("deployment-id")
client.sync_cloud_deployment_template("deployment-id")
client.redeploy_cloud_deployment("deployment-id", mode="template")

#暂停部署

通过将 Sandbox 副本缩为 0 来暂停运行中的 agent-sandbox 工作负载。PVC 会保留，用于稍后恢复或还原。只有命名空间内的当前部署可以被暂停。

响应 (200)：

{
  "ok": true,
  "status": "paused",
  "deployment": {}
}

const result = await client.pauseCloudDeployment('deployment-id', { agentId: 'strategy-buddy' })
console.log(result.status) // 'paused'

result = client.pause_cloud_deployment("deployment-id", agent_id="strategy-buddy")
print(result["status"])  # 'paused'

可能的错误：404 找不到部署，409 不能暂停历史部署实例，422 状态不支持。

#恢复部署

通过将 Sandbox 副本恢复为 1 来恢复已暂停的 agent-sandbox 工作负载。Agent 将从 PVC 上保存的状态中恢复运行。

响应 (200)：

{
  "ok": true,
  "status": "deployed",
  "deployment": {}
}

const result = await client.resumeCloudDeployment('deployment-id', { agentId: 'strategy-buddy' })
console.log(result.status) // 'deployed'

result = client.resume_cloud_deployment("deployment-id", agent_id="strategy-buddy")
print(result["status"])  # 'deployed'

可能的错误：404 找不到部署，409 不能恢复历史部署实例，422 状态不支持，502 恢复失败。

#列出备份

返回部署的所有备份记录，包含 status 和 phase 字段，可用于跟踪快照创建、对象归档上传、PVC 恢复和 Sandbox 恢复等阶段。

响应：

{
  "deploymentId": "uuid",
  "backups": [
    {
      "id": "backup-id",
      "deploymentId": "uuid",
      "namespace": "gstack-buddy",
      "agentId": "strategy-buddy",
      "sandboxName": "strategy-buddy",
      "pvcName": "openclaw-data-strategy-buddy",
      "driver": "volumeSnapshot",
      "snapshotName": "gstack-buddy-strategy-buddy-2025-01-01T00-00-00Z",
      "objectKey": null,
      "status": "succeeded",
      "phase": "completed",
      "error": null,
      "expiresAt": null,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:01:00.000Z"
    }
  ]
}

const { backups } = await client.listCloudDeploymentBackups('deployment-id')
const { backups } = await client.listCloudDeploymentBackups('deployment-id', { agentId: 'strategy-buddy' })

result = client.list_cloud_deployment_backups("deployment-id")
result = client.list_cloud_deployment_backups("deployment-id", agent_id="strategy-buddy")
backups = result["backups"]

#创建备份

为部署创建状态备份。当集群支持 CSI VolumeSnapshot 且目标 PVC 由 CSI StorageClass 支撑且有匹配的 VolumeSnapshotClass 时，API 会创建 VolumeSnapshot。否则会回退到对象归档（基于 Pod 的 tar.gz，可选加密）。

备份异步运行。响应返回 202 及备份记录。通过备份的 phase 字段跟踪进度：queued → snapshot-creating 或 object-archiving → completed。

响应 (202)：

{
  "ok": true,
  "backup": {
    "id": "backup-id",
    "status": "running",
    "phase": "queued"
  }
}

// VolumeSnapshot 备份
const { backup } = await client.createCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  driver: 'volumeSnapshot',
  retentionDays: 30,
})

// 对象归档备份（加密可选）
const objectBackup = await client.createCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  driver: 'restic',
})

# VolumeSnapshot 备份
result = client.create_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    driver="volumeSnapshot",
    retention_days=30,
)
backup = result["backup"]

# 对象归档备份（加密可选）
object_result = client.create_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    driver="restic",
)

可能的错误：404 找不到部署，409 该命名空间已有其他操作正在运行，422 状态不支持或 VolumeSnapshot 不可用。

#从备份还原

从备份还原部署状态。还原流程：

1. 暂停 agent-sandbox（如正在运行）。
2. 从 VolumeSnapshot 或对象归档中还原状态 PVC。
3. 恢复 agent-sandbox 工作负载。

操作异步运行并返回 202。通过备份的 phase 字段跟踪进度：restoring-pausing → restoring-pvc → restoring-resuming → completed。

响应 (202)：

{
  "ok": true,
  "backup": {},
  "status": "resuming",
  "deployment": {}
}

const result = await client.restoreCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  backupId: 'backup-id',
})
console.log(result.status) // 'resuming'

result = client.restore_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    backup_id="backup-id",
)
print(result["status"])  # 'resuming'

可能的错误：404 找不到部署或备份，409 该命名空间已有其他操作正在运行，422 状态不支持或备份驱动不可用。

#自动恢复触发器

已暂停的 Cloud 部署在平台检测到活动时会自动恢复：

App 代理自动恢复是同步的（最多等待 25 秒）。消息提及和 Agent 心跳的自动恢复是触发即忘的。

#部署状态生命周期

部署经历以下状态流转：

resuming 是 paused 和 deployed 之间的瞬态。failed 状态如果原因是 cancelled by user 或 superseded-by-newer-deployment，则不会对用户展示。

#下一步

• Cloud 概览 了解完整的部署模型。
• Cloud CLI 了解 sandbox 命令组。
• SDK 了解客户端方法。