Immich 部署需求详解：硬件、系统与 Docker 环境的选型指南

本篇技术指南基于 Immich 官方文档 安装要求，系统讲解部署一套自托管照片与视频管理服务所需的硬件规格、操作系统约束、存储选型以及 Docker 软件栈要求。读完本文，你将能够判断自己的服务器（或家用 NAS、虚拟机）是否满足 Immich 的运行条件，并针对 Postgres 数据库、x86-64-v2 指令集、Windows 文件系统这几类最常见的部署陷阱提前做出正确配置。

一、需求总览：Immich 由四个容器组成

在讨论具体硬件参数之前，先明确“需求”作用在哪里。从 docker/docker-compose.yml 可以看到，标准部署包含四个容器：

容器	镜像	关键点
immich_server	ghcr.io/immich-app/immich-server	对外监听 2283 端口，挂载媒体目录 /data
immich_machine_learning	ghcr.io/immich-app/immich-machine-learning	挂载 model-cache 卷存放模型缓存
immich_redis	valkey/valkey:9	缓存与队列，健康检查 redis-cli ping
immich_postgres	ghcr.io/immich-app/postgres:14-...	专用 Postgres 14 镜像，shm_size: 128mb，初始化参数含 --data-checksums

官方 docker/example.env 中还给出了两个核心位置变量的默认值：

# The location where your uploaded files are stored
UPLOAD_LOCATION=./library

# The location where your database files are stored. Network shares are not supported for the database
DB_DATA_LOCATION=./postgres

后续的硬件要求基本都围绕这两类数据（媒体文件、数据库文件）以及机器学习容器的算力开销展开。

二、硬件要求

2.1 操作系统

文档明确推荐 Linux 或其他 *nix 的 64 位系统（Ubuntu、Debian 等），原因如下：

• 非 Linux 系统的 Docker 体验较差，官方强烈不建议，且对非 Linux 系统的支持与排错能力“将严重受限”；
• 如果仍想在非 Linux 系统上使用，官方给出的两条路径是：Windows 使用 Docker Desktop（基于 WSL 2）或纯 WSL 2；macOS 使用 Docker Desktop；
• Immich 在完整虚拟机中运行良好；但在 LXC 容器内使用 Docker 不推荐（仅高级用户可能可行），遇到问题时官方建议切换到受支持的 VM 部署方式。

2.2 内存（RAM）

• 最低 6GB，推荐 8GB；
• 对于资源有限的 4GB 系统，可以禁用机器学习功能后运行，但资产上传等场景的体验会受限；
• 如果使用了 Docker 资源限制，Postgres 数据库本身至少需要 2GB RAM。

2.3 CPU 与指令集（重点）

• 最少 2 核，推荐 4 核；
• Immich 同时支持 amd64 与 arm64 平台；
• 一个容易踩坑的约束：自 v3 起，amd64 平台上的机器学习容器要求 CPU 至少支持 x86-64-v2 微架构级别。大约 2012 年之后发布的大多数 CPU 都满足这一级别；
• 如果使用虚拟机（例如 Proxmox），需要显式选择支持该微架构的 QEMU CPU 类型，否则宿主机可能透传 x86-64-v1 导致 ML 容器无法运行；
• 若你的硬件只能跑 x86-64-v1，最后一个支持该指令集的版本是 v2.7.5，但该版本已不再受支持，且必须搭配相同版本的 immich-server 使用。

从 docker/example.env 可见当前仓库默认 IMMICH_VERSION=v3，即默认部署就已经落入 x86-64-v2 的要求范围内。

2.4 存储

• 推荐使用支持用户/组所有权与权限的 Unix 兼容文件系统（EXT4、ZFS、APFS、BTRFS、XFS 等）；
• 缩略图与转码视频的生成会使媒体库体积平均增加 10%～20%，规划磁盘容量时应预留这部分空间；
• 数据库对存储介质有额外要求，见下一节。

三、Postgres 数据库的存储要求（性能关键项）

文档特别用提示框强调了数据库存储，这是整套需求中最容易被忽视、却最直接影响体验的一条：

良好的性能与稳定的 Postgres 连接是平滑使用 Immich 的关键。Postgres 数据库文件通常大小为 1～3GB。因此 DB_DATA_LOCATION 应理想地使用本地 SSD 存储，绝不能使用任何形式的网络共享。

对应到仓库中的具体配置：

1. docker/docker-compose.yml 中 database 服务把 ${DB_DATA_LOCATION} 绑定挂载到 /var/lib/postgresql/data，并设置了 shm_size: 128mb 与 POSTGRES_INITDB_ARGS: '--data-checksums'（启用数据页校验和，保证数据完整性）；
2. 镜像本身是 Immich 定制的 Postgres 14，内置向量检索扩展（镜像 tag 可见 vectorchord 与 pgvectors），用于 AI 搜索与相似图片检索，向量索引的数据量与写入量都会放大磁盘 I/O 需求；
3. 如果数据库不在 SSD 上，compose 文件中提供了调优开关——取消注释 DB_STORAGE_TYPE: 'HDD'：

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

根据 环境变量文档，DB_STORAGE_TYPE 取值为 SSD（默认）或 HDD，其作用是切换底层 Postgres 配置（主要控制 effective_io_concurrency）：SSD 允许并发 I/O，HDD 使用顺序 I/O。也就是说，即便最终不得不把数据库放在机械盘上，也应显式声明 HDD 让 Postgres 采用相应策略。

