백업

업데이트가 잘못되거나 디스크가 고장 나거나 새 장비로 옮길 때 되돌려 놓을 수 있도록 설정의 사본을 보관하세요.

시작하기 전에

• Settings > Backups(설정 > 백업)는 Change settings(설정 변경) 권한이 필요합니다. 복원은 소유자만 할 수 있습니다.
• 다운로드, 삭제, 복원은 최근 몇 분 안에 비밀번호로 로그인한 상태여야 합니다.

백업 만들기

1. Settings > Backups를 여세요.
2. Back up now(지금 백업)를 선택하세요. Saved backups(저장된 백업) 아래에 새 백업이 표시됩니다.
3. 그 옆의 Download(다운로드)를 선택해 서버 밖에 사본을 보관하세요.

마스터 키 보관하기

백업에는 마스터 키가 들어가지 않습니다. 마스터 키는 설정에 저장된 비밀번호와 API 키를 여는 키입니다. 맞는 키가 없으면 복원한 백업에서 이 값들을 읽을 수 없습니다.

1. Master key(마스터 키) 아래에서 소유자가 Download key kit(키 키트 다운로드)을 선택합니다.
2. 이 파일은 서버와 떨어진 곳에, 백업과도 따로 보관하세요. Settings > Backups와 상태 점검에서 키 키트 경고가 사라집니다.

나중에 쓸 때는 파일 이름을 holyarrs.key로 바꿔 설정 폴더에 넣으세요. 소유자가 아니라면 소유자에게 다운로드를 부탁하세요.

백업 복원하기

위험

백업 이후에 바뀐 내용은 사라집니다. 맞는 마스터 키를 먼저 준비하세요.

1. Restore from a file(파일에서 복원)을 선택하고 HolyArrs 백업 zip을 고르세요.
2. 확인하세요.
3. HolyArrs가 파일을 검사합니다. Restore ready. It applies on the next start.(복원 준비 완료. 다음 시작 때 적용됩니다.)가 표시됩니다.
4. HolyArrs가 재시작하면서 백업을 적용합니다. 권장하는 Docker 재시작 정책을 쓰고 있다면 자동으로 진행됩니다.

현재 데이터베이스는 /config/backups/before-restore-<time>으로 옮겨지므로 복원을 되돌릴 수 있습니다.

선택 사항

백업 주기

선택	백업 시점	보관
Balanced(균형, 기본값)	매일	최근 7일과 주간 사본 4개
Light(가볍게)	주 1회	4주. 공간을 가장 적게 씁니다
Careful(꼼꼼하게)	매일	30일 동안의 모든 사본

가장 최근의 예약 백업은 항상 보관됩니다. 이 규칙은 예약 백업만 정리합니다. 직접 만든 백업은 삭제할 때까지 남습니다(해당 행의 휴지통 버튼. 되돌릴 수 없습니다). HolyArrs는 저장된 데이터를 바꾸는 업데이트 전에도 백업하며 최근 3개를 보관합니다. 업데이트를 참고하세요.

새 장비로 옮기기

새로 설치하면 처음 시작할 때 자체 마스터 키가 만들어집니다. 그 키로는 예전 백업을 열 수 없어서 복원이 거부됩니다. 먼저 예전 키를 넣어 두세요. 예시에서는 컨테이너 이름을 holyarrs라고 합니다. 실제 이름으로 바꿔 쓰세요.

