Umgebungsvariablen

Um Umgebungsvariablen zu ändern, müssen die Immich-Container neu erstellt werden. Ein einfaches Neustarten der Container ersetzt nicht die Umgebung innerhalb des Containers!

Um den Container mithilfe von docker compose neu zu erstellen, führen Sie docker compose up -d aus. In den meisten Fällen erkennt Docker, dass sich die .env-Datei geändert hat, und erstellt die betroffenen Container neu. Falls dies nicht funktioniert, versuchen Sie docker compose up -d --force-recreate auszuführen.

Docker Compose

Variable	Beschreibung	Standard	Container
IMMICH_VERSION	Image-Tags	release	server, machine learning
UPLOAD_LOCATION	Host-Pfad für Uploads		server
DB_DATA_LOCATION	Host-Pfad für PostgreSQL-Datenbank		datenbank

Diese Umgebungsvariablen werden von der docker-compose.yml-Datei verwendet und beeinflussen die Container NICHT direkt.

Allgemein

Variable	Beschreibung	Standard	Container	Worker
TZ	Zeitzone	*1	server	microservices
IMMICH_ENV	Umgebung (production, development)	production	server, machine learning	api, microservices
IMMICH_LOG_LEVEL	Log-Level (verbose, debug, log, warn, error)	log	server, machine learning	api, microservices
IMMICH_MEDIA_LOCATION	Medienspeicherort innerhalb des Containers ⚠️Dieser Wert sollte wahrscheinlich nicht gesetzt werden*2⚠️	/usr/src/app/upload	server	api, microservices
IMMICH_CONFIG_FILE	Pfad zur Konfigurationsdatei		server	api, microservices
NO_COLOR	Setzen Sie true, um farbige Log-Ausgaben zu deaktivieren	false	server, machine learning
CPU_CORES	Anzahl der CPU-Kerne, die dem Immich-Server zur Verfügung stehen	Auto-Erkennung der CPU-Kerne	server
IMMICH_API_METRICS_PORT	Port für die OTEL-Metriken	8081	server	api
IMMICH_MICROSERVICES_METRICS_PORT	Port für die OTEL-Metriken	8082	server	microservices
IMMICH_PROCESS_INVALID_IMAGES	Wenn true, generieren Sie Miniaturansichten für ungültige Bilder		server	microservices
IMMICH_TRUSTED_PROXIES	Liste von durch Kommas getrennten IPs, die als vertrauenswürdige Proxies festgelegt sind		server	api
IMMICH_IGNORE_MOUNT_CHECK_ERRORS	Siehe Systemintegrität		server	api, microservices

*1: TZ sollte auf einen TZ-Identifier aus dieser Liste gesetzt werden. Zum Beispiel: TZ="Etc/UTC". TZ wird von exiftool als Fallback verwendet, wenn die Zeitzone nicht aus den Bildmetadaten abgeleitet werden kann. Es wird außerdem für Zeitstempel in Logdateien und die Ausführung von Cron-Jobs verwendet.

*2: Dieser Pfad ist der Ort, an dem Immich nach Dateien sucht und ist innerhalb des Docker-Containers intern. Das Festlegen auf einen Pfad Ihres Hosts wird sicherlich Probleme verursachen; verwenden Sie stattdessen die Variable UPLOAD_LOCATION.

Worker

Variable	Beschreibung	Standard	Container
IMMICH_WORKERS_INCLUDE	Führen Sie nur diese Worker aus.		server
IMMICH_WORKERS_EXCLUDE	Führen Sie diese Worker nicht aus. Abgleiche mit Standard-Workern oder IMMICH_WORKERS_INCLUDE, falls angegeben.		server

Informationen zu den aktuellen Workern finden Sie hier.

Ports

Variable	Beschreibung	Standard
IMMICH_HOST	Listening-Host	0.0.0.0
IMMICH_PORT	Listening-Port	2283 (server), 3003 (machine learning)

Datenbank

Variable	Beschreibung	Standard	Container
DB_URL	Datenbank-URL		server
DB_HOSTNAME	Datenbank-Host	database	server
DB_PORT	Datenbank-Port	5432	server
DB_USERNAME	Datenbank-Benutzer	postgres	server, datenbank*1
DB_PASSWORD	Datenbank-Passwort	postgres	server, datenbank*1
DB_DATABASE_NAME	Name der Datenbank	immich	server, datenbank*1
DB_SSL_MODE	Datenbank-SSL-Modus		server
DB_VECTOR_EXTENSION*2	Datenbank-Vektorerweiterung (eine von [vectorchord, pgvector, pgvecto.rs])		server
DB_SKIP_MIGRATIONS	Ob das Ausführen von Migrationen beim Start übersprungen werden soll (eine von [true, false])	false	server
DB_STORAGE_TYPE	Optimieren Sie gleichzeitiges IO auf SSDs oder sequentielles IO auf HDDs ([SSD, HDD])*3	SSD	server

