설정 백업과 예약 백업

Gately의 모든 설정은 설정 디렉터리의 *.json 파일에 저장됩니다. 백업 기능은 이 파일들을 묶어 수동 다운로드, 여러 위치로의 예약 저장, 백업으로 덮어써서 복원하는 기능을 제공합니다. 관리 UI는 사이드바 「시스템」 그룹 → 「설정」 → 「백업 및 마이그레이션」 탭에 있습니다.

백업 내용

백업 파일은 zip이며 설정 디렉터리 최상위의 모든 *.json(계정, 각 모듈 규칙, 인증서, 토큰 해시 등)을 담고 있습니다. 비밀번호 해시, 키, API 토큰 해시, 인증서 개인 키가 들어 있으므로 안전하게 보관하세요. 실행 로그(logs/)와 작업 감사 로그(audit.log)는 백업에 포함되지 않습니다.

파일 이름 형식은 gately-backup-YYYYMMDD-HHMMSS.zip이고, 암호화 백업은 gately-backup-YYYYMMDD-HHMMSS.zip.enc입니다.

수동 백업과 복원

백업 다운로드

「Gately 설정 백업」 카드의 「백업 다운로드」 버튼으로 현재 설정의 zip을 내려받습니다. 수동으로 내려받은 백업은 암호화되지 않습니다.

복원

「설정 복원」 카드에서 백업 파일을 선택하고 「복원」을 누른 다음, 확인 창에 「복원」이라는 글자를 입력합니다.

• 복원하면 현재 설정 전체를 덮어쓰며 업로드 크기 상한은 64 MB입니다.
• 덮어쓰기 전에 기존 설정을 설정 디렉터리 아래 backup-시간 폴더(시간 형식 YYYYMMDD-HHMMSS)에 복사하며, 복원에 성공하면 UI에 그 경로가 표시됩니다.
• 복원 후 Gately가 자동으로 재시작됩니다.
• 백업에는 계정 설정이 반드시 들어 있어야 하며 없으면 복원을 거부합니다.
• 백업 파일은 zip 최상위에 있고 숨김이 아니며 내용이 유효한 JSON인 *.json만 받아들이고 나머지 항목은 무시합니다.
• .enc 파일을 선택하면 UI에 「백업 암호」 입력란이 나타나며 해당 백업을 만들 때 설정한 암호를 입력합니다. 암호가 틀리거나 파일이 손상되면 복원에 실패합니다.

백업 다운로드와 복원 API는 로그인 세션만 허용하며 API 토큰으로는 호출할 수 없습니다.

예약 백업

「백업 및 마이그레이션」 탭 아래쪽의 「예약 백업」 카드에서 오른쪽 위 스위치로 사용 여부를 정합니다. 해당 모듈 ID는 backup이며 토큰 권한 범위는 backup:read와 backup:write입니다.

설정	설명
실행 일정	5필드 cron 표현식. 기본값 0 3 * * *(매일 03:00)이며 @daily, @weekly 등의 디스크립터도 쓸 수 있습니다
보관 개수	대상마다 최신 N개를 보관하며 범위는 1~365, 기본값 7입니다
암호화 암호	비우면 암호화하지 않습니다. 설정하면 .zip.enc 백업이 생성됩니다. 이미 암호가 설정되어 있을 때 입력란을 비워 두면 그대로 유지됩니다
로컬 디렉터리	스위치, 기본값은 켜짐. 설정 디렉터리 아래 backups 폴더에 저장합니다

「설정 저장」을 누르면 일정이 적용되고, 「지금 백업」은 즉시 한 번 실행합니다. 카드에는 마지막 실행 시간, 실행 방식(수동 또는 예약), 다음 실행 시간, 대상별 성공 또는 실패 결과와 정리된 이전 백업 수가 표시됩니다. 로컬 백업 파일은 카드에 나열되며 내려받을 수 있습니다.

백업 대상

로컬 디렉터리 외에 원격 대상을 여러 개 추가할 수 있으며, 각 대상은 「스토리지 마운트」에 있는 마운트 지점(로컬 디렉터리, 원격 WebDAV 또는 SMB 공유) 하나에 기록합니다.

필드	설명
이름	필수
스토리지 마운트	「스토리지 마운트」에 이미 있는 마운트 지점을 선택하며 읽기 전용이거나 비활성화된 마운트 지점은 선택할 수 없습니다
디렉터리	마운트 지점 안의 하위 디렉터리이며 비우면 루트입니다
사용	스위치

마운트 지점이 아직 없다면 먼저 「스토리지 마운트」에서 추가하세요. 대상을 삭제해도 이미 기록된 백업은 삭제되지 않습니다.

실행 흐름

1. 설정 디렉터리를 압축합니다. 암호를 설정했다면 암호화합니다.
2. 로컬 디렉터리(켜져 있으면)와 활성화된 모든 대상에 기록하며 모든 위치에서 같은 파일 이름을 사용합니다.
3. 기록에 성공하면 보관 개수에 맞춰 해당 위치의 오래된 백업을 정리합니다. 정리는 파일 이름이 gately-backup-으로 시작하고 확장자가 .zip 또는 .zip.enc인 파일만 대상으로 하며 다른 파일은 그대로 둡니다.
4. 결과를 취합하여 모듈 로그에 기록하고 알림 이벤트를 발행합니다.

로컬 디렉터리도 활성화된 대상도 없으면 백업은 실패로 기록됩니다. 동시에는 백업을 한 번만 실행합니다.

알림 이벤트

이벤트	레벨	발생 조건
backup.done	정보	모든 위치에 기록 성공. 메시지에 파일 이름과 위치별 결과가 나열됩니다
backup.failed	오류	압축 실패 또는 어느 위치에 쓰지 못함. 메시지에 위치별 결과가 나열됩니다

알림 센터에서 backup.*을 구독하는 규칙을 만들면 Telegram, 이메일 등의 채널로 백업 결과를 받을 수 있습니다.

암호화

암호를 설정하면 백업은 다음 방식으로 암호화됩니다.

• 키 유도: scrypt(N=32768, r=8, p=1), 32바이트 키를 출력하며 솔트는 16바이트 난수입니다.
• 암호화: AES-256-GCM, nonce는 12바이트 난수입니다.
• 파일 형식: 매직 넘버 GATELYBK1, 솔트, nonce, 암호문을 차례로 이어 붙이며 매직 넘버는 GCM의 추가 인증 데이터로도 쓰입니다.

암호는 설정 디렉터리의 backup.json에만 저장되며 암호를 잃어버리면 백업을 복호화할 수 없습니다.

주의

backup.json과 백업 파일이 같은 머신에 있으면 암호 보호의 효과가 제한적입니다. 암호화 백업은 다른 장치의 마운트 지점에 저장하고 암호는 따로 기록해 두기를 권장합니다.