OpenCodeDocs

한국어

English
简体中文
繁體中文
日本語
Español
Français
Deutsch
Português
Русский

한국어

English
简体中文
繁體中文
日本語
Español
Français
Deutsch
Português
Русский

테마

계정 백업 및 마이그레이션: 가져오기/내보내기, 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 사용.
  • 기본 디렉토리를 구성하지 않은 경우, 시스템 저장 대화상자가 표시되어 경로 선택.

내보내기 파일 내용은 대략 다음과 같음 (배열의 각 항목은 필수 필드만 보유):

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 실행 중인 경우

每次 "계정 추가" 성공 후, 백엔드는 역방향 프록시 토큰 풀 리로드를 시도하여 새 계정이 즉시 적용되도록 함.

3단계: state.vscdb에서 "현재 로그인 계정" 가져오기 ​

이유 때로는 백업 파일을 유지하고 싶지 않고, "Antigravity/IDE의 로그인 상태를 기준으로" 하고 싶음. DB 가져오기는 이 시나리오를 위해 제공됨.

작업: Accounts 페이지로 이동하여 Add Account 클릭, Import 탭으로 전환:

  • "데이터베이스에서 가져오기" 클릭 (기본 DB 경로 사용)
  • 또는 "Custom DB (state.vscdb)" 클릭하여 *.vscdb 파일 수동 선택

기본 DB 경로는 플랫폼 간 (또한 --user-data-dir 또는 portable mode를 우선 인식):

text
~/Library/Application Support/Antigravity/User/globalStorage/state.vscdb
text
%APPDATA%\Antigravity\User\globalStorage/state.vscdb
text
~/.config/Antigravity/User/globalStorage/state.vscdb

예상 화면:

  • 가져오기 성공 후, 이 계정이 Manager의 "현재 계정"으로 자동 설정됨
  • 시스템이 자동으로 할당량 갱신 트리거

4단계: V1 데이터 디렉토리 마이그레이션 (구 버전 가져오기) ​

이유 이전에 V1/스크립트 버전을 사용했던 경우, Manager는 구 데이터 디렉토리를 직접 스캔하여 가져오기 시도를 허용.

작업: Import 탭에서 "V1 가져오기" 클릭.

home 디렉토리에서 다음 경로(및 그 안의 인덱스 파일)를 찾음:

text
~/.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.tsx458-578
Dashboard 계정 JSON 내보내기src/pages/Dashboard.tsx113-148
Import 탭: DB 가져오기 / Custom DB / V1 가져오기 버튼src/components/accounts/AddAccountDialog.tsx491-539
계정 추가: 프론트엔드 email 무시, refresh_token으로 실제 이메일 가져오기, 자동 할당량 갱신, Proxy 핫 리로드src-tauri/src/commands/mod.rs19-60
---------
DB 가져오기: state.vscdb에서 refresh_token 추출 (ItemTable + base64 + protobuf)src-tauri/src/modules/migration.rs192-267
---------
DB 가져오기 후 자동으로 "현재 계정"으로 설정 및 할당량 갱신src-tauri/src/commands/mod.rs495-511
auto_sync: refresh_token 비교, 같으면 바로 건너뜀; 변화 시 DB 가져오기 트리거src-tauri/src/commands/mod.rs532-564
프론트엔드 백그라운드 작업: sync_interval으로 주기적 syncAccountFromDb() 호출src/components/common/BackgroundTaskRunner.tsx43-72