OpenMediaVault 使用指南

外观

进阶Compose 应用开源数据丢失风险OMV 8.x

资料核查：2026-10-23T00:00:00.000Z；尚无本站实机验证记录，请按文中的检查步骤确认本机结果。

Immich：手机相册备份 ​

完成后，手机里的照片和视频会自动备份到 NAS，网页和手机 App 都能浏览，还有人脸、地点和搜索。更重要的是，你清楚照片和数据库各自怎么备份，以及升级前该看什么。

适合谁 ​

  • 想要一个自建的 Google Photos 替代品，核心需求是手机相册自动备份。
  • 机器够用。官方的要求：内存最低 6 GB，推荐 8 GB；CPU 最低 2 核，推荐 4 核。只有 4 GB 内存时，可以关闭机器学习功能再跑。内存更小的机器，用 PhotoPrism 之类更轻的方案，或者只用 SMB 与 Syncthing 同步。
  • 能接受它迭代很快：大版本升级有破坏性改动，而且不支持降级。

Immich 不能替代备份。它的相册管理很强，但照片本身还是要备份到另一块盘或另一台机器，见备份策略：冗余不是备份。

应用信息 ​

项内容
示例清单有 immich，但已经过时，见下
容器immich-server（端口 2283）、immich-machine-learning、redis（Valkey）、database（PostgreSQL，带向量搜索扩展）
数据照片和视频在 UPLOAD_LOCATION；数据库在 DB_DATA_LOCATION；机器学习的模型缓存是一个命名卷，丢了可以重新下载
版本用 .env 里的 IMMICH_VERSION 控制。官方当前的 example.env 写的是大版本标签 v3
官方文档docs.immich.app

插件示例里的 Immich 版本已经落后很多

截至 2026-10-23，示例文件日期是 2025-11-25，但里面的镜像钉在 v1.118.2，而官方最新发布是 v3.x。Immich 官方明确要求使用当前发布版本附带的 docker-compose.yml，并且服务器只兼容匹配的大版本，不支持降级。所以别直接用示例的内容，下面用「从模板添加」只是为了建一个叫 immich 的条目，再把内容换成官方的。

部署 ​

准备 ​

  • 一个放照片的共享文件夹 immich，放在容量大的盘上，文件系统用 EXT4 或 XFS，别用 SMB 共享给别人写入。官方说明，不要通过别的途径改动或删除这里面的文件，否则会产生「找不到的文件」。
  • 数据库目录放在 appdata 下，官方要求它在本地盘上，最好是 SSD，绝不能是网络共享，而且文件系统要支持属主和权限（EXT4、XFS、Btrfs 等，NTFS 和 exFAT 不行）。

步骤 ​

  1. 服务 → Compose → 文件（Services → Compose → Files）→ 添加 → 从模板添加，选 immich，名字保持 immich，添加后点 编辑。
  2. 在你的电脑上，下载官方当前发布的两个文件，只读看，不要运行：
  3. 把 docker-compose.yml 的全部内容粘贴进 文件（File）框，替换掉示例。官方文件里每个服务都用 env_file: .env 读取变量，这依赖设置页默认开启的 创建符号链接，别关。
  4. 勾选 显示环境文件（Show environment file），把 example.env 的内容粘贴进 环境（Environment）框，改成这样：
bash
# 上传的照片和视频：放在大容量盘上的共享文件夹里
UPLOAD_LOCATION=${{ sf:"immich" }}/data
# 数据库文件：必须是本地盘，最好是 SSD，不能是网络共享
DB_DATA_LOCATION=${{ sf:"appdata" }}/immich/postgres
TZ=${{ tz }}
# 大版本标签，以官方 example.env 当前的值为准
IMMICH_VERSION=v3
# 只用字母和数字，不要特殊字符和空格
DB_PASSWORD=<随机密码>
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
  1. 数据库不在 SSD 上的话，在 compose 文件的 database 服务里，取消 DB_STORAGE_TYPE: 'HDD' 那一行的注释，这是官方为机械盘准备的选项。
  2. 端口 2283:2283 被占用时改左边的数字。点 保存，检查，上线。第一次要下载几个体积不小的镜像，耐心等。

首次使用 ​

  1. 浏览器打开 http://<NAS 的 IP>:2283，点 Getting Started。第一个注册的用户就是管理员。
  2. 手机装 Immich App，登录时服务器地址填 http://<NAS 的 IP>:2283。
  3. 点右上角的云图标，选要备份的相册，滚到底部点 Enable Backup，所选相册里的内容会全部上传。
  4. 刚导入完，Immich 会连续跑缩略图、转码、人脸识别、智能搜索这些后台任务，CPU 和内存占用很高，持续多久取决于照片数量。在管理员的 Administration → Job Queues 里可以看进度。

想把已有的照片库接进来，用官方的「外部库」（External Libraries）功能：把目录以只读方式挂进 immich-server 容器，再在管理页添加，见官方文档。

备份：数据库和照片分开想 ​

不要用不停机的方式备份 Immich 的数据库目录

Immich 把文件路径和用户数据都存在数据库里，它不会扫描上传目录来重建，所以数据库至关重要。PostgreSQL 的文件在写入过程中被复制，得到的拷贝可能损坏。

  • 影响范围：只有照片没有可用的数据库，你会丢掉相册、人脸、标签等全部整理工作，要重新导入一遍。
  • 前置条件：不要给 immich 的计划备份勾选 跳过容器停止 / 启动。Postgres 目录通常 1–3 GB，超过插件默认的 最大尺寸（1 GB）会被悄悄跳过，所以别指望插件备份这个目录。
  • 怎么回退：已经用热备份做过备份的，把它当作不可靠，立刻按下面「官方的备份方式」补一份转储和照片备份，并做一次恢复演练。

官方的备份方式 ​

内容位置怎么备份
数据库转储（自动生成）UPLOAD_LOCATION/backupsImmich 默认每天 2:00 自动转储，保留最近 14 份。在 Administration → Settings → Database Dump Settings 调整，也可以在 Administration → Job Queues 里点 Create job，选 Create Database Dump 手动做一份
原始照片和视频UPLOAD_LOCATION/library、upload、profile必须备份
缩略图、转码视频thumbs、encoded-video可以重新生成，不备份的话，恢复后要重跑这些任务

官方的建议是备份整个 UPLOAD_LOCATION，它同时包含了转储文件。具体做法：

  1. 用 rsync 任务把 immich 共享文件夹同步到另一块盘，再按需要做异地备份。同步别加 --delete 这类会删除备份端文件的选项，除非你清楚后果。
  2. 顺序：先数据库，后照片。 这样最坏的结果，是备份里多出几个数据库不知道的文件，可以重新上传；反过来则可能出现数据库引用了备份里没有的文件。要彻底避免不一致，备份时把 immich-server 容器停掉。
  3. 数据库目录 DB_DATA_LOCATION 不用单独备份，靠转储。

官方的 3-2-1 提醒值得再说一遍：Immich 团队只能保证软件本身不丢照片，保证不了硬盘不坏、断电不出事。

恢复 ​

Immich 2.5.0 起，恢复流程在网页里完成：Administration → Maintenance → Restore database backup，选一个备份点击恢复。整机重装时，先放回 UPLOAD_LOCATION 下的几个目录，再在欢迎页点 Restore from backup。命令行恢复需要一个全新的数据库，步骤和风险较高，按官方的备份与恢复文档执行，别凭记忆敲命令。

升级 ​

  • 看发布说明，尤其是大版本。 官方的原则是：破坏性改动，包括 API 和部署方式的改动，只出现在大版本里。官方在 GitHub Discussions 里列出有破坏性改动的版本。
  • 先升手机 App，再升服务器。 手机 App 通常兼容当前和上一个大版本，但服务器只兼容匹配的大版本。
  • 在 服务 → Compose → 文件 选中 immich，点 拉取，再点 上线，最后用 Prune 菜单里的 镜像 清理旧镜像。这对应官方的 docker compose pull && docker compose up -d。
  • 不支持降级，哪怕同一个小版本内。升级出问题，只能恢复升级前的备份，所以升级前先备份数据库和照片。
  • 别放进计划更新。 在计划任务里用 排除过滤器 排除 immich，手动更新，见更新与备份容器。
  • 如果你之前用示例装过旧版本，先备份，再按官方的发布说明逐个大版本升级，不要一次把标签改到最新。

检查结果 ​

  1. 在 OMV 的 shell 里（root）运行 omv-compose-run immich ps，四个容器都是运行状态。
  2. 网页能登录，手机备份一张照片后，网页里能看到它。
  3. immich 共享文件夹里出现了照片文件。在 Job Queues 里手动创建一次数据库转储，UPLOAD_LOCATION/backups 下出现 .sql.gz 文件。
  4. 重启 NAS，应用自己回来了。
  5. 做一次恢复演练，见恢复演练。

常见问题 ​

手机连不上服务器。 手机和 NAS 在同一个局域网吗？地址写的是 http:// 加 IP 和 2283 吗？要在外面用，走 VPN，或者用反向代理与 HTTPS，不要直接映射到公网。

数据库容器反复重启。 先看日志。常见原因：DB_DATA_LOCATION 在不支持属主和权限的文件系统上，或者在网络共享上；DB_PASSWORD 含有特殊字符。

机器学习占满 CPU 和内存。 导入大量照片初期是正常的。内存确实不够，就按官方的说法，关闭机器学习功能。

升级后 App 提示版本不兼容。 服务器和手机 App 的大版本要匹配。先看官方的发布说明。

想用更小的方案。 见 PhotoPrism。

参考资料 ​

OpenMediaVault 非官方中文使用指南，与 openmediavault 项目及其开发者无隶属关系。