메인 콘텐츠로 바로가기

환경 변수

주의

환경 변수를 변경하려면 Immich 컨테이너를 재생성해야 합니다. 컨테이너를 단순히 재시작한다고 해서 컨테이너 내의 환경이 교체되지는 않습니다!

docker compose를 사용하여 컨테이너를 재생성하려면 docker compose up -d 명령을 실행하세요. 대부분의 경우 docker는 .env 파일의 변경을 인식하고 영향을 받는 컨테이너를 재생성합니다. 이것이 작동하지 않을 경우 docker compose up -d --force-recreate를 실행해 보세요.

Docker Compose​

변수설명기본값컨테이너
IMMICH_VERSION이미지 태그release서버, 머신 러닝
UPLOAD_LOCATION업로드를 위한 호스트 경로서버
DB_DATA_LOCATIONPostgres 데이터베이스 경로데이터베이스
팁

이 환경 변수는 docker-compose.yml 파일에서 사용되며 직접적으로 컨테이너에 영향을 주지는 않습니다.

일반​

변수설명기본값컨테이너작업자
TZ시간대*1서버마이크로서비스
IMMICH_ENV환경 (production, development)production서버, 머신 러닝API, 마이크로서비스
IMMICH_LOG_LEVEL로그 수준 (verbose, debug, log, warn, error)log서버, 머신 러닝API, 마이크로서비스
IMMICH_MEDIA_LOCATION컨테이너 내부의 미디어 위치 ⚠️이 설정을 변경하지 않는 것이 좋습니다*2⚠️/usr/src/app/upload서버API, 마이크로서비스
IMMICH_CONFIG_FILE구성 파일 경로서버API, 마이크로서비스
NO_COLORtrue로 설정하면 색상 코딩된 로그 출력을 비활성화false서버, 머신 러닝
CPU_CORESImmich 서버에 사용할 수 있는 CPU 코어 수자동 감지된 CPU 코어 수서버
IMMICH_API_METRICS_PORTOTEL 메트릭을 위한 포트8081서버API
IMMICH_MICROSERVICES_METRICS_PORTOTEL 메트릭을 위한 포트8082서버마이크로서비스
IMMICH_PROCESS_INVALID_IMAGEStrue인 경우, 잘못된 이미지에 대한 썸네일 생성서버마이크로서비스
IMMICH_TRUSTED_PROXIES신뢰할 수 있는 프록시로 설정된 IP 목록서버API
IMMICH_IGNORE_MOUNT_CHECK_ERRORS시스템 무결성 참조서버API, 마이크로서비스

*1: TZ는 이 리스트의 TZ 식별자로 설정해야 합니다. 예를 들어, TZ="Etc/UTC". TZ는 이미지 메타데이터에서 시간대를 결정할 수 없는 경우 exiftool에서 기본 값으로 사용되며, 로그 파일의 타임스탬프 및 크론 작업 실행에도 사용됩니다.

*2: 이 경로는 Immich 코드가 파일을 찾는 위치이며, 이는 docker 컨테이너 내부에 있습니다. 호스트의 경로로 설정하면 문제가 발생할 수 있으니 대신 UPLOAD_LOCATION 변수를 사용해야 합니다.

작업자​

변수설명기본값컨테이너
IMMICH_WORKERS_INCLUDE이 작업자만 실행서버
IMMICH_WORKERS_EXCLUDE이 작업자를 실행하지 않습니다. 기본 작업자와 일치하거나, 지정된 경우 IMMICH_WORKERS_INCLUDE와 일치서버
정보

현재 작업자에 대한 정보는 여기에서 확인할 수 있습니다.

포트​

변수설명기본값
IMMICH_HOST리스닝 호스트0.0.0.0
IMMICH_PORT리스닝 포트2283 (서버), 3003 (머신 러닝)

데이터베이스​

변수설명기본값컨테이너
DB_URL데이터베이스 URL서버
DB_HOSTNAME데이터베이스 호스트database서버
DB_PORT데이터베이스 포트5432서버
DB_USERNAME데이터베이스 사용자postgres서버, 데이터베이스*1
DB_PASSWORD데이터베이스 비밀번호postgres서버, 데이터베이스*1
DB_DATABASE_NAME데이터베이스 이름immich서버, 데이터베이스*1
DB_SSL_MODE데이터베이스 SSL 모드서버
DB_VECTOR_EXTENSION*2데이터베이스 벡터 확장 (예: [vectorchord, pgvector, pgvecto.rs])서버
DB_SKIP_MIGRATIONS시작 시 마이그레이션 실행을 건너뛸지 여부 (예: [true, false])false서버
DB_STORAGE_TYPESSD에서 동시 IO 최적화 또는 HDD에서 순차 IO 최적화 ([SSD, HDD])*3SSD서버

