백업 · 이전 (Export / Import)

다른 컴퓨터로 Blyck을 옮길 때(예: Windows 노트북 → macOS Mac mini) userData 폴더를 수동 복사하면 채팅이 옛 PC의 절대경로를 가리키고, 시크릿은 OS 키체인에 묶여 풀리지 않고, OS 종속 바이너리는 안 돕니다.

백업 · 이전은 버튼 한 번으로 짐을 싸고(export) 풀며(import), 풀 때 경로를 자동 변환해 채팅 이력을 그대로 이어갑니다. Win↔Mac 4방향 모두 동작합니다.

왜 수동 복사가 깨지나

문제	내용
절대경로 불일치	채팅이 `D:\develope\…`를 가리키는데 새 PC는 `/Users/…`
OS 종속 시크릿	DB/SSH 비번·GitHub 토큰이 OS 키체인(safeStorage)으로 암호화돼 다른 PC에서 복호화 불가
OS 종속 바이너리	python venv, LSP 서버 등은 복사해도 안 돌아감
거대한 재생성 캐시	검색/임베딩 색인(`workspace.sqlite` ~226MB)이 통째로 따라옴

무엇을 옮기고 무엇을 버리나

🟢 이식 대상 (번들 포함)

chats/ — 채팅 이력(메시지 포함, 자기완결)
blyck-history.db — 변경 이력 (VACUUM INTO 스냅샷)
db-history.json · db-snippets.json — DB 쿼리 이력·스니펫
layout.json · blyck-locale.json · embeddings-settings.json — 레이아웃·언어·설정
connections.json — DB/SSH 접속 메타 (평문 번들에선 시크릿 strip)
attachments/ · changeSet-snapshots/ — 옵션

⚫ 제외 — 대상 PC에서 재생성

workspace.sqlite — 검색/임베딩 색인(~226MB). 대부분 코드베이스 파생이라 통째 제외하면 번들이 230MB → 수 MB로 줄고, 대상 PC에서 인덱서가 자동 재색인합니다.
python-venvs/ · lsp-servers/ — OS 바이너리(재생성)
Electron/Chromium 런타임 캐시, 로그 등

번들 포맷 `.blyckbundle`

ZIP 컨테이너 + manifest.json(스키마·앱버전·소스 OS·경로 루트·파일별 sha256).

