自托管 Immich：私人照片云存储

Immich 是一款革命性的开源、自托管照片和视频管理解决方案，它赋予你对记忆的完全控制权。凭借与 Google Photos 相媲美的功能，包括人工智能驱动的人脸识别、智能搜索和自动手机备份，同时确保你的数据在你自己的服务器上保持私密和安全。

正如 个人知识管理 帮助你组织和保存你的想法和信息一样，Immich 帮助你组织和保存你的视觉记忆。

什么是 Immich？

Immich 是 Google Photos 和 iCloud 等专有云照片服务的开源、自托管替代方案。使用现代技术构建，包括 TypeScript、PostgreSQL 和机器学习，Immich 提供了一个功能丰富的平台，用于备份、组织和浏览你的照片和视频收藏。

主要功能

以隐私为先的设计：你的所有照片都保留在你的基础设施上。没有第三方服务器，没有数据挖掘，没有隐私问题。你的记忆属于你。

自动手机备份：原生的 iOS 和 Android 应用程序提供自动后台备份，类似于 Google Photos。你拍摄照片后，照片立即得到保护。

人工智能驱动的搜索：利用包括 CLIP 和人脸识别在内的机器学习模型，Immich 实现语义搜索。搜索“海滩日落”、“狗玩耍”或特定人物，无需手动标记。

人脸识别：自动检测和聚类照片中的人脸。Immich 能够识别你整个库中的所有人，使查找特定人物的照片变得容易。

现代网页界面：美观、响应式的网页界面，可用于从任何设备通过浏览器浏览、组织和分享照片。

多用户支持：为家庭成员创建账户，每个账户都有自己的私人库。分享选定的相册，同时保持个人照片的隐私。

Live Photo 支持：完全支持 iOS Live Photos 和 Android Motion Photos，保留静态图像和视频组件。

元数据保留：包括位置、相机设置和时间戳的 EXIF 数据被保留。根据 GPS 坐标在地图上查看照片。

外部库支持：无需复制文件即可从外部存储导入现有照片库，节省磁盘空间。类似于 Obsidian 帮助管理文本知识的方式，Immich 为视觉媒体提供强大的组织功能。

为什么自托管你的照片？

完整的隐私控制

当你使用商业云服务时，你的照片存储在你无法控制的服务器上。它们可能被用于广告分析、包含在机器学习训练数据中，或被第三方访问。使用 Immich 时，除非你明确分享，否则你的照片永远不会离开你的服务器。

没有存储限制

云服务根据存储层级收费。通过自托管，你的唯一限制是你的硬件容量。一个 10TB 的硬盘价格低于两年的高级云存储费用。

成本效益

在初始硬件投资后，自托管的持续成本极低。没有月度订阅，没有超出存储限制时的意外费用。

数据持久性

云服务可能会更改条款、提高价格或完全关闭。你的自托管解决方案将永远在你的控制之下。

学习机会

自托管 Immich 提供了与 Docker、反向代理、SSL 证书、数据库管理和服务器管理相关的动手经验，这些对任何开发人员或 DevOps 专业人士来说都是宝贵的技能。

架构概述

Immich 采用微服务架构，包含以下组件：

Immich 服务器：主 API 服务器，处理身份验证、照片上传和数据库操作。使用 Node.js 和 TypeScript 构建。

Immich 机器学习：独立的 Python 服务，运行 TensorFlow 模型，用于人脸识别、目标检测和基于 CLIP 的语义搜索。

Immich 网页：基于 React 的网页界面，提供面向用户的应用程序。

PostgreSQL：关系型数据库，存储元数据、用户信息以及照片、人物和相册之间的关系。

Redis：用于会话管理和作业队列协调的内存缓存。

TypeSense（可选）：增强搜索功能和性能的搜索引擎。

所有组件都作为 Docker 容器运行，使用 Docker Compose 进行编排，简化部署和管理。

硬件要求

最低规格

