Immich需要多少内存和磁盘空间？

Immich 需要多少 RAM？

Immich 将 6 GB RAM（随机存取存储器）列为文档中的最低要求，将 8 GB 列为推荐值；CPU 最低需要 2 个核心，想要更流畅的安装体验则需要 4 个核心。这个数值针对整个服务栈，因为 Immich 由四个容器组成，而不是一个应用。浏览已经导入的图库并不占用很多资源。内存主要用于导入任务，而且其中大部分会被一个可以关闭的容器使用。

[
  {
    "label": "Documented minimum",
    "ram_gb": 6,
    "cpu_cores": 2
  },
  {
    "label": "Documented recommended",
    "ram_gb": 8,
    "cpu_cores": 4
  }
]

以上是 Immich 需求页面截至 2026 年 8 月公布的数值。这是容量规划建议，不是软件启动时执行的检查。Immich 使用更少的资源也能启动。服务器较小时，变化在于哪些后台任务能够完成，以及内存耗尽时导入任务会发生什么。

有一个确切的硬性限制。Immich 3 及更高版本在 amd64 主机上需要 x86-64-v2 CPU，这涵盖了大约自 2012 年以来销售的大多数处理器。在较旧的硬件上，容器会启动失败，而不是运行缓慢。

如果您还没有开始安装，请先阅读使用 Docker Compose 在 VPS 上完整安装 Immich，然后返回此处规划服务器容量。

内存用在哪里：4 个容器

官方 Compose 文件会启动4个服务。每个服务的内存特征都不同，因此只看总内存无法了解有用的信息。

immich-server提供 Web 界面和 API，同时运行后台作业 worker。这个容器内部运行两个 worker。api处理来自浏览器和移动应用的请求。microservices运行队列，包括缩略图生成和视频编码。变量 IMMICH_WORKERS_INCLUDE 和 IMMICH_WORKERS_EXCLUDE 可将这两个 worker 拆分到不同容器中。这样可以为内存占用较高的部分单独设置内存限制，而不会限制负责提供照片服务的部分。

database是内置 VectorChord 扩展的 PostgreSQL 14 镜像。它保存所有元数据，以及每个资源对应的一个搜索向量。Immich 文档为整个服务栈中的数据库设置了唯一的明确最低要求：如果应用 Docker 资源限制，数据库至少需要2 GB。该页面还说明，数据库必须使用本地 SSD 存储，不能使用任何类型的网络共享。因为向量和索引查询属于小块随机读取，网络卷会将每次读取都变成一次往返。如果方案选择取决于这一点，那么 VPS 上的 NVMe 和 SATA SSD 存储在这里比整个服务栈的其他部分都更重要。

redis运行 Valkey 镜像并保存作业队列。它明显是4个服务中内存占用最小的一个，因为它保存的是作业记录，而不是照片数据。

immich-machine-learning决定您需要选择多大规格的服务。它会加载用于智能搜索、人脸检测和文字识别的模型，已加载的模型会常驻内存。MACHINE_LEARNING_MODEL_TTL默认为300，因此模型在连续5分钟没有请求后会被卸载，并在下一次请求时从 /cache 卷重新读取。批量导入期间不会出现5分钟的间隔，因此模型会从处理第一个资源一直保持加载到最后一个资源。

导入期间会发生什么变化

空闲时的 Immich 很安静。导入时，小型服务器容易过载，因为上传一个资产会排队触发一连串任务，并且多个队列会同时运行。

元数据提取会读取文件头，负载较低。缩略图生成的负载更高。Immich 会为每个资产生成 3 个缩略图输出：模糊的 thumbhash 占位图、WebP 预览图和 JPEG 缩略图；此外，每检测到一张人脸，还会额外生成 1 个缩略图。每个任务都需要解码图像，而任务并发数决定同时解码的图像数量。并发数会将单个任务的较小开销放大为整台服务器的负载，因此 Immich FAQ 将其列为资源受限机器上首先应降低的设置。在 Administration、Settings、Job Settings 中，将高负载队列的并发数设为 1。

视频资产还会增加转码负载。每个转码任务都是一个独立的 FFmpeg 进程，并占用自己的内存；它会使用您允许的所有 CPU 线程。

智能搜索会将每个新资产发送到 machine learning 容器，以计算一个嵌入向量。人脸检测会在同一图像上运行第二个模型。首次导入已有照片库时，这两个队列都会处理您拥有的每个资产，持续数小时。这是整个安装过程中内存压力最大的阶段，而且只会发生一次。

为什么人脸和对象识别需要最多 RAM

人脸处理分为两个任务。人脸检测会在机器学习容器中运行模型并找出人脸框。随后，人脸识别会将这些检测结果归类为具体人员，并查询 Postgres 中的向量索引。因此，较大的图库会依次增加两个服务的压力：检测运行时占用模型容器资源，归类运行时占用数据库资源。

有 4 个设置会改变机器学习容器需要持有的内容。

• 人脸模型。Immich 默认提供 buffalo_l，FAQ 建议小型服务器使用 buffalo_s。该模型更小，因此占用的内存更少、运行速度更快，但对较小或侧脸人脸的识别准确率会降低。
• Worker 数量。MACHINE_LEARNING_WORKERS 默认为 1。每个 worker 都是一个独立进程，并会加载自己的模型副本，因此将其提高到 2 后，常驻模型内存大致会翻倍。除非有足够的可用 RAM，否则保持为 1。
• Batch 大小。MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION 限制一次处理的人脸数量。一个 batch 会同时保存在内存中，因此包含 40 张人脸的合影比单人肖像占用更多内存。
• 实际运行的模型类型。智能搜索、人脸检测和文字识别分别加载各自的模型。在 Administration、Settings、Machine Learning Settings 中关闭不使用的功能后，可以永久释放对应内存，而不是只在导入任务之间释放。

此外还有 MACHINE_LEARNING_MODEL_ARENA。文档将其说明为预分配 CPU 内存，以避免内存碎片，并且默认启用。最后再修改此项。它的效果取决于底层内存分配器，因此唯一可靠的判断方法，是对比修改前后的 docker stats。

三个实用配置：2 GB、4 GB 和 8 GB

[
  {
    "label": "2 GB VPS",
    "server_limit_mb": 768,
    "db_limit_mb": 768,
    "ml_limit_mb": 0,
    "redis_limit_mb": 128,
    "notes": "machine learning container removed"
  },
  {
    "label": "4 GB VPS",
    "server_limit_mb": 1024,
    "db_limit_mb": 1280,
    "ml_limit_mb": 1024,
    "redis_limit_mb": 192,
    "notes": "machine learning on, job concurrency 1, buffalo_s"
  },
  {
    "label": "8 GB VPS",
    "server_limit_mb": 2048,
    "db_limit_mb": 2048,
    "ml_limit_mb": 2560,
    "redis_limit_mb": 256,
    "notes": "everything on at default settings"
  }
]

请将这些数值视为要填入 Compose 的限制，而不是 Immich 实际使用量的测量值。限制是上限。它不会预留资源，也不会让服务变小。它决定主机内存耗尽时由哪个服务被内核终止。相比让内核根据自身评分决定，最好由您明确指定。

2 GB 主机：移除机器学习容器

2 GB 低于文档规定的 6 GB 最低要求，因此这是一个折中方案，应明确说明这一点。请在 docker-compose.yml 中注释掉整个 immich-machine-learning 服务，或者保留该服务运行，并在 Administration、Settings、Machine Learning Settings 中禁用所有模型。移除容器是更彻底的方案，因为禁用模型后，Python 进程仍会常驻内存。

您仍可使用上传、相册、共享、移动备份，以及按日期、地点和文件名搜索。您将无法按描述搜索，无法自动将人脸分组为人物，也无法识别图像中的文字。

