高性能自托管照片和视频管理解决方案，提供类似 Google Photos 的体验。
- 官方文档：Immich Docs
- 项目地址：immich-app/immich
Immich 采用微服务架构。
多容器服务：
- immich-server：核心 Web 服务，提供 Web 界面和 RESTful API，处理照片上传、下载、浏览等核心业务逻辑，是用户交互的主入口。
- immich-machine-learning：机器学习服务，负责照片智能分析，包括人脸识别、场景分类、物体检测等功能。支持 GPU 加速，显著提升处理速度。
- immich-redis：缓存服务，基于 Valkey（Redis 兼容）的高性能缓存层，加速频繁访问的数据查询，提升系统响应速度。
- immich-postgres：数据库服务，基于 PostgreSQL 17 + VectorChord 的关系型数据库，存储用户信息、照片元数据、人脸数据等核心业务数据。
- Service Local (服务自产层)：
./data目录：PostgreSQL 数据库文件。./model-cache目录：机器学习模型缓存（避免重复下载）。
- Resource (媒体资源层)：
${UPLOAD_LOCATION}：映射至${PHOTO_PATH}（由global.env定义，通常指向Resource/DCIM），存储真实照片与视频文件。
为了保证 AI 识别与视频转码的流畅性，官方建议的最低配置为：
- 内存：至少 6GB RAM。
- CPU：至少 2 核心。
- 加速：推荐开启显卡硬解。
Important
前置检查：
- 必须确保
secrets/private.env中包含IMMICH_DB_PASSWORD的定义。 - 必须确保
global.env中的PHOTO_PATH指向正确的存储盘。
- 查阅与验证配置逻辑：
- 配置文件：Immich.yml
- 在 OMV Web UI 的 Compose 标签页，加载此
Immich.yml文件。 - 点击
Up（启动）即可。由于定义了networks: default，堆栈会自动创建immich_network桥接网络。
所有环境变量声明于 Immich.yml，且严格依赖宿主机的 global.env 透传。
| 选项 | 值/变量 | 修改建议 | 说明 |
|---|---|---|---|
| 基础配置 | |||
| 容器命名 | ${SERVER_HOSTNAME} |
🟢 保持默认 | 建议保持 immich-server |
| 主机端口 | 2283 |
🟡 按需调整 | 若冲突可修改，容器内固定为 2283 |
| 镜像版本 | ${IMMICH_VERSION} |
🟡 按需调整 | 当前固定为 v2.5.6 以保证稳定性 |
| 环境变量 (Environment) | |||
| 权限 UID | PUID |
🟢 保持默认 | 指向 ${PUID}（OMV appuser 的数值 1001） |
| 权限 GID | PGID |
🟢 保持默认 | 指向 ${PGID}（users 组的数值 100） |
| 时区同步 | TZ |
🟢 保持默认 | 指向 ${TZ}（如 Asia/Shanghai），防止时间戳错位 |
| 上传路径 | ${UPLOAD_LOCATION} |
🔴 必须对应 | 默认指向全局 DCIM，如有特殊需求可在 Immich.env 覆盖 |
| 数据库密码 | ${DB_PASSWORD} |
🔴 必须对应 | 必须在 private.env 中安全定义 |
| 信任代理 | ${IMMICH_TRUSTED_PROXIES} |
🟡 按需调整 | 填入 Cloudflare 隧道或 Nginx 反代网段 |
| 目录挂载 (Volumes) | |||
| 主机时间挂载 | ${LOCALTIME_PATH} |
🟢 保持默认 | /etc/localtime 确保日志的时间属性严格一致 |
| 数据库存储 | ./data |
🟢 保持默认 | PostgreSQL 数据库文件存储位置 |
| 模型缓存 | ./model-cache |
🟢 保持默认 | 机器学习模型缓存目录 |
| 照片存储 | ${UPLOAD_LOCATION} |
🔴 必须对应 | 照片与视频文件存储位置 |
首次通过 IP:2283 登录后，建议完成以下配置：
- 用户存储标签配置
- 在创建任何新用户时，建议立即配置"存储标签"，否则其物理路径将是一串无法辨认的 UUID
- 操作路径：点击用户右侧的编辑图标 ->
账号设置->账号-> 在存储标签处填入用户个性化名称
- 推荐更换多语言 CLIP 模型
- 操作路径：点击用户右侧的编辑图标 ->
系统管理->机器学习设置->智能搜索-> 在CLIP部分将模型更换为XLM-Roberta-Large-Vit-B-32（中文支持极好）
- 操作路径：点击用户右侧的编辑图标 ->
建议在宿主机开启内存超售，消除 Redis 警告以提升队列稳定性。详见排障指南：06-常见问题与故障排除 - Redis 内存超售警告。
在创建任何新用户（包括家人账号）时，建议立即配置"存储标签"，否则其物理路径将是一串无法辨认的 UUID。
为了让上传后的文件在磁盘上按序排列（如：相册名/年/日期），建议在开始大批量上传前先完成此设置：
配置步骤：
- 进入配置：点击用户右侧的编辑图标 ->
系统管理->存储模板。 - 启用模板：将
启用存储模板引擎开关打开。 - 配置建议：在文本框中输入
{{album}}/{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}。 - 保存设置：点击页面右下角的蓝色保存按钮。
- 手动执行迁移：如果您是先上传后改的模板，请前往
系统管理->任务队列->存储模板迁移点击开始。
进行批量操作前，需要先获取 API KEY：
- 登录 Web UI，点击右上角的 用户头像。
- 进入
Account Settings(账户设置)。 - 在左侧菜单选择
API Keys。 - 点击
New APIKey，输入名称并点击创建。 - 重要：立刻复制保存生成的 Key，关闭后将无法再次查看。
推荐使用预置的一键入库脚本，自动完成目录扁平化、模拟运行和正式上传：
- 脚本位置：
immich_ingest.sh - 用法：
# 完整参数模式 bash immich_ingest.sh -d [源目录] -s [IP:端口] -k [API_KEY] # 交互式模式（脚本会逐步询问参数） bash immich_ingest.sh
如果您需要从 Google Takeout (导出包) 迁移大规模照片，推荐使用 immich-go。它能自动解析 Google 专有的 .json 元数据侧信道文件，保留地点、描述及修正过的时间戳，并支持自动去重。
- 下载工具：前往 immich-go Releases 下载对应系统的版本。
- 执行导入指令 (以 Mac 本地执行为例)：
# 进入解压缩后的 Google 相册目录 cd "/path/to/Google 相册" # 执行导入 (建议先加 --dry-run 预览) ./immich-go -s "http://[NAS-IP]:2283" -k "[API-KEY]" upload from-google-photos .
上传完成后，文件物理上仍在临时目录。若要按模板规则重排：
- 前往
Administration->Jobs。 - 找到
Storage Template Migration，点击All后面的Play (播放按钮)。 - 等待完成后，宿主机
${UPLOAD_LOCATION}中的文件将按相册名物理归档。
如果您违反了规范，在宿主机上手动删除了媒体文件，导致网页端残留"幽灵缩略图"，请使用预置脚本进行清理：
- 脚本路径：
immich_cleanup_ghosts.sh - 用法：
bash immich_cleanup_ghosts.sh - 详细说明：参见 常见问题 - 幽灵缩略图清理
Warning
核心安全纪律：严禁在宿主机直接操作照片文件。请所有的增删改操作始终通过 Immich 网页版进行。
若您的资产同时关联了 Camera (手机同步产生) 和您通过 CLI 指定的相册，可使用脚本精准剔除冗余关系：
- 脚本路径：
immich_album_drop_target.sh - 用法示例 (在 OMV 上运行)：
# 从身兼多职的照片中，移除对 'Camera' 相册的关联 bash AppData/scripts/immich_album_drop_target.sh Camera
- 数据备份：Immich 具备内置的数据库备份机制。但请注意：数据库仅包含元数据，您必须手动备份
${UPLOAD_LOCATION}中的原始照片和视频。 - 数据库恢复：如果需要进行系统重装或环境迁移，仅创建同名用户无法恢复相册与人脸数据。必须使用备份目录下的
.sql.gz文件进行恢复。详见 06-常见问题与故障排除 - Immich 恢复专项。 - 性能限制：若您的 NAS 内存小于 6GB，建议在 YML 中为
immich-machine-learning设置内存限制或增加 Swap。