백업 및 복원

인스턴스를 사용 중이면 업그레이드 또는 서버 이동 전에 백업을 생성하세요. 최초 클라이언트 설정은 다음에서 다룹니다. 첫 번째 요청.

SubLane은 실행 중인 인스턴스를 내보내고, 백업을 확인하고, 새 디렉터리로 복원할 수 있습니다. 명령줄과 시스템 설정 → 백업 및 복원 동일한 아카이브 유효성 검사 및 복원 구현을 사용합니다. 복구는 실행 중인 인스턴스를 덮어쓰지 않습니다. 복원된 데이터로 전환하는 것은 명시적인 운영자 재시작입니다.

무엇이 포함되어 있나요?

새 백업은 비밀번호로 암호화된 바이너리 age 파일입니다. 복호화된 gzip/tar에는 다음이 포함됩니다.

sublane.db: 커밋된 WAL 데이터를 포함한 일관된 SQLite 스냅샷입니다.
credentials.key: 구독 자격 증명과 복구 가능한 게이트웨이 키에 대해 일치하는 암호화 키입니다.
manifest.json: 형식 버전, 생성 시간, SubLane 빌드 버전, 스키마 버전, 파일 크기 및 SHA-256 체크섬.

사용자, 암호 해시, API 키, 구독 계정, 풀, 권한, 카탈로그, 설정, 요청 기록, 사용 요약, 휴지 및 선호도 기록이 포함됩니다. 브라우저 세션은 백업에 캡처되지만 복원된 디렉터리에서는 지워집니다. 브라우저 로컬 테마/언어 선택, 프로세스 환경, 배포 파일 및 보류 중인 메모리 내 OAuth 시도는 포함되지 않습니다.

새 내보내기에는 12~128자의 비밀번호가 필요합니다. SubLane은 이를 저장하지 않습니다. 백업과 따로 보관하세요. 잃어버리면 암호화된 백업을 복구할 수 없습니다. 기존의 암호화되지 않은 .tar.gz는 비밀번호 없이 검증·복원할 수 있지만 읽을 수 있는 키를 포함하므로 비공개로 보관해야 합니다.

명령줄

데이터베이스 스냅샷 및 압축 아카이브를 위한 충분한 여유 공간이 있는 디렉터리에서 명령을 실행합니다.

Command line · 1

mkdir -p backups
./bin/sublane backup --password-stdin --output ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane backup verify --password-stdin --input ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

backup 읽다 SUBLANE_DATA_DIR 또는 ./data, 선택사항 포함 --data-dir 보수. restore 항상 명시적인 새 디렉터리가 필요합니다. 기존의 빈 디렉토리도 거부됩니다. 상위 디렉터리가 있어야 합니다. 기존 아카이브 파일과 복원 디렉터리는 교체되지 않습니다. 성공적인 명령은 작업, 경로 및 백업 메타데이터와 함께 JSON 결과를 인쇄합니다. sublane --help 명령을 나열합니다.

유지 관리 명령은 HTTP 서버, SDK 실행기, OAuth 또는 자동 릴리스 확인을 시작하지 않으며 서버 주소/공개 URL 구성에 의존하지 않습니다. 기한은 15분이며 SIGINT/SIGTERM에 응답합니다. 데이터베이스 스냅샷은 4GiB로 제한되며 아카이브 IO는 제한된 버퍼를 사용합니다. 확인 또는 복원 시 아카이브 자체 외에 추출 및 마이그레이션을 위한 디스크 공간을 허용합니다.

성공적인 복원 후:

현재 SubLane 서비스를 중지합니다.
원래 데이터 디렉터리를 그대로 유지합니다.
복원된 디렉터리로 SubLane을 시작합니다.

Command line · 2

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

팀 트래픽을 재개하기 전에 다시 로그인하고 예상 사용자, 풀, 키 및 계정 상태를 확인하세요.

SubLane을 중지하고 전환하여 원래 디렉터리를 롤백할 수 있습니다. SUBLANE_DATA_DIR 뒤쪽에. 동일한 데이터 디렉터리에 대해 두 개의 게이트웨이 인스턴스를 실행하지 마십시오. 복원하면 저장된 모든 상태가 스냅샷으로 롤백됩니다. 이후의 키 취소, 비밀번호 변경 및 새 레코드는 포함되지 않습니다. 구독 공급자가 백업 이후 이전 새로 고침 토큰을 무효화했을 수 있습니다. 필요한 경우 영향을 받은 계정을 다시 승인합니다. 확인은 공급자에게 연락하지 않고도 암호 해독 및 로컬 무결성을 확인합니다.

