Docker 部署

相关源文件

• .gitignore
• .vscode/launch.json
• Makefile
• cli/Dockerfile
• docker/docker-compose.dev.yml
• docker/docker-compose.prod.yml
• docker/docker-compose.yml
• docs/docs/administration/reverse-proxy.md
• e2e/docker-compose.yml
• server/Dockerfile
• web/Dockerfile

本页面介绍了如何使用 Docker Compose 部署 Immich，这是推荐且官方支持的部署方法。有关替代部署方法或配置选项，请参阅配置选项。

概述

Immich 使用 Docker Compose 来协调多个容器化服务，这些服务协同工作以提供完整的应用程序功能。这种部署方法简化了安装和维护，同时确保了跨不同系统的环境一致性。

来源: docker/docker-compose.yml12-76 docker/docker-compose.prod.yml12-86

先决条件

在用 Docker 部署 Immich 之前，请确保您已

1. 已安装 Docker Engine（版本 20.10.0 或更高版本）
2. 已安装 Docker Compose（V2 或更高版本）
3. 为您的媒体库提供足够的磁盘空间
4. 至少 4GB RAM（推荐 8GB+）

部署方法

标准生产部署

Immich 的推荐部署方式是使用官方发布的 docker-compose.yml 文件

来源: docker/docker-compose.yml1-80

1. 下载最新的 docker-compose.yml:

2. 创建一个 .env 文件，放在 docker-compose.yml 的旁边，其中包含必要的配置

3. 启动 Immich:

开发或手动构建

用于从源代码进行开发或手动构建

1. 克隆仓库:

2. 用于生产构建:

3. 用于开发:

来源: Makefile1-22 docker/docker-compose.dev.yml1-181 docker/docker-compose.prod.yml1-113

容器服务

标准的 Immich 部署由以下核心容器组成

容器名称	目的	图片
immich_server	主应用程序服务器，包括 API 和 Web 界面	ghcr.io/immich-app/immich-server
immich_machine_learning	用于面部识别、对象检测等的机器学习服务	ghcr.io/immich-app/immich-machine-learning
redis	用于作业队列和缓存的消息代理	docker.io/valkey/valkey
database	PostgreSQL 数据库，带向量搜索扩展	docker.io/tensorchord/pgvecto-rs

来源: docker/docker-compose.yml13-76

目录结构和卷

Immich 需要为多个组件提供持久化存储

来源: docker/docker-compose.yml43-49 docker/docker-compose.yml65-67

硬件加速

Immich 支持机器学习任务和视频转码的硬件加速。

机器学习加速

要启用机器学习的硬件加速，您需要

1. 取消注释 docker-compose.yml 中的相关部分
2. 使用适当的镜像标签后缀（例如，-cuda，-rocm，-openvino 等）

来源: docker/docker-compose.yml36-41

转码加速

用于视频转码加速

1. 取消注释 docker-compose.yml 中的相关部分
2. 配置相应的硬件加速服务

来源: docker/docker-compose.yml15-18

监控

Immich 包含可选的 Prometheus 和 Grafana 用于监控。要启用

1. 在您的 .env 文件中设置 IMMICH_TELEMETRY_INCLUDE=all
2. 取消注释您的 docker-compose 文件中的 Prometheus 和 Grafana 部分

可以通过以下方式访问指标

• Prometheus: http://your-server:9090
• Grafana: http://your-server:3000（默认登录: admin/admin）

来源: docker/docker-compose.prod.yml88-108

扩展

对于大型安装，您可以扩展服务器组件

来源: Makefile20-21

使用反向代理

当 Immich 部署在反向代理后面时，请确保它

1. 转发所有头信息 (Host, X-Real-IP, X-Forwarded-Proto, X-Forwarded-For)
2. 支持 WebSocket 连接
3. 允许大文件上传（推荐 50GB+）
4. 拥有足够的超时设置（推荐 10+ 分钟）

请注意，Immich 不支持从子路径提供服务——它必须托管在域或子域的根目录下。

来源: docs/docs/administration/reverse-proxy.md1-131

镜像构建过程

Immich 服务器镜像分多个阶段构建

1. 开发阶段：包含依赖项的基础镜像
2. 生产构建：编译后的服务器应用程序
3. Web 构建：编译后的 Web 界面
4. 最终镜像：服务器和 Web 界面的组合

服务器将 API 服务和嵌入式 Web 界面包含在单个容器中。

来源: server/Dockerfile1-86 web/Dockerfile1-12

故障排除

常见问题

1. 数据库连接问题：使用 docker compose ps 验证您的 PostgreSQL 容器是否正在运行
2. 权限问题：确保 Docker 用户对已配置的卷具有写入访问权限
3. 硬件加速问题：检查硬件兼容性和驱动程序安装

日志和调试

查看日志

用于交互式调试

来源: Makefile36-37 .vscode/launch.json1-23

开发环境设置

为了方便开发，请使用开发 Docker Compose 文件，该文件会将源代码目录挂载为卷，以便进行实时代码更改

开发环境提供了

• 服务器组件的热重载
• 带热重载的 Web 开发服务器
• 用于服务器附件的调试端口

来源: docker/docker-compose.dev.yml17-93 .vscode/launch.json4-12