企业官网建设流程全解析

一个不争的事实是：手机相册正在成为家里最重要、也最容易被绑架的数据资产。这几年我试过各种方案来管理家庭照片，要么受制于第三方云盘的空间和隐私，要么折腾一圈发现软件难用、维护成本高。直到我把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。

原因有三：

1. immich不是一个容器，而是由app（服务端）、machine-learning（机器学习）、redis、postgres四个核心容器组成的。用点鼠标的方式创建四个容器，任何一个参数记错都会导致后续调试极其痛苦。
2. compose文件是文本，天然适合版本管理。你可以把配置文件保存在NAS上，升级或迁移时直接复用。
3. 绿联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: - TZ=Asia/Shanghai - IMMICH_VERSION=release - DB_HOSTNAME=immich_postgres - DB_USERNAME=immich - DB_PASSWORD=your_strong_password_here - DB_DATABASE=immich - REDIS_HOSTNAME=immich_redis - IMMICH_MACHINE_LEARNING_ENABLED=true - IMMICH_MACHINE_LEARNING_URL=http://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: - TZ=Asia/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_USER=immich - POSTGRES_PASSWORD=your_strong_password_here - POSTGRES_DB=immich volumes: - /volume1/immich/postgres:/var/lib/postgresql/data

3.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_HOSTNAME=immich_postgres和REDIS_HOSTNAME=immich_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-server

3.4 初始化管理员账号

容器全部up起来后，第一次打开immich，需要先注册管理员账号。这个步骤大家应该不陌生：

1. 浏览器访问http://你的NAS_IP:2283
2. 页面会提示创建管理员用户（邮箱地址+密码），这个组合一定要牢记，用于后续管理后台。
3. 管理员创建后，可以在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_ENABLED=true

修改后重新部署项目，最后一步是在immich的管理设置里把视频转码的硬件加速选为“Intel Quick Sync（QSV）”，并将转码方案设为“加速”模式。

我实测下来，绿联这台设备的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最常遇到的几类坑。表里是按现象排的，遇到问题直接对号入座。

5.2 两个非常隐蔽的坑：时区与数据库升级

时区坑。immich默认时区走容器内的TZ环境变量，如果不设置或设置错误，你会发现上传的照片时间线整体偏移8小时。这个问题特别隐蔽，因为照片本身没坏，但时间线看起来就是用不了。解决办法也很简单：compose里所有容器统一加入TZ=Asia/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恰恰能做到这一点——只要你把备份和升级这两件“幕后工作”提前安排好。