웹 인터페이스

활성화된 관리자만 페이지 또는 해당 끝점을 사용할 수 있습니다. 변이에는 정확한 브라우저 출처가 필요하며, 내보내기는 파일 준비 후 관리자 세션을 다시 확인합니다.

다운로드 백업 인스턴스를 계속 사용할 수 있는 동안 전체 아카이브를 생성하고 다운로드합니다.
백업하기 선택한 파일을 확인하고 생성 시간, SubLane 버전 및 데이터베이스 크기를 표시합니다.
자주 묻는 질문 파일을 다시 업로드하고 확인한 다음 생성합니다. <current data directory>/restore-ready. 페이지에는 전체 경로 및 다시 시작 지침이 표시됩니다. 현재 인스턴스는 운영자가 디렉터리를 전환할 때까지 원래 데이터로 계속 실행됩니다.

기존 restore-ready 경로는 또 다른 준비를 차단합니다. 서버에서 검사하거나 다른 새 대상과 함께 CLI를 사용하십시오. 웹을 통해 디렉토리를 덮어쓸 수 없습니다 API. 복구 데이터가 준비되었지만 실시간 감사 쓰기가 실패한 경우 디렉터리는 유지되고 페이지는 감사 실패를 보고합니다. 다시 시도하기 전에 검사하세요.

웹 업로드 및 다운로드는 256MiB의 압축 데이터로 제한됩니다. 대규모 백업에는 CLI가 필요합니다. 내보내기/검증/복원 작업은 서버당 한 번에 하나씩 실행됩니다. 업로드, 처리, 다운로드에는 기한이 정해져 있습니다. 임시 파일은 완료, 실패 또는 정상 취소 후에 제거됩니다. 강제 프로세스 종료 또는 전원 손실로 인해 개인 정보가 남을 수 있습니다. .sublane-backup-* 예배 규칙서; 백업 작업이 실행되고 있지 않을 때만 남은 준비 디렉터리를 제거하십시오.

내보내기 및 준비된 복원은 아카이브 내용, 파일 이름, 파일 시스템 경로 또는 자격 증명을 기록하지 않고 감사됩니다. 다운로드 사용 Cache-Control: no-store. 페이지는 선택한 파일에서 업로드를 스트리밍합니다. 브라우저는 다운로드된 아카이브를 임시 blob으로 수신하고 다운로드를 시작한 후 해당 URL을 해제합니다.

브라우저 백업 및 복원 제어 예시:

Backup page with download, archive verification and restore preparation

Docker Compose

실행 중인 컨테이너 내에서 내보내고 확인하려면 다음 안내를 따르세요.

Docker Compose · 3

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec -T sublane sublane backup --password-stdin --output /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml exec -T sublane sublane backup verify --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz.age ./team.sublane-backup.tar.gz.age

복구를 위해 컨테이너 내부에 표시되는 쓰기 가능한 개인 위치에 백업을 복사한 후 별도의 디렉터리를 준비합니다.

Docker Compose · 4

docker compose -f docker.compose.yaml exec -T sublane sublane restore --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age --data-dir /data/restore-ready < /secure/backup-password

웹 복원 작업은 동일한 대상을 생성합니다. 이를 활성화하려면 예를 들어 로컬 Compose 재정의를 생성하십시오. docker.compose.restore.yaml:

Docker Compose · 5

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

그런 다음 원래 프로세스를 중지하고 재정의를 시작합니다.

Docker Compose · 6

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

이미 중지된 컨테이너의 경우 다음을 사용하세요. docker compose -f docker.compose.yaml run --rm --no-deps sublane ... 대신에 exec 명명된 데이터 볼륨에 대해 유지 관리 명령을 실행합니다. 후속 배포 명령에서 선택한 재정의를 유지합니다. 이 절차 중에는 명명된 볼륨을 제거하지 마십시오.

검증 및 실패 동작

검증에서는 정확한 아카이브 항목 및 크기, SHA-256 다이제스트, gzip 무결성, 지원되는 통합 스키마 버전, SQLite 무결성 및 외래 키, 제한된 자격 증명 레코드, 계정 자격 증명 및 암호화된 API 키의 암호 해독을 확인합니다. 검증 연결은 또한 개별 SQLite 값과 SQL 문을 1MiB로 제한합니다. Symlink, 경로 탐색, 중복/예상치 못한 파일, 누락된 파일, 잘린 아카이브 및 알 수 없는 향후 스키마는 거부됩니다. 이 시험판 빌드에서는 이전 개발 스키마가 허용되지 않습니다.

