🖼️ Immich 相册程序完全指南 / 百科 / Yicool 易酷

📐 系统架构设计

架构概述 — 整体设计理念

Immich 采用容器化、微服务架构的设计理念，是一个典型的客户端-服务端（Client-Server）模型，并配备了专用数据库用于数据持久化。

┌─────────────────────────────────────────────────────────┐ │ 客户端层 (Clients) │ ├──────────────┬──────────────┬────────────────────────────┤ │ 📱 Mobile │ 🌐 Web │ 💻 CLI │ │ (Flutter) │ (SvelteKit) │ (npm) │ └──────────────┴──────────────┴────────────────────────────┘ │ REST API ▼ ┌─────────────────────────────────────────────────────────┐ │ 服务端层 (Server) │ ├─────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌──────────────┐ │ │ │ immich- │ │ immich- │ │ │ │ server │◄──►│ machine- │ │ │ │ (NestJS) │ │ learning │ │ │ │ (API + Jobs)│ │ (FastAPI) │ │ │ └─────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │ PostgreSQL │ │ Redis │ │ 文件系统 (Storage) │ │ (数据库) │ │ (消息队列) │ │ (照片/视频存储) │ └───────────────┘ └──────────────┘ └──────────────────┘

核心设计原则

关注点分离：每个服务承担单一职责
六边形架构：将技术实现与核心业务逻辑分离
水平可扩展：各服务可独立扩展实例
完全自托管：所有数据和计算都在用户自己的设备上

💡 设计亮点：

服务端被拆分为两个独立容器 —

immich-server

负责 API 请求，

immich-microservices

负责处理来自 Redis 的后台任务请求。

客户端架构详解

Immich 提供三种客户端接入方式，全部使用 OpenAPI 自动生成 REST 客户端以确保一致性。

1. 移动端应用 (Mobile App)

Flutter

Dart

Android

iOS

框架：Flutter (Dart 语言)
本地数据库：Isar Database（高性能本地存储）
状态管理：Riverpod (基于 Provider 的响应式状态管理)
数据类：分为 Entities（持久化到设备数据库）和 Models（仅存在于内存中的临时数据）
Repositories 层：唯一可以使用 OpenAPI DTO 等外部数据类的地方

2. Web 应用

SvelteKit

TypeScript

TailwindCSS

框架：SvelteKit（基于 Svelte 的全栈框架）
语言：TypeScript
样式：TailwindCSS 实现响应式 UI
特性：SSR + 客户端渲染，首屏加载快

3. CLI 工具

Node.js

npm

包管理：npm 全局安装
用途：批量上传资源、命令行管理
优势：适合脚本化操作和自动化

服务端架构详解

immich-server (主服务)

属性	详情
语言	TypeScript
运行时	Node.js
框架	NestJS + Express
查询构建器	Kysely
架构模式	六边形架构（Hexagonal Architecture）

职责分工

接收并响应所有 REST API 请求
验证用户身份与授权
调度后台任务到 Redis 队列
执行定时任务（Cron Jobs）

immich-microservices (微服务)

专门处理来自 Redis 的后台任务请求
不直接处理 API 请求
负责任务密集型的处理工作

immich-machine-learning (机器学习服务)

属性	详情
语言	Python
框架	FastAPI
语义搜索模型	CLIP（用于向量嵌入）
人脸识别模型	buffalo_l（InsightFace）
聚类算法	DBScan

⚡ 性能优化：

机器学习服务作为独立容器运行，可以部署在不同的物理机器上，也可以根据需要完全禁用。支持硬件加速器（GPU）提升推理速度。

数据层设计 — 数据库与消息队列

PostgreSQL 数据库

Immich 使用 PostgreSQL 作为核心数据存储引擎：

用户数据：账户信息、认证令牌、权限设置
资源元数据：照片/视频的文件信息、EXIF 数据、标签
相册管理：相册创建、资源关联、共享设置
向量嵌入：通过 pgvector 扩展存储 ML 生成的向量数据，支持语义搜索

🔍 语义搜索原理：

CLIP 模型将图片转换为高维向量，存储在 PostgreSQL 的 pgvector 字段中。用户搜索时，文本同样被编码为向量，然后通过向量相似度搜索找到匹配的图片。

Redis 消息队列

使用 BullMQ（基于 Redis 的队列管理工具）处理后台任务：

