先看结论

  • 只下载官方的 docker-compose.yml 和 example.env。四个容器一起启动：主程序、识别、官方数据库、缓存。
  • 照片目录和数据库目录都放固态。机械盘只适合以后放很少打开的旧照片。
  • 第一次打开 http://NAS的局域网IP:2283，最先注册的人就是管理员。
  • 不适合：内存长期低于 6 GB、只想在飞牛应用商店点一下、准备把 2283 直接暴露到公网。
  • 最大风险：拿普通 Postgres 或网上的一体包去接 Immich，容器会起不来或过几天数据对不上。

它和 NAS 自带相册差在哪

相册类的软件功能运行方式都大差不差。我装它是因为人脸分得更准、分类更细，而且不绑死任一操作系统：以后换系统，把照片目录和数据库目录拷走就能再开。

真正拉开差距的是这几处。官方说明分别在 搜索、外部库、手机备份。

用一句话搜照片。 搜索框可以打「穿红衣服的小孩」「海边的晚饭」，不必事先打标签。它看的是画面，不是文件名。照片上的字也能搜到。常见 NAS 相册多半只能搜日期、文件名。

人会自动归堆。 照片多了，侧栏会出现人物。同一个人的脸收在一起，比系统自带相册细。

旧文件夹不用再传一遍。 网盘里已经下好的目录可以挂进去当外部库，Immich 只做索引，文件还在原处。本机后来就是这样挂历史照片的。

手机是官方 App。 勾选相册后会备份；同一张图按内容跳过，不会传两遍。不少开源相册要另找上传工具。

不想碰命令行、内存长期不到 6 GB，或者就要厂商包办远程和备份，用系统自带相册更省事。机器要求见 Immich Requirements：建议 6 GB 内存起、推荐 8 GB。缩略图和转码视频大约再占相册体积的 10%～20%。

Immich 四个官方容器和目录分工
图：网页和手机连 2283；主程序、识别、官方数据库、缓存是一套，不要拆开乱接。

文里这些词是什么意思

你看到的人话
容器一个打包好的小程序，四个加在一起才是完整 Immich
compose 文件告诉电脑「这四个小程序怎么启动」的清单
.env清单旁边的填空：照片放哪、密码是什么
UPLOAD_LOCATION新照片存到 NAS 的哪个文件夹
DB_DATA_LOCATION相册的索引数据库放哪，不是照片本身
healthy这个小程序自己报「我正常」
2283网页和手机要访问的端口

先用 SSH 进飞牛

后面命令都在 NAS 上跑。Windows 不用另装软件。

  1. 飞牛网页打开 SSH（默认端口 22）。
  2. 电脑按 Win + R，输入 cmd 回车。
  3. 输入（用户名和 IP 换成你的）：
ssh 你的用户名@NAS的局域网IP
  1. 第一次问是否继续，输入 yes。密码输入时屏幕不显示字符，输完回车。
  2. 提示符变成 你的用户名@主机名:~$ 就进了。

进不去：确认飞牛已打开 SSH，电脑和 NAS 在同一局域网，IP 在飞牛首页或路由器设备列表里看。

开始前要准备什么

项目要求怎么确认
系统飞牛 fnOS，已打开 Docker飞牛网页能进「容器」或「Docker」
命令能用 docker compose（中间有空格）进 SSH 后跑下面两条
盘系统或数据固态上至少留十几 GBdf -h 看固态那一行
权限账号已加入 docker 组，或能用管理员命令docker ps 不报权限错误
备份这是新装。若目录里已有旧相册，先复制走空目录再开始
docker --version
docker compose version
df -h

本机 2026-08-25 核对：Docker 28.5.2，Compose v2.40.3，固态剩余约 800 GB。Immich 版本是 v3.1.0（镜像标签写 v3，会跟官方当前 v3 走）。

如果提示找不到 docker compose，先去飞牛打开 Docker，不要用已经淘汰的 docker-compose（带横杠）。官方说明见 Immich Docker Compose。

操作步骤

1. 在固态上建目录

为什么做： 照片和数据库分开放，换机器时好搬；数据库不能放网盘共享目录，官方写明网络共享不支持，见 环境变量说明。

mkdir -p /你的固态目录/docker/immich/library
mkdir -p /你的固态目录/docker/immich/postgres
cd /你的固态目录/docker/immich

飞牛里固态常见是单独一块存储空间。不要选机械盘上的「家庭相册」文件夹当数据库目录。

正常结果： pwd 打出的路径以你的固态目录结尾，并且能看到刚建的 library、postgres。

失败时先查： df -h 看你是不是进了机械盘；路径里不要用中文空格和全角标点。

