Immich Docker 容器运维指南：容器状态排查、日志追踪与调试实战

Immich 是基于 Docker Compose 部署的自托管照片与视频管理方案，日常运维中几乎所有排障动作都发生在四个核心容器之上。本篇以官方 Docker Help 指南为主线，讲解如何查看容器状态、挂载进入容器执行调试命令、追踪运行日志，并结合仓库中的 Compose 配置与镜像构建文件，说明健康检查机制与典型排查流程，读完后可独立完成 Immich 部署环境的日常巡检与故障定位。

Immich 的 Docker 部署拓扑

在动手排查之前，先明确容器构成。标准部署由 docker-compose.yml 定义，包含四个服务，其固定容器名（container_name）正是后续所有命令的操作对象：

服务	容器名	镜像	职责
immich-server	immich_server	ghcr.io/immich-app/immich-server	主服务：Web 前端、API、缩略图/转码等 worker，暴露 2283 端口
immich-machine-learning	immich_machine_learning	ghcr.io/immich-app/immich-machine-learning	机器学习推理：CLIP 搜索、人脸识别、OCR
redis	immich_redis	docker.io/valkey/valkey:9	任务队列（BullMQ），由 server 通过 depends_on 依赖
database	immich_postgres	ghcr.io/immich-app/postgres	PostgreSQL 14 定制镜像，内置 pgvector 扩展

版本由 .env 中的 IMMICH_VERSION 控制（${IMMICH_VERSION:-release}），示例见 example.env。生产环境另有 docker-compose.prod.yml（可基于本地源码构建镜像，并额外附带 Prometheus 与 Grafana 监控服务），Rootless 模式使用 docker-compose.rootless.yml（为所有服务添加 user: '1000:1000'、no-new-privileges 与 cap_drop: NET_RAW）。

由于 Compose 文件中已写死 container_name，后文命令可直接使用容器名而不必每次查找容器 ID。

查看容器状态：docker ps

最基本的巡检动作是确认容器是否在运行、是否处于健康状态：

docker ps                         # 查看运行中的容器列表
docker ps -a                      # 查看运行中与已停止的容器列表

排查时的常用变体：

docker ps -l                      # 只按名称列显示，输出更紧凑，便于直接取用容器名
docker ps --filter name=immich    # 只筛选 Immich 相关容器（前缀匹配 immich_server、immich_postgres 等）
docker inspect --format='{{.State.Health.Status}}' immich_server   # 单独查看某容器的健康检查结果

docker ps -a 中出现已退出（Exited）的容器时，可结合其退出码与 docker logs 定位崩溃原因；所有服务均配置了 restart: always，因此容器反复重启往往意味着启动阶段持续报错，此时日志是关键线索。

挂载进入容器：docker exec

当需要执行交互式命令或调试脚本时，使用 docker exec 挂载进入容器：

docker exec -it <id or name> <command>          # 以指定命令挂载进入容器
docker exec -it immich_server bash
docker exec -it immich_machine_learning bash

• immich_server：容器基础镜像带有完整 Bash 环境，可直接进入 shell。
• immich_machine_learning：同为 Python 官方镜像体系，同样支持 bash 进入；容器内推理代码位于 /usr/src（见 machine-learning/Dockerfile 中的 WORKDIR /usr/src 与 PYTHONPATH=/usr/src），模型缓存挂载在 /cache 卷（Compose 中的 model-cache:/cache）。

从源码结构看，两个容器的启动方式不同：server/Dockerfile 使用 ENTRYPOINT ["tini", "--", "/bin/bash", "-c"] 配合 CMD ["start.sh"] 启动主服务，并将 /usr/src/app/server/bin 加入 PATH，同时创建符号链接 server/bin/immich -> ../../cli/bin/immich。这意味着在 immich_server 容器内可以直接执行 immich / immich-admin 管理命令，例如：

# 进入 server 容器后
immich-admin version            # 查看当前版本
immich-admin list-users          # 列出用户
immich-admin schema-check       # 校验数据库迁移与 schema 漂移