backup-YYYY-MM-DD.blyckbundle
├── manifest.json
└── files/                       # userData 상대경로 미러
    ├── chats/index.json, chat_*.json
    ├── blyck-history.db
    ├── db-history.json, db-snippets.json
    ├── layout.json, blyck-locale.json, embeddings-settings.json
    ├── connections.json         # 평문 번들은 시크릿 strip
    ├── attachments/**           # 옵션
    └── changeSet-snapshots/**   # 옵션

경로 리매핑 — 채팅을 그대로 이어가기

import 시 채팅 JSON의 권위 있는 경로 필드만 치환합니다.

필드	리매핑
`projectRoot`	✅ 치환
`_lastSentProjectRoot`	✅ 치환
`extraRoots[]`	✅ 각 원소 치환
`projectRootSftp`	❌ 불변(원격은 PC 무관)
`messages[]`	❌ 불변(이력 보존)

규칙은 최장 프리픽스 매칭입니다 — 경로가 소스 루트로 시작하면 프리픽스만 대상 루트로 교체하고 나머지 구분자를 변환합니다. 매핑 안 한 루트는 그대로 둡니다(채팅은 열리되 프로젝트만 미해결, 사용자가 재오픈).

크로스-OS 4방향 (Win↔Mac 전조합)

remapPath는 소스 구분자(분리)와 타깃 구분자(결합)를 따로 다룹니다. 소스 구분자는 소스 루트에서 자동 감지(\/드라이브레터 → Win, / → POSIX), 타깃 구분자는 대상 OS로 결정합니다.

방향	소스 경로 예	결과 예
Win→Win	`D:\dev\App\src\a.js`	`E:\work\App\src\a.js`
Win→Mac	`D:\dev\App\src\a.js`	`/Users/x/App/src/a.js`
Mac→Win	`/Users/x/dev/App/src/a.js`	`D:\work\App\src\a.js`
Mac→Mac	`/Users/x/dev/App/src/a.js`	`/Users/y/App/src/a.js`

드라이브레터/루트 무관 — 프리픽스 치환이라 D:\ ↔ /Users/ 등 어떤 루트 조합도 매핑 표에서 1:1로 해소됩니다.

암호화 번들 + 시크릿 포함

export 시 비밀번호를 지정하면 번들 전체를 암호화합니다.

방식: 번들 전체 AES-256-GCM — ZIP 내장 암호(ZipCrypto)는 취약하므로 쓰지 않고, zip을 만든 뒤 Node 내장 crypto로 통째 암호화합니다(외부 의존성 0). KDF는 scrypt, 암호는 AES-256-GCM(기밀성 + 무결성).
비밀번호 오입력 = GCM auth tag 검증 실패 → “비밀번호가 틀렸습니다” 즉시 감지(부분 복호 없음, 데이터 미변경).
평문 헤더(BLYCKENC1)로 비번 없이도 암호화 여부를 먼저 판별합니다.

시크릿은 방향 무관 — Win safeStorage로 복호 → 암호화 번들 → Mac safeStorage로 재암호화(역도 동일)라 Win↔Mac 4방향 모두 성립합니다.

Export 흐름

내보내기 옵션 — 포함 항목과 비밀번호 암호화

정지 확인 — busy 턴이 있으면 거부(데이터 일관성)
blyck-history.db → VACUUM INTO로 단일 스냅샷(앱 실행 중 안전)
포함 파일 수집 + 파일별 sha256
chats 스캔 → distinct 경로 루트를 manifest.pathRoots에 기록
시크릿 처리 — 비번 미지정: strip / 비번 지정: 평문 시크릿 포함
ZIP 패키징
비번 지정 시 AES-256-GCM 암호화 → *.blyckbundle 기록

Import 흐름

inspect — magic으로 암호화 여부 판별. 암호화면 비밀번호 입력 프롬프트
복호화 — 비번 → scrypt → AES-256-GCM. auth tag 실패 시 중단(데이터 미변경)
경로 리매핑 UI — 소스 루트별 입력칸(베이스명 자동 추천: D:\develope\Blyck_Web → ~/dev/Blyck_Web)
안전 백업 — 현재 chats/·*.db를 userData/_pre-import-<ts>/로 보존
files/ 추출 → userData에 기록
리매핑 적용 — projectRoot/_lastSentProjectRoot/extraRoots 최장 프리픽스 치환 + 구분자 정규화 (projectRootSftp·messages 불변)
시크릿 복원 — 암호화 번들: 대상 OS safeStorage로 재암호화 / 평문 번들: “재입력 필요” 플래그
workspace.sqlite 없음 → 다음 실행 시 자동 재색인
재시작 안내

모드 — 교체 vs 머지

모드	동작	용도
교체(replace)	현재 `chats/`·`*.db`를 `_pre-import-<ts>`로 백업 후 번들로 교체	새 PC로 통째 이전
머지(merge)	기존 설치에 chat id 기준으로 합치기 (교체 없이 추가)	두 PC의 작업을 한 곳으로 모으기

머지가 안전한 이유는 chats/가 id별 개별 JSON이라 충돌 없이 합쳐지기 때문입니다.

안전장치

import 전 현재 데이터 자동 백업(_pre-import-<ts>)
manifest 스키마/앱버전 호환 게이트
파일별 sha256 무결성 검증
채팅 busy 중 import 거부
교체 전 사용자 명시 확인
암호화 번들 비밀번호 오입력 → 복호 단계에서 중단(데이터 미변경)
평문 번들엔 시크릿 미포함(유출 방지)

FAQ

Q. 채팅 이력이 새 PC에서 그대로 열리나요? → 네. import 시 경로 리매핑으로 projectRoot 등을 새 PC 경로로 자동 변환하므로 채팅과 프로젝트가 그대로 이어집니다.

Q. DB/SSH 비번을 다시 입력해야 하나요? → 암호화 번들(비밀번호 지정)로 내보내면 시크릿이 포함되고 대상 OS로 재암호화되어 재입력이 필요 없습니다. 평문 번들은 보안상 시크릿을 빼므로 재입력이 필요합니다.

Q. Windows에서 만든 번들을 Mac에서 풀 수 있나요? → 네. Win→Mac, Mac→Win 포함 4방향 모두 지원합니다. 경로 구분자(\↔/)와 드라이브레터/루트가 자동 변환됩니다.

Q. 번들이 왜 이렇게 작나요? → 226MB대의 workspace.sqlite(검색 색인)는 코드베이스에서 재생성 가능하므로 제외합니다. 대상 PC에서 인덱서가 자동 재색인하며, 채팅 이력 자체는 그대로 보존됩니다.

Q. 비밀번호를 잊으면요? → 복구 수단이 없습니다. AES-256-GCM은 비번 없이 복호화가 불가능하므로 암호화 번들의 비밀번호는 안전하게 보관하세요.

Q. 기존 PC 작업에 합치고 싶으면요? → 머지 모드를 쓰세요. chat id 기준으로 합쳐 기존 채팅을 지우지 않고 추가만 합니다.