Immich 在群晖 NAS 上的完整部署指南：Container Manager 安装、防火墙规则、升级与固定子网配置

本文基于 Immich 官方文档中的 Synology 社区安装指南（docs/docs/install/synology.md）编写，覆盖从目录规划、配置文件准备、Container Manager 项目创建到防火墙放行的完整流程。读完本文，你可以独立在 DSM 系统上部署 Immich 全家桶（服务端、机器学习、Redis、Postgres 四个容器），理解防火墙 Source IP/端口规则的来由，并掌握版本升级与固定子网（Fixed Subnet）配置这一关键进阶技巧。

适用范围与前置条件

注意：该安装方案为社区贡献（Community contribution），并非 Immich 官方支持的安装方式，相关疑难问题请到 Synology 官方支持渠道咨询。

Immich 可以通过 DSM（DiskStation Manager）中的 Container Manager 在群晖 NAS 上轻松安装。如果尚未安装 Container Manager，请先在群晖的 套件中心（Package Center） 中安装它。

版本适用前提说明：

• 容器镜像标签由 .env 中的 IMMICH_VERSION 控制。当前仓库 docker/example.env 中默认为 IMMICH_VERSION=v3，也可以固定到具体版本号（如 v2.1.0）。
• 安装时请始终使用当前 Release 版本附带的 docker-compose.yml（仓库 docker/docker-compose.yml 顶部注释也明确提醒：main 分支上的 compose 文件可能与最新 Release 不兼容），下文所有讲解均以该文件为准。

Step 1 - 创建目录结构并下载配置文件

1. 规划目录

创建用于存放 Immich 的目录（例如 ./immich-app）。群晖上的一般最佳实践是把所有基于 Docker 的应用放在 ./docker 目录下统一管理，因此最终目录结构为 ./docker/immich-app。

接着在 ./docker/immich-app 下再创建 ./postgres 和 ./library 两个子目录。完成后应当具备：

• ./docker/immich-app/postgres
• ./docker/immich-app/library

2. 下载并上传两个配置文件

下载 docker-compose.yml 与 example.env 到你的电脑（官方发布页的 Release 资源，或执行以下命令），然后上传到 ./docker/immich-app 目录，并把 example.env 重命名为 .env：

# 获取 docker-compose.yml
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

# 获取 .env 文件
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

群晖实用技巧：如果你想用 File Station 中的 Synology 文本编辑器直接编辑 NAS 上的 .env，需要先把它重命名为一个可见文件名（例如 example.txt），否则右键菜单中不会出现"用文本编辑器打开"选项；保存后再改回 .env。

3. 为什么必须是 postgres 和 library 这两个子目录？

这与 docker/docker-compose.yml 中的卷挂载直接对应：

.env 变量	compose 中的挂载	作用
UPLOAD_LOCATION=./library	${UPLOAD_LOCATION}:/data	上传的照片/视频存储位置
DB_DATA_LOCATION=./postgres	${DB_DATA_LOCATION}:/var/lib/postgresql/data	Postgres 数据库数据目录

由于 example.env 中这两个变量是相对路径，它们会相对于 docker-compose.yml 所在目录（即 ./docker/immich-app）解析——这正是 Step 1 要求两个子目录必须建在 ./docker/immich-app 下的原因。compose 文件注释也特别强调：想改媒体/数据库位置，请改 .env 里的值，而不是直接改挂载行。

Step 2 - 为 .env 文件填入自定义值

当前 docker/example.env 的默认内容如下：

# 上传文件的存储位置
UPLOAD_LOCATION=./library

# 数据库文件的存储位置（数据库不支持网络共享存储）
DB_DATA_LOCATION=./postgres

# 设置时区：取消注释并把 Etc/UTC 改为 TZ 标识符
# TZ=Etc/UTC

# 使用的 Immich 版本，可固定到具体版本，如 "v2.1.0"
IMMICH_VERSION=v3

# Postgres 连接口令，建议改为随机密码
# 仅使用 A-Za-z0-9 字符，不要使用特殊字符或空格
DB_PASSWORD=postgres

