跳转到主要内容

环境变量

备注

要更改环境变量，您必须重新创建 Immich 容器。 仅重新启动容器不会替换容器内的环境变量！

要使用 docker compose 重新创建容器，请运行 docker compose up -d。 在大多数情况下，docker 会识别到 .env 文件已更改并重新创建受影响的容器。 如果这不起作用，请尝试运行 docker compose up -d --force-recreate。

Docker Compose​

变量描述默认值容器
IMMICH_VERSION镜像标签releaseserver, machine learning
UPLOAD_LOCATION上传文件的主机路径server
DB_DATA_LOCATIONPostgres 数据库的主机路径database
提示

这些环境变量由 docker-compose.yml 文件使用，并不会直接影响容器。

通用​

变量描述默认值容器工作进程
TZ时区*1servermicroservices
IMMICH_ENV环境（生产、开发）productionserver, machine learningapi, microservices
IMMICH_LOG_LEVEL日志级别（verbose、debug、log、warn、error）logserver, machine learningapi, microservices
IMMICH_MEDIA_LOCATION容器内媒体路径 ⚠️您可能不应设置此值*2⚠️/usr/src/app/uploadserverapi, microservices
IMMICH_CONFIG_FILE配置文件路径serverapi, microservices
NO_COLOR设置为 true 以禁用彩色日志输出falseserver, machine learning
CPU_CORES可用于 Immich 服务器的核心数自动检测 CPU 核心数server
IMMICH_API_METRICS_PORT用于 OTEL 指标的端口8081serverapi
IMMICH_MICROSERVICES_METRICS_PORT用于 OTEL 指标的端口8082servermicroservices
IMMICH_PROCESS_INVALID_IMAGES当为 true 时，为无效图像生成缩略图servermicroservices
IMMICH_TRUSTED_PROXIES作为可信代理设置的 IP 列表（用逗号分隔）serverapi
IMMICH_IGNORE_MOUNT_CHECK_ERRORS查看 系统完整性serverapi, microservices

*1: 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数据库 URLserver
DB_HOSTNAME数据库主机databaseserver
DB_PORT数据库端口5432server
DB_USERNAME数据库用户postgresserver, database*1
DB_PASSWORD数据库密码postgresserver, database*1
DB_DATABASE_NAME数据库名称immichserver, database*1
DB_SSL_MODE数据库 SSL 模式server
DB_VECTOR_EXTENSION*2数据库向量扩展（[vectorchord, pgvector, pgvecto.rs] 之一）server
DB_SKIP_MIGRATIONS是否在启动时跳过运行迁移（[true, false] 之一）falseserver
DB_STORAGE_TYPE优化 SSD 的并发 IO 或 HDD 的顺序 IO（[SSD, HDD]）*3SSDserver

*1: DB_USERNAME、DB_PASSWORD 和 DB_DATABASE_NAME 的值作为变量 POSTGRES_USER、POSTGRES_PASSWORD 和 POSTGRES_DB 传递给 docker-compose.yml 中的 Postgres 容器。

*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_URLRedis URLserver
REDIS_SOCKETRedis socketserver
REDIS_HOSTNAMERedis 主机redisserver
REDIS_PORTRedis 端口6379server
REDIS_USERNAMERedis 用户名server
REDIS_PASSWORDRedis 密码server
REDIS_DBINDEXRedis 数据库索引0server
信息

所有 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（哨兵）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 则禁用）300machine learning
MACHINE_LEARNING_MODEL_TTL_POLL_S模型 TTL 检查的间隔时间（秒）（如果 <= 0 则禁用）10machine learning
MACHINE_LEARNING_CACHE_FOLDER模型下载的目录/cachemachine learning
MACHINE_LEARNING_REQUEST_THREADS*1请求线程池的线程数（如果 <= 0 则禁用）CPU 核心数量machine learning
MACHINE_LEARNING_MODEL_INTER_OP_THREADS并行模型操作的数量1machine learning
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS每个模型操作的线程数量2machine learning
MACHINE_LEARNING_WORKERS*2要生成的工作进程数1machine learning
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3HTTP Keep-alive 超时时间（秒）2machine 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 硬件加速Truemachine learning
MACHINE_LEARNING_ANN_FP16_TURBO以 FP16 精度执行操作：增加速度，降低精度（仅适用于 ARM-NN）Falsemachine learning
MACHINE_LEARNING_ANN_TUNING_LEVELARM-NN GPU 调优级别（1: 快速，2: 正常，3: 耗时）2machine learning
MACHINE_LEARNING_DEVICE_IDS*4在多 GPU 环境下使用的设备 ID0machine learning
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION设置人脸识别模型一次处理的最大人脸数量None（使用 OpenVINO 时为 1）machine learning
MACHINE_LEARNING_PING_TIMEOUT检测 ML 服务器是否可用时等待 PING 响应的时间（毫秒）2000server
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME再次尝试之前忽略离线 ML 服务器的时间长度（毫秒）30000server
MACHINE_LEARNING_RKNN如果支持，启用 RKNN 硬件加速Truemachine learning
MACHINE_LEARNING_RKNN_THREADS推理时运行 RKNN 的运行时线程数1machine learning

*1: 建议在调整机器学习服务的并发级别时首先设置此参数，然后再调整其他参数。

*2: 由于每个进程会在内存中复制模型，因此不建议更改此参数，除非您有充足的内存。

*3: 用于 K8S 中 HPA 等场景。https://github.com/immich-app/immich/discussions/12064

*4: 使用多个 GPU 需要将 MACHINE_LEARNING_WORKERS 设置为大于 1 的值。每个工作进程以轮询优先级被分配一个 GPU。

信息

虽然智能搜索只需要 textual 模型，但一些用户可能会因为备份触发其他模型的加载而导致首次搜索变慢。 此加载过程会占用内存，并阻塞其他请求，直到加载完成。 如果您的内存充足，您可以预加载其他模型（visual、recognition 和 detection）。

更多机器学习参数可以通过管理 UI 调整。

Prometheus​

变量描述默认值容器工作者
IMMICH_TELEMETRY_INCLUDE收集的遥测指标。列表包括 host、api、io、repo、job。注意：可以通过指定 all 启用全部serverapi, microservices
IMMICH_TELEMETRY_EXCLUDE不收集的遥测指标。列表包括 host、api、io、repo、jobserverapi, microservices

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 镜像中使用 Docker Secrets 的详细信息。

*2: 有关如何在 Redis 容器中使用 Docker Secrets 保存密码的示例，请参阅 这条评论。