컨테이너 업데이트 실패 후 Home Assistant 복원 방법

Home Assistant 컨테이너 업데이트에 실패했다면 일반적으로 새 설치를 만들어야 하는 문제가 아니라 런타임 교체 문제로 봐야 합니다. 호스트에 마운트된 /config 디렉터리가 온전하다면, 해당 상태를 보존하고 볼륨 매핑을 확인한 다음 정상 이미지로 시작하여 기존 설치를 테스트하는 것이 이전 백업을 복원하기 전에 취할 가장 안전한 복구 경로입니다.

가장 위험한 조치는 새 컨테이너가 잘못된 호스트 경로 또는 비어 있는 호스트 경로를 사용하도록 두는 것입니다. 그러면 원래 상태가 디스크의 다른 위치에 그대로 남아 있어도 Home Assistant가 설정이 사라진 것처럼 온보딩 화면을 표시할 수 있습니다. 먼저 변경을 중지하고 실제 설정 디렉터리를 확인한 뒤, 복구된 인스턴스가 정상적으로 작동할 때까지 기존 컨테이너나 디렉터리를 삭제하지 마세요.

새 쓰기를 중지하고 실제 /config 경로 찾기

실패한 컨테이너를 중지하고 해당 컨테이너를 생성한 런타임 정의를 확인하세요. 어느 호스트 디렉터리 또는 이름이 지정된 볼륨이 /config에 매핑되어 있는지 확인한 다음, 해당 위치에서 YAML 파일, .storage, 사용자 지정 구성 요소, 시크릿, 데이터베이스를 점검하세요.

Docker 업그레이드 후 발생한 한 커뮤니티 복구 사례에서는 “완전히 새로 설치된” Home Assistant 인스턴스가 실제로는 컨테이너가 잘못된 설정 폴더를 가리킨 결과였습니다. 영구 데이터가 삭제된 것이 아니라, 교체된 런타임이 해당 데이터를 올바르게 마운트하지 않았던 것입니다.

소유권, 경로 또는 데이터베이스 파일을 변경하기 전에 현재 설정 디렉터리를 복사하거나 스냅샷으로 저장하세요. 일부만 손상된 상태라도 중요한 증거가 되며, 마지막 백업보다 최신인 자동화나 자격 증명이 포함되어 있을 수 있습니다.

설치를 다시 만들지 말고 런타임만 재생성하기

업데이트 전에 정상적으로 작동하던 컨테이너와 동일한 네트워크 모드, 시간대, 장치 매핑, USB 라디오 액세스, 권한 또는 기능, 호스트 /config 마운트를 사용하세요. 이미지는 교체할 수 있지만, 이러한 런타임 입력과 영구 데이터가 서비스가 동일한 Home Assistant 인스턴스로 복구되는지를 결정합니다.

컨테이너의 영속성은 컨테이너 파일 시스템이 아니라 호스트 마운트에 따라 결정됩니다. Home Assistant Container 예시에서는 영구 호스트 볼륨을 /config에 직접 마운트하므로 런타임을 재생성해도 가정의 설정이 새로 만들어지지 않습니다. 업데이트 중 이 매핑이 변경되면 원래 상태가 다른 곳에 남아 있어도 교체된 컨테이너가 새로 설치된 것처럼 보일 수 있습니다.

기존 컨테이너 파일 시스템을 새 이미지에 복사하지 마세요. 문서화된 Compose 또는 실행 정의에서 배포를 재생성하고, 영구 상태를 명시적으로 다시 연결하세요.

이전 상태를 복원하기 전에 이미지 롤백하기

설정 마운트가 올바르지만 새 Home Assistant 버전이 시작되지 않거나 중요한 통합 구성 요소가 작동하지 않는다면, 보존한 동일한 /config를 사용하여 이전에 정상 작동했던 이미지를 테스트하세요. 이렇게 하면 “새 런타임이 현재 상태와 호환되지 않는 문제”와 “상태 자체가 손상된 문제”를 구분할 수 있습니다.

