메인 콘텐츠로 바로가기

외부 라이브러리

외부 라이브러리는 Immich 외부 파일 시스템에 저장된 자산을 추적합니다. 외부 라이브러리가 스캔되면 Immich는 디스크에서 비디오와 사진을 로드하여 해당 자산을 생성합니다. 이러한 자산은 기본 타임라인에서 표시되며, 지도에서 보기, 앨범에 추가 등 다른 자산과 동일하게 보이고 작동합니다. 나중에 Immich 외부에서 파일이 수정되면 변경 사항을 표시하려면 라이브러리를 스캔해야 합니다.

외부 자산이 디스크에서 삭제되면 Immich는 다시 스캔할 때 해당 자산을 휴지통으로 이동시킵니다. 자산을 복원하려면 원본 파일을 복원해야 합니다. 30일 후 파일은 휴지통에서 제거되며 Immich 내에서 메타데이터의 변경 사항은 소실됩니다.

주의

외부 자산에 메타데이터를 추가하는 경우(예: 앨범에 추가하거나 설명을 편집), 해당 메타데이터는 Immich 내부에만 저장되며 외부 자산 파일에 영구적으로 저장되지 않습니다. 라이브러리 내에서 자산을 다른 위치로 이동하면 해당 메타데이터는 다시 스캔할 때 모두 소실됩니다. 이는 해당 자산이 이동 후 새로운 자산으로 간주되기 때문입니다. 이는 알려진 문제이며 향후 릴리스에서 수정될 예정입니다.

주의

과도한 캐싱으로 인해 새로고침된 파일이 웹 보기에서 올바르게 나타나기까지 시간이 걸릴 수 있습니다. 브라우저의 캐시를 지워야 변경 사항을 볼 수 있습니다. 이는 알려진 문제이며 향후 릴리스에서 수정될 예정입니다. Chrome에서는 F12 키를 눌러 개발자 콘솔을 열고, F5 키로 페이지를 다시 로드한 다음 오른쪽 클릭하여 '캐시 비우기 및 강력 새로고침'을 선택해야 합니다.

가져오기 경로

외부 라이브러리는 가져오기 경로를 사용하여 스캔할 파일을 결정합니다. 각 라이브러리는 여러 가져오기 경로를 가질 수 있어 다른 위치의 파일을 동일한 라이브러리에 추가할 수 있습니다. 가져오기 경로는 재귀적으로 스캔되며, 파일이 여러 가져오기 경로에 있다면 한 번만 추가됩니다. 각 가져오기 파일은 파일 시스템에서 존재하는 읽을 수 있는 디렉토리여야 하며, 가져오기 경로 대화 상자는 접근할 수 없는 경로를 경고합니다.

가져오기 경로를 편집하여 외부 파일이 더 이상 가져오기 경로에 포함되지 않는 경우, 삭제된 파일처럼 라이브러리에서 제거됩니다. 파일이 가져오기 경로로 다시 이동하면 마치 새 파일인 것처럼 다시 추가됩니다.

문제 해결

때때로 외부 라이브러리가 올바르게 스캔되지 않을 수 있습니다. Immich가 파일에 접근할 수 없는 경우 이러한 문제가 발생할 수 있습니다. 몇 가지 확인해야 할 사항:

  • docker-compose 파일에서 볼륨이 올바르게 마운트되었나요?
  • 볼륨이 워커 컨테이너에도 마운트되었나요?
  • 가져오기 경로가 올바르게 설정되어 있으며 docker-compose 파일의 경로와 일치하나요?
  • 가져오기 라이브러리에서 심볼릭 링크를 사용하지 않았는지, Docker 마운트를 건너뛰며 링크하지 않았는지 확인하세요.
  • 권한이 올바르게 설정되었나요?
  • 반드시 슬래시(/)를 사용하고, 백슬래시를 사용하지 않았는지 확인하세요.

Immich가 외부 라이브러리에 접근할 수 있는지 확인하려면 컨테이너 내부에서 셀을 시작하세요. docker exec -it immich_server bash 명령어를 실행하여 bash 셀을 엽니다. 가져오기 경로가 /data/import/photos인 경우 해당 위치를 ls /data/import/photos로 확인하세요. 동일한 확인을 모든 마이크로서비스 컨테이너에서 수행하세요.

제외 패턴

