콘텐츠로 이동

문제 해결

간단한 FAQ입니다. SSH를 통한 VM 백업의 전체 호스트 측 문제 해결 표(권한 거부, 호스트 키 검증, 누락된 템플릿 변수 등)는 GitHub의 SSH를 통한 VM 백업 가이드를 참고하세요.

무언가가 올바르게 연결되지 않았습니다

웹 UI에서 /spike를 엽니다. 호스트 통합 확인이 모든 마운트와 CLI(Docker 소켓, libvirt, restic, qemu-img, rclone)를 검사하고 누락된 부분을 보고합니다. 버그라고 가정하기 전에 여기서 시작하세요: 누락된 마운트나 도달할 수 없는 호스트는 즉시 나타납니다.

웹 UI에 접근할 수 없습니다

BombVault는 기본으로 포트 3443에서 HTTPS를 제공하므로(자체 서명된 인증서), https://<your-unraid-ip>:3443을 여세요. 자체 서명 인증서 경고를 수락하거나, BombVault를 자체 인증서를 가진 리버스 프록시 뒤에 두세요. HTTP_ONLY=true로 실행하면 대신 포트 3000에서 일반 HTTP를 제공합니다(TLS 종료 프록시 뒤에서 사용하도록 의도됨).

APP_KEY를 잃어버렸습니다

APP_KEY는 restic 저장소 비밀번호를 파생합니다. 이것 없이는(그리고 암호화 키 복구 키트 없이는) 암호화된 백업을 복구할 수 없습니다. 그래서 대시보드가 복구 키트를 다운로드하라고 재촉하는 것입니다. 오프사이트 및 복구를 참고하세요. openssl rand -hex 32로 키를 생성하고 어떤 백업에 의존하기 전에 서버 밖에 보관하세요.

VM 백업이 연결되지 않습니다

VM 백업은 마운트가 아니라 SSH를 통해 libvirt와 통신합니다.

  • 호스트에서 SSH가 활성화되어 있고 BombVault의 공개 키가 /root/.ssh/authorized_keys에 승인되어 있는지 확인하세요(설정, 연동, 호스트 SSH에 키와 연결 테스트 버튼이 표시됨).
  • 사용자 지정 br0.x 네트워크에서는 LIBVIRT_HOST를 Unraid LAN IP로 설정하세요(거기서는 컨테이너가 host.docker.internal을 통해 호스트에 도달할 수 없음). Settings, Docker, Host access to custom networks을 활성화하세요.
  • Unraid의 SSH 포트를 변경했다면 LIBVIRT_SSH_PORT를 일치하도록 설정하세요.
  • 전체 단계별 진단(도달 가능성 테스트, VLAN 라우팅, Permission denied (publickey), Host key verification failed)은 SSH를 통한 VM 백업 가이드에 있습니다.

라이브 VM 스냅샷이 실행되지 않았습니다

라이브 스냅샷은 VM에 설치된 qemu 게스트 에이전트와 /mnt/user가 아닌 /mnt/cache(또는 /mnt/diskX)에 있는 디스크가 필요합니다. 꺼진 VM에서는 라이브가 자동으로 정상 종료로 대체됩니다. 정상 종료 백업은 VM을 종료하고, 디스크를 백업한 다음, 재시작하므로 항상 일관됩니다.

백업이 "repository is already locked"로 실패했습니다

이는 보통 컨테이너가 작업 도중 업데이트되거나 재시작될 때 남겨진 고아 restic 잠금입니다. BombVault는 확실히 고아가 된 잠금을 감지하여 자동으로 강제 해제하고 한 번 재시도합니다. 지속되면 해당 도메인에 대해 설정, 무결성, 잠금 해제를 사용하여 멈춘 잠금을 손으로 제거하세요. 진짜 문제는 숨겨지지 않고 여전히 드러납니다. 재시작 후 BombVault는 그런 잠금이 10분 동안 갱신되지 않을 때까지 기다립니다. 아직 실행 중인 restic은, 예를 들어 같은 저장소를 쓰는 두 번째 BombVault 안에서, 5분마다 잠금을 갱신하기 때문입니다.

백업 후 오프사이트 복사가 일어나지 않았습니다

오프사이트 복제는 설계상 최선 노력 방식이므로, 오프사이트 장애가 로컬 백업을 실패시키는 일은 없습니다. 해당 도메인의 오프사이트 일정(설정, 일정)을 확인하세요: 빈 일정은 매 로컬 백업 후 복제하고, 주기는 덜 자주 보냅니다. 온디맨드 실행에는 오프사이트 페이지의 지금 복제를 사용하고, 대시보드의 복제 표시기를 지켜보세요.

