Immich 서버 권장 RAM 및 디스크 용량 확인하기

Immich는 어느 정도의 RAM이 필요한가?

Immich는 문서화된 최소 사양으로 6 GB의 RAM(임의 접근 메모리)을 요구하며, 권장 사양은 8 GB입니다. CPU 코어는 최소 2개에서 원활한 설치를 위해 4개를 권장합니다. Immich는 단일 애플리케이션이 아니라 4개의 컨테이너로 구성되므로, 이 수치는 전체 스택을 포함합니다. 이미 가져오기가 완료된 라이브러리를 탐색하는 것은 메모리 소모가 적습니다. 메모리는 주로 가져오기 작업에 사용되며, 대부분은 비활성화할 수 있는 특정 컨테이너에서 소비됩니다.

[
  {
    "label": "Documented minimum",
    "ram_gb": 6,
    "cpu_cores": 2
  },
  {
    "label": "Documented recommended",
    "ram_gb": 8,
    "cpu_cores": 4
  }
]

위 수치는 2026년 10월 기준 Immich 요구 사항 페이지에 게시된 공식 수치입니다. 이는 권장 사양이며, 소프트웨어 실행 시점에 수행하는 검사 항목은 아닙니다. 같은 페이지에는 머신 러닝 기능을 비활성화한 4 GB의 소규모 설정도 문서화되어 있으며, 이보다 낮은 사양은 지원하지 않습니다. 사양이 낮은 서버에서는 백그라운드 작업의 완료 여부나 메모리 부족 시 가져오기 작업의 동작 방식이 달라집니다.

실질적인 하드웨어 제한 사항이 하나 존재합니다. 버전 3부터 amd64 호스트의 머신 러닝 컨테이너는 x86-64-v2 CPU를 필요로 하며, 이는 대략 2012년 이후 판매된 대부분의 프로세서를 포함합니다. 이 요구 사항은 서버 전체가 아닌 해당 컨테이너에 적용됩니다. 따라서 구형 하드웨어를 사용하는 경우 머신 러닝을 끄거나, 아래 설명된 대로 다른 머신에서 실행하거나, Immich 문서에서 호환되는 마지막 버전으로 명시된 v2.7.5를 유지해야 합니다.

아직 설치 전이라면 Docker Compose를 사용한 전체 Immich 설치를 먼저 진행한 뒤, 이 가이드로 돌아와 서버 사양을 조정하십시오.

메모리가 사용되는 위치: 4개의 컨테이너

공식 Compose 파일은 4개의 서비스를 시작합니다. 각 서비스의 메모리 사용 형태가 다르므로 전체 메모리만 보면 중요한 부분을 파악할 수 없습니다.

immich-server은 웹 인터페이스와 API를 제공하고 백그라운드 작업 워커도 실행합니다. 워커 2개가 이 단일 컨테이너 안에서 실행됩니다. api는 브라우저와 모바일 앱의 요청에 응답합니다. microservices은 썸네일 생성과 동영상 인코딩을 포함한 큐를 처리합니다. 변수 IMMICH_WORKERS_INCLUDE과 IMMICH_WORKERS_EXCLUDE를 사용하면 이 2개를 별도의 컨테이너로 분리할 수 있습니다. 이렇게 하면 사진을 제공하는 부분의 메모리를 제한하지 않고, 메모리를 많이 사용하는 부분에만 자체 메모리 제한을 설정할 수 있습니다.

database은 VectorChord 확장이 내장된 PostgreSQL 14 이미지입니다. 모든 메타데이터와 자산별 검색 벡터 1개를 저장합니다. Immich 문서는 이 스택에서 유일하게 명시적인 최소 요구량을 이 서비스에 적용합니다. Docker 리소스 제한을 적용하는 경우 데이터베이스에는 최소 2 GB가 필요합니다. 같은 문서에서는 데이터베이스를 가급적 로컬 SSD 스토리지에 두고, 어떤 종류의 네트워크 공유에도 두지 말아야 한다고 설명합니다. 벡터 및 인덱스 조회는 작은 무작위 읽기이므로 네트워크 볼륨을 사용하면 각 조회가 왕복 통신으로 바뀌기 때문입니다. 이 선택이 계획에 영향을 준다면 VPS의 NVMe와 SATA SSD 스토리지의 차이는 이 스택의 다른 부분보다 여기에서 더 중요합니다.