기본적으로 가져오기 경로의 모든 파일은 라이브러리에 추가됩니다. 추가되지 않아야 할 파일이 있는 경우 제외 패턴을 사용하여 제외할 수 있습니다. 제외 패턴은 전체 파일 경로에 대해 일치하는 glob 패턴입니다. 파일이 제외 패턴과 일치하면 라이브러리에 추가되지 않습니다. 제외 패턴은 각 라이브러리의 스캔 설정 페이지에서 추가할 수 있습니다.

기본적인 예:

  • **/*.tif는 확장자가 .tif인 모든 파일을 제외합니다.
  • **/hidden.jpg는 이름이 hidden.jpg인 모든 파일을 제외합니다.
  • **/Raw/**는 이름이 Raw인 디렉토리 내 모든 파일을 제외합니다.
  • **/*.{tif,jpg}는 확장자가 .tif 또는 .jpg인 모든 파일을 제외합니다.

@와 같은 특수 문자는 반드시 이스케이프해야 합니다. 예:

  • **/\@eaDir/**는 이름이 @eaDir인 디렉토리 내 모든 파일을 제외합니다.
정보

내부적으로 Immich는 제외 패턴을 처리하기 위해 glob 패키지를 사용하며, 때때로 이러한 패턴은 Postgres LIKE 패턴으로 변환됩니다. 의도는 기본 폴더 제외를 지원하는 것이지만 Postgres 구문으로 신뢰할 수 없을 정도로 번역될 수 있기 때문에 고급 사용을 권장하지 않습니다. glob 문서를 참조하여 glob 패턴에 대한 기본 개요를 살펴보세요.

자동 감시 (실험적 기능)

이 기능은 실험적이며 고급 사용자만을 위한 것입니다. 활성화하면 파일 시스템을 자동으로 감시하여 새 자산이 Immich에 자동으로 가져오기되며 다시 스캔이 필요하지 않습니다.

사진이 네트워크 드라이브에 있는 경우 자동 파일 감시가 작동하지 않을 가능성이 큽니다. 이 경우 주기적인 라이브러리 업데이트를 통해 변경 사항을 가져와야 합니다.

문제 해결

ENOSPC 오류가 발생하면 파일 감시자 제한을 늘려야 합니다. sysctl에서 이 키는 fs.inotify.max_user_watches라고 하며 기본값은 8192입니다. 파일 감시 수보다 큰 적합한 값으로 이 숫자를 늘리세요. 이때 Immich가 가져오기 경로 내 모든 파일을 감시해야 하며, 무시된 파일도 포함됩니다.

ERROR [LibraryService] Library watcher for library c69faf55-f96d-4aa0-b83b-2d80cbc27d98 encountered error: Error: ENOSPC: System limit for number of file watchers reached, watch '/media/photo.jpg'

드물게 라이브러리 감시자가 멈추어 Immich를 시작할 수 없게 되는 경우가 있습니다. 이 경우 구성 파일에서 라이브러리 감시자를 비활성화하세요. 감시자가 Immich 내부에서 활성화된 경우 앱은 마이크로서비스 없이 시작해야 합니다. docker-compose 파일에서 마이크로서비스를 비활성화하고, Immich를 시작한 후 관리 설정에서 라이브러리 감시자를 비활성화하고, Immich를 닫으며, 마이크로서비스를 다시 활성화하고, Immich를 정상적으로 시작할 수 있습니다.

야간 작업

하루에 한 번 실행되도록 예약된 자동 스캔 작업이 있습니다. 이 작업은 삭제 상태에 고착된 라이브러리를 청소합니다. 라이브러리 관리 페이지에서 "모든 라이브러리 스캔"을 클릭하여 정리를 직접 실행할 수 있습니다.

사용법

기존 갤러리를 Immich에 추가하는 구체적인 예를 보여드리겠습니다. 여기서 다음 폴더를 추가하려고 합니다:

  • /home/user/old-pics: 어린 시절 사진이 들어 있는 폴더.
  • /mnt/nas/christmas-trip: 크리스마스 여행 사진. 하위 폴더 /mnt/nas/christmas-trip/Raw에는 DSLR에서 직접 변환한 RAW 파일이 있습니다. 이 RAW 파일을 Immich에 가져오지 않으려고 합니다.
  • /mnt/media/videos: 같은 크리스마스 여행에서 촬영한 비디오.

먼저 라이브러리를 어떻게 구성할지 계획해야 합니다. 크리스마스 여행 사진은 RAW 파일을 제외하려고 하므로 별도의 라이브러리에 포함되어야 합니다. 비디오와 옛날 사진은 모든 파일을 가져오려고 하므로 동일한 라이브러리에 포함될 수 있습니다. 다른 폴더에 RAW 제외 패턴과 일치하는 파일이 없는 경우 세 개의 폴더를 동일한 라이브러리에 추가할 수도 있습니다.

Docker 볼륨 마운트

immich-server 컨테이너는 갤러리에 접근해야 합니다. docker-compose 파일을 다음과 같이 수정하세요:

docker-compose.yml
  immich-server:
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
+ - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
+ - /home/user/old-pics:/mnt/media/old-pics:ro
+ - /mnt/media/videos:/mnt/media/videos:ro
+ - /mnt/media/videos2:/mnt/media/videos2 # WARNING: Immich will be able to delete the files in this folder, as it does not end with :ro
+ - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # Windows 시스템에서 가져오기 경로.

ro 플래그는 볼륨에 대한 읽기 전용 접근만 허용합니다. 이는 웹 UI에서 이미지를 삭제하거나 라이브러리에 메타데이터 추가를 방지합니다 (XMP 사이드카).

정보

변경 사항을 등록하려면 docker compose up -d를 실행하세요. 컨테이너에서 마운트된 경로를 볼 수 있는지 확인하세요.

새 라이브러리 생성

이 작업은 Immich 관리자가 수행해야 합니다.

  • 오른쪽 상단에서 아바타를 클릭하세요.
  • Administration -> 외부 라이브러리 클릭.
  • 외부 라이브러리 생성... 클릭.
  • 누구에게 라이브러리를 소유할지 선택. 이후 변경할 수 없습니다.
  • /mnt/media/christmas-trip를 입력한 후 추가를 클릭하세요.
  • 저장 클릭.
  • 방금 만든 라이브러리의 드롭다운 메뉴를 클릭하세요.
  • 스캔 클릭.
  • 방금 만든 라이브러리의 드롭다운 메뉴를 클릭하세요.
  • 라이브러리 이름 변경을 클릭하고 "크리스마스 여행"으로 이름을 바꾸세요.

참고: Docker 컨테이너가 보는 모든 경로는 /mnt/media/christmas-trip 경로를 사용해야 하며 /mnt/nas/christmas-trip는 사용할 수 없습니다.

다음으로 RAW 파일을 필터링하기 위해 제외 패턴을 추가하겠습니다.

  • 방금 생성된 크리스마스 라이브러리의 드롭다운 메뉴를 클릭하세요.
  • 관리 클릭.
  • 스캔 설정 클릭.
  • 제외 패턴 추가 클릭.
  • **/Raw/** 입력 후 저장 클릭.
  • 저장 클릭.
  • 방금 만든 라이브러리의 드롭다운 메뉴 클릭.
  • 스캔 클릭.

크리스마스 여행 라이브러리가 이제 백그라운드에서 스캔됩니다. 이 작업 동안 비디오와 옛날 사진을 다른 라이브러리에 추가하겠습니다.

  • 외부 라이브러리 생성 클릭.
참고

오류가 발생하면 다른 외부 라이브러리의 이름을 변경해주세요. 이는 향후 릴리스에서 수정될 버그입니다.

  • 방금 생성된 라이브러리의 드롭다운 메뉴 클릭.
  • 가져오기 경로 수정 클릭.
  • 경로 추가 클릭.
  • /mnt/media/old-pics 입력 후 추가 클릭.
  • 경로 추가 클릭.
  • /mnt/media/videos 입력 후 추가 클릭.
  • 저장 클릭.
  • 스캔 클릭.

몇 초 안에 old-pics와 videos 폴더의 자산이 기본 타임라인에 표시됩니다.

폴더 보기

폴더 보기 기능은 파일 탐색기와 유사한 타임라인 외 추가 보기를 제공합니다. 이를 통해 라이브러리 내 폴더와 파일을 탐색할 수 있습니다. 이 기능은 정밀하게 큐레이션되고 커스터마이즈된 외부 라이브러리 또는 잘 구성된 저장소 템플릿에 유용합니다.

이 기능은 계정 설정 > 기능 > 폴더에서 활성화할 수 있습니다.

사용자 정의 스캔 간격 설정

참고

관리자만 이 작업을 수행할 수 있습니다.

Admin -> Settings -> External Library에서 외부 라이브러리 재스캔 트리거를 위한 사용자 정의 간격을 설정할 수 있습니다. 스캔 간격은 사전 설정 또는 cron 형식을 사용하여 설정할 수 있습니다. 자세한 정보는 Crontab Guru를 참조하세요.