Immich：高性能自托管照片和视频管理解决方案完全指南

# 支持的存储后端
storage:
  - 本地文件系统
  - S3 兼容存储（AWS S3, MinIO, Backblaze）
  - NAS 挂载（SMB/NFS）
  - 外部存储路径

# 用户自定义存储结构
user_storage:
  by_date: "/photos/{year}/{month}/{day}"
  by_album: "/albums/{album_name}"

# docker-compose.yml
version: '3.8'

services:
  immich-server:
    image: immich-app/immich-server:release
    container_name: immich_server
    ports:
      - "2283:3000"
    volumes:
      - ./upload:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    environment:
      - DB_HOSTNAME=immich_postgres
      - REDIS_HOSTNAME=immich_redis
    depends_on:
      - immich_postgres
      - immich_redis

  immich_machine_learning:
    image: immich-app/immich-machine-learning:release
    container_name: immich_ml

  immich_redis:
    image: redis:14
    container_name: immich_redis

  immich_postgres:
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    container_name: immich_postgres

  immich_typesense:
    image: typesense/typesense:26.0
    container_name: immich_typesense

# 创建容器网络
docker network create immich_network

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

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# Nginx 反向代理配置
server {
    listen 443 ssl;
    server_name your-immich-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 文件上传大小限制
        client_max_body_size 100M;
        
        # WebSocket 支持（实时通知）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 备份脚本示例
#!/bin/bash
# 备份 Immich 数据

# 1. 导出数据库
docker exec immich_postgres pg_dump -U postgres > backup_$(date +%Y%m%d).sql

# 2. 备份上传文件
rsync -avz ./upload/ /path/to/backup-drive/

# 3. 备份配置文件
cp .env /path/to/backup-drive/

# 人脸识别伪代码
def recognize_faces(image):
    # 1. 检测人脸
    boxes = face_detector(image)
    
    # 2. 提取特征
    embeddings = face_encoder(image, boxes)
    
    # 3. 与已知人脸比对
    for embedding in embeddings:
        matches = find_similar(embedding, known_faces)
        
    return clusters

# CLIP 搜索原理
def clip_search(query_text, image_db):
    # 1. 将文本编码为向量
    query_embedding = clip.encode_text(query_text)
    
    # 2. 与所有图像向量比对
    results = []
    for image in image_db:
        similarity = cosine_similarity(
            query_embedding, 
            image.embedding
        )
        results.append((image, similarity))
    
    # 3. 返回最相似的图像
    return sorted(results, key=lambda x: x[1], reverse=True)

# 1. 克隆仓库
git clone https://github.com/immich-app/immich.git
cd immich

# 2. 安装依赖（使用 pnpm）
corepack enable
pnpm install

# 3. 启动开发服务
docker-compose -f docker-compose.dev.yml up -d

# 4. 运行 Web 开发服务器
pnpm dev web

# 5. 运行移动端
cd mobile && flutter run

# TypeScript/Node.js
pnpm lint          # ESLint 检查
pnpm format        # Prettier 格式化
pnpm test          # 运行测试

# Flutter/Dart
flutter analyze    # Dart 分析
flutter format     # 格式化
flutter test       # 运行测试

# Python
ruff check .        # Lint 检查
ruff format .       # 格式化
pytest              # 运行测试