在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

immich-app/immich

菜单

部署指南

相关源文件

本指南涵盖了在生产环境中部署 Immich 的各种方法。它侧重于推荐的部署方法、配置选项和安装后步骤。有关开发设置信息，请参阅开发指南。

部署选项概述

Immich 提供了多种部署方法，以适应不同的环境和用户偏好。

来源

  • docs/docs/install/docker-compose.mdx
  • docs/docs/install/script.md
  • docs/docs/install/kubernetes.md
  • docs/docs/install/portainer.md
  • docs/docs/install/truenas.md
  • docs/docs/install/unraid.md
  • docs/docs/install/synology.md
  • docs/docs/install/all-in-one.md

系统要求

在部署 Immich 之前，请确保您的系统满足以下最低要求

组件最低要求推荐要求
操作系统基于 Linux/UnixUbuntu, Debian
内存4 GB6+ GB
CPU2 核4+ 核
存储取决于媒体库大小兼容 Unix 的文件系统（EXT4、ZFS 等）
软件带有 Compose 插件的 Docker Engine带有 Compose 插件的 Docker Engine

特殊的数据库存储要求

  • Postgres 数据库 (DB_DATA_LOCATION) 理想情况下应使用本地 SSD 存储
  • 切勿将网络共享用于数据库
  • Windows 用户必须使用支持用户/组所有权的文件系统（不支持 NTFS 或 exFAT）

来源

  • docs/docs/install/requirements.md

Docker Compose 是 Immich 官方推荐的部署方法。下图展示了容器架构

来源

  • docker/docker-compose.yml
  • docker/docker-compose.prod.yml

部署步骤

  1. 创建目录用于 Immich 安装

  2. 下载所需文件:

  3. 在 .env 文件中配置环境变量

    • 将 UPLOAD_LOCATION 设置为您偏好的媒体存储位置
    • 将 DB_DATA_LOCATION 设置为您偏好的数据库存储位置
    • 将 DB_PASSWORD 更改为安全值（仅使用 A-Za-z0-9 字符）
    • 可通过取消注释 TZ= 行来选择性设置时区

  4. 启动容器:

  5. 通过 http://your-server-ip:2283 访问网页界面以完成设置

来源

  • docs/docs/install/docker-compose.mdx
  • install.sh

配置选项

必需的环境变量

可变描述默认备注
UPLOAD_LOCATION媒体文件存储位置./library应有充足的可用空间
DB_DATA_LOCATION数据库文件存储位置./postgres应位于本地存储，切勿使用网络共享
IMMICH_VERSION要使用的 Immich 版本release可设置为特定版本，例如 v1.71.0
DB_PASSWORDPostgres 密码postgres更改为仅使用 A-Za-z0-9 字符的随机密码
DB_USERNAMEPostgres 用户名postgres
DB_DATABASE_NAMEPostgres 数据库名称immich
TZ时区Etc/UTC取消注释并根据需要更改

高级配置： 对于更高级的配置，可以使用 IMMICH_CONFIG_FILE 环境变量提供 JSON 或 YAML 配置文件。有关详细信息，请参阅配置文件。

来源

  • docker/example.env
  • docs/docs/install/config-file.md

硬件加速选项

Immich 支持视频转码和机器学习任务的各种硬件加速选项

启用硬件加速

  1. 对于 视频转码

    • 取消注释并修改 docker-compose.yml 中 immich-server 服务的 extends 部分
    • 将 service: cpu 更改为您想要的加速类型

  2. 对于 机器学习

    • 要么修改镜像标签（例如：${IMMICH_VERSION:-release}-cuda）
    • 或者取消注释并修改 docker-compose.yml 中 immich-machine-learning 服务的 extends 部分

来源

  • docker/docker-compose.yml:16-18, 38-41

数据存储组织

Immich 将媒体和数据组织在多个存储位置

重要提示

  • 当存储模板关闭时（默认），原始资产存储在 upload/<userID> 中
  • 当存储模板打开时，原始资产将移动到 library/<userID> 中，并可自定义组织方式
  • 数据库存储文件路径，因此请避免手动修改文件
  • 仅通过 Immich 网页或移动界面访问/修改资产

来源

  • docs/docs/administration/backup-and-restore.md:96-212

