백업과 복원

셀프 호스팅 Nodaro는 명령 하나로 백업하고 다른 명령 하나로 복원합니다. 백업 아카이브에는 스택이 다시 만들어 낼 수 없는 모든 것, 즉 데이터베이스, 내 미디어, 인스턴스 암호화 키, .env가 담깁니다. 데이터베이스 마이그레이션은 앞으로만 진행되므로, 복원은 다운그레이드하는 유일한 방법이기도 합니다. 이전 버전으로 돌아가려면 업데이트 전에 만든 백업을 복원해야 합니다.

백업에 담기는 내용

tools/community-backup.sh는 tar.gz 아카이브 하나를 씁니다.

Redis는 의도적으로 제외합니다. 수명이 짧은 작업 상태만 들어 있기 때문입니다.

백업 만들기

docker-compose.community.yml이 있는 설치 디렉터리에서, 스택이 실행 중인 상태로 실행하세요.

tools/community-backup.sh
# -> ./backups/nodaro-backup-<date>-v<version>.tar.gz

스크립트는 아카이브에 들어간 내용을 출력합니다. 암호화 키가 없으면 이를 눈에 띄게 알리고 오류와 함께 종료하므로, 예약된 작업도 이를 알아챌 수 있습니다. 그런 아카이브로는 공급자 키를 복원할 수 없습니다.

데이터베이스 덤프는 항상 일관성이 있습니다. 백업이 진행되는 동안 기록된 미디어는 아카이브에서 빠질 수 있습니다. 미디어 스냅숏의 일관성을 보장하려면 먼저 앱을 중지하세요.

docker compose -f docker-compose.community.yml stop nodaro

Windows에서는 Git for Windows가 설치하는 셸인 Git Bash에서 스크립트를 실행하세요. PowerShell과 WSL의 bash는 컨테이너 경로를 망가뜨립니다.

백업 시기

첫 번째 숫자가 바뀌는 메이저 버전으로 업데이트하기 전마다, 그리고 데이터의 중요도에 맞는 주기로 백업하세요. cron 한 줄을 그대로 쓸 수 있습니다.

0 3 * * * cd /path/to/install && tools/community-backup.sh >> backup.log 2>&1

백업 복원

tools/community-restore.sh backups/nodaro-backup-<date>-v<version>.tar.gz

복원은 데이터베이스와 미디어를 아카이브의 내용으로 바꾸므로, 무엇이든 건드리기 전에 RESTORE를 입력하라고 요청합니다. 그다음 스크립트는 다음을 수행합니다.

1. 앱과 데이터베이스 클라이언트인 auth와 rest를 중지합니다. 이들의 열린 연결이 복원을 막기 때문입니다.
2. Postgres를 복원하고, 종료 코드를 믿는 대신 실제로 작동하는지 확인합니다. Supabase 이미지가 내보내는 무해한 메시지 몇 개는 예상된 것이며 그대로 출력됩니다.
3. 미디어를 복원하고, 버킷이 돌아왔는지와 MinIO가 정상인지 확인합니다. 그다음 암호화 키를 복원하고 볼륨에서 키의 크기를 확인합니다. 그다음 기존 .env가 있으면 따로 보관한 뒤 내 .env를 복원합니다. 확인에 실패하면 앱이 시작되기 전에 스크립트가 멈춥니다. 올바른 키 없이 시작하면 새 키가 만들어지고, 복원된 공급자 키를 영영 읽을 수 없게 되기 때문입니다.
4. 모든 것을 다시 시작하고 앱 자체의 상태 확인을 기다립니다. 스크립트는 앱이 실행된 뒤에만 성공을 보고하고, 그렇지 않으면 오류와 함께 종료합니다.

완료되면 http://localhost:3000/setup을 여세요. 모든 카드가 초록색이어야 합니다.

버전 다운그레이드

마이그레이션 롤백은 없습니다. 이전 버전으로 돌아가려면 다음과 같이 하세요.

1. 위와 같이 업데이트 전에 만든 백업을 복원합니다.
2. NODARO_IMAGE나 docker-compose.community.yml에서 이전 이미지를 고정합니다. 예: ghcr.io/nodaroai/nodaro-community:v1.25.1. 정확한 vX.Y.Z 태그는 절대 바뀌지 않습니다.
3. docker compose -f docker-compose.community.yml up -d nodaro를 실행합니다.

태그는 업데이트를 참고하세요.

관리형 배포 백업

Compose 스택 밖에서는 네 가지가 상태를 보관합니다.

마이그레이션이나 복구 중에 Postgres가 중단되면, API는 데이터베이스에 연결할 수 있을 때까지 재시작을 반복합니다. Postgres가 돌아오면 Nodaro 컨테이너를 재시작하세요.

문제 해결

• the db service is not running. 먼저 스택을 시작하세요: docker compose -f docker-compose.community.yml up -d.
• 복원 후 공급자 키가 missing으로 표시됩니다. 데이터베이스가 짝이 맞는 encryption-key 없이, 또는 다른 키와 함께 복원되었습니다. 키가 들어 있는 아카이브에서 복원하거나 /setup에서 키를 다시 입력하세요.
• 복원 검증에 실패했습니다. 스크립트는 반쯤 복원된 데이터베이스를 조용히 남겨 두지 않습니다. 복원을 다시 실행하세요. 계속 실패하면 아카이브가 잘렸을 수 있으니 원본과 크기를 비교하세요.
• Windows에서 백업 중 could not read the encryption key가 나타납니다. Git Bash에서 실행하지 않았거나 앱 컨테이너가 실행 중이 아닙니다. 스택을 실행한 상태로 Git Bash에서 백업을 다시 실행하세요. 스크립트가 경고한 아카이브는 쓸 수 있는 백업이 아닙니다.
• media restore verification FAILED 또는 encryption key verification FAILED가 나타납니다. 스크립트가 의도적으로 멈추고 앱을 시작하지 않았습니다. 스크립트가 알려 준 볼륨을 확인하고, 대개 중지된 컨테이너나 가득 찬 디스크인 원인을 해결한 뒤 복원을 다시 실행하세요. 반복해도 안전합니다.