Immich 自托管部署：用 Docker 管理照片与视频-尧图网站建设

📅 发布时间：2026/8/2 3:19:03

手机中的照片和视频不断增长后，常见问题不只是磁盘容量，还包括自动备份、跨设备浏览、相册共享、重复文件控制和元数据检索。Immich 把这些能力组合成一个可自托管的照片管理系统，提供 Web 管理界面和移动端应用，适合家庭相册、个人影像归档、小团队素材共享等场景。

Immich 支持照片和视频上传、移动端后台备份、多用户、共享相册、EXIF 与地图信息、RAW 格式、LivePhoto/MotionPhoto、人脸聚类、对象和 CLIP 搜索、公开分享、OAuth 与 API Key。管理员功能主要位于 Web 端，移动端则更偏向照片浏览和自动备份。

移动端可以按网络、电量和后台任务条件调整自动备份行为。

需要提前明确一点：Immich 是照片管理和同步系统，不应被当作照片的唯一副本。项目 README 明确建议对重要照片执行 3-2-1 备份，即至少保留三份数据、使用两种介质，并有一份位于其他位置。

部署结构与数据边界

官方 Docker Compose 部署通常包含以下组件：

组件	用途	是否需要持久化
`immich-server`	Web、API、上传、媒体处理等核心服务	媒体目录需要持久化
`immich-machine-learning`	人脸识别、对象识别和 CLIP 等机器学习任务	模型缓存建议持久化
PostgreSQL	保存用户、相册、资源索引和任务状态等结构化数据	必须持久化
Valkey/Redis 兼容服务	队列和缓存	由 Compose 管理
Web 访问入口	由`immich-server`提供	默认映射到`2283`端口

照片原文件与 PostgreSQL 数据承担不同职责。只备份上传目录，能够保住媒体文件，却不能完整恢复用户、相册关系、分享配置和索引；只备份数据库，则没有照片原件。备份方案必须同时覆盖两者。

Immich 更新频率较高，部署时应以官方发布版本附带的docker-compose.yml和example.env为准，不要从不同版本分别复制这两个文件。混用模板可能导致环境变量、镜像或数据库扩展不匹配。

一、准备 Linux 与 Docker Compose

部署主机需要运行 Linux，并已安装 Docker Engine 和 Docker Compose 插件。CPU、内存和磁盘需求会受照片数量、视频转码及机器学习任务影响，实际部署前应核对官方的最新要求：

Immich 安装要求
Docker Engine 安装文档
Docker Compose 插件文档

检查 Docker 服务和 Compose 插件是否可用：

docker--versiondockercompose versiondockerinfo

这里使用的是docker compose，中间没有连字符。如果系统只能执行旧版docker-compose，不应直接假定它与当前官方模板兼容，建议按 Docker 官方文档安装 Compose 插件。

再检查可用磁盘空间：

df-hdockersystemdf

Immich 的容量规划不能只按现有照片大小计算。缩略图、转码文件、机器学习模型、数据库和后续上传都需要额外空间。上传目录最好位于容量明确、可监控且能纳入备份的文件系统中。

二、下载官方 Compose 和环境变量模板

创建独立部署目录：

mkdir-p./immich-appcd./immich-appwget-Odocker-compose.yml\https://github.com/immich-app/immich/releases/latest/download/docker-compose.ymlwget-O.env\https://github.com/immich-app/immich/releases/latest/download/example.env

这两个文件来自同一个最新版本发布附件，能够减少模板跨版本混用的问题。若生产环境要求固定版本，应从目标版本的 Release 页面下载对应附件，并在变更记录确认无破坏性升级后再更新。

检查文件是否存在：

ls-lahdocker-compose.yml .envdockercompose config--services

docker compose config --services会解析 Compose 文件并列出服务。如果这里已经报错，应先处理 YAML、环境变量或 Compose 版本问题，不要继续启动容器。

Immich 的正常部署入口是 Docker Compose，不需要在部署目录执行npm install或npm run build。仓库根目录的开发构建方式与发布版容器部署不是同一条路径；在一个只有下载文件的目录中执行npm run build，出现Missing script: "build"并不能说明 Immich 服务本身构建失败。

三、设置媒体目录和数据库参数

使用文本编辑器打开.env：

nano.env

官方模板中的关键项目通常包括：

UPLOAD_LOCATION=./library DB_DATA_LOCATION=./postgres TZ=Etc/UTC IMMICH_VERSION=release DB_PASSWORD=replace_with_a_long_random_password DB_USERNAME=postgres DB_DATABASE_NAME=immich