redis은 Valkey 이미지를 실행하고 작업 큐를 저장합니다. 사진 데이터가 아니라 작업 레코드를 저장하므로 4개 중 메모리 사용량이 큰 폭으로 가장 작습니다.

immich-machine-learning은 필요한 플랜 크기를 결정하는 서비스입니다. 스마트 검색, 얼굴 감지, 텍스트 인식을 위한 모델을 로드하며, 로드된 모델은 메모리에 상주합니다. MACHINE_LEARNING_MODEL_TTL의 기본값은 300이므로 요청이 5분 동안 없으면 모델이 제거되고, 다음 요청이 들어오면 /cache 볼륨에서 다시 읽습니다. 대량 가져오기 중에는 5분 간격이 생기지 않으므로 첫 번째 자산부터 마지막 자산까지 모델이 계속 로드된 상태로 유지됩니다.

가져오기 시 발생하는 변화

유휴 상태의 Immich는 조용합니다. 서버가 가장 취약해지는 시점은 가져오기를 수행할 때입니다. 하나의 에셋을 업로드하면 일련의 작업 큐가 생성되고, 여러 큐가 동시에 실행되기 때문입니다.

메타데이터 추출은 파일 헤더만 읽으므로 가볍습니다. 썸네일 생성은 더 무거운 작업입니다. Immich는 에셋 하나당 흐릿한 thumbhash 플레이스홀더, WebP 미리보기, JPEG 썸네일 등 세 가지 썸네일 결과물을 생성하며, 감지된 얼굴마다 썸네일이 하나씩 추가됩니다. 각 작업은 이미지를 디코딩하며, 작업 동시성(concurrency) 설정에 따라 한 번에 처리할 디코딩 개수가 결정됩니다. 동시성은 개별 작업의 비용을 서버 전체의 부하로 증폭시키는 배율기 역할을 합니다. 이것이 바로 Immich FAQ에서 사양이 낮은 기기일 때 가장 먼저 낮춰야 할 설정으로 동시성을 꼽는 이유입니다. Administration, Settings, Job Settings에서 무거운 큐의 동시성을 1로 설정하십시오.

비디오 에셋은 트랜스코딩 과정을 추가합니다. 각 트랜스코딩 작업은 별도의 메모리를 사용하는 독립적인 FFmpeg 프로세스이며, 허용된 모든 CPU 스레드를 사용합니다.

스마트 검색은 모든 새 에셋을 머신러닝 컨테이너로 보내 하나의 임베딩 벡터를 계산합니다. 얼굴 감지 기능은 동일한 이미지에 대해 두 번째 모델을 실행합니다. 기존 사진 라이브러리를 처음 가져올 때는 이 두 큐가 보유한 모든 에셋에 대해 수 시간 동안 실행됩니다. 이는 전체 설치 환경에서 메모리 사용량이 가장 극심한 순간이며, 최초 1회만 발생합니다.

얼굴 및 객체 인식에 가장 많은 RAM이 필요한 이유

얼굴 처리는 두 가지 작업으로 나뉩니다. 얼굴 감지는 머신러닝 컨테이너에서 모델을 실행하여 얼굴 영역을 찾아냅니다. 얼굴 인식은 감지된 결과를 사람별로 그룹화하며, 이 단계에서 Postgres의 벡터 인덱스를 조회합니다. 따라서 라이브러리가 크면 두 서비스에 차례로 부하가 발생합니다. 감지가 실행될 때는 모델 컨테이너에, 그룹화가 실행될 때는 데이터베이스에 부하가 걸립니다.

머신러닝 컨테이너의 메모리 점유율을 결정하는 설정은 네 가지입니다.