*1: DB_USERNAME, DB_PASSWORD, 및 DB_DATABASE_NAME 값은 docker-compose.yml에서 POSTGRES_USER, POSTGRES_PASSWORD, 및 POSTGRES_DB 변수로 Postgres 컨테이너에 전달됩니다.

*2: 제공되지 않을 경우 데이터베이스를 검사하여 적합한 확장을 시작 시 자동 감지합니다. 여러 확장이 설치된 경우, VectorChord, pgvecto.rs, pgvector 순으로 선호됩니다.

*3: postgresql.ssd.conf 또는 postgresql.hdd.conf를 사용하며, 주로 SSD에서의 동시 IO 및 HDD에서의 순차 IO를 허용하도록 Postgres effective_io_concurrency 설정을 제어합니다.

정보

모든 DB_ 변수는 API 및 마이크로서비스를 포함하여 모든 Immich 작업자에 제공되어야 합니다.

DB_URL는 형식이 postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename이어야 합니다. 끝에 ?sslmode=require를 추가하여 SSL을 요구하거나, ?sslmode=require&sslmode=no-verify를 추가하여 SSL을 요구하고 인증서 확인을 건너뛸 수 있습니다.

DB_URL이 정의된 경우, DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD 및 DB_DATABASE_NAME 데이터베이스 변수는 무시됩니다.

Redis​

변수설명기본값컨테이너
REDIS_URLRedis URL서버
REDIS_SOCKETRedis 소켓서버
REDIS_HOSTNAMERedis 호스트redis서버
REDIS_PORTRedis 포트6379서버
REDIS_USERNAMERedis 사용자서버
REDIS_PASSWORDRedis 비밀번호서버
REDIS_DBINDEXRedis DB 인덱스0서버
정보

모든 REDIS_ 변수는 API 및 마이크로서비스를 포함하여 모든 Immich 작업자에 제공되어야 합니다.

REDIS_URL은 ioredis://로 시작해야 하며 구성에 대한 base64로 인코딩된 JSON 문자열을 포함해야 합니다. 자세한 내용은 업스트림 ioredis 문서에서 확인할 수 있습니다.

'REDIS_URL' 또는 'REDIS_SOCKET'이 정의된 경우, 'REDIS_HOSTNAME', 'REDIS_PORT', 'REDIS_USERNAME', 'REDIS_PASSWORD' 및 'REDIS_DBINDEX' 변수는 무시됩니다.

Redis (Sentinel) URL 예제 JSON 인코딩 전:

JSON
{
  "sentinels": [
    {
      "host": "redis-sentinel-node-0",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-1",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-2",
      "port": 26379
    }
  ],
  "name": "redis-sentinel"
}

머신 러닝​