四、软件要求：Docker 与 Compose 插件

Immich 的运行入口是 Docker + Docker Compose 插件，文档区分了两种安装形态：

• Docker Engine：面向 Linux 服务器（或 Windows 下的 WSL2）的 CLI 形态；
• Docker Desktop：面向 Windows / macOS 的 GUI 形态，不推荐用于 Linux；
• 两者按官方安装指南安装时都会自带 Compose 插件，也可以单独安装。

一条重要的兼容性红线：

Immich 要求的是 docker compose（Docker 插件式子命令）；名称相近的 docker-compose（带连字符）已被弃用，不再受 Immich 支持。

配套的 Docker Compose 安装文档 也记录了误用旧版本时的典型报错，例如 unknown shorthand flag: 'd' in -d 或 permission denied，以及 Compose v1 解析新 compose 文件的报错 'name' does not match any of the regexes——这些都指向同一结论：必须安装官方仓库的最新 Docker 并确认使用的是 docker compose。

五、Windows 用户的特殊要求：数据库卷必须落在 Unix 语义文件系统上

文档为 Windows 用户给出了一个折叠的专项说明，核心结论是：

• Postgres 数据（DB_DATA_LOCATION）所在文件系统必须支持用户/组所有权与权限（EXT2/3/4、ZFS、APFS、BTRFS、XFS 等），NTFS 或 ex/FAT/32 上均不可用；
• 在 WSL（Windows Subsystem for Linux）中使用挂载的主机目录（常见的 /mnt 路径）时同样不可用；
• 变通方案：把数据库的 bind mount 改为 Docker volume。文档给出的具体修改步骤如下。

修改 .env：

- DB_DATA_LOCATION=./postgres
+ DB_DATA_LOCATION=pgdata

在 docker-compose.yml 底部追加命名卷：

volumes:
  model-cache:
+ pgdata:

对照仓库中的 docker/docker-compose.yml，默认的顶层 volumes 段本来就定义了 model-cache，pgdata 追加后数据库即可脱离宿主机文件系统、进入 Docker 管理的卷存储，绕开 NTFS 的权限语义缺失问题。

六、机器学习容器的平台与算力变体

需求文档中“amd64 需 x86-64-v2 / arm64 支持”的说法，对应到仓库的 machine-learning/Dockerfile 可以看得更具体：该 Dockerfile 通过 DEVICE 构建参数派生出 cpu、cuda、rocm、armnn、openvino、rknn 等多个产品级镜像阶段，分别面向 CPU、NVIDIA GPU、AMD ROCm、ARM NN（arm64 设备）与 Rockchip NPU 等平台。docker/docker-compose.yml 的注释也说明了在需要硬件加速时如何在镜像 tag 后追加 -cuda、-rocm、-openvino、-rknn、-armnn 等后缀，并通过 docker/hwaccel.ml.yml 与 docker/hwaccel.transcoding.yml 两个扩展文件接入 GPU 设备。

由此可以得出两条实践结论：

1. arm64 设备（ARM 服务器、ARM NAS、开发板）应选择 armnn 或 rknn 变体（后者面向瑞芯微 NPU）；amd64 设备则可选 cuda、rocm、openvino（Intel 集成显卡）或纯 CPU 版本；
2. 选择硬件加速变体前，先确认 环境变数文档 中相应的 MACHINE_LEARNING_* 参数默认值，例如 CPU 版本默认 MACHINE_LEARNING_WORKERS=1、MACHINE_LEARNING_REQUEST_THREADS 默认为 CPU 核数——这也从侧面解释了为何 CPU 推荐 4 核起步：转码与推理任务（OCR、人脸、CLIP 嵌入）是 Immich 的主要 CPU 消耗来源。

七、部署前检查清单

综合 docs/docs/install/requirements.md 与仓库配置，部署前可按以下清单逐项核对：

1. OS：Linux 64 位系统（或完整 VM）；非 Linux 时确认已安装 WSL2 + Docker Desktop；
2. RAM：≥ 6GB（推荐 8GB）；4GB 机器需评估是否关闭机器学习功能，并确保 Postgres 可用 ≥ 2GB；
3. CPU：≥ 2 核（推荐 4 核）；amd64 平台确认支持 x86-64-v2，虚拟机需核对 QEMU CPU 类型透传设置；
4. 存储：媒体目录与数据库目录均位于支持 Unix 权限的文件系统；DB_DATA_LOCATION 落在本地 SSD；媒体库容量按原文件 +10%～20% 预留；
5. 软件：安装最新 Docker 并确认 docker compose version 可用（而非 docker-compose）；
6. 环境变量：按 docker/example.env 设置 UPLOAD_LOCATION、DB_DATA_LOCATION 与强随机 DB_PASSWORD（仅允许 A-Za-z0-9）；
7. Windows/WSL 特例：若数据目录位于 NTFS 或 /mnt 挂载盘，按第五节的 diff 改为 pgdata 命名卷；
8. 非 SSD 数据库：在 compose 中显式设置 DB_STORAGE_TYPE: 'HDD'。

完成以上核对后，即可进入 Docker Compose 安装 流程；对每个变量的完整取值与默认值，可继续查阅 环境变量文档。