任务调度：将耗时操作异步化，保持 API 响应性
任务链：某些任务完成后自动触发后续任务（如缩略图生成 → 语义搜索）
重试机制：失败任务自动重试，确保数据一致性

后台任务类型

🖼️ 缩略图生成

为每张照片生成多种尺寸的预览图

📋 元数据提取

提取 EXIF、GPS、拍摄时间等信息

🎬 视频转码

视频格式标准化和预览生成

🧠 智能搜索

生成 CLIP 向量嵌入

👤 人脸识别

检测并聚类人脸信息

📁 存储迁移

文件模板迁移和清理

🔧 核心技术栈

后端技术栈详细说明

技术	用途	说明
NestJS	后端框架	企业级 Node.js 框架，提供模块化架构
TypeScript	开发语言	类型安全的 JavaScript 超集
Express	HTTP 服务器	轻量级 Web 框架
FastAPI	ML 服务 API	高性能 Python Web 框架
CLIP	语义搜索	OpenAI 的多模态模型
InsightFace	人脸识别	buffalo_l 模型用于人脸检测和识别
PostgreSQL	主数据库	支持 pgvector 向量搜索
Redis	任务队列	通过 BullMQ 管理异步任务
Docker	容器化	统一部署环境

前端技术栈详细说明

Web 应用

SvelteKit — 基于 Svelte 的全栈框架，编译时优化，体积小、速度快
TypeScript — 类型安全，提高代码质量
TailwindCSS — 原子化 CSS，快速构建响应式 UI
OpenAPI Client — 自动生成的 REST 客户端，确保 API 一致性

移动应用

Flutter — Google 的跨平台 UI 框架，一套代码运行 Android 和 iOS
Dart — Flutter 的编程语言
Isar Database — 高性能的本地 NoSQL 数据库
Riverpod — 声明式状态管理库

CLI 工具

Node.js — npm 全局包，跨平台命令行工具
支持批量上传、资源管理、自动化脚本

Docker 容器编排设计

Immich 使用 Docker Compose 进行服务编排，以下为默认容器配置：

🖥️ immich-server

主 API 服务容器

Node.js + NestJS

🤖 immich-machine-learning

ML 推理服务

Python + FastAPI

🗄️ immich-postgres

数据库服务

PostgreSQL + pgvector

📨 immich-redis

消息队列服务

Redis 7.x

容器间通信

所有容器通过 Docker 内部网络进行通信
服务发现基于容器名称（Docker DNS）
外部仅暴露 immich-server 的 HTTP 端口
PostgreSQL 和 Redis 不对外暴露端口（安全设计）

数据持久化

upload/ — 照片和视频文件存储
library/ — 外部库挂载
PostgreSQL data — 数据库持久卷
Redis data — 队列持久化（可选）

🚀 部署教程

系统要求与准备工作

最低硬件要求

资源	最低要求	推荐配置
CPU	2 核	4 核及以上
内存	4 GB	8 GB 及以上
存储空间	50 GB	根据照片量扩展
操作系统	Linux / macOS / Windows	Ubuntu 22.04 LTS

⚠️ 注意：

机器学习功能（语义搜索、人脸识别）会消耗额外的 CPU/GPU 资源。如果使用 GPU 加速，建议至少配备 NVIDIA GPU + 8GB 显存。

软件依赖

Docker 20.10+（或 Docker Desktop）
Docker Compose v2.0+
Git（用于获取配置文件）

安装 Docker（Ubuntu 示例）

# 更新包索引
sudo apt-get update

# 安装依赖
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list

# 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 验证安装
docker --version
docker compose version

使用 Docker Compose 部署（完整步骤）

步骤 1：创建项目目录

# 创建并进入项目目录
mkdir -p ~/immich && cd ~/immich

# 下载 docker-compose 文件和环境变量文件
wget 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 -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml

步骤 2：编辑环境变量

编辑 .env 文件，配置关键参数：

# .env 文件关键配置

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

# 上传存储路径
UPLOAD_LOCATION=./library

# 端口映射（默认 2283）
IMMICH_PORT=2283

# 时区设置
TZ=Asia/Shanghai

步骤 3：创建存储目录

# 创建照片存储目录
mkdir -p ./library

# 设置正确的权限
sudo chown -R 1000:1000 ./library

步骤 4：启动服务

# 拉取镜像并启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

✅ 部署完成！

打开浏览器访问

http://你的服务器IP:2283

即可进入 Immich Web 界面，首次访问需要创建管理员账户。

