Docker 部署 Immich：自建 Google Photos 替代方案，私有相冊全流程教程（2026版）

Docker 部署 Immich

智能手機時代，我們每天都在拍攝海量的照片和視頻。然而，這些珍貴的記憶卻被「關押」在各種雲服務中：Google Photos 的免費無限存儲已於 2021 年結束，iCloud 每年數百元訂閱費，百度雲限速嚴重……

如果你想：

📸 完全掌控 自己的照片數據
🤖 AI 智能識別 物體、場景、人臉
🗺️ 地圖視圖 查看拍攝地點
📱 手機自動備份 隨時隨地上傳
👨‍👩‍👧‍👦 家庭共享 多賬號共用
💰 零訂閱費 一次部署終身使用

那麼 Immich（發音類似 "Image"）就是為你量身定做的解決方案。

Immich 是一個開源的照片和視頻管理與備份系統，功能對標 Google Photos。它由社區驅動，開發非常活躍，在 2025-2026 年持續高速迭代，已成為最受歡迎的自建相冊方案。

本文將帶你從零開始，用 Docker Compose 部署屬於你自己的 Immich 私有相冊。

Immich 是什麼？核心功能一覽
硬件與資源需求
Immich 架構組件解析
Docker Compose 完整部署
Nginx / Caddy 反向代理配置
初始化設置與管理員賬號
手機端 App 安裝與自動備份
AI 智能識別與人臉識別配置
相冊管理、共享與協作
數據備份與恢復策略
性能優化與資源調整
常見問題與故障排查

1. Immich 是什麼？核心功能一覽

1.1 核心功能矩陣

功能模塊	功能詳情	實現狀態
自動備份	手機端 App 自動備份照片、視頻	✅ 完整
Web 界面	網頁端瀏覽、管理、上傳照片	✅ 完整
AI 識別	物體識別、場景識別、CLIP 語義搜索	✅ 完整
人臉識別	自動識別人物、分類命名	✅ 完整
地圖視圖	根據 EXIF GPS 信息顯示照片位置	✅ 完整
相冊管理	創建相冊、收藏夾、智能相冊	✅ 完整
共享相冊	創建共享鏈接、家庭相冊、密碼保護	✅ 完整
多用戶支持	多賬號、配額管理、家庭共享	✅ 完整
視頻支持	視頻上傳、播放、縮略圖生成	✅ 完整
Live Photos	iOS Live Photos 支持	✅ 完整
桌面客戶端	Windows / macOS 客戶端上傳	✅ 可用
API 支持	完整的 RESTful API	✅ 完整

1.2 與 Google Photos 功能對比

特性	Immich	Google Photos
照片/視頻備份	✅	✅
AI 圖片搜索	✅	✅
人臉識別	✅	✅
地圖視圖	✅	✅
相冊管理	✅	✅
共享鏈接	✅	✅
免費存儲	✅（取決於你的服務器容量）	❌（15GB 後需付費）
數據隱私	✅（完全私有）	❌（被 Google 分析用於廣告）
多用戶	✅	✅
原畫質	✅	✅（超出 15GB 需付費）
RAW 格式支持	✅	⚠️
視頻轉碼	✅（硬件加速可選）	✅
地圖熱圖	✅	❌（僅 Google Maps 集成）

1.3 Immich 的核心技術棧

後端:
• Node.js（API 服務器）
• PostgreSQL（主數據庫）
• Redis（緩存和任務隊列）
• Python（機器學習微服務）

AI/ML:
• CLIP（語義搜索 - Contrastive Language-Image Pre-training）
• face-api.js（人臉識別）
• TensorFlow.js 或 ONNX（模型推理）

前端:
• Web: Svelte（響應式界面）
• Mobile: Flutter（iOS / Android 原生 App）
• Desktop: Electron（Windows / macOS）

2. 硬件與資源需求

2.1 服務器配置推薦

Immich 對資源的需求比 Vaultwarden 高得多，尤其是 AI 識別功能會消耗大量 CPU 和內存。

規模	CPU	內存	存儲	推薦用戶數
最小配置	2 核	4 GB	50 GB SSD	1 人
標準配置	4 核	8 GB	500 GB SSD	1-3 人
推薦配置	6 核以上	16 GB	1-4 TB SSD	2-5 人
家庭使用	8 核以上	32 GB	4-8 TB SSD	5-10 人

2.2 詳細說明

CPU:
• 照片上傳和處理主要靠 CPU
• AI 識別（人臉識別、CLIP）最耗 CPU
• 建議 4 核以上，越多越好
• 如開啟 GPU 加速，CPU 壓力會大幅降低

內存:
• PostgreSQL 數據庫佔用 ~512MB-2GB
• AI 微服務啟動後佔用 2-4GB
• 每個用戶會話佔用少量內存
• 推薦 8GB 起步，多用戶建議 16GB+

存儲:
• 原始照片文件：根據用戶上傳量估算
• 縮略圖和緩存：約為原始文件的 15-25%
• 數據庫：每 1 萬張照片約 100-200MB
• 經驗值：1 萬張照片約需 20-40GB 存儲
• 建議使用 SSD，小文件讀寫速度很重要

GPU（可選）:
• 支持 NVIDIA GPU 加速 AI 識別
• 需安裝 NVIDIA Container Toolkit
• 大幅提升人臉和物體識別速度
• 預算充足時推薦：RTX 3050/3060 或更高