2. 下载官方那两份文件

为什么做： 网上很多过期清单会指向普通数据库或一体包。官方每次发版都提供当前可用的两份文件。

cd /你的固态目录/docker/immich
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
ls -l docker-compose.yml .env

浏览器下载也行：把 example.env 改名为 .env，再放到这个目录。地址仍用上面这两条官方链接。

正常结果： 两个文件都在，docker-compose.yml 里能看到 immich-server、immich-machine-learning、immich_postgres、immich_redis。

本机同一天下载的官方清单里，数据库镜像是 ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0。名字很长，记住一点就够：必须是 Immich 自己的 Postgres。

失败时先查： wget 报错就换飞牛能出门的网络后再下；不要改用随便搜到的百度网盘压缩包。

3. 填写照片路径、时区和数据库密码

为什么做： 不填路径，照片会堆在当前目录的 ./library，以后很难分清哪块盘。密码官方要求只用英文字母和数字。

nano .env

不会 nano：用飞牛「文件管理」找到这个隐藏文件（先打开「显示隐藏文件」），用文本编辑保存成 .env，不要存成 .env.txt。

改成类似下面这样，路径换成你的固态目录：

UPLOAD_LOCATION=/你的固态目录/docker/immich/library
DB_DATA_LOCATION=/你的固态目录/docker/immich/postgres
TZ=Asia/Shanghai
IMMICH_VERSION=v3
DB_PASSWORD=换成一串英文字母和数字
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

DB_PASSWORD 只能用 A-Za-z0-9，不要 !@# 和空格，否则 Docker 解析会出问题。改完用 Ctrl + O 保存，Ctrl + X 退出。

编辑 .env 时只改路径、时区、版本和密码
图：照片和数据库都指向固态。密码不要用符号。下面两行用户名和库名一般不用改。

正常结果：

grep -E 'UPLOAD_LOCATION|DB_DATA_LOCATION|TZ|IMMICH_VERSION' .env

四行都是你刚填的值，没有中文引号，没有行尾多余空格。

失败时先查： Windows 记事本有时会存成 UTF-16。尽量在 NAS 上改。路径两端不要加引号，除非路径里真有空格。

4. 启动四个容器

为什么做： 清单和填空都齐了，一次拉起来。第一次会下载镜像，要等几分钟，视网络而定。

cd /你的固态目录/docker/immich
docker compose up -d

国内拉 ghcr.io 若失败，先确认 NAS 能访问外网。本机可以直接拉取。

正常结果： 命令结束没有红色报错。接着查状态：

docker compose ps
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:2283/

四个名字都应是 healthy（或至少 running 且过一两分钟变成 healthy）。本机端口检查返回 200。

四个官方容器均为 healthy，网页端口 2283 返回 200
图：本机 2026-08-25 的状态。主程序映射 2283，数据库只在内部听 5432，不用再映射到外面。

失败时先查：

docker compose logs --tail=80

看到 unknown shorthand flag: 'd' 或抱怨 compose 版本，说明用的不是 docker compose。看到 healthcheck.start_interval，按官方说明把数据库那段里的 start_interval 注释掉再启动。

5. 第一次打开网页，注册管理员

为什么做： 容器起来还不等于相册能用。官方规定：第一个注册的人就是管理员，见 安装后步骤。

同一局域网的电脑浏览器打开：

http://NAS的局域网IP:2283

第一次应看到开始使用 / 注册。填邮箱、密码，记住这对账号。家庭其他成员以后由管理员在网页里添加，不要每人抢着当第一个。

已经装过、再打开，就会看到登录页。本机截到的是登录页：

飞牛上实际打开的 Immich 登录页
图：本机飞牛 Immich 的登录界面。第一次安装应先出现注册管理员；注册完成后才是这一页。

正常结果： 能进相册首页。即使还没有照片，也不应卡在报错页。

失败时先查： 电脑和 NAS 是否同一局域网；飞牛防火墙是否挡了 2283；docker compose ps 里 immich_server 是不是 healthy。不要用 https:// 去开还没做证书的局域网地址。

6. 手机安装官方 App 并备份

为什么做： 电脑网页适合整理；日常拍照靠手机自动传。

  1. 手机装官方 Immich（App Store / Google Play / 官方 GitHub 发布页）。
  2. 服务器地址填 http://NAS的局域网IP:2283，和电脑浏览器一样。
  3. 用刚注册的管理员账号登录。
  4. 按 App 提示打开备份，勾选要上传的相册。

出门以后局域网 IP 会连不上。那是组网的事，不是 Immich 没装好。家里用就先保证同一 Wi-Fi 能传。

