三十而立

立志，躬行

Immich 文档：快速开始

by 请您留言

以下是安装和试用 Immich 的快速、无选择路径。试用之后，您可以使用其他多种方法安装和使用它。

安装要求

Immich 的硬件和软件要求：

硬件

  • 操作系统： 推荐使用 Linux 或 *nix 操作系统（Ubuntu、Debian 等）。
    • 非 Linux 操作系统往往会带来糟糕的 Docker 体验，因此强烈不推荐使用。我们协助在非 Linux 操作系统上进行设置或故障排除的能力将大打折扣。如果您仍想尝试使用非 Linux 操作系统，可以按以下方式进行设置：
      • Windows: Docker Desktop on Windows or WSL 2.
      • macOS: Docker Desktop on Mac.
    • 当在完整的虚拟机中运行时，Immich 在虚拟化环境中运行良好。不建议在 LXC 容器中使用 Docker，但高级用户可以使用。如果遇到问题，我们建议你改用受支持的虚拟机部署。
  • 内存： 最低 4GB，建议 6GB。
  • CPU： 至少 2 核，建议 4 核。
  • 存储： 建议使用与 Unix 兼容的文件系统（EXT4、ZFS、APFS 等），支持用户/组所有权和权限。
    • 生成缩略图和转码视频会使照片库的大小平均增加 10-20%。

提示
良好的性能和与 Postgres 数据库的稳定连接对顺利体验 Immich 至关重要。Postgres 数据库文件的大小通常在 1-3 GB 之间。因此，Postgres 数据库 (DB_DATA_LOCATION) 最好使用本地固态硬盘存储，而不要使用任何类型的网络共享。此外，如果使用 Docker 资源限制，Postgres 数据库至少需要 2GB 内存。Windows 用户在使用非 Unix 兼容文件系统时可能会遇到问题，详情请见下文。

软件

Immich 需要带有 Docker Compose 插件的 Docker：

  • Docker Engine：该 CLI 变体专为 Linux 服务器（或通过 WSL2 使用 Windows）设计。
  • Docker Desktop： 不建议在 Linux 上使用这种 GUI 变体，但可用于 Windows 或 macOS。

Docker Engine 和 Docker Desktop 都将按照链接的安装指南安装 Compose 插件；也可以单独安装。

注意
Immich 需要使用 docker compose 命令；名称相似的 docker-compose 已经过时，不再受 Immich 支持。

对 Windows 用户的特殊要求

Windows 系统上的数据库存储

Immich Postgres 数据库 (DB_DATA_LOCATION) 必须位于支持用户/组所有权和权限的文件系统上（EXT2/3/4、ZFS、APFS、BTRFS、XFS 等）。它不能在任何 NTFS 或 ex/FAT/32 格式的文件系统上运行。在 WSL（Windows Subsystem for Linux）中使用已挂载的主机目录（通常位于 /mnt）时，它将无法运行。如果这是一个问题，你可以按如下方法将绑定挂载改为 Docker 卷：

对 .env 进行如下修改：

- DB_DATA_LOCATION=./postgres
+ DB_DATA_LOCATION=pgdata

在 docker-compose.yml 的底部添加以下一行：

volumes:
  model-cache:
+ pgdata:

设置服务器

Docker Compose [推荐]

Docker Compose 是在生产中运行 Immich 的推荐方法。下面是使用 Docker Compose 部署 Immich 的步骤。

第 1 步 – 下载所需文件

创建一个目录（例如 ./immich-app）来存放 docker-compose.yml 和 .env 文件。

# 移动到你创建的目录
mkdir ./immich-app
cd ./immich-app

运行以下命令下载 docker-compose.yml 和 example.env：

# 下载 docker-compose.yml 文件
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

# 下载 .env 文件
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

您也可以从浏览器下载这两个文件，然后将它们移到您创建的目录中，在这种情况下，请确保将 example.env 重命名为 .env。

第 2 步 – 在 .env 文件中填入自定义值

# 默认环境变量内容
# 有关所有支持的环境变量的文档，请访问 https://immich.app/docs/install/environment-variables

# 上传文件的存储位置
UPLOAD_LOCATION=./library
# 存储数据库文件的位置
DB_DATA_LOCATION=./postgres

# 要设置时区，请取消对下一行的注释，然后将 Etc/UTC 改为以下列表中的时区标识符：https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
# TZ=Etc/UTC

# 要使用的 Immich 版本。可将其固定为特定版本，如 “v1.71.0”。
IMMICH_VERSION=release

# postgres 的连接密码。应将其改为随机密码
# 请仅使用`A-Za-z0-9`字符，不含特殊字符或空格
DB_PASSWORD=postgres

# 此行下面的值无需更改
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
  • 在 UPLOAD_LOCATION 中输入首选的备份资产存储位置。它应该是服务器上一个有足够可用空间的新目录。
  • 考虑将 DB_PASSWORD 改为自定义值。Postgres 不对外公开，因此该密码仅用于本地身份验证。为避免 Docker 在解析该值时出现问题，最好只使用 A-Za-z0-9 字符。
  • 取消 TZ= 行的注释，设置时区。
  • 如有必要，填入自定义数据库信息。

第 3 步 – 为机器学习服务添加国内镜像

Immich 的机器学习服务通过 huggingface.co 网站下载模型，但是这个网站在国内无法访问，需要使用国内镜像。请在 .env 文件中添加下面这行：

HF_ENDPOINT=https://hf-mirror.com

第 4 步 – 启动容器

# 启动容器
docker compose up -d

Docker 版本
如果出现诸如 unknown shorthand flag: ‘d’ in -d 或 open : permission denied 这样的错误，很可能是运行了错误的 Docker 版本。(例如，Ubuntu 22.04.3 LTS 中的 docker.io 软件包就会出现这种情况）。你可以按照发行版的完整 Docker Engine 安装程序，尤其是 “卸载旧版本 ”和 “使用 apt/rpm 软件源安装 ”部分，来纠正这个问题。这些步骤会用 Docker 官方软件包替换发行版的 Docker 软件包。
请注意，正确的命令应该是 docker compose，而不是 docker-compose。如果在 Ubuntu 22.04 上尝试后者，失败的方式会有所不同：
The Compose file ‘./docker-compose.yml’ is invalid because:
‘name’ does not match any of the regexes: ‘^x-‘
请参阅上一段关于从官方 Docker 代码库安装的内容。

健康检查启动间隔
如果出现无法设置 healthcheck.start_interval 的错误，因为该功能需要 Docker Engine v25 或更高版本，那么注释掉 docker-compose.yml 文件中数据库部分的 start_interval 一行会有所帮助。

下一步工作

阅读以下安装后步骤或设置可选功能。

设置可选功能
  • 外部库： 将现有照片库添加到 Immich
  • 硬件转码： 加速视频转码
  • 硬件加速机器学习： 加速 Immich 中的各种机器学习任务
升级

阅读发布说明
Immich 目前正在紧锣密鼓地开发中，这意味着您可能会遇到破坏性更改和错误。因此，我们建议在更新前阅读发行说明，并在使用 Watchtower 等自动化工具时特别小心。
您可以在此处查看有重大变更的版本：https://github.com/immich-app/immich/discussions?discussions_q=label%3Achangelog%3Abreaking-change+sort%3Adate_created

如果设置了 IMMICH_VERSION，则需要更新到最新版本或所需版本。

当发布新版本的 Immich 时，可以使用以下命令升级并重新启动应用程序，这些命令在 docker-compose.yml 文件所在的目录下运行：

# 升级并重启 Immich
docker compose pull && docker compose up -d

要清理磁盘空间，可以使用以下命令删除旧版本的过时容器映像：

# 清理未使用的 Docker 映像
docker image prune

试用网络应用程序

第一个注册的用户将是管理员用户。管理员用户可以向应用程序添加其他用户。

要注册管理员用户，请访问网络应用程序 http://<machine-ip-address>:2283 并单击 “开始 ”按钮。

按照提示注册为管理员用户并登录应用程序。

尝试从浏览器上传图片。

试用移动应用程序

下载手机应用程序

可从以下地方下载手机应用程序：

登录移动应用程序

使用 http://:2283 的服务器端点 URL 登录移动应用程序

在移动应用程序中，你应该能看到从网络用户界面上传的照片。

从移动设备传输照片

  1. 点击屏幕右上角的云图标，导航到备份屏幕。
  2. 您可以在备份界面选择要备份到 Immich 服务器的相册。
  3. 向下滚动到底部，按 “Start Backup（开始备份）”开始备份过程。这将上传所选相册中的所有资产。

备份时间取决于移动设备上的照片数量。大量上传可能需要相当长的时间。要快速开始备份，您可以按照本指南有选择性地先上传几张照片。

您可以选择 “Jobs ”选项卡，查看 Immich 处理照片的过程。

备份和还原

建议采用 3-2-1 备份策略来保护您的数据。您应保留上传的照片/视频以及 Immich 数据库的副本，以提供全面的备份解决方案。本页概述了如何备份数据库以及用户上传图片和视频的位置。此处提供了可作为 cron 作业运行的 bash 脚本模板

危险
本页说明了如何准备备份 Immich 实例，以及备份哪些文件。你仍然需要使用实际的备份工具自行备份。

数据库

注意事项
Immich 将文件路径保存在数据库中，它不会扫描库文件夹来更新数据库，因此备份至关重要。

信息
有关备份和恢复 postgres 数据库的详细信息，请参阅 postgres 官方文档。

注意
不建议直接备份 DB_DATA_LOCATION 文件夹。在数据库运行时这样做会导致备份损坏，无法恢复。

自动数据库备份

为方便起见，Immich 默认会自动创建数据库备份。备份存储在 UPLOAD_LOCATION/backups 中。

如上所述，您应自行备份这些备份以及资产文件夹。

您可以在管理员设置中调整时间表和备份数量。

默认情况下，Immich 会保留最近 14 次备份，并在每天凌晨 2:00 创建新备份。

恢复

我们希望在未来版本中简化还原操作，目前您可以在主机上的 UPLOAD_LOCATION/backups 文件夹中找到备份。

然后，请按照下一节中的步骤还原数据库。

手动备份和恢复

# 备份
docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=postgres | gzip > "/path/to/backup/dump.sql.gz"
# 恢复
docker compose down -v  # 小心！删除所有 Immich 数据，从头开始
## 取消注释下一行，用 Postgres 路径替换 DB_DATA_LOCATION，永久重置 Postgres 数据库
# rm -rf DB_DATA_LOCATION # 小心！删除所有 Immich 数据，从头开始
docker compose pull             # 更新到最新版本的 Immich（如需要）
docker compose create           # 为 Immich 应用程序创建 Docker 容器，而无需运行它们
docker start immich_postgres    # 启动 Postgres 服务器
sleep 10                        # 等待 Postgres 服务器启动
# 如果偏离默认值，请检查数据库用户
gunzip < "/path/to/backup/dump.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| docker exec -i immich_postgres psql --dbname=postgres --username=<DB_USERNAME>  # 恢复备份
docker compose up -d            # 启动其余的 Immich 应用程序

请注意，要使数据库还原正常进行，需要全新安装（即自创建 Docker 容器以来，Immich 服务器从未运行过）。如果运行过 Immich 应用程序，在还原数据库时可能会遇到 Postgres 冲突（关系已存在、违反外键约束、多主键等），在这种情况下，你需要删除 DB_DATA_LOCATION 文件夹以重置数据库。

提示
某些部署方法很难在不启动服务器的情况下启动数据库。在这种情况下，可以在启动服务前设置环境变量 DB_SKIP_MIGRATIONS=true。这将防止服务器运行迁移干扰还原过程。还原数据库后，请务必删除该变量并重新启动服务。

文件系统

Immich 在文件系统中存储两类内容：(a) 原始、未修改的资产（照片和视频），以及 (b) 生成的内容。我们建议备份 UPLOAD_LOCATION 的全部内容，但只有原始内容才是关键，这些内容存储在以下文件夹中：

  1. UPLOAD_LOCATION/library
  2. UPLOAD_LOCATION/upload
  3. UPLOAD_LOCATION/profile

如果只选择备份这些文件夹，则需要在从备份恢复后重新运行所有资产的转码和缩略图生成作业。

注意事项
如果你将其中一些文件夹移到了不同的存储设备上，如 profile/，请确保调整备份路径以符合你的设置

资产类型和存储位置

某些存储位置会受到存储模板的影响。详情请见下文。

存储模板关闭（默认）。

注意
运行 1.92.0 版的新机器默认不使用 UPLOAD_LOCATION/library 文件夹。只有系统管理员激活了存储模板引擎，才会使用该文件夹，更多信息请阅读发行说明。

1. 用户特定文件夹：

  • 每个用户都有一个代表自己的唯一字符串。
  • 你可以在 “账户设置”->“账户”->“用户 ID ”中找到你的用户 ID。

2. 资产类型和存储位置：

  • 源资产：
    • 通过浏览器界面、手机和 CLI 上传的原始资产。
    • 存储在 UPLOAD_LOCATION/upload/。
  • 头像图片：
    • 用户配置文件图像。
    • 存储在 UPLOAD_LOCATION/profile/。
  • 缩略图图像：
    • 每个资产的预览图像（小缩略图和大缩略图）以及识别人脸的缩略图。
    • 存储在 UPLOAD_LOCATION/thumbs/。
  • 编码资产：
    • 为实现更广泛的兼容性而从原始视频重新编码的视频。原始视频不会被删除。
    • 存储在 UPLOAD_LOCATION/encoded-video/。
  • Postgres
    • Immich 数据库，其中包含系统正常运行所需的所有信息。
    • 注意： 该文件夹只会出现在进行了 v1.102.0（可选的非强制更改）中提到的更改或使用该版本启动的用户中。
    • 存储在 DB_DATA_LOCATION 中。

危险
备份此文件夹并不构成备份数据库！请按照此处列出的说明学习如何执行正确的备份。

危险
除备份外，在任何情况下都不要触碰这些文件夹内的文件。更改或删除资产会导致文件无法跟踪和丢失。您可以将其视为 “不可名状的应用程序”，只有通过手机或浏览器界面才能查看、更改和删除资产。

何去何从？

你可以决定以不同的方式安装服务器。

你可能会决定通过 Google Takeout 添加 Google Photos 中的其他照片，甚至是那些不在移动设备上的照片。为此，你可以使用 immich-go：https://github.com/simulot/immich-go。

你可能想从自己的档案中上传照片：https://immich.app/docs/features/command-line-interface。

你可能想从外部资料库（https://immich.app/docs/features/libraries）中加入已有的照片存档，对此有一个指南：https://immich.app/docs/guides/external-library。

你可能希望移动设备自动将照片备份到服务器：https://immich.app/docs/features/automatic-backup。

读者互动

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注