步骤 5：常用管理命令

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 更新到最新版本
docker compose pull
docker compose up -d

# 查看资源占用
docker stats

# 备份数据库
docker exec -t immich_postgres pg_dump -U postgres immich > backup_$(date +%Y%m%d).sql

NAS 系统部署（群晖/威联通/Unraid）

群晖 NAS (Synology) 部署

群晖 NAS 可以通过 Docker 套件或 Docker Compose 部署 Immich：

方法一：使用 Docker 套件（DSM 7+）

在套件中心安装 Container Manager（原 Docker 套件）
通过 SSH 登录 NAS，执行 Docker Compose 命令
确保存储空间映射正确（建议使用 Volume 挂载）

方法二：使用 Portainer 可视化部署

# 通过 Portainer 添加 Stack
# 粘贴 docker-compose.yml 内容
# 配置环境变量和卷映射
# 点击 Deploy

💡 群晖小贴士：

如果 NAS 性能不足，可以将机器学习服务部署在另一台性能更强的机器上，通过网络连接共享。

Unraid 部署

Unraid 用户可以通过 Community Applications (CA) 或自定义 Docker 模板安装：

在 CA 中搜索 "immich"
安装推荐版本
配置共享文件夹作为存储路径
确保分配足够的内存（建议 8GB+）

TrueNAS Scale 部署

TrueNAS Scale 支持通过 Apps 界面一键安装：

进入 Apps → Discover Apps
搜索 "Immich"
配置存储池和路径
应用配置，等待安装完成

GPU 加速配置（硬件转码 & ML推理）

NVIDIA GPU 加速

如果您有 NVIDIA GPU，可以加速视频转码和 ML 推理：

安装 NVIDIA Container Toolkit

# 添加仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/libnvidia-container.list

# 安装
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

修改 docker-compose.yml

为 ML 服务添加 GPU 支持：

  immich-machine-learning:
    container_name: immich_machine_learning
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    # ... 其他配置

Intel Quick Sync 加速

Intel 集成显卡可以加速视频转码：

  immich-server:
    devices:
      - /dev/dri:/dev/dri
    # ... 其他配置

⚡ 性能提升：

GPU 加速可以将 ML 推理速度提升 5-10 倍，视频转码速度提升 3-5 倍。首次索引大量照片时效果尤为明显。

外网访问配置（反向代理 + HTTPS）

方案一：Nginx Proxy Manager

最简单的反向代理管理方案：

部署 Nginx Proxy Manager (NPM)
添加代理主机，指向 Immich 的内部地址
配置域名和 SSL 证书（Let's Encrypt）
在路由器中转发 80/443 端口

方案二：Caddy 自动 HTTPS

# Caddyfile 配置
photos.example.com {
    reverse_proxy immich-server:2283
}

# 启动 Caddy
docker run -d --name caddy \
  -v ./Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -p 80:80 -p 443:443 \
  caddy:latest

方案三：Cloudflare Tunnel（无需公网 IP）

# 安装 cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# 登录并创建隧道
cloudflared tunnel login
cloudflared tunnel create immich
cloudflared tunnel route dns immich photos.example.com

# 配置文件 config.yml
tunnel: immich-tunnel
credentials-file: /root/.cloudflared/tunnel-id.json

ingress:
  - hostname: photos.example.com
    service: http://localhost:2283
  - service: http_status:404

# 运行隧道
cloudflared tunnel run

🔒 安全建议：

外网访问时务必启用 HTTPS，建议配置双因素认证（2FA），并考虑使用 VPN 或 IP 白名单进一步保护。

移动端 App 配置与自动备份

下载安装

Android：Google Play 或 F-Droid 搜索 "Immich"
iOS：App Store 搜索 "Immich"

连接服务器

打开 App，输入服务器地址（如 https://photos.example.com）
使用已创建的账户登录
App 会自动检测服务器 API 版本

配置自动备份

进入 App 设置 → 备份
开启 后台备份
选择备份条件：
- 仅 WiFi / WiFi + 移动网络
- 仅充电时 / 始终
- 备份相册范围
选择备份目标（可创建专属相册）

iOS 特别设置

进入 iOS 设置 → Immich → 开启后台应用刷新
进入 iOS 设置 → 隐私 → 照片 → Immich → 选择完全访问权限
建议开启位置权限以保留 GPS 信息

Android 特别设置