实际文件应以下载到的example.env内容为准，不要因为示例中出现了某个变量，就在旧版本模板中强行添加。

`UPLOAD_LOCATION`

该目录保存上传的照片和视频及 Immich 管理的媒体数据。相对路径会以 Compose 项目目录为基准，例如：

UPLOAD_LOCATION=./library

也可以改成容量更充足的绝对路径：

UPLOAD_LOCATION=/srv/immich/library

如果使用绝对路径，先创建目录，并确保 Docker 能访问对应文件系统：

sudomkdir-p/srv/immich/library

不要把这个目录放在容易被系统清理的临时路径中，也不要在容器运行期间手工移动或重命名内部文件。Immich 的数据库记录与磁盘文件存在对应关系，绕开应用直接整理目录可能产生不一致。

`DB_DATA_LOCATION`

该目录保存 PostgreSQL 数据文件，例如：

DB_DATA_LOCATION=./postgres

数据库数据目录应位于本地 Linux 文件系统。是否适合放到网络文件系统，需要遵守官方数据库存储说明，不能仅因为网络目录可挂载，就默认它具备 PostgreSQL 所需的锁、同步和一致性语义。

`DB_PASSWORD`

将模板密码换成随机强密码。密码应使用模板允许的字符范围，并妥善保管：

openssl rand-base6432

把生成值填写到：

DB_PASSWORD=需要替换的随机密码

编辑.env后限制文件读取权限：

chmod600.env

`TZ`与版本策略

TZ用于时区设置，可替换为部署环境对应的 IANA 时区名称。无法确定时可保留模板值，并通过官方时区数据库核对。

IMMICH_VERSION=release会跟随官方发布标签。它便于获取当前稳定发布，但也意味着重新拉取镜像时可能进入新版本。对可回滚要求较高的环境，更稳妥的方式是记录当前镜像版本、阅读 Release Notes，并在备份完成后执行升级。

四、检查 Compose 展开结果

启动前先让 Compose 完整解析配置：

dockercompose config>/tmp/immich-compose-rendered.ymldockercompose config--services

这一步可以发现以下问题：

.env中变量未定义；
YAML 缩进或语法错误；
当前 Compose 版本无法解析配置；
挂载路径被展开到非预期位置；
手工修改后出现重复端口或服务名。

不要公开/tmp/immich-compose-rendered.yml，其中可能包含已经展开的数据库密码。检查完成后可以删除：

rm-f/tmp/immich-compose-rendered.yml

如果需要确认端口映射，可在本机查看解析后的 Compose 内容，但不要把包含凭据的完整输出粘贴到公开问题中。官方模板默认通过主机的2283端口提供访问入口。

五、拉取镜像并启动服务

在immich-app目录执行：

dockercompose pulldockercompose up-d

pull与up -d分开执行，便于区分镜像下载错误和容器启动错误。启动后查看容器状态：

dockercomposeps

继续观察服务日志：

dockercompose logs--tail=200

需要持续跟踪核心服务时，可执行：

dockercompose logs-fimmich-server

按Ctrl+C只会结束日志跟踪，不会停止后台容器。

若主机启用了防火墙，应按实际访问方式放行端口。直接访问 Immich 时，需要允许 TCP2283；若前面部署了反向代理，则通常只对外开放代理使用的 HTTP/HTTPS 端口，并限制2283的来源范围。不要为了排错一次性开放无关端口，也不要对公网暴露 PostgreSQL 和缓存服务。

六、创建管理员并完成基础验收

浏览器访问：

http://需要替换的服务器地址:2283

首次进入时，按照页面流程创建管理员账户。管理员创建后，可在 Web 管理界面继续添加普通用户。项目功能表表明，用户管理属于 Web 端管理功能，不在移动端执行。

基础验收不应只看“页面能打开”，至少检查以下路径：

docker compose ps中服务没有反复重启。
Web 页面能够完成管理员登录。
上传一张非敏感测试图片。
刷新页面后，测试图片仍可显示。
打开图片详情，检查时间和 EXIF 等元数据。
执行一次搜索，确认搜索界面与索引任务可用。
重启 Compose 后，再次确认测试资源仍然存在。

重启测试命令如下：

dockercompose restartdockercomposepsdockercompose logs--since=5m

高级搜索可以组合元数据、对象、人脸及其他过滤条件，具体可用项取决于资源类型和索引状态。

如果刚上传的照片暂时无法通过对象或人脸检索，不应立即判定上传失败。上传、生成缩略图、提取元数据和机器学习分析属于不同任务，应结合后台任务状态和immich-machine-learning日志排查。