这 4 个限制合计约 1.7 GB，可为主机留下约 300 MB。请注意，数据库的 768 MB 限制低于文档规定的 2 GB 下限。这正是 2 GB 主机必须作出的折中，因此 Postgres 最可能在这里被终止。

首先出问题的是导入，而不是浏览。数万张以内的照片导入完成后，浏览通常仍可接受，因为页面加载只需执行元数据查询并读取文件。同一台主机导入大量视频时会开始使用 swap，因为转码和缩略图队列会同时需要内存。请将所有高负载队列的并发数设为 1，并添加 swap 文件。

4 GB 主机：启用机器学习，每次处理一个任务

4 GB 是值得启用人脸和对象识别的最低配置。将机器学习容器限制为 0 MB，将人脸识别切换为 buffalo_s，并将缩略图生成、人脸检测和智能搜索的任务并发数设为 1。

首次处理现有媒体库需要运行数小时，大型媒体库则可能超过 1 天。这主要受 CPU 限制，而不是内存限制，因此增加 RAM 不会缩短处理时间。

这里首先出问题的是首次批量处理期间的机器学习容器。如果不设置限制，它会在转码任务也增长时持续占用更多内存，内核随后会终止两者中占用较多内存的服务。您会在 docker ps -a 中看到 Exited (137)，并看到容器重启；队列进度则会在您下次查看时悄悄落后更多。

8 GB 主机：文档建议的配置

8 GB 和 4 个核心符合 Immich 的建议，所有功能都可使用默认设置运行：智能搜索、人脸检测、文字识别和转码均使用默认并发数。超过 100,000 个资源的媒体库在此配置下也能正常运行。此时压力会从内存转向磁盘速度，因为数据库全天都在处理向量索引和元数据查询。

仍然建议设置限制。在资源充足的主机上，限制可以防止某个失控的队列连带拖垮数据库。如果您正在将此配置与更小的方案比较，VPS 按内存档位的实际成本通常会表明，8 GB 方案是减少调优工作最经济的选择。

如何使用 Compose limits 限制每个服务的内存

不要修改 docker-compose.yml。每次升级时，该文件都会被 wget 替换。请将限制写入旁边的 docker-compose.override.yml，docker compose 会自动将其合并。

services:
  immich-server:
    deploy:
      resources:
        limits:
          memory: 1024M
  immich-machine-learning:
    deploy:
      resources:
        limits:
          memory: 1024M
          cpus: '1.5'
  database:
    deploy:
      resources:
        limits:
          memory: 1280M
  redis:
    deploy:
      resources:
        limits:
          memory: 192M

docker compose up -d
docker stats --no-stream

现在，docker stats 应在 MEM USAGE / LIMIT 列中显示您设置的上限，而不是主机的总内存。如果限制列仍显示主机的完整内存大小，说明未加载 override 文件：请检查文件名，并运行 docker compose config 查看合并后的结果。

限制过低会使运行缓慢的服务直接停止，因此如果容器开始反复重启，请提高限制。有关其工作机制的更多信息，请参阅在 Docker Compose 中为每个服务设置内存限制，其中还介绍了 deploy 为什么能在 Compose v2 中脱离 Swarm 工作。

如何关闭或迁移机器学习容器

在小型服务器上，将此容器迁移到其他位置是最显著的优化措施。Immich 支持在另一台机器上运行该容器。在第二台主机上创建此文件。第二台主机可以是仅在晚上开机的桌面电脑：

name: immich_remote_ml
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003
volumes:
  model-cache:

docker compose up -d
curl -s http://localhost:3003/ping

然后在 Web 界面中依次进入 Administration、Settings、Machine Learning Settings，点击 Add URL，并输入 http://<host>:3003。两台主机上的版本必须保持一致，因为 Immich 文档警告，版本不匹配会导致错误和不稳定。

该端口会以未加密方式将照片传输到另一台机器，因此应将其限制在私有网络中，或通过在两台主机之间建立 WireGuard 隧道传输。绝不要将 3003 暴露到互联网。

