데이터 이전: lolly-backup 번들

Lolly는 개인 라이브러리를 기기에 보관해요. 백업 번들은 그 라이브러리가 이동하는 방법이에요. 한 설치에서 내보내고, 원하는 방법(USB, AirDrop, 자신에게 이메일, 네트워크 공유)으로 파일을 옮기고, 다른 설치에서 가져와요. 내보내기와 가져오기에는 서버가 필요 없고 대상은 오프라인이어도 돼요.

이 페이지는 백업을 중심으로 셸, 도구, 스크립트를 만드는 사람을 위한 형식 명세예요. zip에 무엇이 들어 있는지, 버전이 어떻게 제한되는지, 가져오기가 어떻게 병합되는지, 무엇이 검사되는지를 다뤄요. 자기 작업을 옮기는 사람을 위한 안내는 작업물을 다른 기기로 옮기기예요.

signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KBCheck it yourself서명된 파일 받기 signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KBCheck it yourself서명된 파일 받기

범위. 번들은 카탈로그 도구가 아니라 사용자 데이터를 담아요. 카탈로그 도구와 카탈로그 에셋은 별도로 동기화되며 대상에 이미 있다고 가정하고, 최악의 경우에도 더 높은 버전이에요. 사용자가 직접 만든 도구는 profile.json 안에 담겨 이동해요. 가져오기는 카탈로그 도구를 설치하거나 업그레이드하지 않아요.

목표

• 하나의 형식, 모든 셸. 웹 앱, 데스크톱 및 모바일 앱, 향후 셸은 같은 봉투와 파트 스키마를 공유해요. 선택적 파트는 각 셸의 기능에 따라 달라지고 지원되지 않는 파트는 보고돼요. 각 기능 브리지가 자체 저장소 어댑터를 제공해요.
• 이동을 견뎌요. 전송 중 손상되거나 잘린 번들은 가져올 때 분명히 실패하며 절반만 복원되는 일이 없어요.
• 이 버전보다 오래가요. 이전 앱도 새 번들에서 인식하는 파트를 가져올 수 있어요. 정말로 호환되지 않는 형식은 깔끔하게 거부돼요.
• 안전하게 병합돼요. 이미 쓰고 있는 설치에 가져와도 번들에 없던 것은 지워지지 않아요.

봉투(envelope)

번들은 일반 .zip이므로 어떤 전송에서도 온전하게 살아남고 어떤 압축 해제 도구로도 내용을 검사할 수 있어요.

다운로드 이름은 그것이 속한 사람의 이름을 따라요. LollyTools-<First>-<Last>-<YYYY-MM-DD>-<n>.zip, 예를 들어 LollyTools-Ada-Lovelace-2026-06-26-1.zip이므로 백업이 모인 Downloads 폴더도 읽기 쉬워요. 이름과 성은 프로필에서 오며 설정되지 않았으면 빠져요. 프로필이 없으면 LollyTools-2026-06-26-1.zip, 이름만 있으면 LollyTools-Ada-2026-06-26-1.zip이에요. 각 이름은 파일 이름에 안전한 토큰으로 줄어들어요(유니코드 문자와 숫자는 유지, 공백과 구두점은 제거, 최대 32자). <n>은 기기별, 날짜별 순번이므로 같은 날 반복해서 내보내도 충돌하지 않고 순서가 유지돼요. data-transfer.ts의 backupFilename()이 이름을 만들며, zip의 내용은 이름과 상관없이 같아요.

manifest.json

{
  "format": "lolly-backup",
  "formatVersion": 3,
  "minReader": 1,
  "app": "lolly",
  "exportedAt": "2026-06-22T09:30:00.000Z",
  "counts": { "profile": true, "sessions": 2, "userAssets": 4, "prefs": 3, "assetVersions": 1, "fileOperations": 1 },
  "integrity": {
    "profile.json": "sha256-…",
    "sessions.json": "sha256-…",
    "assets.json": "sha256-…",
    "assets/blobs/0.bin": "sha256-…",
    "file-history.json": "sha256-…",
    "file-history/versions/0.bin": "sha256-…",
    "file-history/results/0.bin": "sha256-…",
    "prefs.json": "sha256-…"
  }
}

