從雲端備份還原

下載雲端備份並一律建立新的本機環境，不會覆寫既有環境，也不會自動啟動還原出的環境。新環境保留 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 狀態及回應內容，參見錯誤碼與回應相容。