작성자 Immich 셀프 호스팅: 6GB RAM 권장 및 업데이트 주의사항
Immich 운영 시 필요한 6GB RAM의 이유와 exit 137 메모리 부족 오류 해결법을 다룹니다. HTTPS 포트 2283 설정법과 v3 업데이트 시 pgvecto.rs 데이터베이스 호환성 문제 및 복구 절차를 상세히 안내합니다.
구축할 서비스
Immich는 Google Photos를 대체할 수 있는 자체 호스팅 사진 및 동영상 백업 서비스입니다. 카메라 롤을 백그라운드에서 업로드하는 모바일 앱을 제공하며, 타임라인, 앨범, 얼굴 인식, 그리고 별도의 태그 작업 없이도 "해변"이나 특정 인물을 찾아내는 머신러닝 기반 검색 기능을 갖추고 있습니다. 사용자가 소유한 VPS에서 직접 운영하므로 원본 파일은 자신의 디스크에 저장되며, 누구도 광고 목적으로 파일을 스캔하지 않습니다. 다른 대안과 고민 중이라면 PhotoPrism과 Immich 비교 문서를 통해 각 서비스의 최소 RAM 요구 사항, 모바일 앱 기능, 백업 명령어를 비교해 보시기 바랍니다.
설치는 프로젝트에서 제공하는 Docker Compose 파일을 사용하여 4개의 컨테이너를 띄우는 방식으로 진행되며, 이 과정은 10분 정도 소요됩니다. 이 가이드의 나머지 부분은 실제 운영 시 겪게 될 어려움을 다룹니다. 머신러닝 컨테이너는 소형 서버에서 메모리 점유율이 높고, 원본 파일은 디스크 용량을 빠르게 소모합니다. 또한 모바일 앱은 암호화되지 않은 HTTP 서버 연결을 거부하며, Immich는 잦은 업데이트로 인해 변경 사항이 발생하므로 주의 없이 docker compose pull를 실행하면 데이터베이스가 시작되지 않을 수 있습니다. 이러한 네 가지 요소를 신중하게 관리하면 Immich는 매우 안정적으로 동작하지만, 이를 무시하면 주말 내내 문제 해결에 시간을 쏟게 될 것입니다.
사전 요구 사항 및 주의 사항
- RAM: 공식 문서에서는 최소 6 GB, 권장 8 GB를 명시하지만, 4 GB와 스왑(swap) 조합을 절대적인 하한선으로 간주하십시오.
immich-server및 Postgres 컨테이너는 리소스를 적게 사용합니다.immich-machine-learning컨테이너는 메모리 점유율이 높으며, 검색 인덱스를 생성하기 위해 CLIP 및 얼굴 인식 모델을 RAM에 로드합니다. 2 GB 환경에서는 커널이 해당 프로세스를 강제 종료(OOM kill)합니다. 4 GB를 사용하더라도 스왑을 추가하십시오. - 디스크: 전체 라이브러리 용량보다 넉넉하게 할당하십시오. 원본 파일이 그대로 복사되며, Immich가 생성하는 썸네일과 미리보기 이미지로 인해 원본 대비 약 10–20%의 추가 공간이 필요합니다. 200 GB 규모의 사진 컬렉션이라면 300 GB 볼륨을 권장합니다. Postgres가 차지하는 용량은 상대적으로 작습니다.
- CPU: 최신 KVM VPS라면 충분하지만, CPU 기반의 머신러닝은 속도가 느립니다. 대량의 사진을 가져와 스마트 검색 인덱싱을 수행하면 백그라운드에서 몇 시간 동안 작업이 진행될 수 있습니다. 이는 정상적인 동작이며, 반드시 GPU가 필요한 것은 아닙니다.
- VPS를 가리키는 도메인 이름. 모바일 앱은 HTTPS 엔드포인트를 강력히 요구하며, 앞단에 리버스 프록시를 두는 것이 좋습니다. 이는 Docker, TLS, 백업을 사용하는 자가 호스팅 Nextcloud 인스턴스와 동일한 구성 방식이며, Immich는 해당 파일 서버에 대응하는 사진 관리 서비스입니다.
- Docker 및 Compose 플러그인 설치. Docker Compose 기초 가이드에서 다룬 내용과 동일하게, Docker 공식 apt 저장소에서 제공하는 Docker Engine과 Compose v2 플러그인을 설치하십시오.
1단계: 다른 작업에 앞서 스왑 추가하기
소규모 VPS에서 Immich가 실패하는 가장 흔한 원인은 ML 컨테이너가 OOM-killed 되는 것입니다. 먼저 커널이 여유를 가질 수 있도록 공간을 확보하십시오.
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h이제 free -h 명령을 실행하면 4.0Gi 크기의 Swap: 항목이 표시되어야 합니다. 이 설정으로 ML 속도가 빨라지지는 않지만, 4 GB 메모리를 가진 장비에서 인덱싱 도중 컨테이너가 종료되는 현상은 방지할 수 있습니다.
2단계: 공식 compose 및 env 파일 가져오기 (복사본 대신 원본 사용)
Immich는 배포 파일 내부에 서비스 버전과 데이터베이스 이미지를 고정(pin)합니다. 블로그(본 문서 포함)에 있는 compose 파일을 복사하여 진실의 원천으로 삼지 마십시오. 릴리스 에셋을 직접 다운로드하십시오:
sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env이 파일들은 태그가 지정된 릴리스에서 제공되므로 이미지 참조가 일치합니다. compose 파일은 4개의 서비스를 정의하며, 설정을 변경하기 전에 각 서비스의 역할을 이해하는 것이 좋습니다:
immich-server(ghcr.io/immich-app/immich-server, 컨테이너immich_server): API 및 웹 UI이며,2283포트에서 대기합니다. 업로드된 파일을/data경로에 마운트합니다.immich-machine-learning(ghcr.io/immich-app/immich-machine-learning, 컨테이너immich_machine_learning): CLIP 검색 및 얼굴 인식 기능을 수행합니다. 다운로드한 모델을model-cache볼륨에 캐싱합니다. 이 서비스는 메모리 사용량이 많습니다.database(컨테이너immich_postgres): VectorChord 벡터 확장이 포함된 Postgres이며, 유사도 검색 기능을 제공합니다. 이미지 태그는 compose 파일 내에 다이제스트로 고정되어 있습니다(예:ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:...). 이전 설정에서는pgvecto.rs을 사용했으나, Immich v3.0부터 지원이 중단되었습니다. 따라서 현재 설치하는 모든 환경은 VectorChord를 사용합니다. 이 태그를 직접 수정하지 마십시오.redis(컨테이너immich_redis): 작업 큐를 위한 Valkey/Redis 인스턴스입니다.
3단계: 사진과 데이터베이스가 위치할 .env 설정
.env을 열고 다음 네 가지 항목을 설정합니다. 표시된 줄 아래의 모든 내용은 그대로 유지하십시오.
# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library
# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres
# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2
# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING
# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich문제를 방지하기 위한 두 가지 규칙입니다. UPLOAD_LOCATION는 대용량 디스크를 가리켜야 합니다. 나중에 데이터 볼륨을 추가할 계획이라면 처음부터 해당 마운트 경로로 설정하십시오. 나중에 옮기려면 썸네일을 이동하고 자산 경로를 모두 업데이트해야 하기 때문입니다. 또한 DB_DATA_LOCATION은 반드시 로컬 디스크에 있어야 합니다. NFS나 SMB 공유 드라이브에서 Postgres를 실행하면 데이터가 손상되며, 공식 문서에서도 이를 명시하고 있습니다. DB_PASSWORD에 영문자와 숫자만 사용하면 연결 문자열 이스케이프 관련 버그를 방지할 수 있습니다.
4단계: 첫 실행 및 관리자 계정 생성
cd /opt/immich
sudo docker compose up -d
sudo docker compose ps정상적으로 실행되면 4개의 컨테이너가 모두 running 상태가 되며, 최종적으로는 healthy 상태가 됩니다.
NAME STATUS
immich_machine_learning Up (healthy)
immich_postgres Up (healthy)
immich_redis Up (healthy)
immich_server Up (healthy)첫 번째 up 실행 시 수 기가바이트의 이미지를 내려받으므로 충분한 시간을 기다려야 합니다. sudo docker compose logs -f immich-server 명령으로 진행 상황을 확인하십시오. 서버가 준비되면 포트 2283에서 대기 중이라는 로그가 출력됩니다. 이제 브라우저에서 http://YOUR_SERVER_IP:2283에 접속하십시오. 처음 접속하면 Getting Started 마법사가 나타나며, 여기서 생성하는 첫 번째 계정이 관리자 계정이 됩니다. 강력한 암호를 설정하십시오. 이 계정은 서버 설정, 사용자 관리, 그리고 추후 필요한 ML 구성을 관리하는 권한을 가집니다.
5단계: 모바일 앱 및 백그라운드 백업
App Store나 Play Store에서 Immich를 설치합니다. 로그인 화면에서 Server Endpoint URL을 입력하라는 메시지가 나타납니다. 스키마를 포함한 전체 URL을 입력하십시오(예: https://photos.example.com). 앱이 자동으로 /api를 덧붙입니다. 방금 생성한 계정으로 로그인한 뒤, 앱의 Backup 화면을 열어 보호할 앨범(보통 Camera 및 Screenshots)을 선택하고 Background backup을 활성화합니다. iOS의 백그라운드 백업은 운영체제에 의해 제한됩니다. 포그라운드 업로드는 항상 실행되지만, 백그라운드 업로드는 운영체제가 허용할 때만 수행됩니다.
이 단계에서 막히는 경우가 많으므로, 앱과 씨름하기 전에 6단계를 먼저 읽어보시기 바랍니다.
단계 6: 리버스 프록시를 통한 HTTPS 설정 및 전체 URL 규칙
모바일 앱은 HTTPS를 강하게 요구합니다. 2283 포트 앞에 reverse proxy를 배치하고 그 지점에서 TLS를 종료합니다. 이미 여러 컨테이너를 실행하고 있다면 여러 Docker 앱에 자동 TLS를 적용하는 Traefik이 가장 깔끔한 선택입니다. label 블록 하나로 photos.example.com을(를) immich-server 컨테이너로 라우팅하고 인증서도 자동으로 가져옵니다. nginx를 선호한다면 Certbot과 nginx로 Let's Encrypt 인증서 발급하기 가이드에서 인증서와 proxy_pass http://127.0.0.1:2283; 블록을 구성할 수 있습니다. 이 proxy를 구성하면 다음 서비스를 추가할 때 새 서브도메인만 만들면 되는 경우가 많습니다. 따라서 Jellyfin용 90년대 비디오 대여점 스킨인 Halcyon 같은 미디어 프런트엔드도 같은 서버에서 Immich와 나란히 운영할 수 있습니다. Codex와 Claude Code를 하나의 API 뒤에 배치하는 자체 호스팅 HarnessRouter도 마찬가지입니다. 이 서비스는 의도적으로 loopback에 바인딩되며, 앞단의 proxy가 TLS를 종료한 뒤에만 접근할 수 있습니다. 따라서 서브도메인을 연결하기 전에 기본 로그인 정보를 변경해야 합니다. 그러나 모든 컨테이너에 공개 호스트 이름이 필요한 것은 아닙니다. 자체 호스팅 open-kritt 보안 스캐너 같은 관리자 전용 도구는 proxy에 아예 연결하지 않는 편이 낫습니다. UI를 열어야 하는 드문 경우에만 SSH 터널을 통해 접근합니다. HTTP를 전혀 사용하지 않는 서비스도 있으므로 proxy를 생략할 수 있습니다. 자체 호스팅 RustDesk relay server가 대표적인 예입니다. 이 서비스는 여러 raw TCP 및 UDP 포트에서 수신 대기하며 서브도메인보다 firewall 규칙을 사용해야 합니다. Immich에서는 proxy 설정 하나가 중요합니다. 휴대폰 동영상은 크기가 크므로 업로드 크기 제한을 높여야 합니다. nginx에서는 server 블록 안에 client_max_body_size 50000M;를 설정합니다. 기본값인 1 MB는 동영상 업로드를 413 Request Entity Too Large로 거부합니다.
앱이 강제하는 규칙은 다음과 같습니다. 엔드포인트에 접근 가능해야 하며, 실제 환경에서는 반드시 HTTPS여야 합니다. http:// 엔드포인트나 포트 번호가 생략된 직접 IP 주소를 사용하는 경우 "앱이 서버에 연결할 수 없음" 오류가 발생하며, 이에 대한 내용은 아래의 실패 사례에서 다룹니다.
7단계: 외부 라이브러리와 업로드, 기존 사진 트리 가져오기
Immich에 사진을 추가하는 방법은 두 가지가 있으며, 이 둘은 서로 다릅니다.
- 업로드(Uploads)는 Immich가 소유하는 에셋입니다. 앱이나 웹 업로더가 파일을
UPLOAD_LOCATION으로 복사합니다. Immich는 이 파일들의 이름을 변경하거나 이동, 삭제할 수 있습니다. - 외부 라이브러리(External libraries)는 서버의 특정 폴더, 예전
Pictures트리, NAS 익스포트 등에 이미 존재하는 파일을 읽기 전용으로 가져오는 방식입니다. Immich는 해당 위치에서 파일을 인덱싱하여 타임라인에 표시하지만, 원본 파일을 수정하거나 삭제하지 않습니다.
기존 사진 트리를 가져오려면 해당 경로를 서버 컨테이너에 읽기 전용으로 마운트하십시오. immich-server: 아래의 docker-compose.yml를 편집하여 볼륨을 추가합니다.
immich-server:
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
- /srv/photos:/mnt/media/photos:ro:ro는 Immich가 원본 파일에 절대 접근할 수 없음을 보장합니다. sudo docker compose up -d를 사용하여 컨테이너를 다시 생성한 다음, 웹 UI에서 아바타 → 관리(Administration) → 외부 라이브러리(External Libraries) → 라이브러리 생성(Create Library)으로 이동합니다. 소유할 사용자를 선택하고 폴더 아래의 추가(Add)를 클릭한 뒤, 호스트 경로인 /srv/photos이 아닌 컨테이너 경로인 /mnt/media/photos을 입력하십시오. 스캔(Scan)을 클릭합니다. 컨테이너 경로 대신 호스트 경로를 사용하는 것은 외부 라이브러리 설정 시 가장 흔히 발생하는 실수입니다. 이 경우 스캔 결과가 아무것도 나오지 않으며 에셋이 0개로 보고됩니다.
8단계: Immich가 요구하는 업그레이드 원칙
이 부분은 원활하게 작동하는 Immich와 고장 난 Immich를 가르는 기준입니다. Immich는 빠르게 릴리스되며, 이전 버전에 대한 수정 사항을 백포트하거나 다운그레이드를 지원하지 않습니다. v3 태그를 무작정 따라가면 결국 데이터베이스가 손상됩니다. 버전을 고정한 뒤 릴리스 노트를 읽는 습관은 서버의 모든 장기 실행 컨테이너에 적용할 가치가 있습니다. 이것이 바로 KiroCrew 에이전트가 다음 재시작 시 자동으로 변경되지 않도록 특정 버전 태그에 고정되는 이유입니다. 지켜야 할 원칙은 다음과 같습니다.
- 버전 고정.
IMMICH_VERSION를 항상 최신 v3.x를 가져오는 유동적인v3대신,v3.0.2과 같은 구체적인 태그로 설정하십시오. - 업그레이드 전 매번 릴리스 노트를 읽으십시오. 특히 데이터베이스나 벡터 확장 기능과 관련된 변경 사항은 릴리스 노트에 명시됩니다. v3.0 릴리스가 대표적인 예입니다. 이 버전은 pgvecto.rs를 완전히 제거했으므로, 이전 확장을 사용하던 사용자는 업그레이드 전에 반드시 (v1.133에서 도입된) VectorChord 마이그레이션을 완료해야 했습니다.
- 먼저 데이터베이스를 백업하십시오 (9단계). 항상 백업해야 하지만, 릴리스 노트에 데이터베이스 관련 내용이 있다면 더욱 주의해야 합니다.
- 새로운 compose 파일도 함께 받으십시오.
IMMICH_VERSION는 서버와 ML 이미지만 고정합니다. Postgres 이미지는docker-compose.yml내부의 다이제스트(digest)로 고정되므로, 더 새로운 데이터베이스 확장이 필요한 버전은 새로운 compose 파일을 함께 배포합니다. 두 릴리스 에셋을 모두 다시 다운로드하고,.env값을 다시 적용한 뒤 업그레이드하십시오. - 모바일 클라이언트도 비슷한 시기에 업데이트하십시오. 서버는 동일한 메이저 버전과 통신하며, 앱은 현재 및 이전 메이저 버전을 지원합니다. 서버가 앱보다 앞서 나가면 앱을 업데이트할 때까지 휴대폰에
Your app major version is not compatible with the server!가 표시되므로, 앱을 먼저 업데이트하는 것이 가장 안전합니다.
새로운 파일을 준비한 후 실행할 실제 명령어는 다음과 같습니다.
cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune9단계: 백업, 데이터베이스 덤프와 원본 파일, 그리고 복구 테스트
Immich 백업은 두 가지 요소로 구성되며, 하나라도 빠지면 무용지물입니다. 데이터베이스에는 앨범 구조, 얼굴 인식 정보, 검색 인덱스, 자산과 파일 간의 매핑 정보가 저장됩니다. 원본 디렉터리(originals directory)에는 실제 사진 파일이 저장됩니다. 둘 중 하나만 복구하면 조직화되지 않은 사진만 남거나, 존재하지 않는 파일을 가리키는 빈 껍데기만 남게 됩니다. 이러한 이중 구조는 Immich만의 특성이 아닙니다. 자체 호스팅 Chatwoot 지원 데스크 역시 Postgres 덤프와 업로드 디렉터리를 함께 백업해야 하며, 그렇지 않으면 복구된 받은 편지함에서 모든 첨부 파일이 누락됩니다. Postgres 데이터 디렉터리를 파일 트리 형태로 복사하는 것은 덤프 단계를 우회하는 지름길처럼 보이지만, 이는 올바른 백업 방식이 아닙니다. 전체 Immich 백업 및 복구 가이드에서는 이러한 함정을 다루며, 이를 간과할 경우 타임라인이 비어 있는 상태로 복구되는 실수를 범하게 됩니다.
Postgres 컨테이너 내부에서 pg_dump 명령을 사용하여 데이터베이스를 덤프하십시오. 이때 전체 클러스터가 아닌 immich 데이터베이스만 지정해야 합니다.
sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
--dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz그다음 UPLOAD_LOCATION, 즉 전체 /opt/immich/library 트리를 백업하십시오. 특히 library/, upload/, profile/ 하위 폴더를 restic, rsync 또는 borg를 사용하여 다른 머신이나 오브젝트 스토리지로 전송하십시오. 이 작업을 수행하는 스케줄러(cron 항목이나 systemd 타이머)는 실패 시 알림을 보낼 수 있어야 합니다. systemd OnFailure= 유닛을 자체 ntfy 푸시 서버와 연결하면, 덤프 작업이 실패한 밤에 즉시 휴대폰으로 알림을 받을 수 있어 복구 시점에 문제를 발견하는 상황을 방지할 수 있습니다. 데이터베이스를 먼저 백업하고 파일을 나중에 백업하십시오. 그래야 파일 백업이 복사하지 않은 사진을 덤프가 참조하는 일이 발생하지 않습니다. 외부 라이브러리는 Immich가 관리하지 않으므로 실제 원본 위치에서 별도로 백업해야 합니다.
이제 모두가 건너뛰는 단계인 복구 테스트를 수행할 차례입니다. 복구는 서버가 한 번도 실행된 적 없는 새로운 스택을 대상으로 수행해야 합니다. 또한 덤프와 호환되는 벡터 확장(vector extension)이 포함된 Postgres 이미지를 사용해야 하므로, DB 이미지 태그를 임의로 변경해서는 안 됩니다. 동일한 compose 파일과 .env을 사용하는 별도의 환경에서 기존 상태를 모두 삭제하고, 데이터베이스만 실행한 뒤 덤프를 로드하십시오.
cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -dVectorChord 데이터베이스에서 search_path를 sed로 다시 쓰는 과정은 선택 사항이 아닙니다. 이 과정을 생략하면 복구 도중 작업이 중단됩니다. 스택이 다시 시작되고 원본 파일들이 제자리에 배치되면 웹 UI를 열어 확인하십시오. 사진과 앨범이 정상적으로 보인다면 백업이 성공한 것입니다. 이 과정을 한 번도 수행해 본 적이 없다면, 당신은 백업을 가진 것이 아니라 희망을 가진 것뿐입니다.
실패 유형 및 확인 가능한 메시지
ML 컨테이너가 OOM-killed 상태가 됩니다. sudo docker compose logs immich-machine-learning이 갑자기 종료되고, docker compose ps은 이를 Restarting로 표시하며, 종료 코드는 137입니다. sudo dmesg | grep -i oom를 확인하면 Out of memory: Killed process ... (python3)가 나타납니다. 검색 및 얼굴 인식 작업이 중단됩니다. 원인은 모델을 구동하기에 RAM이 부족하기 때문입니다. 해결 방법은 순서대로 다음과 같습니다: 스왑을 추가하거나(1단계), VPS의 RAM을 증설하십시오. 만약 RAM 증설이 불가능하다면, Administration → Settings → Machine Learning Settings에서 Smart Search와 Facial Recognition을 꺼서 ML 기능을 비활성화하십시오. 이 경우 백업과 앨범 기능은 유지되지만, 콘텐츠 기반 검색 기능은 사용할 수 없게 됩니다. compose 파일에서 immich-machine-learning 서비스를 제거해도 동일한 효과가 나타납니다.
업그레이드 후 Postgres가 시작되지 않습니다. 서버 로그에 The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded.과 같은 메시지가 반복되거나, 구버전 스택의 경우 The pgvecto.rs extension is not available in this Postgres instance.이 나타납니다. 원인은 데이터가 업그레이드된 버전보다 낮은 확장 프로그램 버전을 가진 데이터베이스 이미지를 사용했기 때문입니다. 이는 대부분 이미지 태그를 수동으로 수정했거나, 더 최신 버전의 덤프를 구버전 이미지에 복원했을 때 발생합니다. 해결 방법은 데이터베이스와 일치하는 Postgres 이미지를 사용하고, 해당 데이터베이스 버전에 맞는 릴리스의 compose 파일을 사용하는 것입니다. 다운그레이드는 하지 마십시오. 호환되는 이미지에만 복원하십시오.
모바일 앱이 서버에 연결할 수 없습니다. URL을 입력한 후 로그인 화면에 연결 오류 또는 Server is not reachable 메시지가 표시됩니다. 세 가지 원인이 있습니다: 프록시는 https://만 제공하는데 http://를 입력했거나, 백엔드에 직접 연결하면서 포트를 생략하여 example.com:2283 대신 example.com(포트 443)으로 시도했거나, 리버스 프록시가 /api을 전달하지 않는 경우입니다. 전체 https://photos.example.com URL을 입력하고 휴대폰 브라우저에서 먼저 로드되는지 확인하여 해결하십시오. 브라우저에서는 작동하는데 앱에서만 안 된다면, 프록시가 경로를 제거하고 있거나 인증서가 자체 서명된 경우입니다. 앱은 신뢰할 수 없는 인증서를 거부합니다.
가져오기 도중 디스크 공간이 부족합니다. 업로드가 실패하고 썸네일이 표시되지 않으며, 로그에 ENOSPC: no space left on device 또는 Postgres로부터 could not extend file ... No space left on device이 표시됩니다. df -h을 확인하면 UPLOAD_LOCATION 볼륨이 100% 사용 중입니다. 이것이 대규모 라이브러리를 가져오기 전에 디스크 크기를 미리 산정해야 하는 이유입니다. 더 큰 볼륨을 연결하고 스택을 중지한 뒤 UPLOAD_LOCATION를 해당 볼륨으로 이동하고 .env을 업데이트한 후 다시 시작하여 복구하십시오. 또는 클라우드 제공업체가 허용한다면 기존 디스크를 확장하십시오. 디스크가 가득 차면 Postgres가 멈출 수 있으므로, 데이터 손상을 의심하기 전에 공간을 확보하고 데이터베이스 컨테이너를 재시작하십시오.
FAQ
Immich는 어느 정도의 RAM과 디스크 용량이 필요한가요?
Immich의 공식 요구 사양은 최소 6 GB RAM이며 8 GB를 권장합니다. 작은 라이브러리의 경우 swap을 포함해 4 GB가 실질적인 하한선이며, 머신러닝 컨테이너에서 부하가 급증하므로 어떤 경우든 swap을 설정해야 합니다. 디스크는 전체 라이브러리 크기에 썸네일과 미리보기 생성을 위한 10–20%의 여유 공간을 더해 로컬 스토리지에 할당하십시오. Postgres 데이터 디렉터리는 절대 네트워크 공유 드라이브에 두지 마십시오. 다른 서비스를 무엇을 운영할지 고민 중이라면 2026년 셀프 호스팅 가이드에서 다른 서비스들과 비교한 Immich의 리소스 점유율을 확인할 수 있습니다.
GPU 없이 Immich를 실행할 수 있나요?
네, 가능합니다. 머신러닝 컨테이너는 CPU에서도 원활하게 작동합니다. GPU는 스마트 검색 인덱싱 속도를 높이고, 적절한 이미지 버전을 사용할 경우 비디오 트랜스코딩 속도를 향상시킬 뿐입니다. CPU 환경에서는 대규모 라이브러리의 초기 인덱싱에 몇 시간이 걸릴 수 있지만, 백그라운드에서 처리되므로 백업이나 사진 탐색을 방해하지는 않습니다. 만약 서버 사양이 낮아 머신러닝 구동이 어렵다면, 관리자 설정에서 스마트 검색과 얼굴 인식 기능을 비활성화하고 나머지 기능을 그대로 사용할 수 있습니다.
Immich를 안전하게 업그레이드하려면 어떻게 해야 하나요?
IMMICH_VERSION을 v3.0.2와 같은 특정 태그로 고정하고, 업그레이드 전마다 릴리스 노트를 읽은 뒤 데이터베이스를 먼저 백업하십시오. Postgres 이미지가 IMMICH_VERSION가 아닌 docker-compose.yml 내부에 고정되어 있으므로, 대상 릴리스의 compose 파일과 example.env를 새로 내려받아 값을 다시 적용한 뒤 docker compose pull && docker compose up -d을 실행해야 합니다. 버전을 자동으로 업데이트되게 두지 마십시오. Immich는 호환성을 깨뜨리는 변경 사항이 포함될 수 있으며 다운그레이드를 지원하지 않습니다.
정확히 무엇을 백업해야 하나요?
immich 데이터베이스의 pg_dump과 전체 UPLOAD_LOCATION 원본 디렉터리, 이 두 가지를 함께 백업해야 합니다. 데이터베이스에는 앨범, 얼굴 정보, 자산과 파일 간의 매핑 정보가 저장되며, 디렉터리에는 실제 사진 파일이 저장됩니다. 복구 시에는 이 두 가지 모두와 호환되는 벡터 확장이 포함된 데이터베이스 이미지가 필요합니다. 데이터베이스 덤프를 먼저 수행하고 파일 복사를 나중에 진행하십시오. 테스트하지 않은 백업은 백업이 아니므로, 반드시 별도의 테스트 환경에서 복구 과정을 최소 한 번은 검증하십시오.
기존 사진 폴더를 어떻게 가져오나요?
해당 폴더를 immich-server 컨테이너에 추가 볼륨(예: - /srv/photos:/mnt/media/photos:ro)으로 읽기 전용 마운트한 뒤 컨테이너를 재생성하십시오. 그 후 Administration → External Libraries에서 라이브러리를 생성하고 컨테이너 경로인 /mnt/media/photos를 추가하십시오. Immich는 파일을 제자리에서 인덱싱하며, 원본 파일을 수정하거나 삭제하지 않습니다. 가장 흔한 실수는 컨테이너 경로 대신 호스트 경로를 입력하는 것이며, 이 경우 스캔 결과가 나타나지 않습니다.