버전 정책

두 개의 버전 번호가 이전 설치를 고립시키지 않고 형식을 키울 수 있게 해요.

Open this in Diagram Builder

• 리더는 manifest.minReader가 자신의 리더 버전 이하일 때 번들을 가져와요. 번들이 더 새로운 리더를 요구할 때만 "needs a newer version of the app"과 함께 거부해요.
• 새 선택적 파트나 새 선택적 매니페스트 필드 같은 추가형 변경은 formatVersion을 올리고 minReader는 그대로 둬요. 이전 앱도 인식하는 모든 파트를 가져오고, 인식하지 못하는 파트는 조용히 버려지지 않고 건너뛴 것으로 보고돼요.
• 파트를 잘못 가져오면 데이터가 손상되거나 선택적 파트가 필수가 되는 호환 불가형 변경은 minReader를 올려요. 그러면 이전 앱은 처리할 수 없는 것을 가져오는 대신 깔끔하게 거부해요.
• 향후 번들이 formatVersion은 설정하고 minReader를 빠뜨리면, 리더는 formatVersion으로 제한하는 것으로 돌아가 변경을 호환 불가형으로 취급해요.

작성자를 위한 경험칙: 기존의 모든 리더가 추가한 것을 무시해도 올바르게 동작한다면 그 변경은 추가형이에요. formatVersion을 올리고 minReader는 그대로 두세요. 그렇지 않으면 minReader를 올리세요.

무결성

manifest.integrity가 있으면 리더는 아무것도 쓰기 전에 나열된 각 파트의 SHA-256을 확인해요. 불일치("failed its integrity check")나 누락된 파트("incomplete")는 가져오기 전체를 멈추므로 부분 복원은 없어요. 이는 잘린 AirDrop, 첨부 파일을 다시 인코딩한 이메일 게이트웨이, 불량 USB 섹터처럼 파일 전송이 일으킬 수 있는 손상을 걸러내요.

무결성은 최선을 다하는 방식이에요. Web Crypto를 쓸 수 있는 곳(모든 보안 브라우저 컨텍스트와 최신 Node)에서만 쓰이고, 맵과 Web Crypto가 모두 있을 때만 확인돼요. 무결성이 생기기 전의 번들처럼 맵이 없는 번들도 그대로 가져와져요. "확인할 수 없음"은 "손상됨"으로 세어지지 않아요.

매니페스트는 자신도, 다시 생성되는 lolly.txt도 나열하지 않아요. 다이제스트는 매니페스트가 보증하는 파트를 다뤄요.

가져오기 규칙

가져오기는 두 모드 중 하나로 실행돼요.

• Merge는 Import data…가 하는 일이며, sync의 첫 합류인 Bring it to this device도 해요. 대상의 데이터는 남고 번들에 없던 것은 건드리지 않아요. 대상에 있고 번들에 없던 세션은 가져온 뒤에도 남아요.
• Replace는 기기 sync가 기기들을 맞추는 데 쓰는 방식이에요. sync된 사본의 프로필 레코드, 환경설정, 세션, 이미지, 활성 디자인 시스템 선택을 가져오고, 마지막 sync 이후 다른 기기에서 삭제한 항목만 제거해요. 이전 사본을 복원하는 것은 더 나아가 기기를 먼저 저장한 뒤 사본에 없는 모든 것을 제거하여 기기를 그 사본과 일치시켜요. 기기 Sync가 사람이 보는 것을 다뤄요.

병합에서는 대상에만 있는 것은 모두 유지되며, 번들의 각 데이터 종류는 대상과 이렇게 만나요.

저장된 세션은 이미지와 자동으로 다시 연결돼요. 에셋 참조는 ID로 보관되고, 브리지가 이미지가 복원된 후 이를 다시 확인해요. blob: URL이 새로고침을 견디지 못하므로 어차피 해야 하는 일이에요.