# 以下值无需更改
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

各变量的取值建议与底层行为：

变量	默认值	说明
UPLOAD_LOCATION	./library	备份资产的存储位置，建议是服务器上空间充足的新目录
DB_DATA_LOCATION	./postgres	数据库文件位置，不支持网络共享
TZ	Etc/UTC	TZ 标识符；从 环境变量文档 可知它会被 exiftool 作为时区兜底值，同时用于日志时间戳和定时任务（cron）执行
IMMICH_VERSION	v3	镜像标签，可固定到具体版本
DB_PASSWORD	postgres	仅用于容器间本地认证（Postgres 不对外暴露端口），但仍应改为随机值；为避免 Docker 解析问题，仅用 A-Za-z0-9 字符，可用 pwgen 生成
DB_USERNAME / DB_DATABASE_NAME	postgres / immich	通常无需修改

补充两条与 compose 实现的对应关系：

• DB_USERNAME、DB_PASSWORD、DB_DATABASE_NAME 会被 compose 透传给 database 容器的 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB 环境变量（见 docker/docker-compose.yml 第 60-64 行）。
• 修改环境变量后必须重建容器才生效，仅重启容器不会替换容器内环境；在 Container Manager 中对应的操作是重新触发 Build。

Step 3 - 在 Container Manager 中创建新项目

1. 打开 Container Manager，在左侧导航栏选择 "Project"，点击 "Create"。
2. 在新项目设置中，Project name 设为便于记忆的名称（如 immich-app）；Path 选择 Step 1 创建的 ./docker/immich-app 目录。此时 Container Manager 会检测到该目录中已存在 docker-compose.yml，弹出提示询问是否使用现有文件，点击 "OK" 继续。
3. 下一屏允许你进一步编辑 docker-compose.yml。请特别注意 DB_STORAGE_TYPE: 'HDD' 这一行——如果你的 NAS 上数据库不是存放在 SSD 上，请取消该行注释。
4. 跳过 Web Station 门户配置一节，完成向导，Container Manager 将自动构建并启动项目的所有容器。

关于 DB_STORAGE_TYPE 的源码级说明

在 docker/docker-compose.yml 第 65-66 行可以看到该变量默认处于注释状态：

# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'

根据 环境变量文档，DB_STORAGE_TYPE 默认值为 SSD，取值为 SSD 或 HDD，它切换 Postgres 底层使用的 IO 配置（核心是 effective_io_concurrency 参数）：SSD 优化并发 IO，HDD 优化顺序 IO。NAS 上机械硬盘盘位很常见，数据库落在 HDD 存储池时记得打开这一项。

理解四个容器的架构

从 docker/docker-compose.yml 可以看出，Immich 项目实际由 4 个服务组成：

服务	容器名	镜像	关键配置
immich-server	immich_server	immich-server	唯一对外暴露端口 2283:2283，依赖 redis 与 database，挂载 ${UPLOAD_LOCATION}:/data
immich-machine-learning	immich_machine_learning	immich-machine-learning	不暴露端口（内部 3003），仅挂载 model-cache 模型缓存卷
redis	immich_redis	Valkey 9	内部 6379 端口，restart: always
database	immich_postgres	定制 Postgres 14（内置 vectorchord 扩展）	shm_size: 128mb，初始化参数 --data-checksums

四个服务均配置了 restart: always 与健康检查。硬件转码/推理加速可通过 compose 中注释的 hwaccel.transcoding.yml / hwaccel.ml.yml 扩展实现，但群晖场景通常使用 CPU 版本即可。

记录容器 IP（Step 4 要用）

容器全部运行后，进入 Container Manager 的 "Container" 分区，右键点击 immich-server 容器，选择 "Details"，滚动到最底部的 Network 分区，找到并记下 IP Address。

Step 4 - 配置防火墙规则

项目构建完成后容器会自动启动。为了让浏览器能访问 Immich、并允许 Immich 各容器之间正常通信，需要配置群晖防火墙。

