#Cloud API 参考

大多数接口以 /api/cloud-saas 为前缀；Cloud App 暴露接口以 /api/cloud/exposures 为前缀。所有接口都需要 Bearer Token 认证。

#模版 (Templates)

#列出模版

返回已审核通过的模版（官方 + Space），按分类和评分排序。

#获取模版

返回单个模版完整内容。支持服务端国际化渲染。

#获取模版环境变量引用

返回模版标识、必需环境变量、表单字段和自动检测到的环境变量。

#我的模版

列出或获取当前用户的模版，包含待审核/已驳回的。

#创建模版

内容会经过模版策略白名单校验，提交后状态为 pending。

#更新模版

字段同创建（均可选）。仅作者在 draft 或 rejected 状态下可修改。

#重新提交审核

将 draft 或 rejected 模版重新提交审核。

#删除模版

删除自己的模版（不限审核状态）。

#部署 (Deployments)

#列出部署

每个命名空间返回最新的可见部署。

#获取部署成本

返回所有可见 SaaS 部署的聚合成本。

#创建部署

创建部署时进行计费校验、模版校验、命名空间加锁和钱包余额检查（余额不足返回 402）。部署异步排队执行。

#获取部署

返回部署详情，含当前状态、阻塞信息和成本汇总。

#获取单个部署成本

#取消部署

取消进行中的部署/销毁任务。不等待命名空间操作锁。

#删除部署

排队执行 Pulumi 销毁。中断进行中的操作。

#重新部署

同命名空间重新部署，生成新历史记录。不扣费。

#部署日志

GET /logs 返回 SSE 事件流 (text/event-stream)，实时推送 log、status、error、close 事件。部署到终态时自动终止。

GET /logs/history 返回 JSON 数组。

#Pod 信息

GET /pods 列出部署命名空间中 K8s Pod。GET /pod-logs 通过 SSE 流推送实时 Pod 日志。

#孤立命名空间管理

/claim 认领无数据库行的 Cloud 命名空间。/cleanup 强制删除孤立命名空间（仅管理员）。

#Cloud App 暴露

这些接口把 Cloud 部署里的运行时服务发布到 Shadow 管理的稳定 App 域名，并同步 Space App 安装、发布元数据和备份集。

#环境变量 (Environment Variables)

#部署级环境变量

值进行加密存储。GET 列表返回脱敏值 ('****')，按 Key 获取返回解密值供编辑。

#全局环境变量

#全局环境变量分组

#供应商配置与目录 (Provider Profiles & Catalogs)

#列出供应商目录

返回 Cloud 插件发现的模型供应商。每条包含插件 ID、供应商详情和必填密钥字段。

#列出供应商配置

返回当前用户的加密供应商配置。值已脱敏。

#增改供应商配置

校验配置中的模型列表并对 Base URL 做 SSRF 检查。

#测试供应商配置

用加密凭证测试供应商 API 连通性，8 秒超时，含 SSRF 防护。

#刷新模型列表

从供应商原生 API 获取模型列表并写入配置。

#删除供应商配置

删除配置及所有加密值。

#钱包 (Wallet)

#获取余额

返回当前用户虾豆余额。

{
  "balance": 5000,
  "currency": "shrimp_coin"
}

#交易记录

#活动日志 (Activity)

返回用户 Cloud 活动日志（分页），包含部署创建、暂停、恢复、备份、恢复、删除等事件。

#Schema 与校验

GET /schema 返回 CloudConfig JSON Schema，供前端校验和编辑器自动补全。

POST /validate 接收原始 JSON 配置快照，返回校验结果及错误信息。

#客户端方法

const templates = await client.listCloudTemplates({ q: 'web', locale: 'zh-CN' })
const template = await client.getCloudTemplate('web-app', { locale: 'zh-CN' })
const envRefs = await client.getCloudTemplateEnvRefs('web-app')

const deployments = await client.listCloudDeployments({ limit: 20 })
const deployment = await client.createCloudDeployment({
  namespace: 'my-app',
  name: 'My App',
  templateSlug: 'web-app',
  resourceTier: 'standard',
  configSnapshot: {},
})
await client.cancelCloudDeployment(deployment.id)
await client.pauseCloudDeployment(deployment.id)
await client.resumeCloudDeployment(deployment.id)

await client.publishCloudApp({ appKey: 'demo-desk', deploymentId: deployment.id, port: 4216 })
await client.getCloudAppStatus('demo-desk', { deploymentId: deployment.id })
await client.backupCloudApp('demo-desk', { deploymentId: deployment.id })
await client.unpublishCloudApp('demo-desk', { deploymentId: deployment.id, uninstall: true })

await client.upsertCloudProviderProfile({ providerId: 'openai', name: 'My Key', config: {} })

result = client.list_cloud_templates(q="web", locale="zh-CN")
template = client.get_cloud_template("web-app", locale="zh-CN")
env_refs = client.get_cloud_template_env_refs("web-app")

deployments = client.list_cloud_deployments(limit=20)
deployment = client.create_cloud_deployment(
    namespace="my-app",
    name="My App",
    template_slug="web-app",
    resource_tier="standard",
    config_snapshot={},
)
client.cancel_cloud_deployment(deployment["id"])
client.pause_cloud_deployment(deployment["id"])
client.resume_cloud_deployment(deployment["id"])

client.publish_cloud_app(app_key="demo-desk", deployment_id=deployment["id"], port=4216)
client.get_cloud_app_status("demo-desk", deployment_id=deployment["id"])
client.backup_cloud_app("demo-desk", deployment_id=deployment["id"])
client.unpublish_cloud_app("demo-desk", deployment_id=deployment["id"], uninstall=True)

client.upsert_cloud_provider_profile(provider_id="openai", name="My Key", config={})

#Next Steps

• Cloud SaaS 运行时 — 暂停/恢复/备份/恢复操作。
• Cloud CLI — 独立部署 CLI。
• 模版 — 模版目录与编写指南。
• 插件 — 插件生态。
• SDK — 完整客户端方法。