配置选项

相关源文件

• .gitignore
• .vscode/launch.json
• Makefile
• docker/docker-compose.dev.yml
• docker/docker-compose.prod.yml
• docker/docker-compose.yml
• docker/example.env
• docs/docs/FAQ.mdx
• docs/docs/administration/backup-and-restore.md
• docs/docs/administration/postgres-standalone.md
• docs/docs/administration/reverse-proxy.md
• docs/docs/administration/storage-template.mdx
• docs/docs/guides/database-queries.md
• docs/docs/guides/template-backup-script.md
• docs/docs/install/all-in-one.md
• docs/docs/install/config-file.md
• docs/docs/install/docker-compose.mdx
• docs/docs/install/kubernetes.md
• docs/docs/install/portainer.md
• docs/docs/install/post-install.mdx
• docs/docs/install/requirements.md
• docs/docs/install/script.md
• docs/docs/install/synology.md
• docs/docs/install/truenas.md
• docs/docs/install/unraid.md
• docs/docs/install/upgrading.md
• docs/docs/overview/quick-start.mdx
• docs/docs/partials/_server-backup.md
• e2e/docker-compose.yml
• install.sh

本页面记录了 Immich 中可用的各种配置选项。它涵盖了环境变量、配置文件、服务设置以及其他选项，以帮助您自定义 Immich 安装。有关安装说明，请参阅Docker Compose或您平台对应的安装指南。

环境变量

Immich 使用环境变量进行基本配置。这些变量通常定义在与您的 docker-compose.yml 文件位于同一目录的 .env 文件中。

核心环境变量

可变	描述	默认	必填
UPLOAD_LOCATION	上传文件存储位置	./library	是
DB_DATA_LOCATION	数据库文件存储位置	./postgres	是
TZ	应用程序时区	Etc/UTC	否
IMMICH_VERSION	Immich 使用的版本	release	否
DB_PASSWORD	PostgreSQL 数据库密码	postgres	是
DB_USERNAME	PostgreSQL 数据库用户名	postgres	否
DB_DATABASE_NAME	PostgreSQL 数据库名称	immich	否

来源：docker/example.env1-23 docs/docs/install/docker-compose.mdx35-43

连接变量

这些变量用于连接外部服务或使用独立 PostgreSQL 服务器时。

可变	描述	示例
DB_URL	现有 PostgreSQL 数据库的连接 URL	postgresql://username:password@host:port/dbname
DB_SKIP_MIGRATIONS	跳过数据库迁移（用于恢复过程）	true
IMMICH_MACHINE_LEARNING_URL	机器学习服务 URL	http://machine-learning-host:3003

来源：docs/docs/administration/postgres-standalone.md21-33 docs/docs/administration/backup-and-restore.md97-98

附加变量

可变	描述
IMMICH_CONFIG_FILE	配置文件路径（参见“配置文件”部分）
IMMICH_TELEMETRY_INCLUDE	设置为 all 以通过 Prometheus 启用指标
IMMICH_IGNORE_MOUNT_CHECK_ERRORS	跳过挂载点验证（仅限测试）

来源：docs/docs/install/config-file.md210-212 docker/docker-compose.dev.yml156-157 e2e/docker-compose.yml21-25

配置文件

除了通过 UI 配置外，您还可以提供 JSON 或 YAML 格式的配置文件。这种方法适用于自动化部署，并可用于对 Immich 配置进行版本控制。

使用配置文件

1. 创建包含您的配置的 JSON 或 YAML 文件
2. 将 IMMICH_CONFIG_FILE 环境变量设置为您的文件路径
3. 重启 Immich 服务器

将当前配置复制到剪贴板的示例命令（来自 Web UI）

Administration > Settings > Copy Configuration

配置结构

配置文件镜像了 UI 中可用的设置。以下是主要配置部分的摘要

媒体处理

机器学习

后台作业

身份验证

存储配置

有关完整的配置选项列表，请参考示例配置文件。

来源：docs/docs/install/config-file.md9-200

Docker Compose 配置

服务架构

服务说明

服务	目的	默认端口	配置注意事项
immich-server	主应用程序服务器	2283	可启用硬件加速进行转码
immich-machine-learning	用于人脸识别、标签等的机器学习服务	3003	可启用硬件加速进行机器学习推理
redis	缓存和后台作业队列	-	使用 Valkey (Redis 分支)
database	带 pgvecto.rs 扩展的 PostgreSQL 数据库	5432	存储所有元数据，包括向量嵌入

来源：docker/docker-compose.yml13-76 docker/docker-compose.prod.yml13-86

硬件加速选项

转码加速

通过取消注释并配置 docker-compose.yml 文件中的 extends 部分，immich-server 服务可以利用硬件加速视频转码。

可用的加速选项

