一个不争的事实是手机相册正在成为家里最重要、也最容易被绑架的数据资产。这几年我试过各种方案来管理家庭照片要么受制于第三方云盘的空间和隐私要么折腾一圈发现软件难用、维护成本高。直到我把immich跑在绿联NAS的Docker里才真正觉得这件事“闭环了”。这篇就用绿联NAS Pro系统UGOS Pro的实际操作把immich的完整部署过程、参数选型和踩坑记录一次讲清楚适合有一台绿联NAS、想告别iCloud/百度网盘、自己掌握照片数据的玩家参考。1. 为什么把immich装到绿联NAS上1.1 家庭照片管理的真实痛点先说需求端。有娃、有宠物、喜欢出门拍照的家庭手机相册基本是按月增涨的一年少说几千张照片和视频。把这些东西放在iCloud、Google Photos或者百度网盘本质上是把一家人的数字记忆托管给了别人还得按月交“赎金”。免费档空间小收费档年年涨更关键的是想换平台时数据迁移极为痛苦。自建方案里我也试过PhotoPrism、Synology Photos这些各有各的问题要么人脸识别依赖外部API要么地图时间线不完整要么App体验太像“管理系统”而不是“相册”。直到有人跟我推荐immich我才发现它几乎就是对标Google Photos做的自托管项目丢掉云端依赖的同时保留了手机的自动备份体验。这也是我最终在绿联NAS上用Docker部署immich的根本原因照片要掌握在自己手里而且App要好用。1.2 immich能干什么immich的核心能力很直接在你自己控制的设备上提供照片/视频的备份、整理、浏览、分享和智能检索。手机App支持后台自动备份新拍的照片自动上传到NAS跟Google Photos的体验几乎一致。自带AI能力包括人脸识别、图片语义搜索比如搜“海边”“狗”以及按地点、时间自动聚合。有网页端、移动端也有专门的TV端全家人可以各用各的手机同时备份。底层数据是标准化的文件目录和PostgreSQL数据库理论上一台NAS坏了只要硬盘还在数据和目录结构就能恢复。说白了immich是从Google Photos退役的绝佳“本地替代品”而绿联NAS恰好是当前性价比较高的家庭存储硬件载体。两者结合照片自托管这件事才能达到“日常无感、关键时刻可靠”的水准。1.3 绿联NAS Pro系统与Docker的适配情况绿联今年更新的UGOS Pro系统内核基于Linux底层支持完整的Docker运行时而且自带的Docker管理器界面比早期版本强了很多支持项目管理compose stack和docker run两种创建方式。Pro系统默认开箱即带Docker环境不需要额外折腾安装这对新手来说很友好。需要提醒的是不同绿联型号的Pro系统版本可能略有差异但Docker的核心机制一致。我用的设备是绿联DXP系列系统为当前最新的UGOS Pro版本。如果你的机型是DX4600等老款但已升级到Pro系统操作路径基本相同只是在存储池命名和目录挂载上需要按你实际的卷名调整。提示不要被“Pro系统”这个名字吓到它本质上就是一个带图形界面的Linux发行版Docker的部署逻辑和你在任何一台Linux服务器上完全一致。理解这一点后面所有参数、目录、权限问题就都有了判断依据。2. 部署前的准备与方案选型2.1 确认硬件和系统状态部署前建议先确认设备状态存储池和共享文件夹逻辑是否清晰至少有一个专门留给Docker数据的存储空间。确认系统已更新到较新的版本老版本系统里Docker管理器可能缺少compose支持。内存建议4GB起步immich的缩略图生成和机器学习服务比较吃内存8GB会更从容。我自己在这台绿联上面额外加了一块闲置SSD作为Docker数据盘专门用来放immich的数据库和缓存机械硬盘就专心存照片原图。这样不仅缩短了数据库读写时间也减少了机械盘的频繁寻道长期运行稳定性会好很多。2.2 数据目录规划图片库、数据库、模型分开这部分是整个部署方案里最重要的基础。immich运行过程中有几类数据真正的照片/视频文件、PostgreSQL数据库文件、机器学习产生的模型和缓存。这三类的读写频率和存储需求完全不同建议从一开始就分开规划。参考目录结构如下/vol1/immich/ ├── library/ # 照片原图、视频原文件适合放机械盘 ├── postgres/ # 数据库数据目录建议放SSD或高速存储 ├── model-cache/ # 机器学习模型缓存容量不大随库走即可 └── backup/ # 可以另外放一份数据库定期备份在绿联系统里我的做法是先在“控制面板—共享文件夹”里建一个名为immich的共享文件夹再在SSD存储池上单独建一个docker-data共享文件夹。UPLOAD_LOCATION指向immich/library机械盘DB_DATA指向SSD上的docker-data/immich-postgres。之所以要坚持“照片目录和数据库目录分开”是因为immich的备份策略对这两者的要求不同原图你做增量同步就行数据库则需要务实的dump两者生命周期完全不同。实操心得绿联默认共享文件夹的路径不是统一的/vol1/xxx那样直观你在Docker管理器里看到的是类似“/volume1/docker”这样的宿主路径。为了减少混淆我建议直接通过命令行或Docker管理器的挂载选项来找路径不要猜。2.3 部署方式选择Docker Compose优先我在绿联Pro系统上实验过两种部署方式一种是直接在Docker管理器里逐个点“创建容器”另一种是使用docker compose来整体编排。结论非常明确——用compose。原因有三immich不是一个容器而是由app服务端、machine-learning机器学习、redis、postgres四个核心容器组成的。用点鼠标的方式创建四个容器任何一个参数记错都会导致后续调试极其痛苦。compose文件是文本天然适合版本管理。你可以把配置文件保存在NAS上升级或迁移时直接复用。绿联UGOS Pro的Docker管理器原生支持compose项目。你只需要把docker-compose.yml放到NAS的某个目录然后在界面里“创建项目”即可。如果你熟悉命令行也可以SSH登录后在目录里执行docker compose up -d效果完全一致。下面我按compose方式给出完整部署。3. compose文件与核心参数详解3.1 完整compose文件以immich v1.x为例先给出我在绿联Pro系统上验证可用的完整配置注意版本号按需固定我用的是当前较稳定的release版本name: immich services: immich-server: image: ghcr.io/immich-app/immich-server:release container_name: immich_server restart: unless-stopped ports: - 2283:2283 volumes: - /volume1/immich/library:/usr/src/app/upload - /etc/localtime:/etc/localtime:ro environment: - TZAsia/Shanghai - IMMICH_VERSIONrelease - DB_HOSTNAMEimmich_postgres - DB_USERNAMEimmich - DB_PASSWORDyour_strong_password_here - DB_DATABASEimmich - REDIS_HOSTNAMEimmich_redis - IMMICH_MACHINE_LEARNING_ENABLEDtrue - IMMICH_MACHINE_LEARNING_URLhttp://immich-machine-learning:3003 depends_on: - immich-redis - immich-postgres - immich-machine-learning restart: unless-stopped immich-machine-learning: image: ghcr.io/immich-app/immich-machine-learning:release container_name: immich_machine_learning restart: unless-stopped volumes: - /volume1/immich/model-cache:/cache environment: - TZAsia/Shanghai depends_on: - immich-redis - immich-postgres immich-redis: image: docker.io/redis:6.2-alpine container_name: immich_redis restart: unless-stopped volumes: - /volume1/immich/redis-data:/data immich-postgres: image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0 container_name: immich_postgres restart: unless-stopped environment: - POSTGRES_USERimmich - POSTGRES_PASSWORDyour_strong_password_here - POSTGRES_DBimmich volumes: - /volume1/immich/postgres:/var/lib/postgresql/data3.2 参数逐项解释为什么这三个项最关键很多人第一次看到这个compose文件会觉得不就是拉镜像跑容器吗其实不然。immich如果起不来80%的问题出在下面这几个参数上。本地路径挂载核心是这一行- /volume1/immich/library:/usr/src/app/upload宿主机的/volume1/immich/library目录会被映射到容器内部的/usr/src/app/upload目录immich的所有原始上传文件都存在这里。这个路径一旦启动后就不要轻易改动否则终端的相册会指向不存在的位置。数据库密码与用户名DB_USERNAME、DB_PASSWORD、DB_DATABASE必须和PostgreSQL容器中设置的POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB完全一致。这一点官方文档写得清楚但实际操作中极容易犯的错误是只改了Postgres的环境变量忘了同步改immich-server的环境变量结果服务器连不上数据库报错信息又不够直观排查半天才反应上来。容器网络互通compose服务之间通过服务名互相通信DB_HOSTNAMEimmich_postgres和REDIS_HOSTNAMEimmich_redis这两个变量就是让server容器通过Docker内部网络找到数据库和缓存的。如果你把两个服务部署到不同的网络栈就会遭遇“能拉镜像但容器一直崩”的怪问题基本就是服务名解析不到。注意postgres镜像不要随意换成官方postgres:14。immich的数据库要依赖pgvecto-rs插件来做向量检索必须使用官方指定的tensorchord/pgvecto-rs镜像版本也要跟着immich官方示例走否则启动数据库时会直接报错。3.3 在绿联Pro系统上创建项目的两种方法方法一界面操作。打开绿联的“Docker”应用进入“项目”页签点击“创建项目”。名称填immich选择compose文件所在目录系统会自动读取docker-compose.yml然后点击部署即可。部署过程中你可以实时看到日志输出第一次拉镜像需要几分钟取决于网络情况。方法二SSH命令行。如果你习惯命令行可以先SSH登录到NAS把compose文件放到固定目录然后执行cd /volume1/immich docker compose up -d这个过程会自动创建immich的网络和四个容器。执行完用docker compose ps查看状态docker compose ps正常情况下四个容器的状态应该是running或healthy。如果某个容器一直显示restarting说明它的启动条件还没满足多半是环境变量或依赖问题优先查看容器日志docker compose logs -f immich-server3.4 初始化管理员账号容器全部up起来后第一次打开immich需要先注册管理员账号。这个步骤大家应该不陌生浏览器访问http://你的NAS_IP:2283页面会提示创建管理员用户邮箱地址密码这个组合一定要牢记用于后续管理后台。管理员创建后可以在App里继续添加其他家庭成员账号每个账号拥有独立的备份空间。我当时的习惯是管理员账号只用来做系统配置和维护真正日常用的账号是给家人各自创建的独立账号。这样即使某个账号出问题也不会影响整个库的管理权限。4. 部署完成后的关键配置与进阶优化4.1 首次体验前必做的三步配置容器跑通只是第一步真正影响日常体验的是接下来这几个设置。无论如何建议先做完再开始导入照片库。配置外部域名/IP和HTTPS。immich网页端首次启动会检测当前访问地址默认是IP:2283。如果以后你要在外网访问或者用反向代理建议在管理控制台“管理—设置—网络设置”里把外部域名配置好避免App扫描二维码时生成错误链接。调整存储模板。immich默认按“年份/月份”存放原图我觉得不够直观习惯改成“按相册名/年度/月份”的模板。在“管理—设置—库设置—上传存储模板”里可以定制路径规则。比如我用的模板是{{album}}/{{year}}/{{month}}这样在NAS资源管理器里翻照片也能顺着相册找而不是面对一堆按日期分的编号目录。开启定时智能分析。机器学习容器起来了但immich默认不会立刻扫描所有历史照片。你需要在“管理—任务”页面确认“智能搜索”CLIP、“人脸检测”、“重复照片检测”等任务处于启用状态可以手动立即执行也可以设置成定期。这里补一句大实话机器学习服务的负载不低首次对几千张照片做人脸聚类可能要跑几小时期间NAS的CPU会明显拉高属正常现象。4.2 硬件加速与性能优化Intel核显QSV很多绿联NAS用的是Intel平台自带核显而immich的缩略图生成和视频转码都支持硬件加速。开启后不仅速度快CPU占用也会降低不少。先在宿主机确认核显设备存在ls /dev/dri如果能看到renderD128说明核显已识别。然后修改compose文件中immich-server的配置加入设备映射devices: - /dev/dri:/dev/dri environment: - IMMICH_ACCELERATE_ENABLEDtrue修改后重新部署项目最后一步是在immich的管理设置里把视频转码的硬件加速选为“Intel Quick SyncQSV”并将转码方案设为“加速”模式。我实测下来绿联这台设备的QSV转码效率提升非常明显原本软转一个4K视频CPU飙到90%开启后基本稳定在20%以内。这一项强烈建议多做一步。4.3 外网访问与定期备份思路immich部署在家里的NAS上优势是数据在自己手里但外网访问也是刚需。常规做法是在路由器或绿联自带的远程访问功能里做端口映射/DDNS然后用反向代理比如Nginx Proxy Manager、Caddy把HTTPS证书和域名转发到内网的2283端口。需要注意直接暴露2283端口到公网并不安全强烈建议通过HTTPS和反代来访问。绿联UGOS Pro自身也带着远程访问能力但为了immich的App体验和上传速度我还是推荐自己配置固定域名DDNS反向代理的方案。备份这个问题很多人部署完就忘了。immich的元数据都在PostgreSQL里如果数据库损坏就算原图还在相册的结构、人脸识别、分享链接也都会丢失。所以我用corn job每天晚上对immich的postgres库做一次pg_dump备份文件写在机械盘上每周再自动同步一份到另一块硬盘或云盘。这个习惯帮我避免过数据丢失的惨剧值得你提前安排。5. 常见问题与排查技巧实录5.1 典型故障速查表这段时间实际运行下来我整理了一份问题速查表覆盖了绿联Pro系统部署immich最常遇到的几类坑。表里是按现象排的遇到问题直接对号入座。现象可能原因解决办法immich-server不断重启数据库密码不一致或数据库未就绪docker compose logs查看具体报错核对DB_PASSWORD和POSTGRES_PASSWORD等postgres完全healthy后再看server上传照片后一直卡“处理中”机器学习服务没起来或队列被阻塞检查immich-machine-learning日志确认IMMICH_MACHINE_LEARNING_URL无误手动触发一次任务App扫码连不上服务器内网地址填写错误或防火墙拦截确保手机上能访问http://NAS_IP:2283确实通不了再从绿联“安全”设置里放行端口视频无法播放或转码失败未开启QSV或核显设备未映射确认宿主有/dev/dri并在compose中devices映射后重启数据库启动直接失败用了官方postgres镜像或pgvecto-rs版本不对严格按照compose示例使用tensorchord/pgvecto-rs:pg14-v0.2.0镜像存储空间上涨极快原图缩略图数据库都在同一目录用参数把library和postgres分盘存放并定期清理旧缩略图5.2 两个非常隐蔽的坑时区与数据库升级时区坑。immich默认时区走容器内的TZ环境变量如果不设置或设置错误你会发现上传的照片时间线整体偏移8小时。这个问题特别隐蔽因为照片本身没坏但时间线看起来就是用不了。解决办法也很简单compose里所有容器统一加入TZAsia/Shanghai并重启项目。升级坑。immich迭代速度极快官方也经常提醒升级前先备份。最稳妥的升级路径是停止项目 → 备份数据库 → 拉新镜像 → 启动项目 → 跑数据库迁移。绿联的Docker管理器里没有一条龙升级按钮我是手动执行docker compose pull后up的。如果直接换上一个新的release版本有可能数据库结构不兼容导致页面白屏或接口报错。实操心得升级前强烈建议对postgres数据目录做一次快照或者至少用pg_dump导一份SQL出来。immich开发团队虽然很拼但频繁更新也给用户带来了版本兼容压力备份是你唯一的后悔药。5.3 排除“绿联系统重启后容器状态异常”的方法实际使用中还有一个让我头疼过的问题NAS重启后部分容器进入异常状态尤其redis和machine-learning有时候会启动顺序不对导致immich-server短暂连不上依赖。后来我在compose里把depends_on加上condition: service_healthy配置并给redis加healthcheck再配合restart: unless-stopped重启后基本都能自动恢复。redis healthcheck你可以这样加immich-redis: image: docker.io/redis:6.2-alpine healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5这样Docker会在确认redis可响应后才让server启动避免容器互相竞争导致连锁重启。6. 升级维护与长期稳定性建议6.1 immich升级的正确姿势immich的版本更新频率确实不算低这也是很多人不敢持续跟新的原因。我这里说下我实践的升级流程算是比较稳的一套组合拳。先进入immich项目目录拉取新镜像docker compose pull然后重新创建容器docker compose up -d升级后打开管理后台首页会提示进行数据库迁移。此时千万不要中断进程迁移期间最好不要重启其他容器。等页面恢复后去任务中心把“智能搜索”“人脸检测”的队列重新跑一遍因为新版本的模型索引算法可能变化。如果升级后出现异常最简单粗暴的回退方案就是恢复到升级前的数据库快照和旧版本镜像。所以每次升级前备份都不可省略这比各种参数调优都重要一百倍。6.2 给长期稳定运行的几条建议定期清理冗余的机器学习任务队列。有人说后台任务堆积其实大多是相册路径变更或导入大目录时触发的。在管理后台“任务”里直接手动清空队列再重新调度就行。保持绿联系统本身不过度超频负载。immich的机器学习任务可以和备份任务错峰比如凌晨2点到5点再做AI分析白天只跑备份。时刻关注存储余量。immich的备份是增量式的照片多了之后library目录增长很快建议给共享文件夹设置容量告警。把immich容器的日志轮转开启避免长时间运行后日志文件占据大量空间。Docker默认支持json-file日志轮转你可以通过daemon.json或compose的logging字段控制。6.3 一些额外的扩展玩法immich部署完之后其实还能往周边延伸出很多玩法这里仅举几个我已经验证过的方向供参考接入Home Assistant实现家庭智能相册的中心化存储。定时任务把重要相册定期导出到移动硬盘做冷备份。结合绿联自己的相册功能把immich中的library目录作为第二个数据源双向使用。如果你对深度学习感兴趣可以基于immich的CLIP语义索引做一套简单的家庭照片问答机器人。这些都属于锦上添花核心还是先把主链路跑稳。说实话immich在功能、更新速度和社区活跃度上确实都处于自托管应用的第一梯队但在绿联Pro系统上部署时如果你完全照搬官方文档可能会在某些细节上卡壳。这篇文章里的路径、compose和环境变量基本是我在绿联设备上反复跑了多次之后确定的方案。按这套流程来绝大多数人应该能顺利把immich跑起来。我这段时间的体会是自托管的核心不是把服务装上就完事而是要让它在日常使用中像水电一样无感而immich恰恰能做到这一点——只要你把备份和升级这两件“幕后工作”提前安排好。