帳號備份與遷移：匯入/匯出、V1/DB 熱遷移

你真正想「備份」的，其實不是配額數字，而是能讓帳號重新登入的 refresh_token。這節課把 Antigravity Tools 的幾種遷移手段講清楚：匯入/匯出 JSON、從 state.vscdb 匯入、從 V1 資料目錄匯入，以及自動同步的工作方式。

學完你能做什麼

• 把帳號池匯出成一個 JSON 檔案（只包含 email + refresh_token）
• 在新機器上匯入這個 JSON，快速恢復帳號池
• 直接從 Antigravity/IDE 的 state.vscdb 匯入「目前登入帳號」（支援預設路徑與自訂路徑）
• 從 V1 資料目錄自動掃描並匯入舊帳號
• 了解「自動同步目前帳號」到底會做什麼、什麼時候會跳過

你現在的困境

• 重裝系統/換電腦後，帳號池要重新加一遍，成本很高
• 你在 Antigravity/IDE 裡換了登入帳號，但 Manager 裡的「目前帳號」沒跟著變
• 你以前用過 V1/腳本版，手裡只有舊資料檔案，不知道能不能直接遷移

什麼時候用這一招

• 你要把帳號池搬到另一台機器（桌面端/伺服器/容器）
• 你把 Antigravity 作為「權威登入入口」，希望 Manager 自動同步目前帳號
• 你要從舊版本（V1 資料目錄）把帳號遷過來

🎒 開始前的準備

• 你已經能開啟 Antigravity Tools，並至少有一個帳號在帳號池裡
• 你知道帳號資料屬於敏感資訊（尤其是 refresh_token）

安全提醒：把備份檔案當作密碼

匯出的 JSON 檔案包含 refresh_token。任何拿到它的人，都可能用它去刷新 access token。不要把備份檔案上傳到網路硬碟公開連結、不要發群組、不要提交到 Git。

核心思路

Antigravity Tools 的「遷移」本質上就兩件事：

1. 找到可用的 refresh_token
2. 用它換取 access token，並向 Google 取得真實信箱，然後把帳號寫進本機帳號池

它提供了三個入口：

• JSON 匯入/匯出：適合你明確要做「可控備份」
• DB 匯入：適合你把 Antigravity/IDE 的登入狀態當作權威來源（預設找 state.vscdb，也支援手選檔案）
• V1 匯入：適合從舊資料目錄自動掃描並遷移

另外還有一條「自動同步」：它會週期性讀取 DB 裡的 refresh_token，如果與 Manager 目前帳號不同，就自動執行一次 DB 匯入；如果相同就直接跳過（節省流量）。

跟我做

第 1 步：匯出帳號池（JSON 備份）

為什麼 這是最穩定、最可控的遷移方式。你拿到一個檔案，就能在另一台機器恢復帳號池。

操作：進入 Accounts 頁面，點擊匯出按鈕。

• 如果你在設定裡設定了 default_export_path，匯出會直接寫入該目錄，並使用檔名 antigravity_accounts_YYYY-MM-DD.json。
• 如果沒設定預設目錄，會彈出系統儲存對話方塊讓你選擇路徑。

匯出檔案內容大致長這樣（陣列裡每項只保留必要欄位）：

[
  {
    "email": "alice@example.com",
    "refresh_token": "1//xxxxxxxxxxxxxxxxxxxxxxxx"
  },
  {
    "email": "bob@example.com",
    "refresh_token": "1//yyyyyyyyyyyyyyyyyyyyyyyy"
  }
]

你應該看到：頁面提示匯出成功，並顯示儲存路徑。

第 2 步：在新機器匯入 JSON（恢復帳號池）

為什麼 匯入會逐個呼叫「新增帳號」邏輯，用 refresh_token 拉取真實信箱並寫入帳號池。

操作：還是在 Accounts 頁面，點擊「匯入 JSON」，選擇你剛匯出的檔案。

格式要求如下（至少需包含 1 條有效記錄）：

• 必須是 JSON 陣列
• 系統只會匯入包含 refresh_token 且以 1// 開頭的條目

你應該看到：匯入結束後，帳號列表裡出現匯入的帳號。

如果你匯入時 Proxy 正在執行

每次「新增帳號」成功後，後端會嘗試 reload 反代的 token pool，讓新帳號立刻生效。

第 3 步：從 state.vscdb 匯入「目前登入帳號」

為什麼 有時候你不想維護備份檔案，只想「以 Antigravity/IDE 的登入狀態為準」。DB 匯入就是為這個場景準備的。

操作：進入 Accounts 頁面，點擊 Add Account，切到 Import 標籤頁：

• 點「從資料庫匯入」（使用預設 DB 路徑）
• 或點「Custom DB (state.vscdb)」手動選擇一個 *.vscdb 檔案