备份与恢复

全面的备份策略应包括数据库和媒体文件

数据库备份方法

Immich 提供自动数据库备份，备份文件存储在 UPLOAD_LOCATION/backups 中。您可以在管理设置中调整备份计划和保留策略。

手动数据库备份

数据库恢复

文件系统备份

Immich 将文件存储在多个应进行备份的目录中

  1. 关键文件夹（原始内容）

    • UPLOAD_LOCATION/library（当存储模板开启时）
    • UPLOAD_LOCATION/upload（默认位置）
    • UPLOAD_LOCATION/profile（用户头像）

  2. 生成内容（如果需要可重新生成）

    • UPLOAD_LOCATION/thumbs（缩略图）
    • UPLOAD_LOCATION/encoded-video（转码视频）

来源

  • docs/docs/administration/backup-and-restore.md
  • docs/docs/guides/template-backup-script.md

反向代理配置

如果您在反向代理后部署 Immich，请确保其已正确配置以与 Immich 协同工作

反向代理的关键要求

  1. 转发所有标头并设置 Host、X-Real-IP、X-Forwarded-Proto 和 X-Forwarded-For
  2. 允许大文件上传（设置适当的 client_max_body_size）
  3. 启用 WebSocket 支持
  4. 设置更长的超时时间（修复页面至少 10 分钟）
  5. 在（子）域的根路径上提供服务（不支持 /immich 等子路径）

Nginx 配置示例

来源

  • docs/docs/administration/reverse-proxy.md

升级 Immich

要将 Immich 升级到新版本

  1. 在 https://github.com/immich-app/immich/releases 阅读发布说明，了解任何重大更改
  2. 如果您已固定特定版本，请更新 .env 文件中的版本
  3. 升级容器:
  4. 清理旧镜像（可选）

来源

  • docs/docs/install/upgrading.md

高级部署场景

使用预先存在的 PostgreSQL 服务器

Immich 可以使用预先存在的 PostgreSQL 服务器，而不是容器化版本

先决条件

  • 安装 pgvecto.rs 扩展（版本 >= 0.2.0, < 0.4.0）
  • 配置 postgresql.conf，使其包含 shared_preload_libraries = 'vectors.so'
  • 兼容 PostgreSQL 版本 14、15 和 16

配置

  1. 在您的 .env 文件中设置 DB_URL 环境变量

    DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename'

  2. 在没有超级用户权限的情况下，准备数据库

来源

  • docs/docs/administration/postgres-standalone.md

其他部署方法

虽然推荐使用 Docker Compose，但 Immich 也可以通过以下方式部署

  1. 安装脚本（实验性）

  2. Kubernetes：使用来自 https://github.com/immich-app/immich-charts/ 的官方 Helm chart

  3. Portainer：使用官方 docker-compose.yml 作为堆栈添加到 Portainer 中

  4. 社区解决方案:

    • TrueNAS SCALE：可在社区应用中找到
    • Unraid：可通过 Docker Compose Manager 插件或社区应用找到
    • Synology：可通过 DSM 中的 Container Manager 部署
    • 一体化：社区维护的包含所有组件的容器

来源

  • docs/docs/install/script.md
  • docs/docs/install/kubernetes.md
  • docs/docs/install/portainer.md
  • docs/docs/install/truenas.md
  • docs/docs/install/unraid.md
  • docs/docs/install/synology.md
  • docs/docs/install/all-in-one.md

故障排除

常见问题与解决方案

问题解决方案
数据库所有权错误确保您没有将 NTFS 或 exFAT 文件系统用于 DB_DATA_LOCATION
视频上传失败检查反向代理配置，确保允许大文件上传
机器学习 worker 崩溃检查可用 RAM，考虑禁用 ML 功能或增加更多 RAM
服务器显示“离线/未知”在您的反向代理中启用 WebSocket
PostgreSQL 健康检查错误如果使用旧版 Docker，请注释掉 docker-compose.yml 中的 start_interval
无法看到大缩略图/预览增加反向代理配置中的超时时间

数据库验证

检查数据库健康状况

来源

  • docs/docs/FAQ.mdx
  • docs/docs/administration/backup-and-restore.md
  • docs/docs/guides/database-queries.md