FAQ
사용자
관리자 비밀번호를 어떻게 재설정하나요?
관리자 비밀번호는 immich-server 에서 reset-admin-password 명령어를 실행하여 재설정할 수 있습니다.
Immich에서 모든 사용자의 목록을 어떻게 볼 수 있나요?
immich-server에서 list-users 명령어를 실행하면 모든 사용자의 목록을 볼 수 있습니다.
모바일 앱
모바일 앱에 있는 클라우드 아이콘의 차이는 무엇인가요?
| 아이콘 | 설명 |
|---|---|
 | 에셋은 서버에만 있으며 다른 기기(웹 클라이언트 등)에서 업로드되었거나 업로드 후 이 기기에서 삭제되었습니다. |
 | 에셋은 로컬에만 있으며 아직 백업되지 않았습니다. |
 | 에셋은 이 기기에서 업로드되었고 이제 서버에 백업되었습니다. 원본 파일은 여전히 기기에 있습니다. |
업데이트 후 애플리케이션에 로그인할 수 없습니다. 어떻게 해야 하나요?
모바일 앱과 서버 모두 동일한 버전(주 버전 및 부 버전)을 실행하고 있는지 확인하세요.
앱스토어 업데이트는 때때로 시간이 더 걸릴 수 있습니다. 이는 스토어(구글 플레이 스토어 및 애플 앱 스토어)가 먼저 업데이트를 승인해야 하고 시간이 걸릴 수 있기 때문입니다.
앱에 계속 로그인할 수 없으면 다음을 시도하세요:
- 모바일 로그 확인
- 로그인 정보가 올바른지 웹 앱에서 확인
왜 앱에서 벗어날 때 전경 백업이 멈추나요? 작업이 백그라운드 백업으로 전환되어야 하지 않나요?
전경 백업과 백그라운드 백업은 별개의 메커니즘입니다. 서로 통신하거나 상호작용하지 않습니다.
전경 백업은 사용자의 행동에 의해 제어되며, 백그라운드 백업은 기기의 운영 체제가 제어합니다. 앱이 백그라운드로 전환되면 백그라운드 작업 호출이 기기의 운영 체제 스케줄러에게 위임되어 언제 백그라운드 작업을 실행하고 얼마나 오래 실행할지를 결정합니다.
제조사와 운영 체제에 따라 동작이 다르지만 대부분 배터리 절약 정책과 관련이 있습니다.
왜 iOS에서 백그라운드 백업이 작동하지 않나요?
iOS(아이폰 및 아이패드)에서는 운영 체제가 여러 요인을 바탕으로 특정 앱이 백그라운드 작업을 호출할 수 있는지 결정합니다. 이에 따라 Immich 앱이 많은 제어권을 가지지 못합니다. 백그라운드 백업 작업 실행 가능성을 높이려면 아래 단계를 따르세요:
- iOS 설정에서
설정 > 일반 > 백그라운드 앱 새로고침에서 Immich의 백그라운드 앱 새로고침을 활성화하세요. - 필요하지 않을 때 저전력 모드를 비활성화하세요. 이는 앱의 백그라운드 실행을 방지할 수 있습니다.
- 백그라운드 작업 실행이 필요하지 않은 앱의 백그라운드 앱 새로고침을 비활성화하세요. 이는 Immich의 백그라운드 작업 호출 경쟁을 줄여줍니다.
- Immich 앱을 더 자주 사용하세요.
왜 모바일 앱 기능이 자체 서명 인증서, 기본 인증, 맞춤 헤더, 또는 상호 TLS를 사용할 때 작동하지 않나요?
이 네트워크 기능은 실험적인 상태입니다. 종종 비디오 재생, 에셋 업로드 또는 다운로드와 기타 기능에서 작동하지 않습니다. 이러한 제한 사 항 중 많은 부분은 #15230에서 추적됩니다. 이 실험적인 기능 대신 URL 전환 기능, VPN 또는 도메인을 위한 무료 신뢰할 수 있는 SSL 인증서 사용을 권장합니다.
이러한 기능은 적극적으로 개발되지 않으며 지원을 제공할 수는 없지만 이를 개선하기 위한 기여는 환영합니다. 큰 PR은 개발팀과 논의하여 시간을 낭비하지 않도록 해주세요.
왜 모바일 앱이 아직 업데이트되지 않았나요?
앱스토어는 새 앱 빌드를 승인하는 데 며칠이 걸릴 수 있습니다. 기다리기 어려운 경우, GitHub 릴리스에서 Android APK를 다운로드할 수 있습니다.
에셋
Immich가 파일을 변경하나요?
아니요, Immich는 원본 파일을 수정하지 않습니다.
편집된 메타데이터는 .xmp 사이드카 파일 및 데이터베이스에 저장됩니다.
단, Immich는 휴지통 이 UI에서 비워질 때 해당 기기에서 삭제된 원본 파일을 제거합니다.
...
Docker에서 CIFS/Samba 볼륨을 어떻게 마운트할 수 있나요?
호스트에서 Samba를 마운트할 수 없거나 Windows 환경과 같이 비선호할 경우 Docker 내에서 볼륨을 마운트할 수 있습니다.
아래는 docker-compose.yml의 예제입니다.
사용자 이름, 비밀번호, 로컬 IP 및 공유 이름을 변경하세요. 아래에서 - originals:/usr/src/app/originals 줄은 볼륨 originals가 생성된 섹션과 연결됩니다.
이 이름은 원하는 대로 지정할 수 있으며, Docker 컨테이너에 원하는 방식으로 매핑할 수 있습니다.
예를 들어, originals:를 Photos:로 변경하고, - originals:/usr/src/app/originals를 Photos:/usr/src/app/photos로 변경할 수 있습니다.
...
services:
immich-server:
...
volumes:
# 다음 줄을 편집하지 마세요. 시스템의 미디어 저장 위치를 변경하려면 .env 파일의 UPLOAD_LOCATION 값을 편집하십시오
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- /etc/localtime:/etc/localtime:ro
+ - originals:/usr/src/app/originals
...
volumes:
model-cache:
+ originals:
+ driver_opts:
+ type: cifs
+ o: 'iocharset=utf8,username=USERNAMEHERE,password=PASSWORDHERE,rw' # 읽기 전용을 원할 경우 'ro'로 변경하세요
+ device: '//localipaddress/sharename'
앨범
기존 앨범 구조를 유지하면서 Immich에 자산을 가져올 수 있나요?
네, Immich CLI를 --album 플래그와 함께 사용하면 가능합니다.
앨범 내에서 사진 순서를 변경할 수 있는 방법이 있나요?
아직 없습니다. 이 계획된 기능의 업데이트는 GitHub 논의를 팔로우하세요.
외부 라이브러리
기존 앨범 구조를 유지하면서 외부 라이브러리를 추가할 수 있나요?
외부 라이브러리에서 앨범을 생성하는 공식적인 메커니즘은 구현되지 않았지만 이를 달성하기 위한 몇 가지 커뮤니티의 우회 방법이 있습니다.
외부 라이브러리에서 중복 발생 시 어떻게 처리되나요?
중복 확인은 파일 해시를 사용하여 업로드 라이브러리에서만 존재합니다. 게다가 중복 확인은 글로벌 확인이 아닌 _각 라이브러리별_로 작동합니다. 따라서 동일한 파일이 타임라인에 두 번 나타나는 상황이 발생할 수 있으며, 특히 외부 라이브러리에서 발생할 가능성이 있습니다.
읽기 전용 외부 라이브러리에서 파일 편집이 저장되지 않는 이유는?
읽기/쓰기 외부 라이브러리(기본값)에서는 이미지를 정상적으로 편집할 수 있습니다.
읽기 전용 라이브러리(:ro가 docker-compose.yml에 사용된 경우)에서는 Immich가 편집된 파일 메타데이터를 저장하기 위해 .xmp 사이드카 파일을 생성할 수 없습니다.
이로 인해, 읽기 전용 외부 라이브러리의 파일에 대한 메타데이터(타임스탬프, 위치, 설명, 별점 등)를 편집할 수 없습니다.
외부 라이브러리의 파일 삭제는 어떻게 처리되나요?
Immich는 휴지통을 비웠을 때 삭제된 원본 파일을 삭제하려고 시도합니다.
읽기/쓰기 외부 라이브러리(기본값)에서는 Immich가 원본 파일을 삭제합니다.
읽기 전용 라이브러리(:ro가 docker-compose.yml에 사용된 경우)에서는 UI에서 파일을 휴지통에 보낼 수는 있지만, 휴지통을 비울 때 원본 파일을 삭제할 수 없기 때문에 해당 파일들이 메인 타임라인에 다시 나타납니다.
머신 러닝
스마트 검색은 어떻게 작동하나요?
Immich는 CLIP 모델을 사용합니다. 머신러닝 모델은 각 이미지를 '임베딩'으로 변환하며, 이것은 이미지에 포함된 내용을 의미적으로 인코딩한 숫자 문자열입니다. 검색을 할 때 입력하는 텍스트에도 동일한 작업이 수행되며, 해당 텍스트 임베딩은 이미지의 임베딩과 비교하여 유사한 이미지를 찾아냅니다. 따라서 사용자가 볼 수 있는 '태그', '레이블', '설명'은 생성되지 않습니다. CLIP 및 그 기능에 대한 자세한 내용은 여기를 참조하세요.
얼굴 인식은 어떻게 작동하나요?
얼굴 인식 작동 방법를 참조하세요.
머신 러닝을 비활성화하려면 어떻게 해야 하나요?
머신 러닝을 비활성화하면 검색 및 '탐색' 페이지에서의 경험이 저하됩니다. 이는 머신 러닝을 기반으로 제대로 작동하기 때문입니다.
관리 > 설정 > 머신 러닝 설정에서 완전히 또는 특정 모델 유형별로 머신 러닝을 비활성화할 수 있습니다. 예를 들어, CLIP을 사용한 스마트 검색을 비활성화하고 얼굴 인식을 활성화 상태로 유지할 수 있습니다. 이렇게 하면 머신 러닝 서비스가 활성화된 작업만 처리합니다.
그러나 모든 작업을 비활성화한다고 해도 머신 러닝 서비스를 자체적으로 비활성화하지는 않습니다. 이를 아예 시작하지 않도록 하려면 docker-compose.yml의 immich-machine-learning 섹션을 주석 처리하면 됩니다.
모델이 손상되거나 다운로드에 실패했다는 오류를 받습니다. 어떻게 해야 하나요?
모델이 다운로드되는 모델 캐시 볼륨을 삭제할 수 있습니다. 이렇게 하면 서비스가 다시 모델을 다운로드할 수 있는 깨끗한 환 경을 제공합니다. 모델이 다운로드에 완전히 실패한 경우 Hugging Face에서 직접 다운로드하여 캐시 폴더에 배치할 수 있습니다.
커스텀 CLIP 모델을 사용할 수 있나요?
아니요, 지원되지 않습니다. Hugging Face 페이지에 나열된 모델만 호환됩니다. 여기에 나열되지 않은 모델을 추가해야 한다고 생각되는 경우 기능 요청을 보내주십시오.
영어 이외의 다른 언어로 검색할 수 있는 방법이 있나요?
다국어 CLIP 모델로 변경할 수 있습니다. 자세한 방법은 여기를 참조하세요.
Immich는 비디오에 대한 얼굴 인식을 지원하나요?
Immich의 머신 러닝 기능은 생성된 썸네일에서 작동합니다. 비디오 썸네일에서 얼굴이 보이는 경우 얼굴 인식에 포착됩니다. 비디오 전체를 스캔하여 얼굴을 찾는 기능은 추후에 구현될 수 있습니다.
Immich에 동물 인식 기능이 있나요?
아니요.
일정 수준까지는 스마트 검색을 사용할 수 있습니다. 예를 들어, 골든 리트리버나 치와와를 가지고 있다면 스마트 검색에 이 단어를 입력하고 결과를 확인해보세요.
'얼굴'이 아닌 많은 이미지를 얼굴로 인식합니다. 어떻게 해야 하나 요?
MIN DETECTION SCORE를 0.8로 증가시켜 잘못된 썸네일을 방지할 수 있습니다. 점수를 너무 높게 설정하면(0.9 이상) 사용된 라이브러리에 따라 실제 얼굴까지 필터링될 수 있습니다. 특정 얼굴만 숨기고 싶다면, 관리 패널의 'MIN FACES DETECTED' 설정을 조정하여 해당 개인의 '핵심 얼굴'로 간주되는 기준을 높여 잘못된 썸네일이 선택될 가능성을 줄일 수 있습니다.
immich_model-cache 볼륨이 많은 저장 공간을 차지합니다. 문제가 무엇일 수 있나요?
여러 모델을 설치하고 일부를 사용하지 않기로 결정한 경우 immich_model-cache에 있는 사용하지 않는 오래된 모델을 삭제하는 것이 좋습니다. 이를 수행하려면 모델 캐시를 마운트하고 원하지 않는 모델을 제거하면 됩니다.
단계
docker run -it --rm -v immich_model-cache:/mnt-models alpine sh
cd /mnt-models
ls clip/ facial-recognition/
# rm -r clip/ABC facial-recognition/DEF # 사용하지 않는 모델 삭제
성능
왜 Raspberry Pi와 같은 저메모리 시스템에서 Immich가 느리게 작동하나요?
Immich는 여러 기능을 위해 트랜스코딩 및 머신 러닝을 선택적으로 사용합니다. 하지만 Raspberry Pi에서는 너무 무거울 수 있습니다. 이를 완화하거나 Immich의 머신 러닝 컨테이너를 더 강력한 시스템에 호스팅하거나 머신 러닝을 완전히 비활성화할 수 있습니다.
CPU와 RAM 사용률을 낮출 수 있나요?
초기 백업은 실행 중인 작업 수가 많기 때문에 가장 집중적입니다. 가장 CPU 집약적인 작업은 트랜스코딩과 머신 러닝 작업(스마트 검색, 얼굴 검출), 그리고 썸네일 생성 작업입니다. CPU 사용량을 낮추는 몇 가지 방법:
- 이러한 작업을 위한 작업 동시성을 1로 낮춥니다.
- 설정 > 트랜스코딩 설정 > 스레드에서 스레드 수를 1 또는 2로 낮은 값으로 설정합니다.
- 설정 > 머신 러닝 설정 > 얼굴 인식 > 모델 이름에서 얼굴 인식 모델을
buffalo_l대신buffalo_s로 변경할 수 있습니다. 후자는 더 작고 빠른 모델이지만 성능은 약간 떨어집니다.- 새 이미지에서 얼굴 인식이 제대로 작동하려면 모든 이미지에 대해 얼굴 검출 작업을 다시 실행해야 합니다.
- 컨테이너 수준에서 리소스 제한 설정을 적용하여 추가적으로 사용량을 낮출 수 있습니다.
- 성능을 최상으로 하기 위해 이 변경 조치를 적용한 후에만 제한을 적용하는 것이 좋습니다.
- 이러한 변경이 충분하지 않은 경우, 머신 러닝을 비활성화하는 방법에 대한 지침은 위를 참조하세요.
CPU와 RAM 사용량 제한이 가능하나요?
기본적으로 컨테이너는 리소스 제한이 없으며 호스트의 커널 스케줄러가 허용하는 만큼의 리소스를 사용할 수 있습니다. 이를 제한하려면 제한하려는 컨테이너의 docker-compose.yml 블록에 다음을 추가할 수 있습니다.
docker-compose.yml
deploy:
resources:
limits:
# CPU 스레드 수
cpus: '1.00'
# 메모리 크기 (기가바이트)
memory: '1G'
더 자세한 정보는 원본 Docker 문서 또는 이 가이드를 참조하세요.
메모리 제한은 컨테이너를 종료시킴으로 작동하므로 너무 낮게 설정하면 불안정성을 초래할 수 있습니다.
머신 러닝 속도를 어떻게 높일 수 있나요?
이 조언은 처리량을 개선하며 지연 시간을 개선하는 것은 아닙니다. 이는 스마트 검색 작업을 더 빨리 처리하게 하지만, 검색 속도를 높이는 것은 아닙니다.
머신 러닝 작업(스마트 검색, 얼굴 검출)에 대한 작업 동시성을 높임으로써 처리량을 증가시킬 수 있습니다. 동시성을 높이면 호스트가 더 많은 자산을 병렬로 작업할 수 있습니다. 관리 > 설정 > 작업 설정으로 이동하여 필요에 따라 동시성을 높일 수 있습니다.
일반적인 기계에서는 2~3개의 동시 작업이 CPU를 최대한 활용할 수 있습니다. HDD를 사용할 때 저장 장치의 속도와 지연 시간이 이보다 더 중요한 제한 요소가 될 수 있습니다.
GPU를 사용하면 동시성을 좀 더 편안하게 늘릴 수 있지만, 대부분의 경우 16을 초과해서는 안 됩니다.
작업 동시성을 과도하게 설정하면 서버에 과부하가 걸릴 가능성이 높습니다.
내 서버 상태가 서버 상태 오프라인 | 버전 알 수 없음으로 표시됩니다. 무엇을 해야 하나요?
리버스 프록시에서 WebSockets를 활성화해야 합니다.
Docker
Immich 로그를 어떻게 볼 수 있나요?
Immich 구성 요소는 일반적으로 Docker를 사용하여 배포됩니다. 배포된 Docker 컨테이너의 로그를 보려면 Docker CLI의 docker logs 명령을 사용할 수 있습니다. 예제는 Docker 도움말을 참조하세요.
Redis 로그의 상세 수준을 줄이는 방법은 무엇인가요?
Redis 로그를 줄이려면 docker-compose.yml의 redis: 섹션에 다음 줄을 추가하면 됩니다:
command: redis-server --loglevel warning
Immich를 비루트(non-root) 사용자로 실행하려면 어떻게 해야 하나요?
컨테이너의 사용자를 변경하려면 각 서비스에 대해 docker-compose.yml에서 user 인수를 설정할 수 있습니다.
다음의 내부 컨테이너 경로에 대해 마운트 포인트나 Docker 볼륨을 추가해야 할 수도 있습니다:
immich-machine-learning:/.configimmich-machine-learning:/.cacheredis:/data
비루트 사용자/그룹은 UPLOAD_LOCATION 및 머신러닝을 위한 /cache를 포함하여 볼륨 마운트 지점에 대한 읽기/쓰기 접근 권한이 필요합니다.
Docker Compose 최상위 볼륨 요소는 비루트 접근을 지원하지 않습니다. 위의 모든 볼륨은 로컬 볼륨 마운트여야 합니다.
더 강화된 시스템을 위해 모든 컨테이너에 다음 블록을 추가할 수 있습니다.
docker-compose.yml
security_opt:
# 컨테이너 시작 후 권한 증가 방지
- no-new-privileges:true
cap_drop:
# 원시 네트워크 트래픽에 대한 접근 차단
- NET_RAW
Immich에서 데이터를 삭제하려면 어떻게 해야 하나요?
Immich 데이터는 두 가지 형태로 존재합니다:
- 메타데이터:
DB_DATA_LOCATION폴더에 저장된 Postgres 데이터베이스에 저장되며, 이전에는pg_dataDocker 볼륨에 저장되었습니다. - 파일(원본, 썸네일, 프로필 등):
UPLOAD_LOCATION폴더에 저장되며, 더 많은 정보를 확인할 수 있습니다.
이는 데이터베이스를 삭제하고 인스턴스를 재설정하여 처음부터 새로 시작하게 만듭니다.
docker compose down -v
컨테이너와 볼륨을 제거한 후 Immich를 새 설치로 재설정하려면 몇 가지 디렉토리를 삭제해야 합니다. 해당 디렉토리를 삭제하면 Immich를 다시 시작할 수 있으며 새 설치로 설정됩니다.
DB_DATA_LOCATION: 데이터베이스, 미디어 정보 및 설정을 포함합니다.UPLOAD_LOCATION: Immich에 업로드된 모든 미디어를 포함합니다.
Portainer를 사용하는 경우 Portainer에서 스택을 종료합니다. 그런 다음 볼륨 섹션으로 이동하여 Immich와 관련된 모든 볼륨을 제거한 후 스택을 재시작합니다.
머신러닝 서비스가 작업자 충돌을 보고하는 이유는 무엇인가요?
작업자가 종료된다는 오류라면 정상입니다. 이것은 서비스가 사용되지 않을 때 RAM 소비를 줄이기 위한 기능입니다.
이런 문제가 발생할 수 있는 몇 가지 이유가 있습니다.
SIGKILL 또는 오류 코드 137이 언급된 경우, 이는 서비스가 메모리가 부족하다는 것을 의미할 가능성이 높습니다. 서버의 RAM을 증가시키거나 RAM이 더 많은 서버로 서비스를 이동하는 것을 고려하세요.
SIGILL (K가 없는 것) 또는 오류 코드 132가 언급된 경우, 이는 서버의 CPU 가 Immich와 호환되지 않을 가능성이 높습니다.
데이터베이스
데이터베이스 소유권 오류를 받는 이유는 무엇인가요?
만약 FATAL: data directory "/var/lib/postgresql/data" has wrong ownership와 같은 데이터베이스 오류를 받는다면, 이는 파일 시스템 문제로 인해 발생했을 가능성이 높습니다.
NTFS와 ex/FAT/32 파일 시스템은 지원되지 않습니다. 더 자세한 내용은 여기를 참조하세요.
데이터베이스 무결성을 확인하려면 어떻게 해야 하나요?
v1.104.0에서부터 새로운 설치에는 기본적으로 데이터베이스 체크섬이 활성화되어 있습니다. 다음 명령을 실행하여 활성화 여부를 확인할 수 있습니다.
on이 라는 결과가 나오면 체크섬이 활성화된 상태를 의미합니다.
체크섬 활성화 여부 확인
docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="show data_checksums"
data_checksums
----------------
on
(1 row)
체크섬이 활성화된 경우, 다음 명령을 사용하여 데이터베이스 상태를 확인할 수 있습니다. 정상적인 결과는 모두 0으로 나옵니다.
데이터베이스 손상 확인
docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="SELECT datname, checksum_failures, checksum_last_failure FROM pg_stat_database WHERE datname IS NOT NULL"
datname | checksum_failures | checksum_last_failure
-----------+-------------------+-----------------------
postgres | 0 |
immich | 0 |
template1 | 0 |
template0 | 0 |
(4 rows)
Postgres 데이터베이스 파일 구조에서 오류를 탐지하려면 다음 명령을 사용할 수도 있습니다:
파일 구조 오류 검사
docker exec -it immich_postgres pg_amcheck --username=<DB_USERNAME> --heapallindexed --parent-check --rootdescend --progress --all --install-missing
정상적인 결과는 다음과 유사하게 끝나며 0이라는 종료 코드가 반환됩니다:
7470/8832 relations (84%), 730829/734735 pages (99%)
8425/8832 relations (95%), 734367/734735 pages (99%)
8832/8832 relations (100%), 734735/734735 pages (100%)
손상이 발견되면 데이터베이스에서 작업을 수행하기 전에 반드시 백업을 해야 합니다.
이 작업을 수행하려면 pg_dumpall이 성공하도록 데이터베이스 서버에 zero_damaged_pages=on 플래그를 설정해야 할 수도 있습니다.
백업을 수행한 후, 추천되는 다음 단계는 손상이 발견되기 전의 건강한 백업에서 데이터베이스를 복원하는 것입니다.
필요할 경우 손상된 데이터베이스 덤프를 사용하여 마지막 백업 이후의 변경 사항을 수동으로 복구할 수 있습니다.
손상의 가능한 원인은 많지만, 예기치 않은 전원 차단이나 마운트 해제, Postgres 데이터에 네트워크 공유를 사용, 또는 SD 카드나 고장난 HDD/SSD와 같은 열악한 저장 매체 를 포함할 수 있습니다.