현재 Home Assistant Container 작업 흐름은 이미지를 영구 상태와 명확히 분리합니다. 즉, 먼저 백업하고, 대상 이미지를 가져온 다음, 컨테이너를 재생성하며, 다운그레이드가 필요할 때는 특정 이전 이미지 태그를 사용합니다. 보존해야 할 복구 기준도 바로 이것입니다. 권위 있는 설정 경로는 유지한 채 런타임만 교체하세요.

롤백할 때는 일부 업그레이드가 데이터 구조를 마이그레이션한다는 점을 기억하세요. 최신 버전에서 이미 업그레이드된 상태를 이전 버전이 안전하게 읽지 못한다면, 마이그레이션 전에 생성한 백업을 사용하세요. 영구 데이터의 유일한 사본에 여러 버전을 반복해서 적용하지 마세요.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

현재 상태를 신뢰할 수 없을 때만 백업 복원하기

영구 설정이 없거나 손상되었거나 일부가 덮어써졌거나, 안전하게 실행할 수 있는 버전과 더 이상 호환되지 않을 때 백업을 사용하세요. 가능하면 격리된 대상 또는 깨끗한 대상에 복원하여 복구된 상태를 손상된 사본과 비교하세요.

백업을 열 때 필요한 암호화 비밀번호 또는 비상 복구 키트는 실패한 호스트 외부에 보관하세요. 같은 디스크에만 존재하거나 복호화할 수 없는 백업은 복구 경로를 제공하지 못합니다.

ZimaSpace의 Home Assistant 복구를 스토리지 호스트 자체와 분리한 사례도 같은 원칙을 보여줍니다. 애플리케이션 상태에는 단순히 실시간 디스크를 미러링하는 것뿐 아니라 독립적인 복원 경로가 필요합니다.

삭제하기 전에 복구된 컨테이너 검증하기

• 예상한 사용자, 대시보드, 통합 구성 요소, 자동화, 헬퍼, 영역이 모두 있는지 확인하세요.
• Zigbee, Z-Wave 또는 Bluetooth를 사용한다면 로컬 장치 경로 하나와 무선 기반 경로 하나가 작동하는지 확인하세요.
• Recorder에서 데이터베이스 또는 마이그레이션 오류를 확인하세요.
• 복구된 컨테이너를 다시 시작하고 동일한 상태가 다시 나타나는지 확인하세요.
• 두 번째 부팅이 성공할 때까지 이전 이미지 태그, 설정 사본, 마지막으로 정상 작동한 백업을 보관하세요.

원래 설정으로 이전 이미지가 작동한다면 실패한 업데이트는 주로 런타임 또는 버전 문제였습니다. 동일한 상태에서 모든 이미지가 실패한다면 설정 복구 또는 백업 복원으로 진행하세요. 빈 /config에서만 깨끗한 컨테이너가 작동한다면, 영구 상태의 어떤 요소가 복구를 방해하는지 파악하기 전까지 새 설정을 “해결된 상태”로 받아들이지 마세요.

자주 묻는 질문

문제를 해결하기 전에 실패한 Home Assistant 컨테이너를 삭제해야 하나요?

아니요. 먼저 중지하고 런타임 정의와 마운트된 설정 경로를 보존하세요. 실패한 컨테이너를 삭제하지 않고도 교체 컨테이너를 만들 수 있으므로, 새 런타임이 정상적으로 작동하는지 확인하는 동안 롤백 정보도 유지할 수 있습니다.

업데이트 후 Home Assistant에 온보딩 화면이 표시되는 이유는 무엇인가요?

컨테이너에서 가장 흔한 원인은 교체된 런타임이 원래 /config 경로를 인식하지 못하는 것입니다. 설정이 삭제되었다고 판단하거나 이전 백업을 최신 상태 위에 복원하기 전에 호스트 마운트를 확인하세요.