복원이 시작되기 전에 중단되었습니다

어떤 것이 중지되거나 제거되기 전에, 복원은 사전 점검 충돌 검사를 실행합니다: 컨테이너의 고정 IP와 게시된 호스트 포트가 비어 있는지 확인합니다. 다른 컨테이너가 이미 하나를 점유하고 있으면, 중간에 끝난 복원을 남기는 대신 명확하고 실행 가능한 메시지와 함께 중단합니다. 충돌하는 포트나 IP를 비운 다음 다시 시도하세요.

일반 내보내기가 파일을 쓰는 대신 실패했습니다

age 암호화가 켜져 있지만(설정) 유효한 수신자가 설정되지 않으면, 내보내기는 평문을 쓰는 대신 명확한 오류와 함께 실패합니다. 유효한 수신자(age 공개 키 또는 SSH 공개 키)를 추가하거나, 내보내기를 평문으로 의도한다면 암호화를 끄세요. 기능을 참고하세요.

데이터베이스 덤프가 실패했습니다

덤프가 실패해도 그 주위의 백업은 실패하지 않습니다. 덤프 자체가 실패한 실행으로 기록되고, 이유가 무엇을 고쳐야 하는지 알려 줍니다.

  • 로그인 거부. 덤프는 컨테이너 자신의 비밀번호 변수(POSTGRES_PASSWORD, MARIADB_ROOT_PASSWORD, MYSQL_ROOT_PASSWORD 또는 그 _FILE 판)로 로그인합니다. 데이터베이스 컨테이너에서 확인하세요. 컨테이너의 사용자가 읽을 수 없는 비밀을 가리키는 _FILE 변수도 같은 식으로 실패합니다.
  • 권한 부족. 무작위 root 비밀번호에서는 덤프가 앱 사용자로만 로그인할 수 있어 그 데이터베이스 하나만 담기고, MySQL 8.4 이상은 아예 거부할 수 있습니다. 컨테이너에 진짜 root 비밀번호를 주거나, 그 컨테이너의 덤프를 끄세요.
  • 시스템 테이블 업그레이드 필요. MariaDB는 시스템 테이블이 더 낮은 버전에서 온 경우 덤프를 거부합니다(오류 1558). 변수 MARIADB_AUTO_UPGRADE=1을 추가하고 컨테이너를 재시작하거나, 컨테이너 안에서 mariadb-upgrade를 한 번 실행하세요.
  • 덤프 도구 없음. pg_dump, mysqldump, mariadb-dump가 없는 경량 이미지나 직접 만든 이미지는 덤프할 수 없습니다. 공식 이미지를 쓰거나 덤프를 끄세요.
  • 시간 제한. 덤프에는 DB_DUMP_MAX_HOURS(기본 6), 주위 백업에는 BACKUP_MAX_HOURS가 걸리고, 진행이 멈춘 덤프는 BACKUP_STALL_HOURS 뒤에 잘립니다. 마지막 경우의 원인은 대개 애플리케이션이 쥐고 있는 잠금입니다. 걸린 제한을 올리거나, 애플리케이션이 한가할 때 덤프하세요.
  • 컨테이너가 일시 중지되었거나 재시작 중. 덤프는 실행 중인 서버와 이야기합니다. 컨테이너가 계속 재시작한다면 그 이유는 컨테이너 자신의 로그에 있습니다.
  • 손상된 덤프를 제거하지 못함. BombVault는 끝내지 못한 덤프를 다시 삭제합니다. 그 삭제가 실패하면 덤프는 손상 표시가 붙은 채 목록에 남고, 거기서 삭제할 수 있습니다.

가져오기가 실패했습니다

가져오기는 컨테이너를 멈추고, 데이터 폴더를 옆으로 옮긴 뒤, 이미지가 그 자리에 빈 폴더를 만들게 합니다. 가져오기 자체보다 앞선 단계가 실패하면 예전 폴더가 저절로 제자리로 돌아옵니다. 가져오기가 실패하면 컨테이너에는 새 폴더가 남고, 예전 폴더는 <데이터 폴더>.bombvault-before-import-<타임스탬프>로 그 옆에 남습니다. 실행의 오류 메시지가 정확한 경로를 알려 줍니다.