*1: Die Werte von DB_USERNAME, DB_PASSWORD und DB_DATABASE_NAME werden an den PostgreSQL-Container als Variablen POSTGRES_USER, POSTGRES_PASSWORD und POSTGRES_DB in der docker-compose.yml weitergegeben.

*2: Wenn nicht angegeben, wird die passende Erweiterung beim Start automatisch erkannt, indem die Datenbank inspiziert wird. Sind mehrere Erweiterungen installiert, lautet die Präferenzreihenfolge VectorChord, pgvecto.rs, pgvector.

*3: Verwendet entweder postgresql.ssd.conf oder postgresql.hdd.conf, die hauptsächlich die Postgres-Einstellung effective_io_concurrency steuern, um gleichzeitiges IO auf SSDs und sequentielles IO auf HDDs zu ermöglichen.

Alle DB_-Variablen müssen allen Immich-Workern zur Verfügung gestellt werden, einschließlich api und microservices.

DB_URL muss im Format postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename sein. Sie können SSL verlangen, indem Sie ?sslmode=require an das Ende der DB_URL-Zeichenfolge anfügen, oder SSL verlangen und die Zertifikatsüberprüfung überspringen, indem Sie ?sslmode=require&sslmode=no-verify anfügen.

Wenn DB_URL definiert ist, werden die Datenbankvariablen DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD und DB_DATABASE_NAME ignoriert.

Redis

Variable	Beschreibung	Standard	Container
REDIS_URL	Redis-URL		server
REDIS_SOCKET	Redis-Socket		server
REDIS_HOSTNAME	Redis-Host	redis	server
REDIS_PORT	Redis-Port	6379	server
REDIS_USERNAME	Redis-Benutzername		server
REDIS_PASSWORD	Redis-Passwort		server
REDIS_DBINDEX	Redis-DB-Index	0	server

Info

Alle REDIS_-Variablen müssen allen Immich-Workern zur Verfügung gestellt werden, einschließlich api und microservices.

REDIS_URL muss mit ioredis:// beginnen und dann eine base64-kodierte JSON-Zeichenfolge für die Konfiguration enthalten. Weitere Informationen finden Sie in der ioredis-Dokumentation.

Wenn REDIS_URL oder REDIS_SOCKET definiert sind, werden die Variablen REDIS_HOSTNAME, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD und REDIS_DBINDEX ignoriert.

Beispiel-JSON für Redis (Sentinel)-URL vor der Kodierung:

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"
}

Maschinelles Lernen

Variable	Beschreibung	Standard	Container
MACHINE_LEARNING_MODEL_TTL	Inaktivitätsdauer (s), bevor ein Modell entladen wird (deaktiviert, wenn <= 0)	300	Maschinelles Lernen
MACHINE_LEARNING_MODEL_TTL_POLL_S	Intervall (s) zwischen den Überprüfungen der Modell-TTL (deaktiviert, wenn <= 0)	10	Maschinelles Lernen
MACHINE_LEARNING_CACHE_FOLDER	Verzeichnis, in dem Modelle heruntergeladen werden	/cache	Maschinelles Lernen
MACHINE_LEARNING_REQUEST_THREADS*1	Anzahl der Threads des Anfrage-Threadpools (deaktiviert, wenn <= 0)	Anzahl der CPU-Kerne	Maschinelles Lernen
MACHINE_LEARNING_MODEL_INTER_OP_THREADS	Anzahl paralleler Modelloperationen	1	Maschinelles Lernen
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS	Anzahl der Threads für jede Modelloperation	2	Maschinelles Lernen
MACHINE_LEARNING_WORKERS*2	Anzahl der zu startenden Arbeitsprozesse	1	Maschinelles Lernen
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3	HTTP-Keep-Alive-Zeit in Sekunden	2	Maschinelles Lernen
MACHINE_LEARNING_WORKER_TIMEOUT	Maximale Zeit (s) der Antwortlosigkeit, bevor ein Arbeiter beendet wird	120 (300 bei OpenVINO)	Maschinelles Lernen
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL	Kommagetrennte Liste der CLIP-Modelle (textuell), die vorab geladen und zwischengespeichert werden		Maschinelles Lernen
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL	Kommagetrennte Liste der CLIP-Modelle (visuell), die vorab geladen und zwischengespeichert werden		Maschinelles Lernen
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION	Kommagetrennte Liste der Gesichtserkennungsmodelle (Erkennung), die vorab geladen und zwischengespeichert werden		Maschinelles Lernen
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION	Kommagetrennte Liste der Gesichtserkennungsmodelle (Erkennung), die vorab geladen und zwischengespeichert werden		Maschinelles Lernen
MACHINE_LEARNING_ANN	ARM-NN-Hardware-Beschleunigung aktivieren, falls unterstützt	True	Maschinelles Lernen
MACHINE_LEARNING_ANN_FP16_TURBO	FP16-Gleitkomma-Operationen ausführen: erhöht Geschwindigkeit, verringert Präzision (betrifft nur ARM-NN)	False	Maschinelles Lernen
MACHINE_LEARNING_ANN_TUNING_LEVEL	ARM-NN-GPU-Tuning-Level (1: schnell, 2: normal, 3: ausführlich)	2	Maschinelles Lernen
MACHINE_LEARNING_DEVICE_IDS*4	Geräte-IDs für den Einsatz in Multi-GPU-Umgebungen	0	Maschinelles Lernen
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION	Legt die maximale Anzahl der Gesichter fest, die gleichzeitig vom Gesichtserkennungsmodell verarbeitet werden	Keine (1 bei OpenVINO)	Maschinelles Lernen
MACHINE_LEARNING_PING_TIMEOUT	Wartezeit (ms) für eine PING-Antwort beim Überprüfen der Verfügbarkeit eines ML-Servers	2000	Server
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME	Wartezeit, bevor Offline-ML-Server erneut getestet werden	30000	Server
MACHINE_LEARNING_RKNN	RKNN-Hardware-Beschleunigung aktivieren, falls unterstützt	True	Maschinelles Lernen
MACHINE_LEARNING_RKNN_THREADS	Anzahl der RKNN-Laufzeit-Threads, die für Inferencing gestartet werden.	1	Maschinelles Lernen

