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

Immich 需要多少 RAM？

Immich 将 6 GB RAM（随机存取存储器）列为文档中的最低要求，并建议使用 8 GB；CPU 最低需要 2 个核心，若要获得舒适的使用体验，则建议使用 4 个核心。这个数值针对整个服务栈，因为 Immich 由 4 个容器组成，而不是单个应用。浏览已经导入的媒体库所需资源很少。内存主要消耗在导入过程中，而且其中大部分由一个可以关闭的容器使用。

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

以上是截至 2026 年 10 月 Immich 要求页面公布的数值。这是容量规划建议，不是软件启动时执行的检查。同一页面还记录了一种更小的配置：禁用机器学习功能时使用 4 GB，但没有给出低于该数值的配置。服务器内存较小时，受影响的是哪些后台任务可以完成，以及内存耗尽时导入任务的行为。

存在一个明确的硬性限制。从版本 3 开始，amd64 主机上的机器学习容器需要 x86-64-v2 CPU。这涵盖了大多数约从 2012 年开始销售的处理器。该要求仅适用于这个容器，不适用于服务器本身。因此，在较旧的硬件上，可以关闭机器学习功能，按照下文所述将其部署到另一台机器，或继续使用 v2.7.5；Immich 文档将其列为最后一个兼容版本。

如果你还没有开始安装，请先阅读使用 Docker Compose 在 VPS 上完整安装 Immich，然后返回此处评估服务器配置。

内存用在哪里：4 个容器