七、连接移动端并设置自动备份

移动端应用需要填写 Immich 服务地址，例如：

http://需要替换的服务器地址:2283

通过反向代理提供 HTTPS 时，应填写实际 HTTPS 地址。外部访问不应继续依赖局域网地址，也不能只更换端口而忽略证书、代理请求体大小和超时配置。

登录后进入备份页面，按设备相册选择需要同步的目录。

备份范围可以按设备相册选择，避免把截图、缓存图片等目录全部上传。

相册同步设置用于关联设备相册与服务端相册，调整后应以少量测试照片验证归类结果。

自动备份启用后，至少测试以下情况：

新拍摄照片是否进入等待备份队列；
Wi-Fi 或移动网络条件是否符合设置；
应用退到后台后，系统是否允许其执行后台任务；
同一资源重复扫描时是否被重复上传；
LivePhoto/MotionPhoto 是否能按预期备份和播放。

移动系统可能根据省电策略暂停后台任务。Immich 提供后台备份能力，但最终执行仍受系统权限、网络状态和电池优化策略影响。

通知与账户设置

Immich 支持多用户和管理功能，管理员应为每位使用者创建独立账户，不要让所有设备共用管理员凭据。独立账户能隔离个人图库，也便于撤销单个用户的访问权限。

用户可以在设置页面调整通知相关选项，实际可用通知类型以部署版本为准。

需要统一身份认证时，Immich 支持 OAuth。OAuth 涉及回调地址、客户端标识、客户端密钥、发行者地址和外部访问域名，不能只在认证服务中创建客户端而不配置 Immich。相关参数应按官方 OAuth 文档填写，并通过普通用户账户测试登录与退出流程。

外部认证服务需要为 Immich 配置正确的客户端访问范围和重定向地址。

如果只是家庭局域网使用，先完成内置账户、上传、备份和恢复验证，再引入 OAuth，故障边界会更清晰。

备份：媒体文件与数据库必须成套处理

Immich 仓库明确提示采用 3-2-1 备份策略。对 Docker Compose 部署，至少需要保护：

.env和docker-compose.yml；
UPLOAD_LOCATION指向的媒体目录；
PostgreSQL 逻辑备份；
当前 Immich 版本和升级记录；
反向代理配置及证书管理配置，如有。

在immich-app目录中，可以先确认 PostgreSQL 服务名：

dockercompose config--services

官方 Compose 常见数据库服务名为database。确认服务名后，创建逻辑备份目录并导出数据库：

mkdir-p./backupsdockercomposeexec-Tdatabase\pg_dumpall--clean--if-exists\--username="${DB_USERNAME:-postgres}"\>./backups/immich-database.sql

这里的服务名、数据库用户名和具体恢复命令必须与当前版本官方备份文档核对。如果 shell 没有加载.env中的变量，可显式替换用户名：

dockercomposeexec-Tdatabase\pg_dumpall--clean--if-exists--username=postgres\>./backups/immich-database.sql

检查备份文件是否非空：

ls-lh./backups/immich-database.sqltest-s./backups/immich-database.sql

媒体目录可以使用支持增量和校验的备份工具同步到另一块存储介质。下面的目标路径必须替换：

rsync-aH--delete\/srv/immich/library/\/需要替换的备份挂载点/immich-library/

--delete会删除目标端中源端已不存在的文件，只适合维护镜像型副本。若希望保留误删历史，应改用带版本管理或快照能力的备份方案。

配置文件可单独归档：

tar-czf./backups/immich-config.tar.gz\.env docker-compose.yml

数据库导出、媒体副本和配置归档完成后，还要做恢复演练。未经恢复验证的备份，只能证明生成过文件，不能证明能够恢复服务。

应用内的恢复入口用于对应的客户端数据恢复流程，不能代替服务端媒体目录和 PostgreSQL 备份。

升级前后的操作顺序

升级前阅读 Immich Releases 和官方升级说明。跨多个版本时，应检查是否存在要求按中间版本迁移的说明。

记录当前状态：

cd./immich-appdockercomposepsdockercompose imagescpdocker-compose.yml"docker-compose.yml.$(date+%F).bak"cp.env".env.$(date+%F).bak"

完成数据库和媒体备份后，下载同一目标版本配套的 Compose 文件与环境变量模板。不要直接用新example.env覆盖现有.env，应比较新增和废弃变量：

wget-Oexample.env.new\https://github.com/immich-app/immich/releases/latest/download/example.envdiff-u.env example.env.new

.env包含实际密码，而模板包含默认值，差异不能机械覆盖。应把新版本要求的变量合并到现有配置中。