預設 DB 路徑是跨平台的（也會優先識別 --user-data-dir 或 portable mode）：

macOS

~/Library/Application Support/Antigravity/User/globalStorage/state.vscdb

Windows

%APPDATA%\Antigravity\User\globalStorage\state.vscdb

Linux

~/.config/Antigravity/User/globalStorage/state.vscdb

你應該看到：

• 匯入成功後，這個帳號會被自動設為 Manager 的「目前帳號」
• 系統會自動觸發一次配額刷新

第 4 步：從 V1 資料目錄遷移（舊版本匯入）

為什麼 如果你以前用過 V1/腳本版，Manager 允許你直接掃描舊資料目錄並嘗試匯入。

操作：在 Import 標籤頁，點擊「匯入 V1」。

它會去你的 home 目錄下找這個路徑（以及其中的索引檔案）：

~/.antigravity-agent/
  - antigravity_accounts.json
  - accounts.json

你應該看到：匯入完成後，帳號出現在列表裡；如果沒找到索引檔案，後端會傳回錯誤 V1 account data file not found。

第 5 步（可選）：開啟「自動同步目前帳號」

為什麼 當你在 Antigravity/IDE 裡切換登入帳號時，Manager 可以按固定間隔偵測 DB 中的 refresh_token 是否變化，並在變化時自動匯入。

操作：進入 Settings，開啟 auto_sync，並設定 sync_interval（單位：秒）。

你應該看到：開啟後會立即執行一次同步；之後按間隔週期性執行。如果 DB 裡的 refresh_token 與目前帳號相同，會直接跳過，不會重複匯入。

檢查點 ✅

• 你能在 Accounts 列表中看到匯入的帳號
• 你能看見「目前帳號」已經切換到你期望的那一個（DB 匯入會自動設為目前）
• 你把 Proxy 啟動後，新匯入的帳號能被正常用於請求（以實際呼叫結果為準）

踩坑提醒

場景	你可能會怎麼做（❌）	推薦做法（✓）
備份檔案安全	把匯出的 JSON 當普通設定檔隨手發出去	把 JSON 當密碼，最小化傳播範圍，避免公網暴露
JSON 匯入失敗	JSON 不是陣列，或 refresh_token 沒有 1// 前綴	用本專案匯出的 JSON 作為範本，保持欄位名與結構一致
DB 匯入找不到資料	Antigravity 沒有登入過，或 DB 裡缺少 jetskiStateSync.agentManagerInitState	先確認 Antigravity/IDE 已登入，再嘗試匯入；必要時用 Custom DB 選對檔案
V1 匯入後帳號不可用	舊 refresh_token 失效	刪除該帳號後用 OAuth/新 refresh_token 重新新增（以錯誤提示為準）
auto_sync 太頻繁	sync_interval 設得很小，頻繁掃描 DB	把它當作「狀態跟隨」，間隔設到你能接受的頻率即可

本課小結

• JSON 匯出/匯入是最可控的遷移方式：備份檔案裡只保留 email + refresh_token
• DB 匯入適合「以 Antigravity/IDE 目前登入帳號為準」，並會自動設為 Manager 目前帳號
• V1 匯入會掃描 ~/.antigravity-agent 並相容多種舊格式
• auto_sync 會比較 refresh_token；相同則跳過，不會重複匯入

下一課預告

下一課我們把「遷移後的帳號池」真正用起來：啟動本機反代並接入第一個客戶端（/healthz + SDK 設定）。

你會學到：

• 怎麼啟動/停止 Proxy，並用 /healthz 做最小驗證
• 怎麼在 SDK/客戶端裡設定 Base URL

---

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-23

功能	檔案路徑	行號
Accounts 匯出/匯入 JSON（save_text_file / read_text_file）	src/pages/Accounts.tsx	458-578
Dashboard 匯出帳號 JSON	src/pages/Dashboard.tsx	113-148
Import 標籤頁：DB 匯入 / Custom DB / V1 匯入按鈕	src/components/accounts/AddAccountDialog.tsx	491-539
新增帳號：忽略前端 email、用 refresh_token 取得真實信箱、自動刷新配額、Proxy 熱 reload	src-tauri/src/commands/mod.rs	19-60
---	---	---
DB 匯入：從 state.vscdb 提取 refresh_token（ItemTable + base64 + protobuf）	src-tauri/src/modules/migration.rs	192-267
---	---	---
DB 匯入後自動設為「目前帳號」並刷新配額	src-tauri/src/commands/mod.rs	495-511
auto_sync：比較 refresh_token，相同直接跳過；變化則觸發 DB 匯入	src-tauri/src/commands/mod.rs	532-564
前端背景工作：按 sync_interval 週期性呼叫 syncAccountFromDb()	src/components/common/BackgroundTaskRunner.tsx	43-72