1. 打开群晖 控制面板（Control Panel），选择 "Security"，进入 "Firewall"。
2. 点击 "Edit Rules"，添加以下两条规则：
   • Source IP 规则：填入 Step 3 中获取的 immich-server 容器 IP 地址；
   • Ports 规则：填入 docker-compose.yml 中指定的端口，即 2283。

2283 即 Immich 服务端的默认监听端口：在 环境变量文档 中，IMMICH_PORT 的默认值即为 2283（machine-learning 服务内部为 3003）；compose 文件中对应的就是 ports: '2283:2283' 一行。

安装后与升级

安装完成后，请继续完成 安装后步骤（注册管理员账户、设置存储模板、下载并登录移动 App、上传媒体库、配置服务器备份）以及阅读 升级说明。

使用 Container Manager 升级 Immich

在执行以下操作前，请先阅读上述安装后与升级文档。

1. 备份：确保照片与视频已备份（备份位置由 .env 中 UPLOAD_LOCATION 决定）。版本升级时不需要删除 docker 文件夹中的任何文件或目录，除非 Release 说明中另有要求。
2. 检查 Release 说明：升级前务必查看官方 Release 说明。
3. 停止容器并清理：打开 Container Manager → Project → 选择 Immich 项目 → Stop 停止；再选择 Action → Clean 删除容器；然后进入 Image 分区，选择 Remove Unused Images 清理无用镜像。
4. 重新构建：进入 Project → Action → Build，Container Manager 会自动下载、解包、安装并启动容器。
5. 更新防火墙规则：在没有固定子网的情况下，容器安装完成后会自动启动。如果 immich_server 运行几秒后停止，很可能是防火墙规则的 Source IP 与新的服务器容器 IP 不匹配了。请到 Container 分区点击 immich_server，在 General 中滚动查看当前 IP，然后到 控制面板 → Security → Firewall 中编辑防火墙规则使两者一致。为防止以后再出现此类问题，建议配置固定子网（见下一节）。

进阶：配置固定子网（Fixed Subnet）

Docker 默认给 bridge 网络分配动态子网，每次重建容器时子网可能变化，从而导致防火墙规则失效。要避免这一行为，在 docker-compose.yml 中定义固定子网：

Step 1. 确定当前子网

进入 Container 分区，点击 immich_server，在 General 中滚动找到 IP 地址，据此确定当前子网段。

Step 2. 添加网络配置

在 docker-compose.yml 文件末尾追加（若容器实际运行在其他子网，请按实际网段修改）：

networks:
  immich-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
          gateway: 172.20.0.1

Step 3. 为每个服务挂接该网络

为全部四个服务（immich-server、immich-machine-learning、redis、database）分别添加网络：

services:
  immich-server:
    # other config options
    networks:
      - immich-network

  immich-machine-learning:
    # other config options
    networks:
      - immich-network

  redis:
    # other config options
    networks:
      - immich-network

  database:
    # other config options
    networks:
      - immich-network

Step 4. 保存并视情况更新防火墙规则

保存后，Synology 会询问是仅保存修改还是重建容器，请选择重建容器（rebuild containers）。如果防火墙规则尚未针对该子网设置，则需按上文 Step 4（防火墙配置）更新规则。

常见排查点速查

现象	原因与处理
File Station 中看不到 .env 或无法用文本编辑器打开	.env 是隐藏文件，临时重命名为 example.txt 编辑后再改回
升级后 immich_server 启动几秒即停止	容器 IP 变化导致防火墙 Source IP 规则失配，按"升级 Step 5"更新规则，或配置固定子网
数据库位于 HDD 存储池	取消 docker-compose.yml 中 DB_STORAGE_TYPE: 'HDD' 的注释
修改了 .env 但行为未变	环境变量变更需要重建容器才会生效（Container Manager 中重新 Build）

参考仓库内文档与配置：docker/docker-compose.yml、docker/example.env、Docker Compose 安装指南、环境变量说明、升级说明。