企业官网建设流程全解析

如何用环境变量把 Immich 拆分为独立的 API 与微服务容器

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich

默认情况下，Immich 的immich-server容器内部同时运行两类 worker：api负责响应 Web 与移动端的数据和文件请求，microservices负责缩略图生成、视频转码等后台任务（官方称之为 job）。如果你希望限制某一容器承担的任务类型，或者把这两类负载分布到不同容器上，Immich 提供了IMMICH_WORKERS_INCLUDE和IMMICH_WORKERS_EXCLUDE两个环境变量来完成拆分。本文基于官方文档中的“Split workers”方案，说明如何用 Docker Compose 把 Immich 拆成一个只服务 Web UI 与 API 的容器，和一个处理其余所有后台任务的容器。

适用前提：你已经按 Docker Compose 方式安装并运行了 Immich（参见 Docker Compose 安装文档），并且正在使用当前发布版本的docker-compose.yml——仓库 docker/README.md 明确提醒，main 分支上的 compose 文件可能与最新发布版不兼容，应使用 release 版本的文件。

拆分原理：两个容器共享同一套基础设施

按 Scaling Immich 的说明，后端设计为可以并行运行多个实例，唯一的硬性要求是：每个实例都要连接到同一套共享基础设施——相同的 Postgres、相同的 Redis，并把相同的文件目录挂载进容器。拆分 API 与微服务容器时，这一点同样成立。

两个关键事实来自官方文档：

• 环境变量文档 明确要求：所有DB_变量和REDIS_变量都必须提供给所有 Immich worker，包括api和microservices。默认的 compose 文件里，immich-server通过env_file: .env加载数据库与 Redis 配置，因此复制出来的新服务只要保留env_file: .env，这部分要求就自动满足，不需要单独改动数据库或 Redis 配置。
• 同一文档的警告框还指出：修改环境变量后必须重新创建容器才能生效，仅仅重启容器不会替换容器内的环境变量。因此拆分完成后不能只用docker compose restart。

操作步骤

以下命令都在你的docker-compose.yml所在目录（例如./immich-app）中执行。

1. 复制 immich-server 服务块

参照 jobs-workers 文档 的做法：把immich-server服务块整体复制为一个新的服务，并对副本做以下改名。以仓库中的 docker/docker-compose.yml 为例，原服务是：

immich-server: container_name: immich_server image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} ... ports: - '2283:2283'

按文档给出的 diff，副本改为：

- immich-server: - container_name: immich_server ... - ports: - - 2283:2283 + immich-microservices: + container_name: immich_microservices

也就是说，副本的变更是：服务名改为immich-microservices，容器名改为immich_microservices，并删掉ports映射——新的微服务容器不需要对外暴露 2283 端口。副本的image、volumes（包括${UPLOAD_LOCATION}:/data和/etc/localtime挂载）、env_file: .env、depends_on、restart和healthcheck保持与原服务一致，这样两个容器天然满足“共享同一 Postgres、Redis 和文件挂载”的要求。

2. 用环境变量区分两个容器

当immich-server服务有了两份之后，按文档要求给各自加上environment。原服务只运行apiworker，副本排除apiworker：

services: immich-server: ... + environment: + IMMICH_WORKERS_INCLUDE: 'api' immich-microservices: ... + environment: + IMMICH_WORKERS_EXCLUDE: 'api'

这两个变量的含义（见 环境变量文档 的 Workers 一节）：

因此拆分后的分工是：immich-server只跑api，immich-microservices跑除api之外的所有默认 worker。

3. 重新创建容器

环境变量变更必须通过重建容器生效，在 compose 文件所在目录执行：

docker compose up -d

大多数情况下 Docker 会识别到配置变化并重建受影响的容器。如果没有生效，按文档的补救措施强制执行：

docker compose up -d --force-recreate

注意这会停止并重新创建受影响的容器，期间 Immich 短暂不可用；数据都在 Postgres、Redis 和文件系统里，immich-microservices容器本身的停止不会丢数据。

结果验证

• 用docker compose ps检查：应能看到immich_server和immich_microservices两个 server 容器，加上原有的immich_redis、immich_postgres、immich_machine_learning，状态均为 healthy。
• 两个 server 容器各自带有 compose 文件里的healthcheck。需要留意的是，仓库中 server/bin/immich-healthcheck 的健康检查脚本会读取IMMICH_WORKERS_INCLUDE/IMMICH_WORKERS_EXCLUDE：当某个容器没有运行apiworker 时（即设置了IMMICH_WORKERS_EXCLUDE包含api），它跳过对 API 的 HTTP 探测。因此immich_microservices即使不监听 2283 端口，健康检查也不会因缺少 API 而失败。
• 上传或等待后台任务处理时，进入 Web 管理界面的 Administration -> Jobs 页面查看任务状态，确认缩略图生成等 job 正常流转，即可确认immich-microservices容器在承接后台工作；浏览器照常访问 2283 端口的 Web UI，确认immich-server仍在提供 API。

限制与说明

• 单台机器上拆成两个容器未必有收益。Scaling Immich 明确指出：如果只有一台机器，immich-server容器本身就会并行跑多个后台任务，且任务并发数可以在管理面板中调高，拆分“不太可能带来好处”。拆分的典型动机是限制（throttle）某个容器的负载，或把负载分布到不同机器上。
• 该文档同时说明了“向下缩容”的用法：因为所有状态都存放在 Postgres、Redis 和文件系统里，随时停掉一个immich-server容器都没有风险，只要还有apiworker 在运行就能继续浏览 Immich，后台 job 会等待有可用 worker 时再处理。
• 反向操作（合并回单容器）同样通过环境变量控制：删掉新复制的服务块和两处的IMMICH_WORKERS_*设置，再执行docker compose up -d --force-recreate重建即可。恢复默认时不要遗漏重建这一步，否则旧的环境变量仍然留在容器里。
• 如果后续要做跨机器的进一步拆分，Scaling Immich 说明具体方式因环境而异（Kubernetes 副本、网络隧道、NFS 挂载等），官方文档不提供统一的具体步骤。

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich