软件与创作

Immich:自托管相册部署与备份规划

  • 0 次阅读
  • 0 条评论
文章摘要

Immich 管理照片与视频并支持移动端上传。部署相册前最重要的是原文件和数据库的备份规划,缩略图与识别能力可在基本流程稳定后启用。 手机上传与服务端索引共同形成时间轴,机器学习组件再提供人物和语义检索。原始照片、数据库与缩略图承担不同角色,备份时需分清。 适合集中管理家庭照片并保持手机上传习惯。首次导入应先小批量测试,确认拍摄时间、重复文件和账号权限。

项目介绍

Immich 管理照片与视频并支持移动端上传。部署相册前最重要的是原文件和数据库的备份规划,缩略图与识别能力可在基本流程稳定后启用。

手机上传与服务端索引共同形成时间轴,机器学习组件再提供人物和语义检索。原始照片、数据库与缩略图承担不同角色,备份时需分清。

适合集中管理家庭照片并保持手机上传习惯。首次导入应先小批量测试,确认拍摄时间、重复文件和账号权限。

核心功能

功能 作用与使用方式
自动上传 按手机相册设置备份范围
时间轴 按拍摄日期浏览
相册分享 组织照片并设置访问
人物与检索 使用对应机器学习能力
外部图库 按版本管理已有照片

功能示意

Immich 功能示意图

图 1:自制功能示意图,概括本文的使用要点。

Immich 官方界面示例
项目官方界面示例,展示上游演示数据。

项目信息

项目 说明
类型 Docker
分类 软件与创作
项目仓库 immich-app/immich
官方入口或文档 直接访问
整理日期 2026-11-14

安装或使用条件

准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。

安装与使用步骤

  1. 建立独立项目目录,先保存当前发行版的 Compose 与环境模板,核对同一个发行版的文档。数据库目录必须位于本地支持的文件系统,不能放在 SMB 网络挂载中。
  2. 根据下面环境表创建 .env,设置实际媒体路径、数据库路径与长随机密码。检查 docker compose config --quiet 通过后再启动完整服务栈。
  3. 打开 http://NAS_IP:2283,创建管理员,再创建普通测试账号。先上传十几张测试照片,检查时间、原件下载、缩略图和重复处理。
  4. 在手机端连接同一地址,测试自动备份和后台权限。确认备份完成后也不要立即删除手机唯一副本,先检查原文件和独立 NAS 备份。
  5. 需要硬件加速时使用同发行版的加速配置文件,不把别的版本 GPU 示例拼进现有 Compose。

环境文件 .env

在 Compose 同目录保存:

路径已写入 Compose;数据库账号和随机密码由下方准备命令生成。

IMMICH_VERSION=v3 来自本次获取的官方环境模板,部署前应与所选发行版保持一致。更换主版本不能只修改这个变量。示例已给出群晖绝对路径,密码由准备命令自动生成。

首次使用与操作检查

用几十张含不同日期的视频照片测试上传,核对时间、定位和播放。确认手机后台上传和重复处理后再迁移全部资料。

升级使用同版本官方配置并阅读迁移说明。备份后在独立位置恢复核对原文件与相册记录,不把缩略图目录当作原片备份。

Docker Compose

采用本次从 Immich 最新发行版下载的完整配置,保留匹配的应用、机器学习、Valkey 与带向量扩展的 PostgreSQL 镜像。以下用于新建实例;已有旧实例升级必须先按相应版本迁移说明处理,不能直接替换数据库组件。

群晖目录准备

在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/immich/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。

sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/immich /volume1/docker/immich/postgres /volume1/photos/immich
cd /volume1/docker/immich
umask 077
touch .env
if ! grep -q "^DB_PASSWORD=." .env; then
  generated_secret=$(openssl rand -hex 32)
  printf 'DB_PASSWORD=%s\n' "$generated_secret" >> .env
fi
if ! grep -q "^DB_USERNAME=." .env; then printf 'DB_USERNAME=postgres\n' >> .env; fi
if ! grep -q "^DB_DATABASE_NAME=." .env; then printf 'DB_DATABASE_NAME=immich\n' >> .env; fi
if ! grep -q "^IMMICH_VERSION=." .env; then printf 'IMMICH_VERSION=v3\n' >> .env; fi
chmod 600 .env
HALO_PREPARE
cd /volume1/docker/immich

所需密码和密钥已自动生成到项目目录的 .env,已有非空值会保留。查看初始化密码可在自己的终端执行 sudo cat /volume1/docker/immich/.env;该文件只保留在本机。

配置中的命名卷由 Docker 创建并管理,不需要手动填写 UID/GID。备份时同时保存这些数据卷,不能只备份项目目录。

#
# WARNING: To install Immich, follow our guide: https://docs.immich.app/install/docker-compose
#
# Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
    volumes:
      - /volume1/photos/immich:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    environment:
      MACHINE_LEARNING_MODEL_REVISION: v2
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
    healthcheck:
      test: redis-cli ping | grep -q PONG || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: postgres
      POSTGRES_DB: immich
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      - /volume1/docker/immich/postgres:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    healthcheck:
      disable: false

volumes:
  model-cache:

在项目目录保存为 compose.yaml 后,先检查配置,再启动:

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100

配置与常见问题

  • 原件目录与数据库缺一不可,机器学习模型缓存不能替代照片备份。
  • 首次批量生成缩略图和索引可能占用较多 CPU、内存和磁盘,先小规模确认容量。
  • 家庭共享与账号权限需要分别测试,管理员看到所有数据不代表普通账号也应看到。
  • 页面无法打开:先用 docker compose ps 检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。
  • 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。

更新与备份

同时备份原始媒体、数据库和环境配置,做一次独立恢复验证。

更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。

参考资料