完整的 immich-admin 命令清单（重置管理员密码、启停维护模式、变更媒体存储位置等）见 Server Commands 文档，其「How to run a command」一节正是通过本文介绍的 docker exec 方式进入 immich_server 容器执行的。而 immich_machine_learning 容器以 ENTRYPOINT ["tini", "--"] + CMD ["python", "-m", "immich_ml"] 启动，进入后适合用 python 排查依赖与模型加载问题。

查看与追踪容器日志：docker logs

日志是定位容器故障的第一手材料。按容器 ID 或名称查看：

docker logs <id or name>          # 查看指定容器的日志（按 ID 或名称）

docker logs immich_server
docker logs immich_machine_learning

Tip（跟随日志）：为 docker logs <id or name> 追加 --follow 参数后，命令不会立即退出，而是持续流式输出新日志，这在调试实时行为时非常有用。

docker logs --follow immich_server

排查时同样高频的几个参数：

docker logs --tail 100 immich_server        # 只看最近 100 行，避免被历史日志淹没
docker logs --since 10m immich_server       # 只看最近 10 分钟的日志
docker logs --timestamps immich_machine_learning  # 输出带时间戳，便于对齐事件发生时刻

一个典型的组合是：docker logs --tail 100 <容器> 快速定位崩溃前的最后报错，确认需要复现后用 docker logs --follow <容器> 挂起观察，同时在前台触发操作（上传照片、搜索等）。

容器健康检查机制

四个服务在 Compose 中均启用了 healthcheck（healthcheck: disable: false），理解其检查逻辑能帮助你区分「容器在运行」与「服务真正可用」：

• immich_server：server/Dockerfile 声明 HEALTHCHECK CMD immich-healthcheck，由镜像内置的健康检查程序探测服务自身状态；
• immich_machine_learning：machine-learning/Dockerfile 声明 HEALTHCHECK CMD python3 healthcheck.py，其实现见 healthcheck.py——读取 IMMICH_PORT（默认 3003）与 IMMICH_HOST（默认 0.0.0.0，探测时转换为 localhost），对 http://{host}:{port}/ping 发起 2 秒超时的 GET 请求，返回 200 则健康；
• immich_redis：Compose 中定义 test: redis-cli ping | grep -q PONG || exit 1，直接验证 RESP 协议连通性；
• immich_postgres：使用定制 Postgres 镜像的内置健康检查。

当 docker inspect 显示某容器健康状态为 unhealthy 时，应优先 docker logs 该容器查看具体异常，而不是重启服务。

常见排查流程与进阶操作

综合以上内容，一条推荐的排障路径为：

1. docker ps -a 确认四个容器是否全部 Up，观察健康状态与重启次数；
2. docker logs --tail 100 <异常容器> 查看最近的错误输出；
3. 若需实时复现，docker logs --follow <异常容器> 挂起日志流；
4. docker exec -it <异常容器> bash 进入容器执行诊断命令（immich-admin version、Python 依赖检查等）。

两个进阶场景值得了解：

• 拆分 worker 容器：immich_server 容器内同时运行 api 与 microservices 两类 worker（详见 Jobs and Workers 文档）。若需将 Web/API 与后台任务分到不同容器做资源隔离，可通过环境变量 IMMICH_WORKERS_INCLUDE 指定各容器承担的任务类型，例如将副本容器配置为只处理 microservices。
• 环境变量调整：容器行为大量由 .env 驱动，UPLOAD_LOCATION（媒体存储位置，映射到 /data）、DB_DATA_LOCATION（数据库数据目录）、IMMICH_VERSION（镜像版本）等变量的完整说明见 Environment Variables 文档。修改 .env 后需通过 Compose 重启服务生效。

小结

Immich 的日常运维集中在三类命令：docker ps 看状态、docker logs（配合 --follow）看日志、docker exec -it 进容器执行调试与管理命令。掌握四个固定容器名（immich_server、immich_machine_learning、immich_redis、immich_postgres）与健康检查逻辑，再配合 immich-admin 管理命令，即可覆盖绝大多数自托管环境的巡检、升级验证与故障定位场景。

延伸阅读

• Docker Help 原始文档
• Compose 文件 与 环境变量示例
• Server Commands（immich-admin）
• Jobs and Workers（worker 拆分）