关闭电池优化（设置 → 电池 → 应用优化 → Immich → 不优化）
允许自启动（部分国产 ROM 需要单独设置）
锁定后台进程（在最近任务中下拉锁定）

✨ 功能特性详解

🧠 AI 智能搜索 (Semantic Search)

Immich 的核心特色之一是语义搜索，允许用户使用自然语言描述来查找照片。

工作原理

图片编码：CLIP 模型将每张图片转换为 512 维向量
向量存储：向量嵌入存储在 PostgreSQL 的 pgvector 字段中
文本编码：搜索文本同样被 CLIP 编码为向量
相似度匹配：通过余弦相似度计算找到最匹配的图片

搜索示例

📝 "海边的日落" — 找到所有海边日落照片
📝 "一家人在公园" — 找到家庭户外照
📝 "红色的汽车" — 通过颜色+物体组合搜索
📝 "2023年生日派对" — 时间+事件搜索

💡 高级技巧：

在管理面板 → 系统设置 → 机器学习中，可以调整置信度阈值、切换不同的 CLIP 模型（如多语言模型）来优化搜索效果。

👤 人脸识别与人物相册

Immich 使用 InsightFace 的 buffalo_l 模型进行人脸检测和识别，并通过 DBScan 算法进行聚类。

处理流程

人脸检测：识别照片中的所有人脸位置
特征提取：为每张人脸生成特征向量
聚类：DBScan 算法将相似人脸归为一组
命名：用户可为聚类结果命名

管理人物

在"浏览" → "人物" 中查看所有检测到的人物
点击人物可查看所有包含该人物的照片
可以合并错误分类的人脸
支持为宠物命名

优化识别效果

为常见人物添加多张样本照片
手动合并同一人物的不同聚类
将不应被识别人脸标记为"忽略"

🗺️ 地图视图与地理定位

Immich 可以提取照片的 GPS 信息并在地图上展示拍摄地点。

功能特点

地图展示：在世界地图上查看照片拍摄位置
热力图：密集区域以热力图形式展示
时间线：结合时间轴查看旅行路线
地理围栏：按地区筛选照片

隐私设置

可以选择隐藏精确位置信息
共享相册时自动剥离位置数据
管理员可以全局禁用地标信息

📤 共享与协作功能

相册共享

创建相册并邀请其他用户加入
设置权限：查看/上传/管理
共享相册中的照片对所有成员可见

合作伙伴共享

将其他用户添加为"合作伙伴"
合作伙伴可以访问你选择共享的所有照片
适合家庭成员之间共享整个照片库

公开分享链接

为特定照片或相册生成公开链接
可设置密码保护和过期时间
无需账户即可访问
支持下载权限控制

📱 多用户与权限管理

用户角色

角色	权限
管理员	完全控制：用户管理、系统设置、所有资源
普通用户	管理自己的照片、创建相册、查看共享内容

存储配额

管理员可为每个用户设置存储配额
超出配额后自动暂停备份
用户可查看自己的使用情况

用户管理功能

创建/删除/暂停用户账户
重置用户密码
查看用户活跃状态
导出用户数据

🔧 高级功能与配置

外部库导入

可以将已有的照片目录导入 Immich 而无需重新上传：

# 在 docker-compose.yml 中挂载外部库
volumes:
  - /path/to/existing/photos:/usr/src/app/external:ro

# 在管理面板 → 外部库 → 添加扫描路径

XMP Sidecar 支持

自动读取 XMP 元数据文件
支持 Lightroom、Capture One 等软件的标签和评分
修改会回写到 XMP 文件

存储模板

自定义文件存储路径结构：

# 示例模板
{{y}}/{{M}}/{{filename}}
# 结果：2024/03/IMG_1234.jpg

{{y}}/{{MM}}/{{dd}}/{{filename}}
# 结果：2024/03/15/IMG_1234.jpg

{{album}}/{{filename}}
# 按相册名称组织文件

视频转码配置

支持 H.264、H.265/HEVC、VP9、AV1 编解码
可设置目标分辨率和比特率
硬件加速可大幅降低 CPU 占用

⚙️ 配置说明

环境变量完整配置参考

以下为 .env 文件的完整配置参考：

# ==================
# 通用配置
# ==================
IMMICH_VERSION=release
UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres

# ==================
# 数据库配置
# ==================
DB_PASSWORD=immich_password_change_me
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
DB_HOSTNAME=database
DB_PORT=5432