복원은 원자성 교체 없음 작업으로 전체 새 디렉터리를 게시하기 전에 준비된 데이터베이스/키를 닫고 동기화합니다. Linux 및 macOS에서는 해당 작업을 위한 파일 시스템 지원이 필요합니다. 지원되지 않는 작업은 덮어쓰기로 대체되지 않고 실패합니다. 백업 지원으로 인해 추가 데이터베이스 테이블이나 스키마 마이그레이션이 도입되지 않습니다. SQLite 스냅샷 생성은 다음을 사용합니다. SQLite 온라인 백업 API 라이브 데이터베이스 파일을 복사하는 대신 고정된 Go 드라이버를 통해.

엔드포인트	목적
`GET /api/settings/backup`	웹 크기 제한 및 고정된 복원 대상 읽기
`POST /api/settings/backup/export`	JSON `{password}` → `.age`
`POST /api/settings/backup/verify`	`multipart/form-data`: `password` + `file`
`POST /api/settings/backup/restore`	`multipart/form-data`: `password` + `file`

사용 application/gzip 또는 application/octet-stream 업로드용. 잘못된 아카이브는 400을 반환하고, 기존 대상은 409를 반환하고, 크기가 너무 큰 업로드는 413을 반환하고, 점유된 작업 슬롯은 429를 반환합니다. Retry-After. 저장소 및 기타 운영 오류는 삭제된 503 오류를 반환합니다.

credentials.key · 백업 비밀번호

기존 인스턴스를 중지하고 원래 키를 데이터 디렉터리 밖의 비공개 위치로 복사한 뒤 서비스 사용자 권한을 설정하세요. 시작 및 암호화 백업을 확인한 후 원래 사본을 제거하세요.

SUBLANE_CREDENTIALS_KEY_FILE: 데이터 디렉터리 외부의 선택적 비공개 자격 증명 키 파일. 미설정 시 기존 위치 유지.

키를 분리해 보관하는 경우 복원된 credentials.key를 데이터 디렉터리 밖의 새로운 비공개 위치로 옮기고 다시 시작하기 전에 SUBLANE_CREDENTIALS_KEY_FILE을 갱신하세요. 원래 인스턴스의 키를 덮어쓰지 마세요.

12~128자를 사용하세요. 비밀번호는 별도로 보관하세요. 분실 시 재설정할 수 없습니다. 암호화된 백업에는 필수입니다. 기존 비암호화 파일은 비워 두세요.

--key-file FILE · --password-stdin · scrypt: 18 (~256 MiB)

권한이 0600인 비공개 한 줄 파일에서 --password-stdin으로 비밀번호를 읽으세요. 인수나 환경 변수에 비밀번호를 넣지 마세요.

화면은 multipart/form-data로 password 다음에 file을 보냅니다. 기존 원시 업로드도 비밀번호 없이 계속 지원됩니다.

Compose 키 자동 마이그레이션

애플리케이션 저장소의 scripts/separate-key.sh는 기존 SubLane v0.12.0+ Compose 배포를 지원합니다. Docker 호스트에 스크립트를 저장하고 내용을 검토한 뒤 실행하세요. 먼저 비밀번호로 암호화한 복구용 백업을 내보내고 검증하세요.

기존 키 분리

sudo bash scripts/separate-key.sh --dir /srv/sublane --key-dir /srv/sublane-secrets

--dir는 docker.compose.yaml과 선택적 .env가 있는 기존 배포 디렉터리입니다. --key-dir는 부모 디렉터리는 있지만 대상 자체는 아직 없는 절대 경로여야 하며, 실제 데이터 마운트 및 복구 디렉터리 밖의 영구 호스트 저장소를 사용해야 합니다. 공백이 포함된 일반 ASCII 경로를 지원합니다. 로컬 Linux rootful Docker(userns 재매핑 및 SELinux 미사용), Compose, Bash, jq, GNU coreutils가 필요합니다. 정상 상태인 기존 서비스의 이름은 sublane이어야 하고, 데이터 디렉터리는 쓰기 가능한 bind 또는 이름 있는 볼륨의 마운트 루트여야 합니다. Compose는 서비스에 두 칸 들여쓰기, environment 블록 매핑, volumes 블록 목록을 사용해야 합니다. 지원하지 않는 구성은 서비스 중지 전에 거부됩니다.