确认配置后执行：

dockercompose pulldockercompose up-ddockercomposepsdockercompose logs--since=10m

升级完成后重新检查登录、上传、缩略图、视频播放、搜索、后台任务和移动端连接。数据库迁移完成后，简单切换旧镜像不一定能回滚数据库结构，因此真正的回滚基础仍然是升级前的数据库与媒体备份。

常见故障定位

`docker compose`命令不存在

表现通常是：

docker: 'compose' is not a docker command

这说明 Compose 插件未安装或 Docker 安装不完整。按 Docker 官方文档安装 Compose 插件，并重新执行：

dockercompose version

端口`2283`无法访问

先确认容器和端口监听状态：

dockercomposepsss-lntp|grep2283curl-Ihttp://127.0.0.1:2283

本机能够访问而外部不能访问，排查主机防火墙、上游防火墙和来源地址限制。本机也不能访问，则查看immich-server日志。不要把数据库端口开放到公网作为处理方式。

容器不断重启

查看最近日志：

dockercomposepsdockercompose logs--tail=300

常见边界包括：

PostgreSQL 数据目录权限或文件系统不适用；
.env中数据库参数不一致；
磁盘空间或 inode 耗尽；
内存不足导致进程被系统终止；
Compose 文件和.env来自不同版本；
升级跨度过大或迁移未完成。

检查系统层面的终止记录：

df-hdf-ifree-hdmesg--ctime|tail-n100

上传失败或大视频中断

直接访问2283时先检查服务日志。经反向代理访问时，还应检查代理的请求体大小、读取超时和上游超时。若内网直连成功、域名访问失败，问题更可能位于代理层，而不是 Immich 上传逻辑。

搜索、人脸识别没有结果

检查机器学习容器和后台任务：

dockercompose logs--tail=200immich-machine-learningdockercomposeps

模型首次下载、资源分析和索引需要时间，并会消耗 CPU、内存和磁盘。是否完成应以任务状态和日志为依据，不能仅通过页面暂时没有搜索结果来判断。

PostgreSQL 启动失败

重点检查DB_DATA_LOCATION：

dockercompose logs--tail=200databasels-ld./postgresdf-h./postgres

如果.env使用绝对路径，则将./postgres替换为实际目录。不要在没有数据库备份的情况下删除该目录或重新初始化数据库。

移动端后台备份停止

依次核对：

应用是否获得照片访问权限；
系统是否允许后台运行；
电池优化是否限制应用；
网络条件是否符合备份设置；
服务地址在当前网络中是否可达；
用户存储配额是否已满；
服务端是否存在上传错误。

重新安装应用不应作为首要排障动作，因为它可能改变本地任务和设置状态。先查看备份队列、网络和服务端日志。

执行`npm run build`报错

发布版 Docker Compose 部署不需要在部署目录执行 Node.js 构建。出现Missing script: "build"时，先确认自己是否误把容器部署步骤与源码开发步骤混在一起。正确的部署检查入口是：

dockercompose configdockercompose pulldockercompose up-d

只有参与源码开发时，才应按照仓库开发文档准备完整源码、包管理器和对应脚本。

部署后的维护边界

Immich 同时管理原文件、派生媒体、数据库关系和机器学习任务，日常维护应围绕这几类数据展开：

定期检查上传目录、数据库目录和 Docker 存储占用；
定期导出 PostgreSQL，并验证 SQL 文件不是空文件；
将媒体副本保存到独立存储介质；
升级前阅读 Release Notes，保留目标版本的 Compose 文件；
不在应用运行期间手工改动媒体目录内部结构；
不把2283、数据库或缓存服务无条件暴露到公网；
通过 HTTPS 提供外部访问，并保护.env、OAuth 密钥和管理员账户；
使用少量测试资源定期验证上传、搜索、下载和恢复链路。

Immich 可以承担照片归档、浏览和自动备份入口，但数据安全仍取决于部署者是否建立了独立、可恢复、经过验证的备份体系。

参考资料

Immich 项目仓库：https://github.com/immich-app/immich
Immich 官方文档：https://docs.immich.app/
项目介绍：https://docs.immich.app/overview/introduction
安装要求：https://docs.immich.app/install/requirements/
Docker Compose 安装：https://docs.docker.com/compose/install/linux/
Immich Releases：https://github.com/immich-app/immich/releases
3-2-1 备份策略：https://www.backblaze.com/blog/the-3-2-1-backup-strategy/
项目 README 标示的许可证：https://opensource.org/license/agpl-v3

Immich 自托管部署：用 Docker 管理照片与视频