# ==================
# Redis 配置
# ==================
REDIS_HOSTNAME=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# ==================
# 机器学习配置
# ==================
MACHINE_LEARNING_HOST=immich-machine-learning
MACHINE_LEARNING_PORT=3003
MACHINE_LEARNING_CACHE_FOLDER=/cache

# ==================
# 服务器配置
# ==================
IMMICH_API_URL_INTERNAL=http://immich-server:2283/api
IMMICH_WEB_URL=http://immich-web:2283

# ==================
# 时区
# ==================
TZ=Asia/Shanghai

Docker Compose 完整配置

version: "3.8"

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:release
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - "2283:2283"
    depends_on:
      - redis
      - database
    restart: always

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:release
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: redis:6.2-alpine
    volumes:
      - redis-data:/data
    restart: always

  database:
    container_name: immich_postgres
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    env_file:
      - .env
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always

volumes:
  model-cache:
  redis-data:

备份与恢复策略

需要备份的内容

照片文件：UPLOAD_LOCATION 目录
数据库：PostgreSQL 数据
配置：.env 和 docker-compose.yml

自动备份脚本

#!/bin/bash
# immich-backup.sh

BACKUP_DIR="/backup/immich"
DATE=$(date +%Y%m%d_%H%M%S)

# 备份数据库
docker exec -t immich_postgres pg_dump -U postgres immich | gzip > ${BACKUP_DIR}/db_${DATE}.sql.gz

# 备份照片文件
rsync -av /path/to/upload ${BACKUP_DIR}/files_${DATE}/

# 保留最近 30 天的备份
find ${BACKUP_DIR} -name "db_*.sql.gz" -mtime +30 -delete
find ${BACKUP_DIR} -name "files_*" -type d -mtime +30 -exec rm -rf {} \;

echo "Backup completed: ${DATE}"

恢复步骤

# 1. 停止服务
docker compose down

# 2. 恢复数据库
gunzip < backup.sql.gz | docker exec -i immich_postgres psql -U postgres -d immich

# 3. 恢复照片文件
rsync -av /backup/files/upload ./library/

# 4. 重启服务
docker compose up -d

⚠️ 重要：

定期测试备份恢复流程，确保在灾难发生时能成功恢复。建议至少每月进行一次恢复演练。

性能优化建议

数据库优化

# 在 PostgreSQL 中执行优化设置
ALTER SYSTEM SET shared_buffers = '2GB';
ALTER SYSTEM SET effective_cache_size = '6GB';
ALTER SYSTEM SET work_mem = '32MB';
ALTER SYSTEM SET maintenance_work_mem = '512MB';
ALTER SYSTEM SET max_parallel_workers_per_gather = 4;

# 重新加载配置
SELECT pg_reload_conf();

Docker 资源限制

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

  immich-machine-learning:
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: '4.0'

缓存策略

使用 CDN 或 Nginx 缓存缩略图和静态资源
为静态资源配置较长的浏览器缓存时间
使用 Redis 缓存频繁查询的 API 响应

图片处理优化

适当降低缩略图质量以减少存储和带宽
使用渐进式 JPEG 提升加载体验
为大图生成 WebP 格式预览（体积更小）

常见问题排查 (FAQ)

Q: 照片上传失败怎么办？

检查服务器磁盘空间是否充足
检查 Docker 容器的文件权限
查看 immich-server 日志：docker compose logs immich-server
确认 Nginx 或反向代理的 client_max_body_size 设置足够大

Q: 机器学习服务很慢？

首次索引需要大量计算，耐心等待完成
考虑启用 GPU 加速
可以在管理面板中降低 ML 处理的优先级
确保系统有足够内存（ML 服务建议 4GB+）

Q: 移动端无法连接服务器？

确认服务器地址正确（包含 http:// 或 https://）
检查防火墙是否允许端口访问
如果是外网访问，确认 DNS 解析正常
尝试使用 IP 地址直连排除 DNS 问题

Q: 如何迁移到新的服务器？

在旧服务器执行完整备份
在新服务器安装 Docker 环境
恢复数据库和文件到对应位置
使用相同的 .env 配置（注意修改密码等敏感信息）
启动服务并验证数据完整性

Q: 更新后服务无法启动？

查看日志定位具体错误：docker compose logs
确认 docker-compose.yml 格式正确
如果数据库 schema 变更，可能需要执行迁移
参考 GitHub Release Notes 中的升级说明