• CPU：2 核（x86_64 或 ARM64）
• RAM：4GB（推荐 8GB）
• 存储：10GB 用于应用程序 + 照片库大小
• 网络：100 Mbps 用于本地访问

推荐规格

• CPU：4 核以上，具有良好的单线程性能
• RAM：8-16GB（库更大时更多）
• 存储：SSD 用于数据库和应用程序，HDD 用于照片存储
• GPU：可选，但显著加速 ML 任务（NVIDIA 带 CUDA 支持）

存储考虑

计划使用当前照片库大小的 1.15 倍，以容纳缩略图和多种分辨率。使用 SSD 存储 PostgreSQL 数据库以获得更好的性能。

对于大型库（100,000 张以上照片），考虑：

• 带 RAID 的 NAS 以实现数据冗余
• 用于数据库的独立 SSD
• 用于频繁访问照片的 NVMe 缓存层

安装指南

先决条件

在安装 Immich 之前，请确保你有：

1. Linux 服务器：推荐使用 Ubuntu 22.04 LTS 或 Debian 12（有关详细设置说明，请参阅我们的 如何安装 Ubuntu 24.04 及有用工具）
2. Docker：版本 20.10 或更新
3. Docker Compose：版本 2.0 或更新
4. 域名：可选，但推荐用于外部访问
5. 反向代理：Nginx 或 Caddy 用于 SSL 终止

分步安装

1. 安装 Docker 和 Docker Compose

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 将用户添加到 docker 组
sudo usermod -aG docker $USER

# 安装 Docker Compose
sudo apt install docker-compose-plugin

有关 curl 命令和选项的更多详细信息，请参阅我们的 cURL 快速参考。如果你是 Docker 新手，我们的 Docker 快速参考 提供了基本命令和概念。

2. 创建 Immich 目录结构

# 创建应用程序目录
mkdir -p ~/immich/{library,database,machine-learning}
cd ~/immich

# 下载 docker-compose.yml
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

如果你是 bash 脚本和命令行操作的新手，我们的 Bash 快速参考 提供了常见命令和目录操作的有用参考。

3. 配置环境变量

编辑 .env 文件并输入你的设置：

# 数据库配置
DB_PASSWORD=your_secure_password_here
DB_DATABASE_NAME=immich
DB_USERNAME=postgres

# 上传位置
UPLOAD_LOCATION=./library

# 机器学习
MACHINE_LEARNING_ENABLED=true

# 时区
TZ=America/New_York

# 公共 URL（用于外部访问）
IMMICH_SERVER_URL=https://photos.yourdomain.com

重要：为 DB_PASSWORD 生成一个强随机密码：

openssl rand -base64 32

4. 启动 Immich

# 启动所有服务
docker compose up -d

# 检查服务状态
docker compose ps

# 查看日志
docker compose logs -f

这些只是基础内容 - 有关 Docker Compose 命令和操作的全面参考，请参阅我们的 Docker Compose 快速参考。

5. 访问网页界面

导航到 http://your-server-ip:2283 并创建你的管理员账户。这个第一个账户将成为系统管理员。

设置外部访问

为了安全的外部访问，请配置反向代理：

Nginx 配置示例