손으로 되돌리려면 컨테이너를 멈추고, 현재 데이터 폴더의 이름을 바꿔 치운 다음, 보관된 폴더를 원래 이름으로 되돌리고 컨테이너를 시작하세요. Unraid에서는 Shares 탭의 파일 관리자로 할 수 있습니다.

ZFS 데이터세트 백업이 실패했거나 데이터세트를 건너뛰었습니다

문제마다 대괄호 안에 이유 코드가 붙으며, ZFS 데이터세트 페이지에 모든 코드와 해결 방법이 있습니다. 가장 흔한 세 가지:

  • snapshot-loop: Host Data가 새 마운트를 전달하지 않아 스냅샷이 BombVault에 도달하지 못했습니다. 컨테이너를 편집해 Host Data의 Access Mode를 Read/Write - Slave로 바꾸고 BombVault를 다시 시작하세요.
  • key-not-loaded: 키가 로드되지 않은 암호화 데이터세트는 건너뜁니다. zfs load-key로 키를 로드하고 데이터세트를 마운트하면 다음 백업에 포함됩니다.
  • ssh-auth: 서버가 BombVault의 키를 거부했습니다. ZFS 페이지의 연결 카드에 키를 허용하는 명령이 나옵니다. 서버에서 한 번 실행하세요.

대상이 "학습 중 N/10"에 머물러 있음

대부분의 이상 징후 검사는 대상의 백업이 10번 성공한 뒤에 시작되며, 예상된 것으로 표시 후와 대상의 선택이 바뀐 뒤에는 횟수를 다시 셉니다. 일정이 없는 대상은 학습하지 않고, appdata가 없는 컨테이너는 학습할 것이 없으며, 배지도 그렇게 알려 줍니다.

보존 정책이 한 대상의 오래된 백업을 더 이상 삭제하지 않음

열린 심각한 이상 징후가 붙잡고 있습니다. 대상의 소스가 거의 비었거나, 크게 줄었거나, 한 백업이 데이터 대부분을 다시 저장했습니다. 대상의 배지에서 이상 징후를 여세요. 데이터가 없어졌거나 암호화되었다면 먼저 연결된 마지막 정상 백업에서 복원하세요. 그런 다음 이상 징후를 확인하거나, 변경이 본인에 의한 것이면 예상된 것으로 표시하면 다음 실행부터 평소대로 정리합니다. 보존 미리보기는 이런 대상을 보존됨으로 표시합니다. ZFS 대상에서는 이상 징후가 가리키는 데이터세트만 오래된 백업을 유지하고, 트리의 다른 데이터세트는 평소처럼 정리됩니다.

수동 정리에서 일부 대상이 보존되었다고 표시됨

원인은 같습니다. 정리는 이런 이상 징후가 있는 대상의 오래된 백업을 건드리지 않고 메시지에 그 대상을 적습니다. 나머지는 평소대로 정리됩니다.

기록 가져오기에서 저장소를 읽지 못했다고 표시됨

업데이트 뒤 BombVault는 각 저장소에서 이전 백업의 크기를 한 번 읽어 옵니다. 그때 연결할 수 없었던 저장소(멈춰 있던 오프사이트 대상이나 마운트되지 않은 공유 등)는 설정, 무결성의 이상 징후 카드에 표시되고 하루에 한 번 다시 시도합니다. 그동안 그 저장소의 대상은 새 백업으로 학습합니다.

디스크 공간 경고가 Unraid 대시보드와 맞지 않음

Unraid 사용자 공유(/mnt/user)에서 여유 공간은 디스크 하나가 아니라 어레이 전체의 것입니다. 원격 저장소는 여유 공간을 보고하는 rclone 원격을 통해서만 측정됩니다. S3, B2, REST, SFTP 저장소는 값이 없으며 이상 징후 카드에 측정되지 않음으로 표시됩니다.

AI 어시스턴트가 연결되지 않음

MCP 서버 페이지에 MCP 엔드포인트의 각 상태 코드와 각 거부가 무엇을 뜻하는지, 어떻게 하면 되는지 정리되어 있습니다.

컨테이너가 계속 재시작하거나 비정상으로 보입니다

BombVault는 자체 /api/health에서 정상/비정상을 보고합니다. 자가 치유 도구(예: Autoheal)가 엔진이 멈추면 자동으로 재시작할 수 있습니다. 근본 원인은 컨테이너 로그와 /spike 보고서를 확인하세요.

여전히 막혔나요?