프로젝트, 이미지, 데이터 마운트, 기존 키의 비공개 권한, 32바이트 크기 및 해시를 확인합니다. Compose 원문과 변수 보간을 유지하고 정규화된 구성을 비교합니다. 새 호스트 디렉터리는 root 소유의 0700 권한을 유지합니다. 서비스 UID/GID가 소유한 0600 키 파일만 컨테이너에 읽기 전용으로 마운트하며, 서비스 권한을 높이지 않습니다.

전환 전, 전환 후, 기존 키 삭제 후에 각각 새로운 임의 비밀번호로 임시 암호화 백업을 만들고 검증합니다. 검증용 임시 공간은 데이터 디렉터리 밖에 두며 완료 후 삭제합니다. 충분한 디스크 공간과 백업 KDF에 필요한 메모리를 확보하세요. 이 검사는 복구용 백업을 보관하지 않습니다. 새 구성, 상태 검사, 키 해시 및 자격 증명 검증이 모두 통과해야 기존 복사본을 삭제합니다. 다시 컨테이너를 만들고 검증하여 기존 파일에 더 이상 의존하지 않는지 확인합니다.

전환 시작 후 처리 가능한 오류나 신호가 발생하면 롤백을 시도합니다. 마이그레이션 성공 후에도 직접 롤백할 수 있습니다.

키 분리 롤백

sudo bash scripts/separate-key.sh --dir /srv/sublane --rollback

비공개 복구 기록은 /srv/sublane/.key-migration에 남습니다. 롤백은 원래 구성과 일치하는 키를 복원하고 원래 서비스를 다시 만들고 검증합니다. 이후 변경된 구성이나 환경, 다른 키와 충돌하면 덮어쓰기를 거부하며 이미지나 데이터베이스를 다운그레이드하지 않습니다. 외부 키와 복구 기록은 롤백 후에도 비공개로 유지되며, 재마이그레이션은 기존 기록이나 대상을 덮어쓰지 않습니다. 재시도 전에 검증된 복구 기록을 안전하게 보관하고 새 키 디렉터리를 선택하세요.

설치 프로그램의 .update-lock을 공유하므로 다른 배포 작업을 동시에 실행하지 마세요. 강제 종료나 정전 후에는 마이그레이션 또는 업데이트가 실행 중이지 않은지 확인하고, 남아 있는 빈 .update-lock만 제거한 뒤 --rollback을 실행하세요. 롤백을 검증할 수 없으면 복구 키 자료와 비공개 operation.log를 보존합니다. 복구가 끝날 때까지 복구 디렉터리와 외부 키 디렉터리를 모두 유지하세요. 보관한 백업과 비밀번호는 별도로 관리해야 합니다.

자동 암호화 백업

아래 배포 설정으로 활성화합니다. 대상 디렉터리는 비공개(0700), 12–128자 독립 암호는 비공개 일반 파일(0600, 심볼릭 링크 금지)에 두고 데이터 및 백업 디렉터리와 분리하세요. 매 실행마다 다시 읽습니다.

Automatic backup deployment settings

export SUBLANE_BACKUP_DIR=/srv/sublane-backups
export SUBLANE_BACKUP_PASSWORD_FILE=/secure/sublane/backup-password
export SUBLANE_BACKUP_INTERVAL=24h
export SUBLANE_BACKUP_KEEP=7

시작 시 실행하고 각 시도 후 설정된 간격을 기다립니다. 새 보관 파일을 완전히 검증한 후 예약된 scheduled- 파일만 정리하며 수동 파일과 새 검증 파일은 보존합니다. 결과는 서비스 로그에 기록됩니다. 원격 업로드나 웹 일정 양식은 없으며 데모에서는 실행하지 않습니다.

SUBLANE_BACKUP_INTERVAL: 1h–720h (default 24h). SUBLANE_BACKUP_KEEP: 1–365 (default 7).

인스턴스마다 전용 백업 디렉터리를 사용하세요.

선택 항목 SUBLANE_BACKUP_WEBHOOK_URL에 공개 HTTPS 주소를 지정하면 실패한 시도마다 제한된 backup_failure JSON 알림을 보냅니다. 작업 공간 알림과 별도인 인스턴스 운영자 설정이며 전송 실패는 로그에 기록합니다.

Docker에서는 컨테이너 경로를 사용하고 로컬 Compose 재정의로 비공개 암호 파일과 쓰기 가능한 전용 백업 디렉터리를 마운트하며 서비스 사용자에게 권한을 부여하세요. 기본 /tmp tmpfs는 64 MiB입니다. 큰 검증 작업에는 별도 비공개 쓰기 마운트와 TMPDIR 설정이 필요합니다.