기록은 작성된 후 절대 바뀌지 않아요. 에셋 버전과 작업 ID를 반복해서 가져와도 아무것도 추가되지 않으며, 이미 다른 바이트나 기록을 가리키는 ID는 덮어쓰지 않고 거부돼요. 동일한 현재 에셋을 다시 가져오면 버전이 유지되고, 변경된 현재 에셋은 다른 버전을 가져야 해요.

작품 기록에는 몇 가지 규칙이 더 있어요. 대상이 다른 작품에 쓰는 슬롯의 작품은 별도의 작품으로 추가되고, 대상의 휴지통에 있는 작품은 그곳에 남아요. 대상에서 다른 내용을 가리키는 체크포인트 ID는 대상의 것을 유지해요. 자체 검사에 실패한 아카이브는 프로필, 세션, 에셋, 환경설정이 바뀌기 전에 가져오기를 멈추며, 동일한 반복 가져오기는 저장소를 추가로 쓰지 않아요.

요약이 일어난 일을 보고해요. 모든 가져오기는 profile, sessions, userAssets, prefs, skipped, failedAssets를 반환해요.

• failedAssets는 기기 저장소가 가득 찬 경우처럼 복원할 수 없었던 업로드된 에셋의 수예요.
• skipped는 이 빌드가 인식하지 못한 더 새로운 작성기의 파트 수예요. 앱이 이를 보여주므로("… · N newer items skipped") 복원은 남겨 둔 것을 밝혀요.
• 파일 기록이 있으면 요약에 assetVersions, fileOperations, fileBatches, failedHistory가 추가돼요. 저장소 고갈이나 불변 ID 충돌은 부분 복원을 일으킬 수 있으며, 그러면 앱이 원본 백업을 보관하라고 안내해요.
• 작품 기록이 있으면 이번 가져오기가 추가한 것만 세는 revisions와 recoveryDrafts, 각 작품이 병합된 방식을 나타내는 added, kept, replaced, copies, hidden이 추가돼요. skippedCheckpoints는 ID가 대상에서 다른 내용을 가리키는 체크포인트 수이고, historyLeftOut은 기기의 기록 공간에 맞지 않았던 오래된 체크포인트와 초안의 수예요.
• Replace 가져오기는 removed와 failedRemovals를 추가해요.

복원은 프로필, 세션, 에셋, 기록 저장소를 가로지르는 하나의 트랜잭션이 아니에요. 클라우드 sync는 부분 또는 지원되지 않는 복원 후에 적용된 개정본을 진행시키지 않으므로, 사본은 다시 시도할 수 있도록 남아 있어요.

이동하지 않는 것

• 카탈로그 캐시(내려받은 에셋 메타데이터와 블롭, 도구 색인)는 대상이 무료로 다시 동기화해요.
• 카탈로그 도구와 카탈로그 에셋은 범위 밖이며 대상에 있다고 가정해요. 사용자가 추가한 브랜드 토큰, 글꼴, 로고는 사용자 에셋이므로 이동해요.
• blob: 및 객체 URL은 브리지가 로드 시 다시 생성해요.
• 변환 원본, 실행 중인 임대, 기기 로컬의 접근 또는 서명 비밀. 이들은 이식 가능한 기록이 아니에요. 저장된 결과는 사본이며 원본 소스가 백업되었다는 약속이 아니에요.
• 내보내기 순번 카운터는 localStorage의 날짜별 다운로드 이름 카운터(lolly-export-seq)예요. PREF_KEYS에서 제외되어 있으므로 번들에 실리지 않아요.

저장소 미터도 같은 구분을 보여줘요. Saved sessions, My images, File results & versions는 번들에 들어가요. 그 아래의 에셋 캐시, 도구 미리보기, 오프라인 고정은 모두 다시 만들 수 있으므로 남아요.

signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KBCheck it yourself서명된 파일 받기 signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KBCheck it yourself서명된 파일 받기

Lolly Work의 조직 데이터

이 번들은 기기의 개인 라이브러리를 백업해요. Lolly Work 인스턴스의 백업이 아니에요. 조직 계정, 접근 정책, 공유 프로젝트, 카탈로그 버전, 승인, 렌더 작업, 감사 기록은 해당 서비스가 보관해요. 공유 작업에 다시 접근하려면 다시 연결하고 로그인하세요. 개인 번들을 가져와도 그 접근 권한은 부여되지 않아요.

