셀프 호스팅 갤러리에서 HEIC 사진의 미리보기가 사라지는 원인은 무엇인가요?

갤러리가 원본을 디코딩하거나 파생 이미지를 생성하거나 해당 파생 이미지를 현재 클라이언트에 전달하지 못하면 HEIC 미리보기가 사라집니다.

셀프 호스팅 갤러리는 일반적으로 HEIC 원본을 보존하면서, 모든 HEIF 프로필을 직접 표시하지 못할 수 있는 브라우저와 휴대폰을 위해 JPEG 또는 WebP 썸네일과 미리보기를 생성합니다. 타임라인이 비어 있어도 원본을 다운로드할 수 있는 이유는 손상, 새 휴대폰 인코딩 프로필, 매우 큰 해상도, 디코더 지원 누락, 작업자 작업 실패, 오래된 썸네일 기록 또는 클라이언트 측 원본 로딩 문제가 파생 이미지 경로에만 영향을 주기 때문일 수 있습니다. 원본 바이트부터 생성된 미리보기까지 하나의 자산을 기준으로 진단하세요.

원본 HEIC 파일이 정상인지 확인

갤러리에서 원본을 다운로드한 뒤 휴대폰, 내보낸 파일 또는 백업본과 크기와 해시를 비교하세요. HEIC를 지원하는 신뢰할 수 있는 데스크톱 애플리케이션에서 파일을 열어 보세요.

Immich 사용자들은 HEIC 및 DNG를 업로드한 뒤 썸네일과 미리보기가 더 이상 생성되지 않았다고 보고했습니다. 따라서 손상된 원본과 실패한 파생 이미지 파이프라인을 구분하는 것이 중요합니다. 눈에 보이는 증상은 업로드 후 썸네트가 사라지는 현상이었습니다.

다운로드한 원본이 잘렸거나 손상된 경우 전송 경로를 복구하고 검증된 소스에서 다시 업로드하세요. 원본이 정상적으로 열리면 원본을 보존한 채 메타데이터, 디코더 및 작업 수준 점검을 계속 진행하세요.

정상 작동하는 HEIC와 실패하는 HEIC의 메타데이터 비교

미리보기가 생성되는 HEIC 파일 하나와 생성되지 않는 파일 하나를 선택하세요. 기기 모델, 운영체제 버전, 해상도, 비트 심도, 색상 프로필, 보조 이미지, 방향, HDR 메타데이터, 파일 크기 및 컨테이너 브랜드를 비교하세요.

새 휴대폰 소프트웨어에서 현재 서버 디코더가 이해하지 못하는 프로필이 추가될 수 있습니다. 한 Immich 이슈에서는 iOS 18 HEIC 파일에서 잘못된 헤더 메시지와 함께 썸네일 생성이 실패했지만 이전 iOS 이미지는 정상적으로 작동했습니다. 이를 통해 새로운 소스 프로필 차이를 확인할 수 있었습니다.

실패 원인을 분류하기 위한 목적으로만 카메라 설정을 변경한 뒤 같은 휴대폰으로 찍은 다른 사진을 테스트하세요. 호환되지 않는 프로필과 서버 버전을 확인하기 전에는 원본 라이브러리를 변환하거나 덮어쓰지 마세요.

이미지 해상도 및 리소스 제한 확인

문제가 발생한 이미지의 너비, 높이, 메가픽셀, 파일 크기 및 포함된 보조 이미지를 기록하세요. 매우 큰 HEIC 파일은 압축된 파일 크기에서 예상되는 것보다 디코딩 중 훨씬 많은 메모리를 요구할 수 있습니다.

Immich에서는 썸네일을 생성하거나 미리보기를 표시할 수 없는 2억 화소 HEIC 파일 사례가 문서화되었습니다. 실제 경계는 일반적인 갤러리 탐색이 아니라 극도로 큰 HEIC 해상도였습니다.

파일 하나를 처리하는 동안 썸네일 작업자의 메모리, CPU, 컨테이너 제한 및 메모리 부족 이벤트를 모니터링하세요. 작은 HEIC 이미지가 정상 작동한다면 지원되는 작업자 리소스를 늘리거나, 전체 해상도 원본을 폐기하지 않고 호환 가능한 미리보기 사본을 유지하세요.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

