从云端备份恢复

下载云备份并始终创建新的本地环境，不会覆盖已有环境，也不会自动启动恢复出的环境。新环境保留 cloudId 和提供方关联，但自动云同步默认关闭：HTTP 恢复在内部传入 enableCloudSync: false，响应返回 enabled: false。

这是 API 专用的安全标记，不是请求参数，不改变客户端现有共享 UI 恢复行为。用户核对恢复出的数据及密码后，可在客户端显式启用云同步。

请求

POST /api/restoreCloudBackup
api-key: REPLACE_WITH_LOCAL_API_KEY
Content-Type: application/json

需保持客户端运行，登录有效 VIP（专业版）会员，并具备 local_api 和云同步权限。从客户端 API 页面复制实际本地服务地址和 API key，不要使用浏览器 CDP 端口。参见概述与鉴权。

JSON 请求体

参数	类型	必填	说明
cloudId	string	是	ASCII 标识，须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$，长度 1～128。使用云备份列表中的 ID，不是本地环境 ID。
provider	string	否	仅接受 oss 或 webdav；默认使用客户端全局云同步提供方。
name	string	否	新本地环境名称。使用前去除首尾空白，处理后长度须为 1～200；禁止控制字符 U+0000～U+001F 及 U+007F。省略则使用备份中的名称，备份无名称时自动生成。
password	string	否	独立保存账号密码信封的同步加密密码，长度 1～1024；不是 WebDAV 认证密码，也不是 API key。

请求体必须是只包含上述字段的 JSON 对象。未知属性（包括 id、webdav、endpoint、username、enableCloudSync、enabled）返回 HTTP 400；不支持指定目标本地 ID、覆盖选项或自动同步开关。

WebDAV 仅使用客户端已保存的服务器、账号和基础目录。请先在客户端配置，不能通过此 API 参数传入 WebDAV 地址、用户名或认证密码。

cURL

运行前替换基础地址、API key 及可选同步密码的占位符。UUID 和环境名称均为虚构值。如需使用客户端本地保存的同步密码，可省略 password。

BASE_URL='http://127.0.0.1:REPLACE_WITH_API_PORT'
API_KEY='REPLACE_WITH_LOCAL_API_KEY'
curl --request POST "${BASE_URL}/api/restoreCloudBackup" \
  --header "api-key: ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"cloudId":"8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034","provider":"oss","name":"EXAMPLE_RESTORED_PROFILE","password":"REPLACE_WITH_SYNC_ENCRYPTION_PASSWORD"}'

Python

此示例不传 password，只发起一次请求，不自动重试。

import requests

base_url = "http://127.0.0.1:REPLACE_WITH_API_PORT"
response = requests.post(
    f"{base_url}/api/restoreCloudBackup",
    headers={"api-key": "REPLACE_WITH_LOCAL_API_KEY"},
    json={
        "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
        "provider": "oss",
        "name": "EXAMPLE_RESTORED_PROFILE",
    },
    timeout=120,
)
result = response.json()
if response.status_code == 409 and result.get("code") == "CLOUD_RESTORE_COMMITTED":
    print("Restore committed; inspect local profile before retrying:", result["data"]["id"])
else:
    response.raise_for_status()
    print(result)

成功响应

HTTP 200。本例表示主环境已恢复且自动云同步关闭，但因没有可用同步密码，未还原单独保存的账号密码。

{
  "success": true,
  "data": {
    "id": 86,
    "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
    "provider": "oss",
    "enabled": false,
    "loginsRestore": {
      "restored": false,
      "reason": "NO_PASSWORD"
    }
  }
}

字段	类型	说明
success	boolean	主环境恢复成功。
data.id	integer	新分配的正整数本地环境 ID，不是 cloudId 或已有目标 ID。
data.cloudId	string	新环境绑定的云备份 ID。
data.provider	string	实际使用的 oss 或 webdav 提供方。
data.enabled	boolean	恢复时固定为 false：新环境自动云同步关闭，但保留云端关联。
data.loginsRestore.restored	boolean	是否成功还原独立保存的账号密码。
data.loginsRestore.count	integer，可选	返回时为非负整数，表示还原的账号数量。
data.loginsRestore.reason	string，可选	restored 为 false 时的原因，不是顶层 API 错误码。

账号密码还原成功时可返回 "loginsRestore": {"restored": true, "count": 2}。这个独立步骤失败或跳过，不会使已经恢复的主环境失效，仍可返回 success: true。