正常结果： App 显示备份进行中或已完成；过几分钟网页时间线出现新照片。

失败时先查： 手机是不是连了访客 Wi-Fi；地址有没有漏写 http://；端口是不是 2283。

装完先不要做的事

  • 不要把 2283 在路由器上对公网做端口映射。要出门看，另做带密码和 HTTPS 的方案。
  • 不要先关手机备份「为了让机械盘睡觉」。照片目录在固态上时，备份不会去转机械盘。机械盘反复转的问题见 飞牛机械硬盘被频繁唤醒如何解决。
  • 不要改完 .env 只点「重启」。官方要求重建容器：docker compose up -d。必要时再加 --force-recreate，见 环境变量说明。
  • 不要用飞牛里已经在跑的普通 Postgres，也不要找「一个容器包打天下」的第三方镜像。本机踩过：postgres:latest 缺 Immich 要的扩展，端口对不上，相册起不来。

常见问题与排错

浏览器打不开 2283

现象： 电脑提示无法访问，或一直转圈。

怎么查：

cd /你的固态目录/docker/immich
docker compose ps
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:2283/
ss -lnt | grep 2283

看到什么算是它： NAS 本机 curl 已是 200，但别的电脑打不开 → 网络或防火墙。本机都不是 200 → 主程序没起来。

处理： 先让四个容器变 healthy。电脑改用局域网 IP，不要用 127.0.0.1（那是电脑自己）。飞牛安全设置里不要挡 2283。

确认好了： 电脑浏览器能看到注册或登录页。

容器一直重启，日志在抱怨数据库

现象： immich_server 或 immich_postgres 状态是 Restarting。

怎么查：

docker compose ps
docker compose logs --tail=100 immich-server
docker compose logs --tail=100 database

看到什么算是它： 日志出现向量扩展、vectorchord、连不上 database:5432、密码认证失败。

处理： 停掉并确认你没有把飞牛里别的 Postgres 填进这份清单。数据库镜像必须是 Immich 官方那一行。密码和 .env 里完全一致，且只有字母数字。数据库目录必须是空目录或这份 Immich 自己写过的目录，不要指向别的库。

确认好了： docker compose ps 四个都是 healthy。

改了照片路径，容器拒绝启动

现象： 日志提到缺少 .immich 标记，或系统完整性检查失败。

怎么查：

docker compose logs --tail=80 immich-server
ls -la /你的固态目录/docker/immich/library

看到什么算是它： 你把已经用过的相册目录换了位置，但没有把里面的标记文件一起拷走。

处理： 新装、空目录可以直接启动。已经有照片再搬家时，把旧目录里各子文件夹中的 .immich 小文件一起拷到新位置，再 docker compose up -d。不要为了图省事把检查关掉。

确认好了： 网页能打开，时间线照片还在。

手机能登录，照片却一直停在机械盘那一声响

现象： 一备份，机箱里的机械盘就转。

怎么查：

grep UPLOAD_LOCATION /你的固态目录/docker/immich/.env

看到什么算是它： 路径落在机械盘存储空间上。

处理： 停容器，把 library 拷到固态，改 .env，把 .immich 一起带走，再 docker compose up -d。不要先关手机备份。

确认好了： 再传一张新照片，机械盘可以继续睡着。判断盘睡没睡的命令见 机械盘唤醒那篇。

备份、更新和回滚

相册有两块都要留：

留下什么在哪丢了会怎样
照片文件UPLOAD_LOCATION 指向的目录原图没了
数据库DB_DATA_LOCATION 指向的目录人脸、相册、分享关系没了，照片文件可能还在

Immich 网页里也可以打开定期倒出数据库。那是数据库的副本，不是再拷一遍照片。官方备份说明见 Backup and Restore。

更新（仍在这个目录里）：

cd /你的固态目录/docker/immich
docker compose pull
docker compose up -d

大版本先看官方发布说明。更新前把上面两个目录复制一份到另一块盘。

停掉但不删数据：

cd /你的固态目录/docker/immich
docker compose down

数据还在那两个文件夹里。只有当你确认不要这套相册时，才删除目录。删除不可恢复。

维护和更新

  • 飞牛大升级后，再跑一次 docker compose ps，确认四个还在。
  • 官方把默认版本写在 IMMICH_VERSION。本机按 v3 跟踪，核对日为 2026-08-25，页面接口返回 3.1.0。
  • 以后若要挂已经在机械盘上的旧照片文件夹，用 Immich 的「外部库」，不要把数据库也挪到机械盘。
  • 最近核对：2026-08-25。四个容器 healthy，http://127.0.0.1:2283/ 返回 200。

参考资料