썸네일 작업자의 첫 번째 디코딩 오류 확인

영향을 받은 자산 하나에 대해 누락된 썸네일 생성 또는 재생성 작업을 실행하고 마이크로서비스나 작업자 로그를 추적하세요. 최종적인 일반 오류가 아니라 최초의 디코더, 헤더, 색 공간, 권한 또는 쓰기 오류를 기록하세요.

최근 Immich 보고에서도 업그레이드 후 특정 HEIC 파일의 썸네일 생성이 계속 실패하는 사례가 나타났습니다. 2026년 이슈 하나에서는 업그레이드와 관련된 HEIC 처리 실패를 확인했습니다.

첫 번째 HEIC 오류 이후 새 파일이 모두 실패한다면 로그를 보존한 뒤 실패한 작업자만 재시작하고 대기열 상태를 확인하세요. 단일 손상 자산 때문에 작업자 프로세스 자체가 이후 모든 미리보기 생성을 중단했는지 여부가 가려져서는 안 됩니다.

디코더 라이브러리 및 버전 호환성 확인

갤러리 버전, 컨테이너 이미지, 이미지 처리 라이브러리, HEIF 디코더, CPU 아키텍처 및 업데이트 중 하드웨어별 빌드가 변경되었는지 기록하세요. 마지막으로 정상 작동한 배포와 비교하세요.

일부 HEIC 오류는 하나의 서버 버전 안에서도 일부 이미지에만 영향을 줍니다. 한 Immich 이슈에서는 특정 HEIC 파일만 실패했다고 보고되어, HEIC 지원이 완전히 없는 것이 아니라 형식 기능의 경계에서 발생한 문제임을 보여 줍니다.

동일한 원본을 이전 애플리케이션 버전 또는 격리된 현재 작업자 이미지로 테스트하세요. 일관된 데이터베이스 및 구성 백업이 있을 때만 롤백하세요. 이미지 디코더를 테스트하기 위해 운영 데이터베이스를 무작정 다운그레이드하지 마세요.

서버 미리보기 실패와 클라이언트 원본 로딩 문제 구분

영향을 받은 자산을 웹 클라이언트, 모바일 앱 및 시크릿 브라우저 세션에서 열어 보세요. 타임라인 썸네일, 중간 크기 미리보기, 전체 크기 파생 이미지 및 원본 다운로드가 서로 독립적으로 실패하는지 기록하세요.

브라우저가 원본 HEIC를 표시하지 못하더라도 생성된 미리보기는 정상적으로 작동할 수 있습니다. 한 Immich Safari 이슈에서는 원본 HEIC 로딩이 실패했지만 클라이언트가 미리보기 또는 전체 크기 파생 이미지로 대체할 수 있었습니다.

한 클라이언트에서만 실패한다면 해당 클라이언트의 캐시된 자산 응답을 지우고 원본 로딩 설정을 비교하세요. 모든 클라이언트에서 썸네일이 없고 작업자 로그에도 생성된 파일이 표시되지 않는다면 서버 측 문제를 계속 진단하세요.

원인을 해결한 후 누락된 파생 이미지만 재생성

데이터베이스와 메타데이터 볼륨을 백업한 뒤, 영향을 받은 소규모 자산 집합에 애플리케이션의 누락된 썸네일 작업을 실행하세요. 원본을 교체하지 않고 새 파생 이미지를 생성하는지 확인하세요.

Immich 릴리스에서는 썸네일 관련 수정 후 썸네일이 손상된 사용자에게 누락된 썸네일 작업을 실행하도록 안내해 왔습니다. 이는 전체 썸네일 저장소를 먼저 삭제하기보다 문제 해결 후 대상을 지정해 재생성하는 방식을 뒷받침합니다.

ZimaSpace의 비공개 iPhone 사진 백업 가이드는 갤러리 미리보기와 별도로 원본 사진을 보존하고 검증해야 한다는 관련 요구 사항을 설명합니다.

원본 해시가 변경되지 않고, 작업자가 문제가 발생한 HEIC 프로필의 썸네일을 생성하며, 지원되는 모든 클라이언트에서 파생 이미지를 로드하고, 같은 휴대폰에서 새로 찍은 사진도 전체 라이브러리를 다시 구축하지 않고 정상 처리되면 문제가 해결된 것입니다.