自托管 Immich Docker 栈：ML 人脸识别、外部存储扩展、反向代理与 WiFi 手机自动备份

在自托管照片管理中，Immich 以 Docker 栈形式脱颖而出，支持 ML 人脸 / 物体识别、外部存储扩展、反向代理集成及 WiFi 手机自动备份，实现 Google Photos 级体验却完全掌控数据。相较商业云服务，避免隐私泄露与订阅费；对比 PhotoPrism，Immich 手机 App 备份更无缝，ML 模型（如 ArcFace）识别率达 97%+。

核心优势在于 Docker Compose 一键部署，包含 immich-server（API / 前端，端口 2283）、immich-machine-learning（ML 服务，人脸检测 / 分组）、Redis（队列）、Postgres（向量数据库）。最小配置：4GB RAM、2 核 CPU；推荐 6GB+、4 核 + GPU 加速（NVIDIA CUDA 或 Intel QuickSync）。

部署参数清单：

1. 环境准备：

   • 创建目录：mkdir immich && cd immich
   • 下载文件：wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml 和 wget https://github.com/immich-app/immich/releases/latest/download/example.env，复制为 .env。
   • 编辑 .env：

     UPLOAD_LOCATION=/path/to/library  # 照片存储，推荐 NFS/SMB 挂载外部盘扩展
     DB_DATA_LOCATION=/path/to/postgres
     DB_PASSWORD=强随机密码（A-Za-z0-9）
     TZ=Asia/Shanghai
     IMMICH_VERSION=release  # 或 v1.XX.X 固定版
     

     权限：chown -R 10000:10000 /path/to/library（容器 UID）。

2. 启动栈：

   docker compose up -d
   

   首次拉取镜像～3GB，等待 ML 模型下载（buffalo_l 默认）。验证：docker compose logs immich-server，访问 http://IP:2283 注册 admin。

3. 外部存储扩展：

   • 本地：UPLOAD_LOCATION 指向大容量盘。
   • 分布式：docker-compose.yml 中 volumes 添加 - nfs-server:/mnt/external:ro（外部库只读导入）。
   • S3 兼容：.env 加 STORAGE_TEMPLATE=import/path/%DATE\ 等，Admin > Storage Template 配置年 / 月 / 设备分层，避免单盘瓶颈。Scaling 时用 RAID 或 Ceph。

4. ML 人脸识别配置：

   • 默认启用，immich-machine-learning 容器自动扫描库（Job Queue > Face Detection）。
   • 加速：下载 hwaccel.ml.yml，extends: service: cuda（NVIDIA），或 quicksync（Intel）。
   • 参数：Admin > Settings > Machine Learning > Model（antelopev2 高精度）。阈值 0.5（平衡 FAR/FRR）。监控：队列长度 <10，避免 backlog。

5. 反向代理（Traefik/Nginx）：

   • Traefik（动态发现）：docker-compose.yml 加：

     labels:
       - "traefik.enable=true"
       - "traefik.http.routers.immich.rule=Host(`photos.example.com`)"
       - "traefik.http.routers.immich.tls.certresolver=letsencrypt"
     

     Traefik dashboard 监控流量。
   • Nginx：/etc/nginx/sites-available/immich：

     server {
       listen 443 ssl;
       server_name photos.example.com;
       proxy_pass http://localhost:2283;
       proxy_set_header Host $host;
       location /api/ { proxy_pass http://localhost:2283/api/; }
     }
     

     HTTPS：Certbot。防火墙：ufw allow 443。

6. WiFi 手机自动备份：

   • 下载 App：iOS App Store/Android GitHub APK。
   • 配置：Server Endpoint https://photos.example.com/api（HTTPS 必备）。
   • 备份设置：WiFi only、充电时后台、选相册（防重复）。参数：视频质量 medium、Live Photos 支持。
   • 监控：App > Backup，Admin > Users 查看进度。

运维清单：

• 备份：3-2-1 规则。Cron：0 2 * * * docker exec immich_postgres pg_dump -U postgres immich > backup.sql；rsync library。
• 升级：docker compose pull && docker compose up -d，备份先。
• 监控：Prometheus + Grafana（container metrics）、存储使用 >80% 警报。
• 回滚：固定 IMMICH_VERSION，docker compose down/up。
• 风险：ML 高负载（限 2G 内存），无冗余存储风险数据丢失。

实际测试：10 万张照片，首次索引 24h（GPU 加速 4h），备份 1GB/min。外部 NFS 扩展无缝，Traefik 零配置 HTTPS。

资料来源：

• Immich GitHub: https://github.com/immich-app/immich
• 部署指南（CSDN/Juejin 等教程）
• Primary: https://stapelberg.ch/posts/2025-12-05-self-hosting-photos-immich/（自托管照片实践）