• 얼굴 모델. Immich는 기본값으로 buffalo_l를 제공하며, FAQ에서는 소규모 서버의 경우 buffalo_s 사용을 권장합니다. 이 모델은 크기가 작아 메모리를 덜 차지하고 더 빠르게 실행되지만, 작거나 측면을 향한 얼굴에 대한 정확도는 떨어질 수 있습니다.
• 워커 수. MACHINE_LEARNING_WORKERS의 기본값은 1입니다. 각 워커는 별도의 프로세스로서 모델의 복사본을 각각 메모리에 로드하므로, 이 값을 2로 높이면 상주 모델 메모리 사용량이 대략 두 배로 늘어납니다. 여유 RAM이 충분하지 않다면 1로 유지하십시오.
• 배치 크기. MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION은 한 번에 처리할 얼굴 수를 제한합니다. 배치는 한꺼번에 메모리에 적재되므로, 40명의 얼굴이 포함된 단체 사진은 인물 사진보다 더 많은 메모리를 소모합니다.
• 실행할 모델 유형. 스마트 검색, 얼굴 감지, 텍스트 인식은 각각 고유한 모델을 로드합니다. Administration, Settings, Machine Learning Settings에서 사용하지 않는 기능을 끄면, 가져오기 작업 사이가 아니라 상시적으로 해당 모델의 메모리 점유를 해제할 수 있습니다.

또한 MACHINE_LEARNING_MODEL_ARENA 설정이 있습니다. 이는 파편화를 방지하기 위해 CPU 메모리를 미리 할당하는 기능으로 기본 활성화되어 있습니다. 이 설정은 가장 마지막에 변경하십시오. 효과는 하부 메모리 할당자에 따라 달라지므로, 변경 전후의 docker stats를 모니터링하는 것이 유일한 객관적인 판단 방법입니다.

작동이 확인된 프로필: 2 GB, 4 GB, 8 GB

[
  {
    "label": "2 GB VPS",
    "server_limit_mb": 768,
    "db_limit_mb": 768,
    "ml_limit_mb": 0,
    "redis_limit_mb": 128,
    "notes": "below every documented configuration, machine learning container removed"
  },
  {
    "label": "4 GB VPS",
    "server_limit_mb": 1024,
    "db_limit_mb": 2048,
    "ml_limit_mb": 0,
    "redis_limit_mb": 192,
    "notes": "documented 4 GB setup: machine learning disabled or moved to another host, job concurrency 1"
  },
  {
    "label": "8 GB VPS",
    "server_limit_mb": 2048,
    "db_limit_mb": 2048,
    "ml_limit_mb": 2560,
    "redis_limit_mb": 256,
    "notes": "everything on at default settings"
  }
]

이 수치들은 Immich가 사용하는 메모리 양이 아니라 Compose에 입력할 제한값으로 이해해야 합니다. 제한값은 상한선입니다. 이는 자원을 미리 예약하거나 서비스를 더 작게 만드는 것이 아닙니다. 서버 자원이 고갈되었을 때 커널이 어떤 서비스를 종료할지 결정하는 기준이며, 커널의 자체 점수 산정 방식에 맡기는 것보다 사용자가 직접 결정하는 것이 더 낫습니다.

2 GB 서버: 머신러닝 컨테이너 제거

2 GB는 문서화된 최소 요구 사양인 6 GB보다 낮으며, 머신러닝을 비활성화한 4 GB 구성보다도 낮습니다. Immich는 2 GB 구성을 공식적으로 제공하지 않으므로, 이 프로필은 권장 사항이 아닌 지원되지 않는 타협안입니다. 그럼에도 시도하려면 docker-compose.yml 파일에서 immich-machine-learning 서비스 전체를 주석 처리하거나, 서비스를 실행한 상태에서 Administration, Settings, Machine Learning Settings의 모든 모델을 비활성화하십시오. 모델을 비활성화해도 Python 프로세스가 상주하므로 컨테이너를 제거하는 것이 더 확실한 방법입니다.

이 경우 업로드, 앨범, 공유, 모바일 백업, 썸네일, 날짜·장소·파일명 기반 검색 기능은 유지됩니다. 하지만 설명 기반 검색, 얼굴 자동 그룹화, 이미지 내 텍스트 인식 기능은 사용할 수 없습니다.

