Skip to content

🚀 使用 Docker Compose 部署 Immich 自托管相册

🚀 使用 Docker Compose 部署 Immich 自托管相册

Immich 是一个开源的自托管照片和视频备份解决方案，可直接从手机备份媒体文件。它提供了与 Google Photos 相似的界面和功能，支持多用户、相册分享、人脸识别、地理位置标记和智能搜索等特性。

进入自用通道 [[🚀 使用 Docker Compose 部署 Immich]]

📖 项目简介

Immich 专为希望完全掌控个人数据的用户设计，您可以将它部署在个人服务器或 NAS 上。其核心优势包括：

  • 数据自主与隐私安全：所有照片和视频都存储在您自己的设备上，无需担心第三方云服务的政策变更或隐私问题。
  • 功能丰富：
    • AI驱动：支持人脸识别、物体分类和智能搜索。
    • 多用户支持：可以为家人或朋友创建独立账户，并共享相册。
    • 跨平台应用：提供 Web 界面以及 iOS 和 Android 手机客户端。
    • 外部库支持：可以导入和管理服务器上已有的照片目录。
  • 活跃的开源社区：项目在 GitHub 上非常活跃，持续迭代更新。

⚙️ 部署前准备

  1. 环境要求

    • 已安装 Docker 和 Docker Compose。请确保 Docker 守护进程正在运行。
    • 操作系统：支持 Linux、Windows (WSL2) 或 macOS。
    • 硬件建议：
      • 内存：建议至少 4GB。如果照片数量庞大或启用所有 AI 功能，推荐 8GB 或更多。
      • 存储：准备足够的硬盘空间来存储照片和视频，并确保 UPLOAD_LOCATION 和 DB_DATA_LOCATION 指向的路径有足够容量。
      • CPU：较新的多核处理器能提供更好性能。

  2. 创建工作目录 在服务器上创建一个独立的目录来存放所有部署文件，便于管理。 bash mkdir -p ~/immich-app cd ~/immich-app

🔧 配置 Docker Compose

Immich 的部署主要涉及两个配置文件：docker-compose.yml 和 .env。

  1. 下载配置文件 从官方 GitHub Release 页面下载最新的配置文件。
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

如果无法使用 wget，也可在浏览器中打开链接下载，并将 example.env 重命名为 .env。

  1. 配置环境变量 (.env 文件) 编辑 .env 文件，以下是一些关键配置项（根据你的配置，部分可能已设置）：

    环境变量 说明 示例值/建议
    UPLOAD_LOCATION 上传的照片和视频的存储路径。务必设置为有足够空间的路径。 /mnt/10t/file/Immich/Photos/library
    DB_DATA_LOCATION PostgreSQL 数据库文件的存储路径。不支持网络共享。 /mnt/10t/file/Immich/Photos/postgres
    TZ 设置时区，确保照片时间戳正确。 Asia/Shanghai
    IMMICH_VERSION 指定要使用的 Immich 版本。 release
    DB_PASSWORD 数据库密码，务必修改为强密码，仅使用 A-Za-z0-9 字符。 BaLt42Ncd7s3XX6

    你提供的配置中已正确设置了这些关键变量。

  2. 检查 Docker Compose 文件 (docker-compose.yml) 该文件定义了 Immich 的多个服务，包括 immich-server（主程序）、immich-machine-learning（AI功能）、redis（缓存）和 database（PostgreSQL数据库）。

    • 确保 volumes 挂载路径正确。
    • 你已配置 ports: - '2283:2283'，这意味着可通过服务器的 2283 端口访问 Web 界面。

🚀 启动与验证

  1. 启动服务 在包含 docker-compose.yml 和 .env 文件的目录下，执行以下命令以后台模式启动所有服务： bash docker compose up -d 首次运行会从 Docker Hub 拉取镜像，需要一些时间。

  2. 验证部署

    • 检查容器状态： bash docker compose ps 确认所有容器状态均为 Up (healthy)。
    • 查看日志： bash docker compose logs -f immich-server
    • 访问 Web 界面： 打开浏览器，访问 http://你的服务器IP:2283。

🛠️ 基础配置与使用

  1. 初始设置

    • 注册管理员账户：首次访问 Web 界面，点击 "Getting Started" 并按照提示注册。第一个注册的用户会自动成为管理员。
    • 创建其他用户（可选）：管理员可以在 "Administration" 面板中为家人或朋友创建用户账户。

  2. 配置存储模板（推荐） 存储模板决定了上传文件在服务器上的存储目录结构。

    • 进入 "Administration -> Settings -> Storage Template"。
    • 你可以使用默认模板，或根据日期、相册名称等变量自定义。
    • 一个常见的自定义模板示例，将文件按相册（如果有）以及年份和月份分组存储： {{#if album}}{{album}}/{{y}}/{{MM}}/{{filename}}{{else}}Other/{{y}}/{{MM}}/{{filename}}{{/if}} 注意：如果需要根据条件（如是否存在相册）构建不同路径，请确保将整个路径结构包裹在条件语句 {{#if}}...{{/if}} 内，否则条件块之后的内容会被无条件添加到所有路径中。

  3. 使用手机 App 备份

    • 从官方应用商店下载 Immich 手机 App。
    • 打开 App，输入服务器地址：http://你的服务器IP:2283。
    • 使用注册的账户登录。
    • 在 App 的备份设置中，选择要备份的相册并开启自动备份。

  4. 批量导入现有照片 对于服务器上已有的照片目录，可以使用 Immich CLI 工具进行批量导入。

    • 基本命令示例： bash # 首先进行身份验证 immich login-key http://你的服务器IP:2283/api 你的API密钥 # 递归上传整个目录，并根据文件夹名称自动创建相册 immich upload --recursive --album /path/to/your/photos
    • API 密钥可以在 Web 界面的用户设置中获取。

🔄 维护与管理

  1. 服务停止与启动 bash # 停止服务 docker compose down # 启动服务 docker compose up -d

  2. 数据备份 至关重要：定期备份你配置的 UPLOAD_LOCATION（照片视频文件）和 DB_DATA_LOCATION（数据库）目录。团队建议遵循 3-2-1 备份策略（至少三个数据副本，两种不同介质，一个异地副本）来保护珍贵记忆。

  3. 更新 Immich 当有新版本发布时： bash # 拉取最新镜像 docker compose pull # 重新启动服务 docker compose up -d 更新前，建议查阅官方发布说明，并确保你的数据已备份。

❓ 常见问题排查

  1. 容器启动失败

    • 检查 .env 文件：确保所有路径设置正确，且 DB_PASSWORD 不包含特殊字符。
    • 查看日志：使用 docker compose logs [服务名] 查看具体错误信息。

  2. 无法访问 Web 界面

    • 检查防火墙/安全组：确保服务器的 2283 端口已开放。
    • 确认容器状态：运行 docker compose ps 检查所有容器是否正常运行。

  3. AI 识别（人脸、物体）不工作或速度慢

    • 硬件加速：考虑为 immich-machine-learning 服务配置 GPU 硬件加速（如 CUDA、OpenVINO）以提升性能。具体请参考官方硬件加速文档。
    • 资源检查：AI 功能可能占用大量内存和 CPU，确保服务器资源充足。

  4. 上传照片失败

    • 检查存储路径权限：确保 UPLOAD_LOCATION 对应的目录对 Docker 容器有读写权限。

通过以上步骤，你应该能够成功部署并开始使用你的私有云相册。如果在使用过程中遇到问题，Immich 活跃的官方文档和社区论坛是寻求帮助的好去处。