官方 Compose 文件会启动4个服务。每个服务的内存占用模式不同，因此只看总内存会掩盖真正有用的信息。

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

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": "below every documented configuration, machine learning container removed"
  },
  {
    "label": "4 GB VPS",
    "server_limit_mb": 1024,
    "db_limit_mb": 2048,
    "ml_limit_mb": 0,
    "redis_limit_mb": 192,
    "notes": "documented 4 GB setup: machine learning disabled or moved to another host, job concurrency 1"
  },
  {
    "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 最低要求，也低于 Immich 文档中唯一的精简配置，即禁用机器学习时使用 4 GB。Immich 没有发布 2 GB 配置，因此此配置属于不受支持的折中方案，而不是可直接采用的配置。如果仍要尝试，请在 docker-compose.yml 中注释掉整个 immich-machine-learning 服务，或者保留该服务运行，并在 Administration、Settings、Machine Learning Settings 下禁用每个模型。移除容器更可靠，因为禁用模型后，Python 进程仍会驻留。

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

4 个限制合计约为 1.7 GB，只给主机留下约 300 MB。Immich 文档指出，启用 Docker 资源限制后，仅数据库就至少需要 2 GB，这已经等于整台主机的内存。因此，数据库的 768 MB 限制远低于该下限，这也是 Postgres 最可能在此配置下被终止的原因。

最先出问题的是导入。提供页面只需要执行元数据查询和文件读取，因此浏览已有媒体库对主机的压力最小；但导入大量视频时会开始使用 swap，因为转码和缩略图队列会同时需要内存。如果您只有 2 GB，请将所有高负载队列的并发数设为 1，并添加 swap 文件。如果您正在选择方案，请将 4 GB 视为实际最低配置。

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

Immich 文档将禁用机器学习功能的 4 GB 视为可用配置，这也是其需求页面中唯一的精简配置。数据库设为文档规定的 2 GB 下限后，图表中的 3 个限制合计约为 3.2 GB，只给主机留下约 800 MB。将缩略图生成的任务并发数设为 1，并将转码线程数保持在较低水平。

若要保留人脸和对象识别，文档建议的做法是在另一台机器上运行机器学习容器，如下文所述，然后让本服务器连接该容器。在同一台 4 GB 主机上运行机器学习超出了 Immich 文档支持的范围，因为数据库下限只为服务器、Redis、模型和主机共同留下约 2 GB。如果仍要尝试，请使用 Compose 限制机器学习容器的资源，将人脸识别切换为 buffalo_s，并将缩略图生成、人脸检测和智能搜索的任务并发数都设为 1。

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

如果机器学习在此主机上运行，最先出问题的是该容器在首次批量处理期间的资源使用。未设置限制时，它会在转码任务同时增长时持续占用更多资源，内核会终止两者中占用更多资源的进程。由于容器会在数秒内重启，docker ps -a 显示的状态是 Up，其运行时间远短于其他容器，而不是 Exited (137)；队列的处理进度也会在不知不觉中落后于上次查看时。

8 GB 主机：文档建议配置

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

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

如何使用 Compose 限制为每个服务设置内存上限

不要编辑 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: 2048M
  redis:
    deploy:
      resources:
        limits:
          memory: 192M

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

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

将数据库的内存保持在 2048M 或更高。只要使用 Docker 资源限制，Immich 就将 2 GB 记录为数据库的最低要求。限制过低会使运行缓慢的服务直接停止，因此如果容器开始反复重启，请提高限制。有关其工作机制的更多信息，请参阅在 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 文档警告，版本不匹配可能导致错误和不稳定。

该端口会以未加密方式将照片的图像预览传输到另一台机器。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 解码和编码。每个 FFmpeg 进程仍会在内存中保存已解码帧的缓冲区。因此，导入部分会将一次转码计为独立的内存开销，但转码速度取决于 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。只有在容器停止期间才能看到这个状态。重启策略使容器恢复后，docker ps -a 会再次显示 Up，而运行时间明显短于其他 Immich 容器就是线索。单独出现信号 9 不能证明是内存问题，因为正常停止超过超时时间时，Docker 也会发送该信号。OOMKilled 的值为 true 表明进程因内存耗尽而被终止；容器重启后，应以 dmesg 中的 oom-kill 行作为依据。

启用 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 文档说明的任何配置中都不可以。需求页面将 6 GB 列为最低内存要求，并指出禁用机器学习功能时，唯一可用的较小配置是 4 GB；该页面还说明，在使用 Docker 资源限制后，仅数据库就至少需要 2 GB。注释掉 immich-machine-learning 服务并将作业并发数设为 1 可能可以启动，但这属于不受支持的折中方案；导入期间最可能被终止的是 Postgres 服务。如果只有 2 GB 内存，请添加 2 GB swap 文件。这样导入出现内存峰值时，服务器会变慢，而不是直接终止容器。如果正在选择方案，请从 4 GB 开始。

为什么我的 Immich 导入会在没有错误消息的情况下停止？

从浏览器看，两个不同的原因表现相同。第一种情况是容器因内存不足被终止后已经重新启动。此时，docker ps -a 会显示它处于 Up 状态，并且运行时间异常短（只有在容器仍处于停止状态时，Exited (137) 才会显示）。第二种情况是主机正在使用 swap。此时所有容器仍在运行，但整体速度非常慢。vmstat 1 5 可以区分这两种情况：如果 si 和 so 列中的非零数值持续存在，表示正在使用 swap。无论是哪种情况，都应降低缩略图生成、人脸检测和智能搜索的作业并发数。

Immich 日志中的退出代码 137 表示什么？

137 等于 128 加信号 9，因此表示进程被 SIGKILL 终止。在 Immich 主机上，这通常表示达到内存上限，原因可能是容器自身的限制，也可能是主机内存耗尽。但仅凭该代码无法确认原因：如果容器在超时时间内未停止，Docker 也会发送 SIGKILL；在 Linux 上，默认超时时间为 10 秒。使用 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 运行。显卡可以加快机器学习容器中的模型推理和视频编码，但两者都不是必需的。大多数 VPS 方案不提供 GPU。在仅使用 CPU 的硬件上，将转码线程数设为 1 或 2，使用 buffalo_s 人脸模型，并让首次批量导入在夜间运行。