4개의 제한값을 합치면 약 1.7 GB가 되며, 호스트에는 약 300 MB 정도만 남습니다. Immich 문서에 따르면 Docker 자원 제한을 사용할 경우 데이터베이스만 최소 2 GB가 필요합니다. 따라서 데이터베이스에 768 MB를 할당하는 것은 최소 기준치보다 훨씬 낮으며, 이 때문에 Postgres가 가장 먼저 종료될 가능성이 높습니다.

가장 먼저 문제가 발생하는 부분은 가져오기(import) 작업입니다. 페이지 서빙은 메타데이터 쿼리와 파일 읽기 작업이므로 이미 라이브러리에 있는 항목을 탐색할 때는 부하가 적지만, 영상이 많은 데이터를 가져올 때는 스왑이 발생합니다. 트랜스코딩과 썸네일 큐가 동시에 메모리를 요구하기 때문입니다. 2 GB가 전부라면 모든 무거운 작업 큐의 동시성(concurrency)을 1로 설정하고 스왑 파일을 추가하십시오. 서버 사양을 선택하는 단계라면 4 GB를 실질적인 최소 사양으로 고려하십시오.

4 GB 서버: 머신러닝 활성화, 작업 동시성 1로 제한

Immich는 머신러닝 기능을 비활성화한 4 GB 구성을 유일한 저사양 구성으로 문서화하고 있습니다. 데이터베이스에 문서화된 최소치인 2 GB를 할당하면, 차트에 기재된 3개의 제한값 합계는 약 3.2 GB가 되어 호스트에 약 800 MB가 남습니다. 썸네일 생성 작업의 동시성을 1로 설정하고 트랜스코딩 스레드 수를 낮게 유지하십시오.

얼굴 및 객체 인식 기능을 유지하려면 아래에 설명된 대로 머신러닝 컨테이너를 다른 서버에서 실행하고 이 서버가 해당 컨테이너를 바라보게 하는 것이 공식적인 방법입니다. 4 GB 서버에서 머신러닝을 함께 실행하는 것은 Immich의 권장 범위를 벗어납니다. 데이터베이스 최소 요구 사양을 제외하면 서버, Redis, 모델, 호스트가 사용할 수 있는 메모리가 2 GB 정도에 불과하기 때문입니다. 그럼에도 시도하려면 Compose 제한을 통해 머신러닝 컨테이너의 자원을 제한하고, 얼굴 인식 설정을 buffalo_s로 변경하며, 썸네일 생성·얼굴 인식·스마트 검색의 작업 동시성을 1로 설정하십시오.

기존 라이브러리를 처음 스캔할 때는 수 시간이 소요되며, 라이브러리가 클 경우 하루 이상 걸릴 수 있습니다. 이는 메모리보다는 CPU 제한에 따른 것이므로 RAM을 늘려도 단축되지 않습니다.

이 서버에서 머신러닝을 실행할 경우, 첫 대량 스캔 중에 해당 컨테이너가 가장 먼저 종료될 것입니다. 제한을 두지 않으면 트랜스코딩 작업이 커지는 동안 머신러닝 컨테이너도 함께 커지며, 커널은 둘 중 더 큰 프로세스를 종료합니다. 컨테이너는 수 초 내에 재시작되므로 docker ps -a 명령을 실행하면 주변 컨테이너보다 가동 시간이 훨씬 짧은 Up 상태로 표시되며, Exited (137) 상태가 되지 않습니다. 결과적으로 작업 큐는 이전보다 더 뒤처지게 됩니다.

8 GB 서버: 문서화된 권장 사양

8 GB RAM과 4 코어 구성은 Immich의 권장 사양과 일치하며, 스마트 검색, 얼굴 인식, 텍스트 인식, 트랜스코딩 등 모든 기능을 기본 동시성 설정으로 원활하게 실행할 수 있습니다. 10만 개 이상의 에셋이 포함된 라이브러리도 무리 없이 처리하며, 데이터베이스가 하루 종일 벡터 인덱스와 메타데이터 쿼리를 처리하므로 병목 현상은 메모리에서 디스크 속도로 이동합니다.

그럼에도 제한값은 설정하십시오. 여유가 있는 서버에서도 제한값을 설정하면 하나의 큐가 폭주하여 데이터베이스까지 함께 다운되는 상황을 방지할 수 있습니다. 더 낮은 사양의 옵션과 비용을 비교한다면, 메모리 계층별 실제 VPS 비용을 고려할 때 8 GB 플랜이 설정을 조정하는 수고를 덜어주는 가장 저렴한 방법인 경우가 많습니다.

Compose limits를 사용하여 서비스별 메모리 제한하기

이 작업을 위해 docker-compose.yml을 수정하지 마십시오. 해당 파일은 wget로 업그레이드할 때마다 교체됩니다. 제한 설정은 그 옆의 docker-compose.override.yml에 작성하십시오. docker compose은 이 파일을 자동으로 병합합니다.

services:
  immich-server:
    deploy:
      resources:
        limits:
          memory: 1024M
  immich-machine-learning:
    deploy:
      resources:
        limits:
          memory: 1024M
          cpus: '1.5'
  database:
    deploy:
      resources:
        limits:
          memory: 2048M
  redis:
    deploy:
      resources:
        limits:
          memory: 192M

docker compose up -d
docker stats --no-stream

이제 docker stats의 MEM USAGE / LIMIT 열에는 호스트의 전체 메모리 대신 설정한 상한값이 표시되어야 합니다. 제한 열에 여전히 호스트의 전체 메모리 크기가 표시된다면, override 파일이 적용되지 않은 것입니다. 파일 이름을 확인하고 docker compose config를 실행하여 병합된 결과를 확인하십시오.

데이터베이스는 2048M 이상으로 유지하십시오. Immich 문서에 따르면 Docker 리소스 제한을 사용할 경우 데이터베이스의 최소 사양은 2 GB입니다. 제한값이 너무 낮으면 서비스가 느려지는 것을 넘어 중단될 수 있으므로, 컨테이너가 재시작을 반복한다면 제한값을 높이십시오. 이와 관련된 상세한 메커니즘은 Docker Compose에서 서비스별 메모리 제한 설정하기에서 확인할 수 있으며, 여기에는 deploy이 Swarm 외부의 Compose v2에서 어떻게 작동하는지에 대한 내용도 포함되어 있습니다.

머신러닝 컨테이너를 끄거나 이동하는 방법

소규모 서버에서 이 컨테이너를 다른 곳으로 옮기는 것은 성능 향상을 위해 취할 수 있는 가장 큰 조치입니다. Immich는 다른 머신에서 컨테이너를 실행하는 것을 지원합니다. 저녁에만 켜두는 데스크톱과 같은 두 번째 호스트에 다음 파일을 생성하십시오.

name: immich_remote_ml
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003
volumes:
  model-cache:

docker compose up -d
curl -s http://localhost:3003/ping

그런 다음 웹 인터페이스에서 Administration, Settings, Machine Learning Settings로 이동하여 Add URL을 클릭하고 http://<host>:3003을 입력하십시오. Immich 문서에 따르면 두 호스트 간의 버전 불일치는 버그와 불안정성을 유발할 수 있으므로, 양쪽 호스트의 버전을 동일하게 유지하십시오.

해당 포트는 사진의 미리보기를 암호화되지 않은 상태로 다른 머신에 전송합니다. 또한 Immich 문서에서는 머신러닝 컨테이너 자체에는 보안 조치가 없다고 경고하므로, 반드시 사설 네트워크 내에서 사용하거나 두 호스트 간의 WireGuard 터널을 통해 실행하십시오. 3003 포트를 인터넷에 절대 노출하지 마십시오.

상주 모델 컨테이너를 운영하는 것 자체가 문제라면, 계획을 확정하기 전에 PhotoPrism과 Immich가 유휴 상태에서 무엇을 실행하는지 비교해보는 것도 합리적인 방법입니다.

Immich 라이브러리에는 디스크 공간이 얼마나 필요한가?

네 가지 요소가 각기 다른 비율로 증가하기 때문에 단일 배수를 적용할 수 없습니다. 사진 50,000장과 짧은 영상 500개가 포함된 라이브러리를 기준으로 계산해 보겠습니다.

