環境變數
要更改環境變數，您必須重新建立 Immich 容器。 僅重新啟動容器並不會更改容器內的環境變數！
要使用 docker compose 重新建立容器，請運行 docker compose up -d。
在大多數情況下，docker 會識別 .env 文件已更改並重新建立受影響的容器。
如果這不起作用，請嘗試運行 docker compose up -d --force-recreate。
Docker Compose
| 變數 | 描述 | 預設值 | 容器 |
|---|---|---|---|
IMMICH_VERSION | 圖像標籤 | release | server, machine learning |
UPLOAD_LOCATION | 上傳檔案的主機路徑 | server | |
DB_DATA_LOCATION | Postgres 資料庫的主機路徑 | database |
這些環境變數由 docker-compose.yml 文件使用，並且不會直接影響容器。
通用
| 變數 | 描述 | 預設值 | 容器 | 工作者 |
|---|---|---|---|---|
TZ | 時區 | *1 | server | microservices |
IMMICH_ENV | 環境 (production, development) | production | server, machine learning | api, microservices |
IMMICH_LOG_LEVEL | 日誌級別 (verbose, debug, log, warn, error) | log | server, machine learning | api, microservices |
IMMICH_MEDIA_LOCATION | 容器內的媒體位置 ⚠️您可能不應該設置此項*2⚠️ | /usr/src/app/upload | server | api, microservices |
IMMICH_CONFIG_FILE | 設定文件的路徑 | server | api, microservices | |
NO_COLOR | 設置為 true 可禁用色彩化的日誌輸出 | false | server, machine learning | |
CPU_CORES | Immich 服務器可用的 CPU 核心數量 | 自動檢測的 CPU 核心數 | server | |
IMMICH_API_METRICS_PORT | OTEL 指標的端口 | 8081 | server | api |
IMMICH_MICROSERVICES_METRICS_PORT | OTEL 指標的端口 | 8082 | server | microservices |
IMMICH_PROCESS_INVALID_IMAGES | 設為 true 時，為無效圖像生成縮略圖 | server | microservices | |
IMMICH_TRUSTED_PROXIES | 可信代理的逗號分隔的 IP 列表 | server | api | |
IMMICH_IGNORE_MOUNT_CHECK_ERRORS | 查看 系統完整性 | server | api, microservices |
*1: TZ 應設置為 這個清單 中的一個 TZ 標識符。例如，TZ="Etc/UTC"。
TZ 被 exiftool 用作後備選項，以防無法從圖像元資料中確定時區。它也被用於日誌文件的時間戳和定時任務執行。
*2: 該路徑是 Immich 程式查找檔案的位置，它是 Docker 容器的內部路徑。將其設置為主機上的路徑很可能會導致問題，您應該使用 UPLOAD_LOCATION 變數。
工作者
| 變數 | 描述 | 預設值 | 容器 |
|---|---|---|---|
IMMICH_WORKERS_INCLUDE | 僅運行這些工作者。 | server | |
IMMICH_WORKERS_EXCLUDE | 不運行這些工作者。匹配默認工作者，或者如果指定則匹配 IMMICH_WORKERS_INCLUDE | server |
有關當前工作者的資訊，可以在 這裡 找到。
埠配置
| 變數 | 描述 | 預設值 |
|---|---|---|
IMMICH_HOST | 監聽主機 | 0.0.0.0 |
IMMICH_PORT | 監聽埠號 | 2283 (server), 3003 (machine learning) |
資料庫
| 變數 | 描述 | 預設值 | 容器 |
|---|---|---|---|
DB_URL | 資料庫 URL | server | |
DB_HOSTNAME | 資料庫主機 | database | server |
DB_PORT | 資料庫埠 | 5432 | server |
DB_USERNAME | 資料庫用戶 | postgres | server, database*1 |
DB_PASSWORD | 資料庫密碼 | postgres | server, database*1 |
DB_DATABASE_NAME | 資料庫名稱 | immich | server, database*1 |
DB_SSL_MODE | 資料庫 SSL 模式 | server | |
DB_VECTOR_EXTENSION*2 | 資料庫向量擴展（[vectorchord, pgvector, pgvecto.rs] 中的一個） | server | |
DB_SKIP_MIGRATIONS | 是否在啟動時跳過執行遷移（[true, false] 之一） | false | server |
DB_STORAGE_TYPE | 優化 SSD 並發 IO 或 HDD 順序 IO（[SSD, HDD]）*3 | SSD | server |
*1: DB_USERNAME、DB_PASSWORD 和 DB_DATABASE_NAME 的值分別通過 docker-compose.yml 傳遞給 Postgres 容器作為 POSTGRES_USER、POSTGRES_PASSWORD 和 POSTGRES_DB。
*2: 如果未提供，啟動時會透過檢查資料庫自動檢測要使用的適當擴展。如果同時安裝了多個擴展，優先順序為 VectorChord、pgvecto.rs 和 pgvector。
*3: 使用 postgresql.ssd.conf 或 postgresql.hdd.conf，主要通過控制 Postgres 的 effective_io_concurrency 設定來支援 SSD 並發 IO 或 HDD 順序 IO。
所有 DB_ 變數必須提供給所有 Immich 工作者，包括 api 和 microservices。
DB_URL 必須格式化為 postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename。
您可以通過在 DB_URL 字符串末尾添加 ?sslmode=require 要求 SSL，或者添加 ?sslmode=require&sslmode=no-verify 要求 SSL 並跳過證書驗證。
當 DB_URL 被定義時，DB_HOSTNAME、DB_PORT、DB_USERNAME、DB_PASSWORD 和 DB_DATABASE_NAME 資料庫變數將被忽略。
Redis
| 變數 | 描述 | 預設值 | 容器 |
|---|---|---|---|
REDIS_URL | Redis URL | server | |
REDIS_SOCKET | Redis socket | server | |
REDIS_HOSTNAME | Redis 主機 | redis | server |
REDIS_PORT | Redis 埠 | 6379 | server |
REDIS_USERNAME | Redis 用戶名 | server | |
REDIS_PASSWORD | Redis 密碼 | server | |
REDIS_DBINDEX | Redis 資料庫索引 | 0 | server |
所有 REDIS_ 變數必須提供給所有 Immich 工作者，包括 api 和 microservices。
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 |
MACHINE_LEARNING_MODEL_TTL_POLL_S | 檢查模型 TTL 的間隔時間（秒）（若 <= 0 則禁用） | 10 | machine learning |
MACHINE_LEARNING_CACHE_FOLDER | 模型下載的目錄 | /cache | machine learning |
MACHINE_LEARNING_REQUEST_THREADS*1 | 請求線程池的線程數量（若 <= 0 則禁用） | CPU 核心數量 | machine learning |
MACHINE_LEARNING_MODEL_INTER_OP_THREADS | 模型並行操作的數量 | 1 | machine learning |
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS | 每個模型操作的線程數 | 2 | machine learning |
MACHINE_LEARNING_WORKERS*2 | 要生成的工作進程數量 | 1 | machine learning |
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3 | HTTP Keep-alive 的時間（以秒計算） | 2 | machine learning |
MACHINE_LEARNING_WORKER_TIMEOUT | 工作進程無響應的最大時間（秒），超過該時間後將其終止 | 120（使用 OpenVINO 時為 300） | machine learning |
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL | 預加載並緩存的（文本）CLIP 模型的逗號分隔列表 | machine learning | |
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL | 預加載並緩存的（視覺）CLIP 模型的逗號分隔列表 | machine learning | |
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION | 預加載並緩存的（識別）面部識別模型的逗號分隔列表 | machine learning | |
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION | 預加載並緩存的（檢測）面部識別模型的逗號分隔列表 | machine learning | |
MACHINE_LEARNING_ANN | 在支持的情況下啟用 ARM-NN 硬件加速 | True | machine learning |
MACHINE_LEARNING_ANN_FP16_TURBO | 使用 FP16 精度運行操作：在 ARM-NN 中提高速度但降低精度 | False | machine learning |
MACHINE_LEARNING_ANN_TUNING_LEVEL | ARM-NN GPU 調整級別（1: 快速，2: 正常，3: 全面） | 2 | machine learning |
MACHINE_LEARNING_DEVICE_IDS*4 | 在多GPU環境中使用的設備 ID | 0 | machine learning |
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION | 設定面部識別模型一次處理的最大人臉數量 | 無（使用 OpenVINO 時為 1） | machine learning |
MACHINE_LEARNING_PING_TIMEOUT | 檢查機器學習服務器是否可用時等待 PING 響應的時間（以毫秒計算） | 2000 | server |
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME | 機器學習服務器離線後多久再次嘗試連接 | 30000 | server |
MACHINE_LEARNING_RKNN | 在支持的情況下啟用 RKNN 硬件加速 | True | machine learning |
MACHINE_LEARNING_RKNN_THREADS | 啟動 RKNN 運行時進行推理的線程數量 | 1 | machine learning |
*1: 建議先調整此參數以改變機器學習服務的並發級別，然後再調整其他參數。
*2: 由於每個進程會在內存中複製模型，因此除非擁有充足的內存，否則不建議更改此值。
*3: 用於 K8S 中像 HPA 這樣的場景。例如 https://github.com/immich-app/immich/discussions/12064
*4: 使用多GPU需要將 MACHINE_LEARNING_WORKERS 設定為大於 1。每個工作進程按輪詢優先順序分配一個設備。
雖然智慧搜索功能僅需要 textual 模型，但部分用戶可能會遇到首次搜索速度較慢的情況
這是由於備份過程觸發了其他模型載入到內存中，從而在完成之前阻止了其他請求。
為了避免這種情況，如果擁有足夠的內存，您可以預加載其他模型（visual、recognition 和 detection）。
可通過管理界面調整其他機器學習參數。
Prometheus
| 變數 | 描述 | 預設值 | 容器 | 工作者 |
|---|---|---|---|---|
IMMICH_TELEMETRY_INCLUDE | 收集這些遙測數據。可以是 host、api、io、repo、job 列表。注意：您也可以指定 all 來啟用全部 | server | api, microservices | |
IMMICH_TELEMETRY_EXCLUDE | 不收集這些遙測數據。可以是 host、api、io、repo、job 列表 | server | api, microservices |
Docker Secrets
以下變數支持使用 Docker secrets 以提高安全性。
要使用這些變數，需將常規環境變數替換為相應的 _FILE 環境變數。_FILE 變數的值應設為包含變數值的文件路徑。
| 常規變數 | 相應 Docker Secrets _FILE 變數 |
|---|---|
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: 請參閱 官方文檔 獲取 有關如何在 Postgres 映像中使用 Docker Secrets 的詳細信息。
*2: 請參閱 該評論 獲取在 Redis 容器中使用密碼的 Docker secret 示例。