변수설명기본값컨테이너
MACHINE_LEARNING_MODEL_TTL모델이 언로드되기 전 비활성 상태 시간 (초) (비활성화: <= 0)300머신 러닝
MACHINE_LEARNING_MODEL_TTL_POLL_S모델 TTL 확인 간격 (초) (비활성화: <= 0)10머신 러닝
MACHINE_LEARNING_CACHE_FOLDER모델을 다운로드할 디렉토리/cache머신 러닝
MACHINE_LEARNING_REQUEST_THREADS*1요청 스레드 풀의 스레드 수(비활성화: <= 0)CPU 코어 수머신 러닝
MACHINE_LEARNING_MODEL_INTER_OP_THREADS병렬 모델 작업 수1머신 러닝
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS각 모델 작업에 대한 스레드 수2머신 러닝
MACHINE_LEARNING_WORKERS*2생성될 작업자 프로세스 수1머신 러닝
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3HTTP Keep-alive 시간 (초)2머신 러닝
MACHINE_LEARNING_WORKER_TIMEOUT작업자가 종료되기 전 최대 비응답 시간 (초)120 (300오픈VINO 사용 시)머신 러닝
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL미리 로드 및 캐시할 (텍스트) CLIP 모델 목록(쉼표로 구분)머신 러닝
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL미리 로드 및 캐시할 (시각) CLIP 모델 목록(쉼표로 구분)머신 러닝
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION미리 로드 및 캐시할 (인식) 안면 인식 모델 목록(쉼표로 구분)머신 러닝
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION미리 로드 및 캐시할 (감지) 안면 인식 모델 목록(쉼표로 구분)머신 러닝
MACHINE_LEARNING_ANN지원되는 경우 ARM-NN 하드웨어 가속 활성화True머신 러닝
MACHINE_LEARNING_ANN_FP16_TURBOFP16 정밀도로 작업 수행: 속도 증가, 정밀도 감소(ARM-NN에만 적용됨)False머신 러닝
MACHINE_LEARNING_ANN_TUNING_LEVELARM-NN GPU 튜닝 수준 (1:빠름, 2:보통, 3:철저)2머신 러닝
MACHINE_LEARNING_DEVICE_IDS*4다중 GPU 환경에서 사용할 장치 ID0머신 러닝
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION안면 인식 모델이 한 번에 처리할 최대 얼굴 수 설정없음 (1오픈VINO 사용 시)머신 러닝
MACHINE_LEARNING_PING_TIMEOUTML 서버가 사용 가능한지 확인할 때 PING 응답 대기시간 (ms)2000서버
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME오프라인 ML 서버를 무시하고 다시 시도하기 전까지의 대기 시간30000서버
MACHINE_LEARNING_RKNN지원되는 경우 RKNN 하드웨어 가속 활성화True머신 러닝
MACHINE_LEARNING_RKNN_THREADS추론 중 RKNN 런타임의 스레드 수 결정1머신 러닝

*1: 머신 러닝 서비스의 동시성 수준을 변경할 때 이 매개변수부터 시작하고 이후 다른 매개변수를 조정하는 것이 좋습니다.

*2: 각 프로세스는 메모리에 모델을 복제하므로, 충분한 메모리 자원이 있는 경우를 제외하고는 값 변경이 권장되지 않습니다.

*3: K8S에서 HPA와 같은 시나리오를 위해. https://github.com/immich-app/immich/discussions/12064

*4: 여러 GPU를 사용할 경우 MACHINE_LEARNING_WORKERS를 1보다 크게 설정해야 합니다. 각 작업자에 대해 라운드 로빈 우선순위로 하나의 장치가 할당됩니다.

정보

'textual' 모델은 스마트 검색에 필수적이지만, 백업으로 인해 다른 모델이 메모리에 로드되어 완료될 때까지 요청을 차단하여 첫 검색이 느려질 수 있습니다. 이를 방지하려면 충분한 RAM이 있는 경우 다른 모델('visual', 'recognition', 'detection')을 미리 로드할 수 있습니다.

추가 머신 러닝 매개변수는 관리자 UI에서 조정할 수 있습니다.

Prometheus​

변수설명기본값컨테이너작업자
IMMICH_TELEMETRY_INCLUDE수집할 대한 텔레메트리들, 'host', 'api', 'io', 'repo', 'job' 목록. 참고: 'all'을 지정하여 전체 활성화할 수도 있습니다.서버API, 마이크로서비스
IMMICH_TELEMETRY_EXCLUDE수집하지 않을 대한 텔레메트리들, 'host', 'api', 'io', 'repo', 'job' 목록서버API, 마이크로서비스

Docker Secrets​

다음 변수들은 추가 보안을 위해 Docker secrets 사용을 지원합니다.

이를 사용하려면 기존 환경 변수값을 동일한 _FILE 환경 변수로 대체하세요. _FILE 변수 값은 변수 값을 포함하는 파일 경로로 설정되어야 합니다.

일반 변수해당 Docker Secrets '_FILE' 변수
DB_HOSTNAMEDB_HOSTNAME_FILE*1
DB_DATABASE_NAMEDB_DATABASE_NAME_FILE*1
DB_USERNAMEDB_USERNAME_FILE*1
DB_PASSWORDDB_PASSWORD_FILE*1
DB_URLDB_URL_FILE*1
REDIS_PASSWORDREDIS_PASSWORD_FILE*2

*1: 공식 문서를 참조하여 Postgres 이미지를 사용하는 방법에 대한 세부 정보를 확인하세요.

*2: Redis 컨테이너에서 비밀번호를 위한 Docker secret 사용 예제로 이 댓글을 참조하세요.

이 페이지 편집
마지막 업데이트 에 업데이트됨 vscodeuser@aigc에 의해 업데이트됨