### Docker Compose 配置文件技术解析 Immich 作为一款现代化的自托管照片管理解决方案，其 Docker Compose 部署文件采用了多容器微服务架构设计，通过容器化技术实现服务解耦与水平扩展。该配置文件定义了完整的应用堆栈，涵盖 Web 前端、API 后端、机器学习引擎、数据库及缓存等核心组件。 #### 核心服务容器架构 | 服务名称 | 容器镜像 | 核心功能 | 网络依赖 | 数据卷映射 | | :--- | :--- | :--- | :--- | :--- | | **immich-server** | `ghcr.io/immich-app/immich-server:release` | 提供 RESTful API 与业务逻辑处理，是系统的中枢服务。 | 依赖 PostgreSQL 与 Redis | `/usr/src/app/upload:/usr/src/app/upload` | | **immich-web** | `ghcr.io/immich-app/immich-web:release` | 基于 React 构建的用户交互界面，通过 API 与 Server 通信。 | 依赖 immich-server | 无状态，无需持久化存储 | | **immich-machine-learning** | `ghcr.io/immich-app/immich-machine-learning:release` | 负责图像分析、人脸识别、对象检测等 AI 任务。 | 依赖 immich-server | 模型缓存目录（可选） | | **postgres** | `tensorchord/pgvecto-rs:pg14-v0.2.0` | 主数据库，存储用户、元数据、人脸向量等结构化数据。 | 无 | `/path/to/postgres:/var/lib/postgresql/data` | | **redis** | `redis:7.0-alpine@sha256:...` | 缓存会话、临时任务队列及频繁访问的数据，提升性能。 | 无 | 通常配置为内存存储，无需映射 | #### 关键配置参数与环境变量 配置文件通过 `environment` 部分为各服务注入运行时参数，这是配置的核心所在。 **immich-server 服务的关键环境变量：** ```yaml environment: - DB_HOSTNAME=postgres - DB_USERNAME=postgres - DB_PASSWORD=postgres - DB_DATABASE_NAME=immich - REDIS_HOSTNAME=redis - JWT_SECRET= # 必须自定义的强密钥 - IMMICH_WEB_URL=http://immich-web:3000 - IMMICH_SERVER_URL=http://immich-server:3001 - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003 ``` * **数据库连接 (`DB_*)`**：定义了 Server 服务与 PostgreSQL 容器的连接凭证。在生产环境中，`DB_PASSWORD` 和 `JWT_SECRET` 必须替换为高强度随机字符串，并考虑通过 Docker Secrets 或外部配置文件管理。 * **服务发现 (`*_URL`)**：定义了微服务内部通信的端点。采用 Docker Compose 的 service name 作为主机名（如 `immich-web`），这是容器网络内的 DNS 解析机制，确保了服务间可发现性。 * **JWT_SECRET**：用于签名和验证 JSON Web Tokens，是系统安全性的基石。必须设置且不能使用默认值。 **存储卷映射策略：** 配置文件通过 `volumes` 声明了两种类型的持久化存储： 1. **数据库数据卷**：将宿主机的目录（如 `/docker/immich/postgres`）映射到容器内的 `/var/lib/postgresql/data`，确保数据库文件在容器重建后得以保留 [ref_1]。 2. **上传文件卷**：将宿主机的目录（如 `/docker/immich/upload`）映射到 `immich-server` 容器的 `/usr/src/app/upload`，这是用户上传的原始照片和视频的物理存储位置。此路径的规划需考虑 NAS 存储池的容量与备份策略。 #### 网络配置与依赖关系 默认配置会创建一个名为 `immich` 的定制桥接网络，所有服务均接入此网络。这实现了： * **网络隔离**：与宿主机或其他 Docker 网络隔离，增强安全性。 * **服务互通**：通过服务名直接进行 DNS 解析，简化了连接配置（如 `DB_HOSTNAME=postgres`）。 * **启动顺序控制**：通过 `depends_on` 字段（在博客提及的部署实践中隐含此逻辑），确保 `immich-server` 在 `postgres` 和 `redis` 就绪后才启动，避免连接失败。 #### 配置优化与生产建议 1. **资源限制**：建议为 `immich-machine-learning` 服务添加 `deploy.resources.limits`，限制其 CPU 和内存使用，防止 AI 模型推理时耗尽 NAS 资源。 2. **日志管理**：配置 `logging` 选项，使用 `json-file` 驱动并设置 `max-size` 和 `max-file`，避免日志文件无限增长占用存储空间。 3. **版本锁定**：所有镜像标签应使用明确的版本号（如 `release` 或具体的版本标签 `v1.90.0`），而非 `latest`，以保证部署的一致性和可回滚性。 4. **反向代理集成**：在 Docker Compose 文件中可添加 `nginx` 或 `traefik` 服务，配置 SSL 证书和域名，实现安全的远程访问，此步骤通常在初始部署后进行。 该 Docker Compose 文件体现了 Immich 项目良好的工程化实践，通过清晰的容器划分与环境变量配置，平衡了易用性与灵活性。用户通过修改环境变量和卷映射路径，即可轻松完成从基础部署到个性化定制的过渡。