*1: Es wird empfohlen, mit diesem Parameter zu beginnen, wenn man die Parallelitätsstufen des Services für maschinelles Lernen anpassen möchte, und anschließend die anderen Parameter zu optimieren.

*2: Da jeder Prozess Modelle im Speicher dupliziert, wird eine Änderung dieses Parameters nicht empfohlen, es sei denn, es steht ausreichend Speicher zur Verfügung.

*3: Für Szenarien wie HPA in K8S. https://github.com/immich-app/immich/discussions/12064

*4: Die Nutzung mehrerer GPUs erfordert, dass MACHINE_LEARNING_WORKERS auf einen Wert > 1 gesetzt wird. Ein einzelnes Gerät wird jedem Arbeiter im Round-Robin-Prioritätsmodus zugewiesen.

Info

Während das textual Modell das einzige ist, das für die intelligente Suche erforderlich ist, könnten einige Benutzer langsame erste Suchen erleben wegen Backups, die das Laden der anderen Modelle in den Speicher auslösen, was andere Anfragen blockiert, bis abgeschlossen. Um dies zu vermeiden, können Sie die anderen Modelle (visual, recognition und detection) vorab laden, wenn Sie über genügend RAM verfügen.

Zusätzliche Parameter für maschinelles Lernen können über die Admin-UI angepasst werden.

Prometheus

Variable	Beschreibung	Standard	Container	Arbeiter
IMMICH_TELEMETRY_INCLUDE	Diese Telemetrien sammeln. Liste von host, api, io, repo, job. Hinweis: Sie können auch all angeben, um alle zu aktivieren		Server	API, Microservices
IMMICH_TELEMETRY_EXCLUDE	Diese Telemetrien nicht sammeln. Liste von host, api, io, repo, job		Server	API, Microservices

Docker Secrets

Die folgenden Variablen unterstützen die Verwendung von Docker Secrets für zusätzliche Sicherheit.

Für die Nutzung einer dieser Variablen ersetzen Sie die reguläre Umgebungsvariable durch die entsprechende _FILE-Umgebungsvariable. Der Wert der _FILE-Variable sollte auf den Pfad einer Datei gesetzt werden, die den Variablenwert enthält.

Reguläre Variable	Äquivalente Docker Secrets _FILE Variable
DB_HOSTNAME	DB_HOSTNAME_FILE*1
DB_DATABASE_NAME	DB_DATABASE_NAME_FILE*1
DB_USERNAME	DB_USERNAME_FILE*1
DB_PASSWORD	DB_PASSWORD_FILE*1
DB_URL	DB_URL_FILE*1
REDIS_PASSWORD	REDIS_PASSWORD_FILE*2

*1: Siehe die offizielle Dokumentation für Details zur Verwendung von Docker Secrets im Postgres-Image.

*2: Siehe diesen Kommentar für ein Beispiel zur Verwendung eines Docker Secrets für das Passwort im Redis-Container.