1. 처음 시작하기 전에 컨테이너를 시작하지 않고 만들기만 하세요. docker compose create를 쓰거나, docker run 명령에서 docker run -d 자리에 docker create를 넣으세요.
2. 예전 키를 복사해 넣으세요: docker cp holyarrs.key holyarrs:/config/. 키 키트의 이름을 holyarrs.key로 바꾼 것도 됩니다. 네임드 볼륨이든 호스트 폴더든 이 방법이 통합니다. HolyArrs는 시작할 때 /config의 파일을 PUID와 PGID의 소유로 넘깁니다. HOLYARRS_MASTER_KEY_FILE을 쓴다면 키를 호스트의 그 경로에 두고, PUID와 PGID가 읽을 수 있게 하세요.
3. 백업을 복원하세요. 한 가지 방법을 고르세요.

   • HolyArrs를 시작하고 첫 실행을 마친 다음 Settings > Backups의 Restore from a file을 사용하세요.

   • 또는 처음 시작하기 전에 복원하세요. zip을 이름 그대로 backups라는 폴더에 넣고 docker cp backups holyarrs:/config/로 복사해 넣으세요. 그런 다음 같은 이미지로 복원을 한 번 실행하세요.

     • Compose: docker compose run --rm holyarrs restore <zip name>
     • Docker CLI: docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> holyarrs/holyarrs:<tag> restore <zip name>

     키 파일 경로를 쓴다면 -e HOLYARRS_MASTER_KEY_FILE=<its path>를 추가해 복원이 그 키로 검사하게 하세요. restore --list는 인식되는 백업 이름을 보여 줍니다.

4. HolyArrs를 시작하세요. 라이브러리와 설정이 돌아와 있습니다.

키를 복사하기 전에 새 설치를 이미 시작했나요? 거기에 남길 것이 없다면 HolyArrs를 중지하고, 같은 docker cp로 예전 키를 새 키 위에 덮어쓴 뒤 복원하고 시작하세요.

문제가 생기면

증상: “Backups are off in this build”(이 빌드에서는 백업이 꺼져 있습니다). 원인: 이 사본은 백업 관리자 없이 실행됩니다. 해결: 앱에서는 방법이 없습니다. 백업 조작 버튼이 없습니다.

증상: 다운로드, 삭제, 복원에서 비밀번호를 묻습니다. 원인: 이 작업은 최근에 비밀번호로 로그인한 상태여야 합니다. 해결: 비밀번호로 다시 로그인한 뒤 다시 시도하세요.

증상: 마스터 키 때문에 복원이 거부됩니다. 원인: 설정 폴더의 키가 백업과 맞지 않습니다. 해결: 맞는 holyarrs.key를 다시 넣고 다시 시도하세요.

zip이 너무 크거나 손상됐을 때, 예상하지 못한 파일이 들어 있을 때, 더 새로운 데이터베이스 버전에서 만들어졌을 때, 키로 읽을 수 없는 데이터가 들어 있을 때도 복원이 거부됩니다.

전문가용

백업에 들어 있는 것

각 백업은 zip 파일이며 주 데이터베이스, 이벤트 데이터베이스(있는 경우), backup.json(HolyArrs 버전, 데이터베이스 버전, 백업 종류, 만든 시각)이 들어 있습니다. 미디어, 다운로드, 아트워크, 로그, 마스터 키는 들어 있지 않습니다.

처음 시작하기 전에 복원하기

docker cp는 네임드 볼륨이든 호스트 폴더든 통합니다. HolyArrs는 시작할 때 /config의 파일을 PUID와 PGID의 소유로 넘깁니다. HOLYARRS_MASTER_KEY_FILE을 쓴다면 키를 호스트의 그 경로에 두고, PUID와 PGID가 읽을 수 있게 하세요.

1. zip을 이름 그대로 backups라는 폴더에 넣고 복사해 넣으세요: docker cp backups holyarrs:/config/.
2. 같은 이미지로 복원을 한 번 실행하세요.
   • Compose: docker compose run --rm holyarrs restore <zip name>
   • Docker CLI: docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> holyarrs/holyarrs:<tag> restore <zip name>
3. 키 파일 경로를 쓴다면 -e HOLYARRS_MASTER_KEY_FILE=<its path>를 추가해 복원이 그 키로 검사하게 하세요.
4. HolyArrs를 시작하세요.

restore --list는 인식되는 백업 이름을 보여 줍니다.

관련 문서

• 업데이트
• 설치
• 상태 점검