[
  {
    "label": "Originals: 50,000 photos at 4 MB",
    "gb": 200
  },
  {
    "label": "Originals: 500 videos at 120 MB",
    "gb": 60
  },
  {
    "label": "Thumbnails and encoded video at 15%",
    "gb": 39
  },
  {
    "label": "Postgres database",
    "gb": 3
  },
  {
    "label": "Machine learning model cache",
    "gb": 2
  }
]

200 GB의 사진과 60 GB의 영상은 가정치입니다. 영상이 전체 용량을 결정하므로(휴대폰 영상 1분은 사진 100장보다 큽니다), 저장 장치를 구매하기 전에 본인의 평균 데이터 크기로 대체하십시오.

find /srv/immich/upload -type f -printf '%s\n' \
  | awk '{n++; s+=$1} END {printf "%d files, %.1f MB average\n", n, s/n/1048576}'

39 GB 행은 Immich에서 공식적으로 제시하는 유일한 비율입니다. 생성된 썸네일과 트랜스코딩된 영상은 라이브러리 크기에 평균 10에서 20퍼센트를 추가합니다. 이 범위는 브라우저 호환성을 위해 재인코딩이 필요한 영상 자산의 비율에 따라 달라집니다. JPEG 위주의 라이브러리는 이 범위의 하단에 위치합니다.

데이터베이스는 3 GB이며, 이는 거의 고정 비용에 가깝습니다. Immich 문서에 따르면 데이터베이스 파일은 픽셀 데이터가 아닌 메타데이터와 검색 벡터를 저장하므로 일반적으로 1에서 3 GB를 차지합니다. 모델 캐시는 2 GB이며, 여러 모델을 활성화하거나 다양한 모델을 테스트할 경우 증가합니다. FAQ에서 이 볼륨을 공간 점유의 원인으로 명시하는 이유가 바로 이것입니다.

다섯 개의 행을 합치면 300 GB를 약간 넘으므로, 500 GB 볼륨은 확장 여유가 있지만 250 GB 볼륨은 그렇지 않습니다. 다음 명령으로 폴더별 용량을 확인하십시오:

grep UPLOAD_LOCATION .env
du -sh /srv/immich/*

UPLOAD_LOCATION 하위에는 6개의 폴더가 존재합니다. upload와 library은 원본을 보관하고, thumbs은 미리보기 및 얼굴 썸네일을, encoded-video은 재인코딩된 사본을, profile는 아바타를, backups은 자동 데이터베이스 덤프를 보관합니다. upload, library, profile은 원본으로부터 재생성할 수 없으므로 이 폴더들만이 대체 불가능한 데이터입니다.

두 가지 사실이 사용자들을 놀라게 합니다. 삭제된 자산은 먼저 휴지통으로 이동하며 휴지통을 비우기 전까지는 공간을 계속 차지하므로, 대규모 정리를 수행한 당일에는 여유 공간이 늘어나지 않습니다. 또한 데이터베이스 덤프는 메타데이터일 뿐이므로 원본 파일 없이는 아무런 가치가 없습니다:

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /srv/backups/immich-dump.sql.gz

이와 함께 원본 파일의 파일 수준 복사본을 서버 외부의 다른 곳에 보관하십시오. 이것이 바로 VPS에서 외부 저장소로 restic 백업을 수행하는 이유입니다.

트랜스코딩은 RAM이 아닌 CPU에 의해 제한됩니다

RAM을 추가한다고 해서 트랜스코딩이 빨라지지는 않습니다. Immich는 FFmpeg를 사용하여 트랜스코딩을 수행하며, 일반적인 VPS 환경에서는 모든 프레임이 CPU에 의해 디코딩 및 인코딩됩니다. 각 FFmpeg 프로세스는 디코딩된 프레임 버퍼를 메모리에 유지하므로 가져오기 섹션에서 트랜스코딩을 메모리 비용으로 간주하지만, 처리 속도는 CPU에 의해 결정됩니다. 하드웨어 가속을 사용할 수 있는 경우에도 Immich 문서에 따르면 기본적으로 인코딩만 가속되므로, 하드웨어 디코딩을 별도로 활성화하지 않으면 디코딩과 톤 매핑은 여전히 CPU가 담당합니다.

하드웨어 가속을 사용하려면 추가적인 hwaccel.transcoding.yml Compose 파일과 NVENC, Quick Sync, RKMPP 또는 VAAPI를 사용하여 패스스루할 장치가 필요합니다. 대부분의 VPS 플랜은 이러한 장치를 제공하지 않으므로 CPU 성능을 기준으로 계획하십시오.

실질적인 설정은 스레드 수입니다. Administration, Settings, Video Transcoding Settings에서 스레드 값을 0으로 설정하면 모든 코어를 사용하게 되며, 이로 인해 2코어 플랜에서는 영상 하나만 처리해도 웹 인터페이스가 멈출 수 있습니다. Immich FAQ의 제안대로 이 값을 1 또는 2로 설정하면 트랜스코딩이 중단되는 대신 속도가 느려집니다.

스왑 스래싱으로 인한 가져오기 작업이 멈춘 것처럼 보이는 이유

이는 사용자가 가장 자주 오해하는 장애 유형입니다. Immich에서 메모리가 부족해지면 두 가지 결과가 나타나며, 그중 하나만 장애처럼 보입니다.

스왑이 없으면 커널이 프로세스를 강제 종료합니다. 컨테이너는 수 초 내에 재시작되므로 브라우저에서는 작업 대기열이 잠시 멈췄다가 다시 시작되는 것처럼 보입니다. 이에 대한 증거는 docker ps -a에서 확인할 수 있습니다.

docker ps -a --filter name=immich
docker inspect immich_machine_learning | grep -i oomkilled
sudo dmesg -T | grep -i -E 'out of memory|oom-kill'

Exited (137)는 프로세스가 시그널 9에 의해 종료되었음을 의미합니다. 137은 128에 9를 더한 값입니다. 이 상태는 컨테이너가 중지된 동안에만 확인할 수 있습니다. 재시작 정책에 의해 컨테이너가 다시 실행되면 docker ps -a는 다시 Up 상태를 보여주며, 다른 Immich 컨테이너보다 훨씬 짧은 가동 시간이 단서가 됩니다. 시그널 9 자체가 메모리 문제를 증명하는 것은 아닙니다. Docker는 정상적인 중지 명령이 제한 시간을 초과할 때도 이 시그널을 보내기 때문입니다. OOMKilled 값이 true라면 메모리 부족으로 종료되었음이 확실하며, 컨테이너가 재시작된 후에는 dmesg의 oom-kill 라인이 신뢰할 수 있는 기록이 됩니다.

스왑이 있으면 프로세스가 종료되지 않으며 오류도 발생하지 않습니다. 커널이 페이지를 디스크로 이동하기 시작하면 가져오기 속도가 10배가량 느려지고, 웹 인터페이스는 일반적인 시간 제한 내에 응답하지 않게 됩니다. 모든 컨테이너는 실행 중이며, 모든 상태 확인(health check)도 통과할 수 있습니다. 이는 시스템이 멈춘 것처럼 보이며, 이 시점에서 사용자는 서버를 재부팅하게 되는데, 이는 작업 대기열의 진행 상황을 잃게 만들 뿐 아무것도 해결하지 못합니다.

free -m
vmstat 1 5

vmstat의 si 및 so 열에서 0이 아닌 값이 지속적으로 나타난다면 시스템이 스왑을 계속 읽고 쓰고 있다는 의미이며, 이것이 바로 스래싱의 정의입니다. 동시에 Swap 사용량에 대한 free -m 행의 수치가 상승할 것입니다.

2 GB 또는 4 GB 서버라면 어쨌든 스왑을 추가하십시오. 원인을 파악할 수 있는 느린 가져오기 작업이 원인을 알 수 없는 컨테이너 강제 종료보다 낫기 때문입니다.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

그다음 원인을 해결하십시오. 작업 동시성을 1로 낮추거나, 머신 러닝 컨테이너의 자원을 제한하거나, 해당 컨테이너를 다른 호스트로 옮기십시오. 스왑은 이를 수행할 시간을 벌어줄 뿐, 그 자체가 해결책은 아닙니다.

FAQ

2 GB VPS에서 Immich를 실행할 수 있습니까?

Immich 문서에 명시된 어떤 구성으로도 불가능합니다. 요구 사항 페이지에서는 최소 6 GB를 권장하며, 머신 러닝 기능을 비활성화한 4 GB 구성을 유일한 하위 설정으로 언급합니다. 또한 Docker 리소스 제한을 사용할 경우 데이터베이스 단독으로 최소 2 GB가 필요하다고 명시합니다. immich-machine-learning 서비스를 주석 처리하고 작업 동시성을 1로 설정하면 실행될 수도 있으나, 이는 지원되지 않는 타협안이며 가져오기 작업 중 Postgres가 종료될 가능성이 가장 높습니다. 2 GB 환경이라면 2 GB 스왑 파일을 추가하여 가져오기 작업 시 컨테이너가 종료되는 대신 서버 속도가 느려지도록 조치하십시오. 플랜을 선택하는 단계라면 4 GB 이상으로 시작하십시오.

Immich 가져오기 작업이 오류 메시지 없이 중단되는 이유는 무엇입니까?

브라우저에서는 두 가지 다른 원인이 동일한 현상으로 나타납니다. 메모리 부족으로 컨테이너가 종료된 후 재시작된 경우 docker ps -a 명령을 실행하면 가동 시간이 비정상적으로 짧은 Up 상태를 확인할 수 있습니다(Exited (137)는 컨테이너가 중지된 상태에서만 나타납니다). 또는 호스트가 스왑을 사용 중인 경우 모든 컨테이너는 실행 중이지만 전체적으로 매우 느려집니다. vmstat 1 5 명령은 이를 구분해 줍니다. si 및 so 열에 0이 아닌 숫자가 지속적으로 나타난다면 스왑이 발생하고 있다는 의미입니다. 어떤 경우든 썸네일 생성, 얼굴 인식, 스마트 검색의 작업 동시성을 낮추십시오.

Immich 로그의 종료 코드 137은 무엇을 의미합니까?

137은 128에 신호 9를 더한 값이므로, 프로세스가 SIGKILL 신호로 종료되었음을 의미합니다. Immich 서버에서 이는 보통 메모리 한계 도달을 뜻하며, 컨테이너 자체 제한이거나 호스트 메모리 부족일 수 있습니다. 하지만 코드만으로는 이를 확정할 수 없습니다. Docker는 컨테이너가 제한 시간(Linux 기본값 10초) 내에 종료되지 않을 때도 SIGKILL을 보냅니다. docker inspect immich_machine_learning | grep -i oomkilled 명령으로 확인하십시오. true 값이 확인되면 커널이 메모리 부족으로 프로세스를 종료한 것이며, free -m 및 sudo dmesg -T | grep -i oom-kill를 통해 컨테이너 제한인지 호스트 전체의 문제인지 파악할 수 있습니다. 머신 러닝 컨테이너는 일반적으로 가장 큰 프로세스이므로 가장 자주 종료되는 대상입니다.

Immich는 사진당 어느 정도의 디스크 공간이 필요합니까?

원본 파일 용량에 10~20퍼센트를 추가하여 예산을 잡으십시오. Immich 문서에 따르면 생성된 썸네일과 트랜스코딩된 비디오는 라이브러리 크기를 평균 10~20퍼센트 증가시키며, 데이터베이스 자체는 대규모 라이브러리라 하더라도 일반적으로 1~3 GB를 차지합니다. 전체 용량은 비디오 파일이 결정하므로, 사진 개수에 배수를 적용하기보다 본인의 평균 파일 크기를 측정하여 플랜을 선택하십시오.

Immich를 위해 GPU가 필요합니까?

아닙니다. Immich의 모든 구성 요소는 CPU에서 실행됩니다. 그래픽 카드는 머신 러닝 컨테이너의 모델 추론과 비디오 인코딩 속도를 높여주지만, 필수 사항은 아닙니다. 대부분의 VPS 플랜은 GPU를 제공하지 않습니다. CPU 전용 하드웨어에서는 트랜스코딩 스레드를 1 또는 2로 설정하고, buffalo_s 얼굴 인식 모델을 사용하며, 첫 대량 가져오기 작업은 밤새 실행되도록 두십시오.