如果主环境提交后，后续账号/会话步骤被中断，则改为返回 HTTP 409、CLOUD_RESTORE_COMMITTED 及已提交的本地 ID，详见下文；这个错误响应不表示本地环境已回滚。

账号密码还原原因

显式传入的 password 优先，否则尝试客户端本地保存的同步密码。当账号密码信封需要解密、但两者都不可用时，此非交互式 HTTP 流程返回 NO_PASSWORD，不会弹出密码输入框。

reason	说明
NO_PASSWORD	未传同步密码，且本地也未保存可用同步密码。
NOT_FOUND	未找到账号密码信封；不表示主备份缺失，也不是 HTTP 404。
DOWNLOAD_FAILED	账号密码信封下载失败。
EMPTY	账号密码信封没有可还原的账号。
SKIPPED	跳过账号密码还原。
SYNC_PASSWORD_INVALID	同步密码校验或信封解密失败。
SYNC_PASSWORD_REQUIRED	需要同步密码；此非交互式接口缺少密码时通常返回 NO_PASSWORD。
FAILED	其他账号密码还原失败。

不要自动重试

同一 cloudId 每次成功 POST 都会再创建一个本地环境。超时或响应丢失不代表没有创建环境。不要自动重试：先检查本地环境列表，并在可用时查看云备份列表的 localIds，确认结果后再决定是否重新恢复。

收到 CLOUD_RESTORE_COMMITTED 时，优先检查返回的 data.id，不要仅因 success 为 false 就再次提交恢复。

错误响应

新接口自身产生的错误结构如下：

{
  "success": false,
  "code": "CLOUD_BACKUP_NOT_FOUND",
  "error": "Cloud backup not found"
}

HTTP	code	说明
400	INVALID_PARAMETERS	JSON 请求体字段、标识、名称或密码无效，或包含未知属性。
400	INVALID_PROVIDER	提供方不是严格的 oss 或 webdav。
400	WEBDAV_CONFIG_REQUIRED	客户端保存的 WebDAV 配置缺失或无效。
401	AUTH_REQUIRED / LOGIN_REQUIRED	需要登录客户端。缺失或无效的 API key 也会由全局中间件返回 401。
403	VIP_REQUIRED	云同步 VIP 权限缺失或过期。缺少 local_api 授权也会由全局中间件返回 403。
404	CLOUD_BACKUP_NOT_FOUND	主云备份不存在。
409	CLOUD_SESSION_CHANGED	主环境提交前切换了账号，不返回新的本地 ID。
409	CLOUD_RESTORE_COMMITTED	主本地环境已提交，但后续账号/会话步骤被中断；先检查 data.id，不要盲目重试。
500	CLOUD_BACKUP_RESTORE_FAILED	主备份恢复失败；按现有服务行为，普通 OSS 初始化失败也可能以此返回。
502	WEBDAV_AUTH_FAILED	已保存的 WebDAV 凭据认证失败，请修改客户端配置。
503	CLOUD_SYNC_UNAVAILABLE	客户端云同步模块不可用。
504	REQUEST_TIMEOUT	检测到的云传输超时；重试前先检查本地环境。

504 适用于检测到的云传输超时，不表示所有远端初始化失败都会归类为超时；按现有服务行为，普通 OSS 初始化失败仍可能返回 500。

主环境已提交（HTTP 409）

CLOUD_RESTORE_COMMITTED 表示主本地环境已经存在，即使整体响应为 success: false；中断发生在后续账号/会话步骤。以下为结构示例，error 文案以实际返回为准：

{
  "success": false,
  "code": "CLOUD_RESTORE_COMMITTED",
  "error": "Restore committed; inspect the local profile before retrying",
  "data": {
    "id": 86,
    "committed": true,
    "enabled": false
  }
}

字段	类型	说明
data.id	integer	已提交环境的正整数本地 ID，应优先检查这个环境。
data.committed	boolean	true 表示主本地环境已提交，并未回滚。
data.enabled	boolean	false 表示自动云同步仍关闭。

先核对该本地环境的数据及密码，再显式启用同步；不要盲目重试 POST。与此不同，普通 CLOUD_SESSION_CHANGED 仅在提交前返回，不包含新的本地 ID。

现有全局鉴权中间件可能返回 success: false 和 error，但没有 code。请同时检查 HTTP 状态与响应体，参见错误码与响应兼容。