2.3 部署地點選擇

方案一：家用服務器（推薦）
• 優點：存儲成本低、網絡免費、數據最安全
• 缺點：需要內網穿透才能在外訪問、需要公網 IP 或 DDNS
• 硬件：群暉 / 威聯通 NAS、臺式機、樹莓派 4（8GB）、小主機

方案二：VPS（雲服務器）
• 優點：部署簡單、公網 IP 穩定、無需操心硬件
• 缺點：大容量存儲成本高、數據上傳下載成本高
• 推薦：Contabo、Hetzner（大硬盤、性價比高）

方案三：混合方案
• VPS 運行 Web 和數據庫，照片存儲在本地 NAS（通過 NFS）
• 兼顧便捷性和經濟性

3. Immich 架構組件解析

Immich 由多個 Docker 容器協同工作：

immich-server（主 API 服務器）
  ↓
immich-microservices（後臺任務處理）
  ↓
immich-machine-learning（AI / ML 微服務）
  ↓
immich-postgres（主數據庫）
  ↓
immich-redis（緩存 / 任務隊列）
  ↓
immich-web（前端 Web 界面）
  ↓
immich-proxy（統一入口 / Nginx 反代，可選）
  ↓
immich-typesense（搜索引擎，用於 CLIP 語義搜索）
  ↓
immich-upload（上傳處理服務）

各組件職責：

組件	職責	資源佔用
immich-server	處理 API 請求、用戶認證、相冊管理	中 ~ 高
immich-microservices	縮略圖生成、視頻轉碼、EXIF 提取、任務隊列	高（CPU 密集）
immich-machine-learning	人臉識別、CLIP 語義搜索、物體識別	非常高（CPU/GPU 密集）
immich-postgres	主數據庫、存儲所有元數據	低 ~ 中
immich-redis	緩存、會話管理、任務隊列	極低
immich-web	Web 前端界面（靜態資源）	極低
immich-typesense	搜索引擎，支持文本搜索、向量搜索	中
immich-upload	上傳服務，處理照片/視頻上傳	低 ~ 中

4. Docker Compose 完整部署

4.1 創建項目目錄

bash

# 創建項目目錄
mkdir -p ~/immich/{app,database,upload,thumbs,profile,logs}

# 進入目錄
cd ~/immich

4.2 創建環境變量文件 .env

bash

# ~/immich/.env

# ======== 基本配置 ========
# 域名（必須是 https）
EXTERNAL_DOMAIN=https://photos.yourdomain.com

# 數據庫密碼（自行設置，務必複雜）
DB_PASSWORD=your-complex-db-password-here
DB_USERNAME=immich
DB_DATABASE_NAME=immich
DB_HOSTNAME=postgres

# Redis 配置
REDIS_HOSTNAME=redis

# ======== 上傳與存儲 ========
# 上傳文件大小限制（單位：字節）
# 建議設置為較大值，如 4GB = 4294967296
UPLOAD_LOCATION=/path/to/your/upload/storage
MAX_FILE_SIZE=4294967296

# ======== 數據庫配置 ========
# PostgreSQL 數據目錄
DB_DATA_LOCATION=/path/to/your/postgres/data

# ======== AI/ML 配置 ========
# 是否啟用機器學習（人臉識別、CLIP）
MACHINE_LEARNING_ENABLED=true

# 啟用的模型（越多功能越強，但越耗資源）
MACHINE_LEARNING_WORKERS=2

# CLIP 模型選擇（影響搜索效果）
# 可選：ViT-B-32__openai（快速）| ViT-L-14__openai（更準，更慢）
CLIP_MODEL=ViT-B-32__openai

# ======== 時區設置 ========
TZ=Asia/Shanghai

# ======== 可選配置 ========
# 啟用/禁用圖片地理信息顯示
MAP_ENABLED=true

# 地圖服務選擇（可選：maptiler | google | none）
MAP_PROVIDER=maptiler
MAP_KEY=your-maptiler-api-key-here

# 用戶註冊控制（默認允許，部署後可改為 false）
ALLOW_SIGNUP=true

# 管理員郵箱（首次啟動後可在管理面板設置）
# IMMICH_ADMIN_EMAIL=your@email.com
# IMMICH_ADMIN_PASSWORD=your-admin-password

4.3 創建 docker-compose.yml

yaml

# ~/immich/docker-compose.yml

version: "3.8"

# ======== 網絡配置 ========
networks:
  immich-network:
    name: immich-network
    driver: bridge

# ======== 數據卷（自動管理存儲位置） ========
volumes:
  pgdata:
    driver: local
  model-cache:
    driver: local

services:

  # ======== PostgreSQL 數據庫 ========
  postgres:
    image: tensorchord/pgvecto-rs:pg16-v0.3.0
    container_name: immich-postgres
    hostname: postgres
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      TZ: ${TZ}
    networks:
      - immich-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      interval: 15s
      timeout: 5s
      retries: 10

  # ======== Redis 緩存 ========
  redis:
    image: redis:7.4-alpine
    container_name: immich-redis
    hostname: redis
    restart: unless-stopped
    volumes:
      - ./redis:/data
    environment:
      TZ: ${TZ}
    networks:
      - immich-network
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 10

  # ======== Immich Server（主 API） ========
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    container_name: immich-server
    restart: unless-stopped
    volumes:
      - ./upload:/usr/src/app/upload
      - ./thumbs:/usr/src/app/thumbs
      - ./encoded-video:/usr/src/app/encoded-video
    environment:
      DB_HOSTNAME: ${DB_HOSTNAME}
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE_NAME: ${DB_DATABASE_NAME}
      REDIS_HOSTNAME: ${REDIS_HOSTNAME}
      TYPESENSE_ENABLED: true
      TZ: ${TZ}
      # === 可選：GPU 加速（需要 NVIDIA Container Toolkit） ===
      # NVIDIA_VISIBLE_DEVICES: all
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - immich-network
    ports:
      - "127.0.0.1:2283:2283"  # 僅本地監聽，通過 Nginx/Caddy 暴露
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:2283/server-info/ping"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

  # ======== Immich Microservices（後臺任務） ========
  immich-microservices:
    image: ghcr.io/immich-app/immich-microservices:release
    container_name: immich-microservices
    restart: unless-stopped
    volumes:
      - ./upload:/usr/src/app/upload
      - ./thumbs:/usr/src/app/thumbs
      - ./encoded-video:/usr/src/app/encoded-video
      - ./model-cache:/cache
    environment:
      DB_HOSTNAME: ${DB_HOSTNAME}
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE_NAME: ${DB_DATABASE_NAME}
      REDIS_HOSTNAME: ${REDIS_HOSTNAME}
      TZ: ${TZ}
      # === 可選：GPU 加速 ===
      # NVIDIA_VISIBLE_DEVICES: all
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - immich-network

  # ======== Immich Machine Learning（AI 微服務） ========
  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:release
    container_name: immich-machine-learning
    restart: unless-stopped
    volumes:
      - ./model-cache:/cache
      - ./upload:/usr/src/app/upload
    environment:
      DB_HOSTNAME: ${DB_HOSTNAME}
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE_NAME: ${DB_DATABASE_NAME}
      REDIS_HOSTNAME: ${REDIS_HOSTNAME}
      TZ: ${TZ}
      # === 資源限制（防止 AI 服務佔用過多資源） ===
      MACHINE_LEARNING_WORKERS: ${MACHINE_LEARNING_WORKERS}
      # === 可選：GPU 加速 ===
      # NVIDIA_VISIBLE_DEVICES: all
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - immich-network
    # === CPU 資源限制（根據你的服務器調整） ===
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G

  # ======== Typesense（搜索引擎） ========
  typesense:
    image: typesense/typesense:27.0.rc1
    container_name: immich-typesense
    restart: unless-stopped
    volumes:
      - ./typesense:/data
    environment:
      TYPESENSE_API_KEY: ${TYPESENSE_API_KEY:-your-typesense-api-key}
      TYPESENSE_DATA_DIR: /data
      TZ: ${TZ}
    command: ["--enable-cors"]
    networks:
      - immich-network
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8108/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

  # ======== Immich Web（前端界面） ========
  immich-web:
    image: ghcr.io/immich-app/immich-web:release
    container_name: immich-web
    restart: unless-stopped
    environment:
      TZ: ${TZ}
    networks:
      - immich-network
    ports:
      - "127.0.0.1:3000:3000"  # 僅本地監聽
    depends_on:
      - immich-server

📌 說明：
以上是簡化版本配置，官方推薦使用官方的 docker-compose.yml
官方最新版本會不斷更新組件和鏡像名稱
建議參考官方文檔獲取最新配置：https://immich.app/docs/install/docker-compose

4.4 使用官方推薦的最簡配置

官方提供了一個更簡潔、更易維護的配置（推薦初學者使用）：

bash

# 從官方獲取最新的配置文件
cd ~/immich
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

# 編輯 .env 文件，修改以下內容：
# 1. EXTERNAL_DOMAIN=https://photos.yourdomain.com
# 2. DB_PASSWORD=你的數據庫密碼
# 3. UPLOAD_LOCATION=./upload
# 4. TZ=Asia/Shanghai
nano .env

4.5 啟動 Immich

bash

# 創建必要目錄
mkdir -p ~/immich/upload
mkdir -p ~/immich/postgres
mkdir -p ~/immich/model-cache
mkdir -p ~/immich/thumbs
mkdir -p ~/immich/encoded-video

# 啟動服務（首次會拉取所有鏡像，較慢）
cd ~/immich
docker compose up -d

# 查看容器狀態
docker compose ps

# 查看所有容器日誌（前 50 行，瞭解啟動情況）
docker compose logs --tail=50

# 查看特定容器日誌（查看主服務器）
docker compose logs -f immich-server

# 等待所有容器狀態變為 healthy
# 首次啟動可能需要 3-5 分鐘（模型文件需要下載）

4.6 驗證本地訪問

bash

# 測試 Web 界面是否響應
curl -I http://127.0.0.1:3000

# 測試 API 是否響應
curl -I http://127.0.0.1:2283

# 正常輸出應該是 HTTP/1.1 200 OK

5. Nginx / Caddy 反向代理配置

5.1 方案一：Caddy（推薦，自動 HTTPS）

caddyfile

# /etc/caddy/Caddyfile（或 ~/immich/Caddyfile）

photos.yourdomain.com {
    # 主 Web 界面反代到 immich-web
    reverse_proxy 127.0.0.1:3000

    # API 請求反代到 immich-server
    # /api/* / /auth/* / /oauth/* / /user/* / /mobile/* / /share/*
    @api_paths {
        path /api/* /auth/* /oauth/* /user/* /mobile/* /share/*
    }
    reverse_proxy @api_paths 127.0.0.1:2283

    # 大文件上傳超時設置
    reverse_proxy {
        to 127.0.0.1:3000
        transport http {
            read_timeout 300s
            write_timeout 300s
        }
    }

    # 文件上傳大小限制（10GB）
    request_body {
        max_size 10GB
    }

    # 安全頭
    header Strict-Transport-Security "max-age=31536000; includeSubDomains"
    header X-Content-Type-Options nosniff

    # Gzip 壓縮
    encode gzip

    # 日誌
    log
}

5.2 方案二：Nginx + Certbot

nginx

# /etc/nginx/sites-available/immich

server {
    # HTTP 跳轉到 HTTPS
    listen 80;
    listen [::]:80;
    server_name photos.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    # HTTPS 配置
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name photos.yourdomain.com;

    # SSL 證書（Certbot 自動配置）
    ssl_certificate /etc/letsencrypt/live/photos.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/photos.yourdomain.com/privkey.pem;

    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # 大文件上傳支持
    client_max_body_size 10G;
    client_body_timeout 300s;
    proxy_connect_timeout 300;
    proxy_send_timeout 300;
    proxy_read_timeout 300;

    # Gzip 壓縮
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;
    gzip_min_length 1024;

    # 日誌
    access_log /var/log/nginx/immich_access.log;
    error_log /var/log/nginx/immich_error.log;

    # 主應用反代
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }

    # API 和認證路徑反代到 API 服務器
    location /api/ {
        proxy_pass http://127.0.0.1:2283;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }

    location /auth/ {
        proxy_pass http://127.0.0.1:2283;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }

    location /oauth/ {
        proxy_pass http://127.0.0.1:2283;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }

    # WebSocket 支持（實時通知）
    location /socket.io/ {
        proxy_pass http://127.0.0.1:2283;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 安全頭
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options SAMEORIGIN;
}

bash

# 啟用 Nginx 配置
sudo ln -s /etc/nginx/sites-available/immich /etc/nginx/sites-enabled/

# 申請證書（如果還沒有）
sudo certbot --nginx -d photos.yourdomain.com --email your@email.com

# 測試配置
sudo nginx -t

# 重啟 Nginx
sudo systemctl restart nginx

6. 初始化設置與管理員賬號

6.1 首次訪問 Web 界面

部署完成後，在瀏覽器中訪問：

https://photos.yourdomain.com

你會看到 Immich 歡迎界面。

6.2 創建管理員賬號

1. 點擊「註冊」或「Sign up」
2. 輸入郵箱和密碼
3. 點擊「創建賬號」
4. 登錄後進入主界面
5. 第一個註冊的用戶會自動成為管理員

⚠️ 部署完成後，建議先創建自己的賬號，然後關閉註冊功能：
   管理面板 → 設置 → 服務器設置 → 關閉「Allow signup」

6.3 管理面板

訪問：https://photos.yourdomain.com/admin
或點擊右上角頭像 → 「管理」/「Administration」

在管理面板中可以：
• 查看和管理所有用戶
• 設置用戶配額（存儲配額）
• 禁用 / 刪除用戶
• 查看系統狀態
• 修改服務器設置（註冊、上傳限制等）
• 查看存儲使用統計
• 管理後臺任務和作業

7. 手機端 App 安裝與自動備份

7.1 下載 App

iOS（iPhone / iPad）：
  App Store → 搜索 "Immich" → 下載安裝

Android：
  Google Play → 搜索 "Immich" → 下載安裝
  或 F-Droid（開源商店）搜索下載

iOS 快捷方式（官方推薦）：
  App Store → 搜索 "Immich Mobile App"

7.2 App 配置連接自建服務器

1. 打開 Immich App
2. 首次打開會提示輸入服務器地址：
   https://photos.yourdomain.com
3. 輸入郵箱和密碼登錄
4. 授予照片訪問權限（iOS 需在系統設置中授權）
5. 授予位置訪問權限（可選，用於上傳 GPS 信息）
6. 完成配置！

7.3 配置自動備份

在 App 中設置：
1. 點擊「設置」或「Settings」
2. 選擇「備份」或「Backup」
3. 開啟「自動備份」
4. 選擇要備份的相冊：
   • 相機膠捲（Camera Roll）
   • 所有相冊
   • 指定相冊
5. 選擇備份條件：
   • 僅 Wi-Fi（推薦，節省流量）
   • Wi-Fi 和移動數據
   • 電量充足時（僅當電量 > 20%）
6. 選擇是否備份視頻
7. 選擇是否刪除已備份的本地照片（謹慎選擇）
8. 啟動首次備份

💡 提示：首次備份如果照片較多（數千張），可能需要較長時間
   建議在 Wi-Fi 環境、充電狀態下啟動

7.4 後臺自動上傳

iOS 特性：
• iOS 由於系統限制，後臺上傳時間有限（約 10-30 分鐘）
• 建議每天打開一次 App 以觸發後臺備份
• 可使用「快捷指令」自動化（如充電時自動打開 Immich）

Android 特性：
• Android 後臺限制相對寬鬆
• 可以設置 App 始終在後臺運行
• 支持充電時自動備份、夜間自動備份

通用建議：
• 首次備份完成後，後續增量備份很快（只需上傳新照片）
• 建議每天至少打開 App 一次確保觸發備份
• 在充電時打開 App 可加速備份過程

8. AI 智能識別與人臉識別配置

8.1 啟用 AI 功能

AI 功能默認在標準配置中啟用，但需要以下條件：

1. immich-machine-learning 容器運行正常
2. 模型文件已下載（首次啟動會自動下載）
3. 服務器有足夠 CPU / 內存資源

驗證 AI 服務：
管理面板 → 系統狀態 → 檢查 Machine Learning 狀態

8.2 人臉識別

功能說明：
• 上傳照片後，系統會自動檢測照片中的人臉
• 相同人物的照片會被歸為一組
• 用戶可以為人物命名、合併/拆分人物

首次使用：
1. 等待系統處理所有照片（可能需要幾個小時）
2. 在 Web 界面點擊「人物」或「People」查看識別結果
3. 為每個識別到的人物命名（如「爸爸」「媽媽」「孩子」）
4. 系統會持續學習，識別效果越來越好

手動觸發處理：
如果某些照片未被自動處理，可以在管理面板手動觸發：
管理面板 → 作業 → 運行「人臉檢測」或「CLIP 編碼」

8.3 CLIP 語義搜索

CLIP（Contrastive Language-Image Pre-training）是 Immich 的核心 AI 功能之一：
它讓你能用「文字描述」來搜索圖片，而不需要依賴標籤和文件名。

示例搜索：
• "日落" → 返回所有日落照片
• "海灘" → 返回海灘場景
• "狗" → 返回有狗的照片
• "生日蛋糕" → 返回生日聚會照片
• "全家福" → 返回多人合照
• "冬天" → 返回雪景/冬裝照片

使用方法：
Web 界面頂部搜索框 → 輸入文字描述 → 系統智能匹配

⚠️ 首次搜索可能需要等待 CLIP 模型處理所有照片（幾小時到幾天）
   取決於你的服務器性能和照片數量

8.4 智能相冊（Smart Albums）

基於條件自動創建相冊：
1. 點擊「相冊」→「創建智能相冊」
2. 設置篩選條件：
   • 拍攝日期範圍（如「2024 年之後」）
   • 拍攝地點（如「北京」）
   • 特定人物（如「寶寶」）
   • 特定標籤（如「美食」）
   • 相機型號
   • 文件大小
3. 命名相冊
4. 系統會自動將符合條件的照片加入相冊
5. 新上傳的符合條件的照片會自動加入

8.5 地圖視圖

Immich 會讀取照片的 EXIF GPS 信息，在地圖上展示照片：

1. 點擊左側菜單「地圖」或「Map」
2. 可以看到所有帶 GPS 信息的照片
3. 支持縮放、拖動、按時間篩選
4. 支持熱力圖模式（展示拍攝熱點）

⚠️ 如果照片沒有 GPS 信息，不會顯示在地圖上
   在手機相機設置中啟用「保存位置信息」
   或使用後期處理工具添加 GPS 信息

9. 相冊管理、共享與協作

9.1 創建相冊

1. 登錄 Web 界面
2. 點擊左側「相冊」
3. 點擊「創建相冊」
4. 選擇照片（可多選、批量選擇）
5. 為相冊命名（如「2025 年春節」「孩子成長」）
6. 可選：設置共享、設置封面
7. 完成創建

9.2 收藏夾

• 點擊照片右上角的「❤」可收藏
• 收藏的照片出現在「收藏夾」中
• 常用於快速標記珍貴照片

9.3 共享相冊

創建共享鏈接：
1. 在相冊頁面點擊「共享」
2. 選擇「創建共享鏈接」
3. 可選設置：
   • 是否允許他人上傳（協作模式）
   • 是否允許下載
   • 是否顯示 EXIF 信息
   • 密碼保護（可選）
   • 有效期（可選）
4. 複製鏈接發送給家人/朋友

多人共享（家庭模式）：
1. 管理面板 → 用戶 → 邀請家庭成員註冊
2. 每個成員有自己的獨立空間
3. 可以創建「共享相冊」（所有成員可查看/上傳）
4. 管理員可設置每個用戶的存儲配額

9.4 從其他平臺遷移

從 Google Photos 遷移：
1. 訪問 Google Takeout: https://takeout.google.com
2. 選擇 Google Photos，導出為 zip 文件
3. 下載導出文件到本地電腦
4. 使用 Immich CLI 工具上傳：
   npm install -g @immich/cli
   immich login https://photos.yourdomain.com <你的API Key>
   immich upload --recursive /path/to/takeout/photos

從 iCloud 遷移：
1. Mac 電腦：照片 App → 文件 → 導出 → 導出原片
2. 將導出的照片上傳到 Immich
3. iOS 設備：直接用 Immich App 備份所有相冊

從百度網盤/OneDrive/其他雲存儲：
1. 下載所有照片到本地
2. 使用 Immich CLI 或 Web 界面批量上傳

10. 數據備份與恢復策略

10.1 需要備份的內容

📁 ~/immich/upload/          → 原始照片和視頻（核心！）
📁 ~/immich/postgres/        → PostgreSQL 數據庫（核心！）
📁 ~/immich/model-cache/     → ML 模型緩存（可重下載，可選）
📁 ~/immich/thumbs/          → 縮略圖（可重新生成，可選）
📁 ~/immich/encoded-video/   → 轉碼後的視頻（可重新生成，可選）

10.2 備份方案一：手動備份（簡單）

bash

# 1. 停止 Immich（防止數據庫寫入衝突）
cd ~/immich
docker compose down

# 2. 創建備份（帶時間戳）
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=~/backups/immich_$BACKUP_DATE
mkdir -p $BACKUP_DIR

# 3. 壓縮核心數據
cd ~/immich
sudo tar -czf $BACKUP_DIR/upload.tar.gz ./upload/
sudo tar -czf $BACKUP_DIR/postgres.tar.gz ./postgres/
sudo cp .env $BACKUP_DIR/.env
sudo cp docker-compose.yml $BACKUP_DIR/docker-compose.yml

# 4. 重啟 Immich
docker compose up -d

# 5. 查看備份
ls -lh $BACKUP_DIR/

10.3 備份方案二：自動備份腳本

創建自動備份腳本：

bash

# ~/immich/backup.sh

#!/bin/bash
# Immich 自動備份腳本

BACKUP_DIR="/home/yourusername/backups"
IMMICH_DIR="/home/yourusername/immich"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_NAME="immich_$DATE"
RETENTION_DAYS=14

# 創建備份目錄
mkdir -p $BACKUP_DIR/$BACKUP_NAME

# 停止 Immich
cd $IMMICH_DIR
docker compose down

# 備份核心數據
cd $IMMICH_DIR
tar -czf $BACKUP_DIR/$BACKUP_NAME/upload.tar.gz ./upload/
tar -czf $BACKUP_DIR/$BACKUP_NAME/postgres.tar.gz ./postgres/

# 備份配置文件
cp .env $BACKUP_DIR/$BACKUP_NAME/
cp docker-compose.yml $BACKUP_DIR/$BACKUP_NAME/

# 重啟 Immich
docker compose up -d

# 刪除 14 天前的舊備份
find $BACKUP_DIR -name "immich_*" -type d -mtime +$RETENTION_DAYS -exec rm -rf {} \;

# 日誌
echo "[$DATE] 備份完成: $BACKUP_NAME" >> $BACKUP_DIR/backup.log

bash

# 設置可執行權限
chmod +x ~/immich/backup.sh

# 測試運行
cd ~/immich
./backup.sh

10.4 設置定時任務

bash

# 編輯 crontab
crontab -e

# 添加（每週日凌晨 3 點備份）
0 3 * * 0 /home/yourusername/immich/backup.sh

# 保存退出
# 查看當前任務
crontab -l

10.5 數據恢復

bash

# 1. 停止當前 Immich
cd ~/immich
docker compose down

# 2. 備份當前數據（以防恢復失敗）
mv ./upload ./upload_backup_$(date +%Y%m%d)
mv ./postgres ./postgres_backup_$(date +%Y%m%d)

# 3. 從備份恢復
BACKUP_FILE="/path/to/backups/immich_20260612_030000"
tar -xzf $BACKUP_FILE/upload.tar.gz
tar -xzf $BACKUP_FILE/postgres.tar.gz

# 4. 重啟 Immich
docker compose up -d

# 5. 檢查數據是否恢復
# 等待容器啟動後，訪問 Web 界面，檢查照片是否可用
# 首次恢復後，縮略圖可能需要重新生成（需要時間）

11. 性能優化與資源調整

11.1 根據硬件調整配置

低配服務器（2 核 4GB）：
• MACHINE_LEARNING_WORKERS=1
• 關閉視頻轉碼（如視頻上傳量不大）
• CLIP_MODEL=ViT-B-32__openai（最快的模型）

標準服務器（4 核 8GB）：
• MACHINE_LEARNING_WORKERS=2
• 開啟視頻轉碼（但限制併發）
• CLIP_MODEL=ViT-B-32__openai

高配服務器（8 核 32GB+）：
• MACHINE_LEARNING_WORKERS=4
• 開啟所有 AI 功能
• CLIP_MODEL=ViT-L-14__openai（最準確的模型）
• 考慮添加 GPU 加速

11.2 視頻轉碼優化

視頻轉碼是 Immich 中最耗時的操作之一：

優化方法：
1. 在手機端預先壓縮（部分 Android 手機可設置）
2. 在 App 設置中調整「視頻上傳質量」
3. 在服務器端啟用硬件加速（VA-API / NVENC）

啟用 NVENC（NVIDIA GPU 加速）：
在 docker-compose.yml 中為 immich-microservices 添加：
environment:
  NVIDIA_VISIBLE_DEVICES: all
runtime: nvidia

需要先在服務器上安裝 NVIDIA Container Toolkit

11.3 存儲擴展

方法一：移動到更大的磁盤
1. 停止 Immich
2. 將 upload 目錄複製到新位置
3. 修改 .env 中的 UPLOAD_LOCATION
4. 重啟 Immich

方法二：使用網絡存儲（NFS）
1. 掛載 NFS 共享到本地目錄
2. 將 UPLOAD_LOCATION 指向該目錄
3. 注意：NFS 會影響上傳速度，建議局域網內使用

方法三：使用對象存儲（S3）
Immich 支持 S3 兼容存儲（MinIO、AWS S3）
適合大容量、高可用的部署場景

11.4 定期清理

清理臨時文件和緩存：
docker system prune -af
docker volume prune -f

清理日誌：
docker compose logs immich-server --tail=1000 > logs-$(date +%Y%m%d).txt
docker compose logs immich-server --tail=100  # 只保留最近 100 行

12. 常見問題與故障排查

12.1 啟動失敗 / 容器無法啟動

排查步驟：
1. 查看容器日誌：docker compose logs
2. 檢查數據庫密碼是否正確（.env 中的 DB_PASSWORD）
3. 檢查磁盤空間：df -h
4. 檢查權限問題：目錄讀寫權限
5. 檢查 Docker 網絡：docker network ls

常見原因：
• PostgreSQL 數據庫損壞（斷電、強制關機導致）
• 磁盤空間不足
• 目錄權限錯誤（使用 sudo 創建的目錄可能屬主為 root）
• 端口被佔用（2283、3000、5432 等）

12.2 AI 識別不工作

排查步驟：
1. 檢查 immich-machine-learning 容器是否在運行：
   docker compose ps | grep machine-learning
2. 查看容器日誌：
   docker compose logs -f immich-machine-learning
3. 常見錯誤：
   • 模型下載失敗（網絡問題）→ 手動下載模型文件到 model-cache 目錄
   • 內存不足 → 增加服務器內存或減少 workers
   • CPU 資源不足 → 升級服務器或增加 worker 數量

手動觸發 AI 處理：
管理面板 → 作業 → 運行「人臉檢測」「CLIP 編碼」

12.3 照片上傳失敗

排查步驟：
1. 檢查文件大小是否超過限制（默認最大 4GB）
2. 檢查反向代理中的 client_max_body_size 配置
3. 檢查磁盤空間是否充足
4. 檢查容器日誌查看具體錯誤
5. 檢查上傳目錄權限：ls -la ~/immich/upload/

常見原因：
• 反向代理限制了文件大小 → 修改 Nginx/Caddy 配置
• 磁盤滿 → df -h 檢查
• 單個視頻文件過大 → 壓縮後上傳
• 上傳目錄權限錯誤 → chown -R 你的用戶:你的用戶 ~/immich/upload

12.4 人臉識別人物混亂

問題表現：
• 同一個人被識別為多個不同的人物
• 多個人物被識別為同一個人

解決方法：
1. 在 Web 界面手動合併/拆分人物
2. 系統會根據你的操作持續學習
3. 照片越多，識別效果越好
4. 可在管理面板觸發「重新檢測人臉」作業

12.5 手機 App 無法連接

排查步驟：
1. 檢查服務器是否可以從手機訪問（瀏覽器訪問 https://photos.yourdomain.com）
2. 檢查域名證書是否有效（不要使用自簽名證書）
3. 檢查是否在同一 Wi-Fi 網絡下的局域網問題
4. 檢查是否有 DNS 解析問題
5. 在 App 中點擊「測試連接」

常見原因：
• 手機網絡無法訪問服務器（服務器僅在局域網部署）
• SSL 證書問題 → 使用 Let's Encrypt 等受信任證書
• 域名解析錯誤 → 檢查 DNS 設置
• 防火牆阻止了 443 端口 → 開放端口

12.6 照片無法在地圖上顯示

排查步驟：
1. 檢查照片是否有 GPS EXIF 信息（右鍵屬性查看）
2. 確認 Immich 已啟用地圖功能
3. 檢查地圖服務 API Key 是否正確（Maptiler）
4. 檢查手機相機是否開啟 GPS 保存

解決方法：
• 無 GPS 的照片：使用 ExifTool 手動添加 GPS 信息
• 使用手機 App：在照片查看器中手動設置地理位置
• 批量處理：使用 GPS 工具軟件（如 GeoSetter）為照片添加 GPS 信息

總結

恭喜！你現在擁有了一個完全由自己掌控的私有照片管理系統：

✅ 手機自動備份：所有照片自動上傳到服務器
✅ AI 智能識別：人臉識別、場景識別、CLIP 語義搜索
✅ 地圖視圖：在地圖上查看照片拍攝地點
✅ 完全隱私：照片數據完全在你的服務器上
✅ 零訂閱費：除了服務器成本，無任何額外費用
✅ 家庭共享：多人共用，可設置存儲配額
✅ Web 訪問：隨時隨地通過瀏覽器查看照片

Immich 是一個非常活躍的開源項目，每週都會有功能更新和改進。作為自部署用戶，建議：

📌 每月執行一次：
• 檢查 Immich 更新：docker compose pull && docker compose up -d
• 驗證數據備份是否正常
• 查看磁盤空間

📌 每季度執行一次：
• 查看 Immich 發行說明（Release Notes）
• 測試恢復最近的備份（驗證備份有效性）
• 檢查服務器資源使用情況：CPU、內存、磁盤

📌 每年執行一次：
• 評估是否需要升級服務器硬件（存儲空間、CPU、內存）
• 全面檢查系統健康狀態

📖 延伸閱讀：
Docker 安裝與基礎教程
Docker Compose 實戰教程
Nginx 反向代理與 HTTPS 配置
數據安全與隱私保護實踐
家庭 NAS 與私有云部署指南

延伸阅读

免责声明

本文仅供技术交流和学习参考。涉及第三方服务的链接可能包含 sponsored 标记，请自行核实服务条款、价格和可用性，并遵守当地法律法规。

Docker 部署 Immich：自建 Google Photos 替代方案，私有相冊全流程教程（2026版） ​

目錄 ​

1. Immich 是什麼？核心功能一覽 ​

1.1 核心功能矩陣 ​

1.2 與 Google Photos 功能對比 ​

1.3 Immich 的核心技術棧 ​

2. 硬件與資源需求 ​

2.1 服務器配置推薦 ​

2.2 詳細說明 ​

2.3 部署地點選擇 ​

3. Immich 架構組件解析 ​

4. Docker Compose 完整部署 ​

4.1 創建項目目錄 ​

4.2 創建環境變量文件 .env ​

4.3 創建 docker-compose.yml ​

4.4 使用官方推薦的最簡配置 ​

4.5 啟動 Immich ​

4.6 驗證本地訪問 ​

5. Nginx / Caddy 反向代理配置 ​

5.1 方案一：Caddy（推薦，自動 HTTPS） ​

5.2 方案二：Nginx + Certbot ​

6. 初始化設置與管理員賬號 ​

6.1 首次訪問 Web 界面 ​

6.2 創建管理員賬號 ​

6.3 管理面板 ​

7. 手機端 App 安裝與自動備份 ​

7.1 下載 App ​

7.2 App 配置連接自建服務器 ​

7.3 配置自動備份 ​

7.4 後臺自動上傳 ​

8. AI 智能識別與人臉識別配置 ​

8.1 啟用 AI 功能 ​

8.2 人臉識別 ​

8.3 CLIP 語義搜索 ​

8.4 智能相冊（Smart Albums） ​

8.5 地圖視圖 ​

9. 相冊管理、共享與協作 ​

9.1 創建相冊 ​

9.2 收藏夾 ​

9.3 共享相冊 ​

9.4 從其他平臺遷移 ​

10. 數據備份與恢復策略 ​

10.1 需要備份的內容 ​

10.2 備份方案一：手動備份（簡單） ​

10.3 備份方案二：自動備份腳本 ​

10.4 設置定時任務 ​

10.5 數據恢復 ​

11. 性能優化與資源調整 ​

11.1 根據硬件調整配置 ​

11.2 視頻轉碼優化 ​

11.3 存儲擴展 ​

11.4 定期清理 ​

12. 常見問題與故障排查 ​

12.1 啟動失敗 / 容器無法啟動 ​

12.2 AI 識別不工作 ​

12.3 照片上傳失敗 ​

12.4 人臉識別人物混亂 ​

12.5 手機 App 無法連接 ​

12.6 照片無法在地圖上顯示 ​

總結 ​

延伸阅读 ​

Docker 部署 Immich：自建 Google Photos 替代方案，私有相冊全流程教程（2026版）

目錄

1. Immich 是什麼？核心功能一覽

1.1 核心功能矩陣

1.2 與 Google Photos 功能對比

1.3 Immich 的核心技術棧

2. 硬件與資源需求

2.1 服務器配置推薦

2.2 詳細說明

2.3 部署地點選擇

3. Immich 架構組件解析

4. Docker Compose 完整部署

4.1 創建項目目錄

4.2 創建環境變量文件 .env

4.3 創建 docker-compose.yml

4.4 使用官方推薦的最簡配置

4.5 啟動 Immich

4.6 驗證本地訪問

5. Nginx / Caddy 反向代理配置

5.1 方案一：Caddy（推薦，自動 HTTPS）

5.2 方案二：Nginx + Certbot

6. 初始化設置與管理員賬號

6.1 首次訪問 Web 界面

6.2 創建管理員賬號

6.3 管理面板

7. 手機端 App 安裝與自動備份

7.1 下載 App

7.2 App 配置連接自建服務器

7.3 配置自動備份

7.4 後臺自動上傳

8. AI 智能識別與人臉識別配置

8.1 啟用 AI 功能

8.2 人臉識別

8.3 CLIP 語義搜索

8.4 智能相冊（Smart Albums）

8.5 地圖視圖

9. 相冊管理、共享與協作

9.1 創建相冊

9.2 收藏夾

9.3 共享相冊

9.4 從其他平臺遷移

10. 數據備份與恢復策略

10.1 需要備份的內容

10.2 備份方案一：手動備份（簡單）

10.3 備份方案二：自動備份腳本

10.4 設置定時任務

10.5 數據恢復

11. 性能優化與資源調整

11.1 根據硬件調整配置

11.2 視頻轉碼優化

11.3 存儲擴展

11.4 定期清理

12. 常見問題與故障排查

12.1 啟動失敗 / 容器無法啟動

12.2 AI 識別不工作

12.3 照片上傳失敗

12.4 人臉識別人物混亂

12.5 手機 App 無法連接

12.6 照片無法在地圖上顯示

總結

延伸阅读