운영자는 Lolly Work의 자체 가이드인 백업과 복원과 Work 저장소와 데이터 수명 주기로 서버 데이터를 백업, 보관, 삭제해요. 기기를 지우거나 내보내도 그런 서버 작업은 일어나지 않아요.

셸 간

data-transfer.ts는 기능 브리지(host.profile, host.state, host.assets)와 공유 localStorage 환경설정을 통해서만 읽고 써요. 같은 모듈이 웹과 데스크톱 및 모바일 앱에서 IndexedDB나 파일 시스템 저장소 위에서 공통 봉투를 읽고 써요. 선택적 기록 파트는 어댑터를 쓸 수 있는 곳에서만 나타나고, 지원되지 않는 파트는 가져올 때 건너뛴 것으로 보고돼요. 헤드리스 모음은 메모리 내 브리지로 공통 파트를 검증하며, 기록 트랜잭션에는 실제 브라우저 테스트도 있어요.

두 셸은 서로 다른 이유로 이 보장 밖에 있습니다:

• 일회성 CLI는 옮길 것이 없어요. 상태가 메모리에 있고 한 번의 호출 동안만 유지돼요.
• TUI는 상태(세션, 폴더, 프로필)를 ~/.lolly에 보관하며 Profile 보기에서 백업할 수 있지만, 세션당 saved-state/<slot>.json과 profile.json, folders.json으로 이루어진 더 단순한 자체 아카이브를 써요. 매니페스트도 formatVersion이나 minReader도 무결성 맵도 없어요. 이 형식은 이를 가져올 수 없고(리더가 "not a Lolly backup"으로 거부해요), 이름도 헷갈릴 만큼 비슷해요(lolly-backup-<stamp>.zip). 둘을 통합하는 것은 알려진 과제예요.

아직 이식할 수 없는 것

봉투는 매니페스트와 이름 붙은 파트로 이루어져 있으므로, 새로운 종류의 이식 가능한 데이터가 나중에 추가형 파트(새 formatVersion, 같은 minReader)로 합류할 수 있고, 오늘의 리더는 인식하지 못하는 것을 건너뛰어요. 디자인 시스템은 이미 design-systems.json과 사용자 에셋으로 이렇게 이동해요.

아직 이동하지 않는 데이터를 위해 두 이름이 예약되어 있어요.

• tokens.json은 그룹, 세트, 테마가 있는 W3C DTCG 디자인 토큰 문서 전체를 담을 거예요. Penpot이 가져오고 내보내는 형식이에요. 사용자 자신의 브랜드 토큰은 이미 assets.json의 user/tokens/brand 에셋으로 이동하고, 디자인 시스템의 토큰은 레코드와 함께 이동해요.
• penpot/은 가져온 Penpot 파일 또는 Lolly와 관련된 일부를 도구로 노출하기 위해 예약되어 있어요.

오늘의 리더는 두 이름 모두 아직 몰라요. 위 파트 밖의 다른 것처럼 이들에게는 알 수 없는 파트이며 건드리지 않고 skipped로 세어요.

기록 파트

두 기록 파트는 선택 사항이며 자체 버전이 있어요. 대부분의 리더는 이 섹션을 건너뛰어도 돼요.

참고 자료

• 모듈: shells/web/src/data-transfer.ts(exportBackup, importBackup, BACKUP_FORMAT, BACKUP_FORMAT_VERSION, BACKUP_READER_VERSION. backupFilename() 이름 생성기는 내부용이에요).
• 계약 테스트: tests/data-transfer.test.ts가 왕복, 병합, 무결성, 순방향 호환성, 리더 게이트를 다뤄요.
• 기록 계약 테스트: tests/file-history-backup.test.ts, tests/file-batch-history.test.ts, tests/file-result-library.test.ts. 브라우저 수락: tests/file-history.browser.test.ts, tests/file-batch-history.browser.test.ts, tests/file-result-reuse.browser.test.ts.
• 사용하는 브리지 영역: host.profile, host.state, host.assets. Host API를 참고하세요.