server {
    listen 443 ssl http2;
    server_name photos.yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 50000M;

    location / {
        proxy_pass http://localhost:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Caddy 配置示例（更简单，自动 HTTPS）

photos.yourdomain.com {
    reverse_proxy localhost:2283
    
    @uploads {
        path /api/upload/*
    }
    request_body @uploads {
        max_size 50GB
    }
}

移动应用设置

iOS

1. 从 App Store 下载 Immich
2. 输入你的服务器 URL（https://photos.yourdomain.com）
3. 使用凭据登录
4. 在设置中启用自动备份
5. 选择要备份的相册（或所有照片）
6. 配置备份设置（仅限 WiFi、仅限充电等）

Android

1. 从 Google Play 商店或 F-Droid 下载 Immich
2. 输入服务器 URL 和凭据
3. 授予照片/视频访问权限
4. 配置自动备份设置
5. 启用前台服务以实现可靠的后台备份

备份配置技巧

• 仅限 WiFi：启用以避免移动数据费用
• 仅限充电：防止大文件上传时耗尽电池
• 包含视频：视频会占用大量存储和带宽
• 后台应用刷新：在 iOS 上启用以实现可靠同步
• 前台服务：在 Android 上启用以实现一致的备份

机器学习功能

人脸识别

Immich 的人脸识别自动检测并聚类库中的面孔：

1. 初始处理：上传后，ML 服务分析每张照片中的人脸
2. 人脸聚类：相似的人脸被分组在一起
3. 手动分配：查看聚类并为人物分配名称
4. 持续学习：随着你标记更多照片，准确性提高

配置：

# 在 docker-compose.yml 中，ML 服务环境
MACHINE_LEARNING_MODEL_CACHE=/cache
MACHINE_LEARNING_WORKERS=1  # 随着更多 CPU 核心增加

目标检测和 CLIP 搜索

Immich 使用 CLIP（对比语言-图像预训练）进行语义搜索：

• 搜索没有标签的概念：“山景”、“生日蛋糕”、“红色汽车”
• 自然语言查询理解上下文和关系
• 支持多种语言（尽管英语通常效果最佳）

GPU 加速

为了显著加快 ML 处理速度，请启用 GPU 支持：

NVIDIA GPU 带 CUDA

# 在 docker-compose.yml 中，ML 服务
services:
  immich-machine-learning:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

确保你已安装 NVIDIA Container Toolkit：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

备份策略

虽然 Immich 从移动设备备份你的照片，但你也应该备份 Immich 本身：

需要备份的内容

1. 照片库：包含原始照片的 UPLOAD_LOCATION 目录
2. 数据库：包含元数据和关系的 PostgreSQL 数据库
3. 配置：.env 文件和 docker-compose.yml

数据库备份

自动化每日备份脚本

#!/bin/bash
# 保存为 ~/immich/backup.sh

BACKUP_DIR=~/immich-backups
DATE=$(date +%Y%m%d_%H%M%S)

# 创建备份目录
mkdir -p $BACKUP_DIR

# 备份 PostgreSQL 数据库
docker exec -t immich-postgres pg_dumpall -c -U postgres | \
    gzip > $BACKUP_DIR/immich_db_$DATE.sql.gz

# 保留最近 30 天的备份
find $BACKUP_DIR -name "immich_db_*.sql.gz" -mtime +30 -delete

echo "备份完成: $BACKUP_DIR/immich_db_$DATE.sql.gz"

使其可执行并使用 cron 调度：

chmod +x ~/immich/backup.sh
crontab -e
# 添加行: 0 2 * * * ~/immich/backup.sh

有关 bash 脚本、自动化和 cron 作业的更多信息，请参阅我们的全面 Bash 快速参考。

照片库备份

你的照片库应单独备份到另一个位置：

选项 1：使用 Rsync 备份到 NAS

rsync -avz --delete ~/immich/library/ nas:/backups/immich-photos/

选项 2：加密云备份

# 使用 rclone 加密
rclone sync ~/immich/library/ remote:immich-backup-encrypted/ --encrypt

选项 3：本地外部驱动器

rsync -avz --delete ~/immich/library/ /mnt/backup-drive/immich/

维护和更新

定期维护任务

监控磁盘空间

# 检查磁盘使用情况
df -h ~/immich/library
df -h ~/immich/database

# 检查 Docker 卷
docker system df

监控性能

# 查看资源使用情况
docker stats

# 检查特定服务日志
docker compose logs immich-server --tail=100
docker compose logs immich-machine-learning --tail=100

更新 Immich

Immich 经常更新，包含新功能和错误修复。定期更新：

cd ~/immich

# 更新前备份数据库
docker exec -t immich-postgres pg_dumpall -c -U postgres > backup_pre_update.sql

# 拉取最新镜像
docker compose pull

# 停止并删除旧容器
docker compose down

# 使用新镜像启动
docker compose up -d

# 检查日志是否有任何问题
docker compose logs -f

数据库维护

定期数据库维护确保最佳性能：

# 真空和分析数据库
docker exec -it immich-postgres psql -U postgres -d immich -c "VACUUM ANALYZE;"

# 检查数据库大小
docker exec -it immich-postgres psql -U postgres -d immich -c \
    "SELECT pg_size_pretty(pg_database_size('immich'));"

性能优化

存储优化

使用 SSD 存储数据库：PostgreSQL 从 SSD 存储中受益匪浅。考虑：

volumes:
  pgdata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/ssd/immich-db

分离照片存储：将大型照片库保留在 HDD 上，而数据库保留在 SSD 上：

UPLOAD_LOCATION=/mnt/hdd/immich-photos

数据库性能调优

对于 50,000 张以上照片的库，调整 PostgreSQL：

# 在 docker-compose.yml 中，PostgreSQL 服务环境
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
POSTGRES_MAINTENANCE_WORK_MEM=64MB
POSTGRES_CHECKPOINT_COMPLETION_TARGET=0.9
POSTGRES_WAL_BUFFERS=16MB
POSTGRES_DEFAULT_STATISTICS_TARGET=100

机器学习性能

批量处理：同时处理多张照片：

MACHINE_LEARNING_WORKERS=4  # 与 CPU 核心数匹配

GPU 加速：如前所述，GPU 加速可为 ML 任务提供 5-10 倍的速度提升。

安全最佳实践

身份验证和访问控制

1. 强密码：使用密码管理器生成和存储复杂密码
2. 双因素认证：为管理员账户启用 2FA（如果你的版本支持）
3. 定期访问审查：定期审查用户账户并删除未使用的账户

网络安全

带有 SSL 的反向代理：不要在没有 HTTPS 的情况下直接将 Immich 暴露在互联网上：

# 使用 Let's Encrypt 免费 SSL 证书
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d photos.yourdomain.com

防火墙配置：

# 仅允许必要的端口
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP（重定向到 HTTPS）
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

VPN 或 Tailscale：为了最大安全性，通过 VPN 访问 Immich：

• 在服务器和设备上安装 Tailscale
• 通过 Tailscale IP（100.x.x.x）访问
• 没有端口暴露在公共互联网上

容器安全

定期更新：保持 Docker 镜像更新以修补安全漏洞

无根运行：配置 Docker 无根模式以获得额外的隔离

资源限制：通过限制容器资源防止 DoS 攻击：

services:
  immich-server:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

常见问题排查

上传失败

症状：照片无法从移动应用上传

解决方案：

• 检查服务器磁盘空间：df -h
• 验证反向代理 client_max_body_size 设置
• 检查服务器日志：docker compose logs immich-server
• 确保移动应用使用最新版本

机器学习未处理

症状：人脸识别或搜索不起作用

解决方案：

• 检查 ML 容器状态：docker compose ps immich-machine-learning
• 查看 ML 日志：docker compose logs immich-machine-learning
• 重启 ML 服务：docker compose restart immich-machine-learning
• 验证模型文件是否已下载：ls ~/immich/machine-learning/cache/

数据库连接错误

症状：网页界面显示数据库连接错误

解决方案：

• 验证 PostgreSQL 容器是否正在运行：docker compose ps immich-postgres
• 检查数据库日志：docker compose logs immich-postgres
• 验证 .env 文件中的正确密码
• 测试连接：docker exec -it immich-postgres psql -U postgres

性能缓慢

症状：网页界面或搜索缓慢

解决方案：

• 检查系统资源：CPU、RAM、磁盘 I/O
• 运行数据库真空：VACUUM ANALYZE;
• 重启服务：docker compose restart
• 审查 PostgreSQL 性能设置
• 考虑硬件升级（SSD、更多 RAM）

移动应用未同步

症状：照片未从移动设备备份

解决方案：

• 验证后台刷新是否启用（iOS）
• 启用前台服务（Android）
• 检查 WiFi 仅设置（如果使用移动数据）
• 验证服务器 URL 是否可通过移动网络访问
• 检查应用权限以访问照片
• 清除应用缓存并重新登录

从其他服务迁移

从 Google Photos 迁移

导出你的数据：

1. 前往 Google Takeout（takeout.google.com）
2. 选择 Google Photos
3. 选择导出格式和大小
4. 下载存档

导入到 Immich：

1. 解压下载的存档
2. 使用 Immich CLI 工具或网页上传
3. 从 JSON 侧边文件保留元数据

# 使用 Immich CLI（从发布版安装）
immich upload --recursive /path/to/google-photos-export/

从 iCloud Photos 迁移

导出：

1. 访问 iCloud.com
2. 选择要下载的照片
3. 或使用 iCloud for Windows/Photos 应用导出

导入： 与 Google Photos 类似，通过网页界面或 CLI 工具上传

从本地存储迁移

外部库功能：而不是上传，将 Immich 指向现有照片目录：

1. 导航到管理 > 外部库
2. 添加库路径（必须可从 Docker 容器访问）
3. Immich 扫描并索引而不复制文件
4. 节省大量磁盘空间和时间

# 在 docker-compose.yml 中，添加卷挂载
volumes:
  - /mnt/existing-photos:/mnt/external-library:ro

社区和支持

官方资源

• GitHub：https://github.com/immich-app/immich
• 文档：https://immich.app/docs
• Discord：活跃社区，提供实时帮助
• Reddit：r/immich 讨论和技巧

贡献

Immich 是开源的，欢迎贡献：

• 错误报告：在 GitHub 上提交详细的问题报告
• 功能请求：在 Discord 或 GitHub 讨论中讨论
• 代码贡献：按照贡献指南提交拉取请求
• 文档：改进文档以获得更好的用户体验
• 翻译：帮助将 Immich 翻译成你的语言

替代工具

如果 Immich 无法满足你的需求，可以考虑：

• PhotoPrism：更成熟、功能丰富、不同架构
• Piwigo：传统画廊式界面
• Nextcloud Photos：Nextcloud 生态系统的一部分
• Photoview：更简单、轻量级的替代方案
• LibrePhotos：另一个带有 AI 功能的 Google Photos 替代方案

结论

自托管 Immich 提供了一种强大且私密的替代商业云照片服务的方案。虽然它需要初始的技术设置和持续的维护，但完全的隐私控制、无存储限制和免订阅费用的好处对许多用户来说是值得的。

自动手机备份、人工智能驱动的搜索、人脸识别和现代界面的结合，创造了一种与商业产品相当的体验，同时让你的数据保持在你的控制之下。无论你是隐私爱好者、拥有大型照片库的成本敏感用户，还是希望获得动手基础设施经验的技术专业人士，Immich 都提供了一个有吸引力的解决方案。

从小型家庭服务器或 VPS 开始，用你照片库的一部分进行测试，随着你对系统的熟悉程度提高，逐步迁移。活跃的社区和频繁的更新确保 Immich 将继续改进并添加新功能。

你的记忆是宝贵的 - 使用 Immich 来掌控它们。

有用的链接

• 官方网站: https://immich.app
• GitHub 仓库: https://github.com/immich-app/immich
• 文档: https://immich.app/docs/overview/introduction
• 安装指南: https://immich.app/docs/install/docker-compose
• Discord 社区: https://discord.gg/immich
• 移动应用:
  • iOS: https://apps.apple.com/app/immich/id1613945652
  • Android: https://play.google.com/store/apps/details?id=app.alextran.immich
• Docker Hub: https://hub.docker.com/r/ghcr.io/immich-app
• 版本更新日志: https://github.com/immich-app/immich/releases
• Awesome Immich: https://github.com/varun-raj/awesome-immich (社区资源)
• r/immich: https://reddit.com/r/immich