• nvenc - NVIDIA GPU 加速
• quicksync - Intel QuickSync 加速
• rkmpp - Rockchip MPP 加速
• vaapi - 视频加速 API
• vaapi-wsl - 适用于 Linux 的 Windows 子系统 VAAPI

机器学习加速

通过以下任一方式，immich-machine-learning 服务可以利用硬件加速进行机器学习操作：

1. 将加速类型添加到镜像标签

2. 或通过取消注释并配置 extends 部分

可用的加速选项

• armnn - ARM 神经网络加速
• cuda - NVIDIA CUDA 加速
• rocm - AMD ROCm 加速
• openvino - Intel OpenVINO 加速
• openvino-wsl - 适用于 Linux 的 Windows 子系统 OpenVINO
• rknn - Rockchip 神经网络加速

来源：docker/docker-compose.yml14-19 docker/docker-compose.yml34-42

存储配置

存储位置

存储模板

存储模板决定了文件上传到系统时的组织方式。启用后，资产将根据指定的模板从 upload 目录移动到 library 目录。

模板变量

• {{y}} - 年（例如，2023）
• {{MM}} - 月（例如，01）
• {{dd}} - 日（例如，27）
• {{filename}} - 原始文件名

示例模板：{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}

这将按以下结构组织文件：library/user123/2023/2023-01-27/photo.jpg

来源：docs/docs/administration/storage-template.mdx1-6 docs/docs/administration/backup-and-restore.md102-212

作业配置

Immich 使用作业系统异步处理资产。您可以为每种作业类型配置并发数，以根据服务器的性能进行优化。

作业类型	描述	默认并发
backgroundTask	通用后台任务	5
smartSearch	处理智能搜索资产	2
metadataExtraction	从资产中提取元数据	5
faceDetection	检测和分析图像中的人脸	2
search	处理搜索请求	5
sidecar	处理边车文件（XMP 等）	5
library	库扫描和处理	5
migration	数据迁移任务	5
thumbnailGeneration	为资产生成缩略图	3
videoConversion	转码视频	1
notifications	处理通知任务	5

性能考量

• 更高的并发值可以提高吞吐量但会增加资源使用
• 对于机器学习任务（智能搜索、人脸检测），2-3 个并发作业通常会在标准硬件上使 CPU 达到最大负载
• 视频转换是 CPU 密集型任务；增加并发数超过 1 可能会导致高资源使用率
• 存储速度（特别是使用 HDD 时）可能会成为更高并发的瓶颈

来源：docs/docs/install/config-file.md49-82 docs/docs/FAQ.mdx307-318

备份配置

Immich 包含自动数据库备份功能，可通过以下设置进行配置

• enabled：是否启用自动备份
• cronExpression：何时运行备份（默认：每天凌晨 2:00）
• keepLastAmount：保留的备份数量（默认：14）

备份存储在 UPLOAD_LOCATION/backups 中。

可以通过管理界面手动触发备份

1. 导航到管理作业状态页面
2. 打开“创建作业”模态框
3. 选择“备份数据库”并点击“确认”

来源：docs/docs/administration/backup-and-restore.md26-38

认证配置

密码认证

密码认证默认启用。可以通过配置文件进行配置

OAuth 配置

OAuth 可以配置为与外部身份提供商集成

来源：docs/docs/install/config-file.md120-139

高级配置

反向代理

在反向代理后部署 Immich 时，请确保

1. 代理转发所有头部信息
2. 代理正确设置 Host、X-Real-IP、X-Forwarded-Proto 和 X-Forwarded-For 头部信息
3. WebSocket 支持已启用
4. 允许大文件上传（建议：至少 50GB）
5. 超时设置为至少 10 分钟

Nginx 配置示例

来源：docs/docs/administration/reverse-proxy.md1-131

资源限制

在 Docker 环境中，您可以通过为服务添加约束来限制资源使用

来源：docs/docs/FAQ.mdx320-338

非 Root 用户

通过在 docker-compose.yml 中设置 user 参数，Immich 容器可以作为非 root 用户运行

可以添加额外的安全选项

来源：docs/docs/FAQ.mdx375-406

故障排除

常见配置问题

1. 数据库连接问题:

   • 确保 .env 文件中数据库密码设置正确
   • 检查数据库是否可访问并具有正确的权限
   • 对于预先存在的 PostgreSQL 部署，请确保安装了 pgvecto.rs 扩展

2. 存储权限问题:

   • 检查运行 Immich 的用户对 UPLOAD_LOCATION 具有写入权限
   • 对于 Windows 和非 Linux 系统，请确保数据库位于兼容的文件系统上

3. 上传大小限制:

   • 使用反向代理时，请确保允许大文件上传
   • 检查可用磁盘空间

4. 性能问题:

   • 检查作业并发设置并根据系统资源进行调整
   • 考虑为视频转码和机器学习任务使用硬件加速

来源：docs/docs/FAQ.mdx446-485 docs/docs/install/requirements.md46-70