如果问题在于常驻模型容器本身，那么在确定方案规模前，比较PhotoPrism 和 Immich 在空闲状态下运行的组件差异也是合理的。

Immich 媒体库需要多少磁盘空间？

没有一个固定的倍数，因为有 4 类内容以 4 种不同的速度增长。下面以包含 50,000 张照片和 500 个短视频的媒体库为例计算。

[
  {
    "label": "Originals: 50,000 photos at 4 MB",
    "gb": 200
  },
  {
    "label": "Originals: 500 videos at 120 MB",
    "gb": 60
  },
  {
    "label": "Thumbnails and encoded video at 15%",
    "gb": 39
  },
  {
    "label": "Postgres database",
    "gb": 3
  },
  {
    "label": "Machine learning model cache",
    "gb": 2
  }
]

照片占用的 200 GB 和视频占用的 60 GB 是假设值。在购买硬件前，请替换为您自己的平均值，因为视频决定了这个数字：手机拍摄 1 分钟视频所占的空间大于 100 张照片。

find /srv/immich/upload -type f -printf '%s\n' \
  | awk '{n++; s+=$1} END {printf "%d files, %.1f MB average\n", n, s/n/1048576}'

39 GB 这一行是 Immich 唯一公布的比例：生成缩略图和转码视频平均会使媒体库大小增加 10 到 20%。这是一个范围，因为具体数值取决于需要为浏览器兼容性重新编码的视频数量。以 JPEG 为主的媒体库通常接近该范围的下限。

数据库占用 3 GB，接近固定成本。Immich 文档显示，数据库文件通常为 1 到 3 GB，因为其中保存的是元数据和搜索向量，而不是像素数据。模型缓存占用 2 GB；启用多个模型或测试不同模型时，该空间会增加。FAQ 正是因为这个原因，将此目录列为空间消耗项。

这 5 行合计略超过 300 GB，因此 500 GB 卷有足够的增长空间，而 250 GB 卷不够。使用以下命令查看空间分布：

grep UPLOAD_LOCATION .env
du -sh /srv/immich/*

UPLOAD_LOCATION 下有 6 个目录。upload 和 library 保存原始文件，thumbs 保存预览图和人脸缩略图，encoded-video 保存重新编码的副本，profile 保存头像，backups 保存自动生成的数据库转储。只有 upload、library 和 profile 不可替代，因为其他内容都可以从它们重新生成。

有两点容易让人意外。删除的内容会先进入回收站，在清空回收站前仍会占用空间，因此大规模清理不会在执行当天释放空间。数据库转储只包含元数据，没有文件就没有价值：

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /srv/backups/immich-dump.sql.gz

还应将原始文件按文件级别复制到服务器之外的位置，这正是 将 VPS 备份到服务器外部存储的 restic 所适用的场景。

转码使用 CPU，而不是 RAM

增加 RAM 不会让转码更快。Immich 使用 FFmpeg 进行转码。在普通 VPS 上，每一帧都由 CPU 解码和编码。即使系统支持硬件加速，Immich 文档也说明只有编码会使用硬件加速，因此 CPU 仍需执行软件解码和色调映射。

硬件加速需要额外的 hwaccel.transcoding.yml Compose 文件，并需要传递相应设备，使用 NVENC、Quick Sync、RKMPP 或 VAAPI。大多数 VPS 方案都不提供这些设备，因此应按 CPU 转码进行规划。

实际需要调整的是线程数。在 Administration、Settings、Video Transcoding Settings 中，线程数设为 0 表示使用所有核心。在 2 核方案上，这可能导致单个视频占满资源，使 Web 界面冻结。按照 Immich FAQ 的建议，将该值设为 1 或 2。这样转码会变慢，但不会影响其他操作。

交换抖动导致导入任务看似卡死的原因

这是最容易被误判的故障。当 Immich 内存不足时，会出现两种结果，只有其中一种看起来像故障。

没有 swap 时，内核会终止进程。容器会在几秒内重启，因此从浏览器看，任务队列只是暂时停滞，然后继续运行。证据位于 docker ps -a：

docker ps -a --filter name=immich
docker inspect immich_machine_learning | grep -i oomkilled
sudo dmesg -T | grep -i -E 'out of memory|oom-kill'

Exited (137) 表示进程因信号 9 被终止。137 等于 128 加 9。OOMKilled 值为 true 表明进程是因内存不足被终止，而不是因崩溃退出。

有 swap 时，不会终止任何进程，也不会报告错误。内核开始将内存页移到磁盘，导入速度降低一个数量级，Web 界面在正常超时时间内停止响应。所有容器都在运行。所有健康检查可能仍然通过。此时看起来像是卡死，用户通常会重启主机，但这样会丢失队列进度，而且无法解决问题。

free -m
vmstat 1 5

vmstat 的 si 和 so 列持续出现非零值，表示机器在持续读写 swap，这就是交换抖动。与此同时，Swap 的 free -m 行中的已用量也会不断增加。

即使是 2 GB 或 4 GB 的主机，也应添加 swap，因为可诊断的慢速导入总比无法诊断的容器被终止更好：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

然后修复根因。将任务并发数降为 1，限制机器学习容器的资源，或将其迁移到其他主机。swap 可以为处理问题争取时间，但不能单独解决问题。

FAQ

我可以在 2 GB VPS 上运行 Immich 吗？

可以，但需要将 immich-machine-learning 服务从 docker-compose.yml 中注释掉，并将作业并发数设为 1。这低于文档规定的 6 GB 最低要求，因此应将其视为已知的妥协。您仍可使用上传、相册、共享、移动端备份，以及按日期、地点和文件名搜索的功能。但无法使用按描述搜索、自动将人脸归类为人物，以及识别图片中的文字。添加一个 2 GB swap 文件，这样导入出现峰值时只会拖慢服务器，而不是导致容器被终止。

为什么我的 Immich 导入停止时没有错误消息？

从浏览器看，这两种原因完全相同。可能是容器因内存不足被终止，此时 docker ps -a 会显示 Exited (137)，而容器已经重新启动；也可能是主机正在使用 swap，此时所有容器仍在运行，只是整体速度非常慢。vmstat 1 5 可以区分这两种情况：如果 si 和 so 列中的数值持续为非零，说明正在使用 swap。无论是哪种情况，都应降低缩略图生成、人脸检测和智能搜索的作业并发数。

Immich 日志中的退出代码 137 是什么意思？

137 等于 128 加信号 9，因此表示进程被 SIGKILL 终止。实际上，这意味着触及了内存上限，原因可能是容器自身的限制，也可能是主机内存耗尽。使用 docker inspect immich_machine_learning | grep -i oomkilled 检查。true 的值可以确认内核是否因内存不足将其终止，随后通过 free -m 和 sudo dmesg -T | grep -i oom-kill 判断是容器限制还是整个主机导致的问题。机器学习容器通常最容易受到影响，因为它通常包含占用内存最大的进程。

Immich 每张照片需要多少磁盘空间？

按原始文件大小再增加 10 到 20% 进行预留。Immich 文档说明，生成的缩略图和转码后的视频平均会使媒体库大小增加 10 到 20%，即使是大型媒体库，数据库本身通常也只需要 1 到 3 GB。实际决定总空间的是视频，因此在选择方案前应测量自己的平均文件大小，而不是直接将照片数量乘以某个系数。

Immich 需要 GPU 吗？

不需要。Immich 的所有部分都可在 CPU 上运行。GPU 可以加速机器学习容器中的模型推理和视频编码，但这两者都不是必需的。大多数 VPS 方案不提供 GPU。在仅使用 CPU 的硬件上，将转码线程数设置为 1 或 2，使用 buffalo_s 人脸模型，并让首次批量导入在夜间运行。