前述

为什么选择 Immich？

起初木子一直使用的是 PhotoPrism 进行照片管理，具体参考链接：DIY NAS系列16 — 照片管理之 PhotoPrism – Rocky Linux。但 PhotoPrism 有一个显著的不足，它缺乏配套的客户端应用。虽然服务器端支持通过 WebDAV 对照片进行上传和同步，但由于木子最近将手机更换为 iPhone，苦寻多日都没有找到称心如意的 iOS 客户端工具，使日常同步变得不便。其实木子很早就知道 Immich 这个项目，只是不想频繁折腾，所以一直没有尝试。但这次受限于 PhotoPrism 的客户端短板，终于下决心切换到了 Immich。
Immich 的最大优势在于它原生支持跨平台客户端，包括：Windows、macOS、iOS、Android 等主流系统，真正实现了照片在不同设备间的无缝上传和同步。相比 PhotoPrism，Immich 的便捷性和易用性都更上一层楼，非常适合家庭或个人私有云照片管理使用。

Immich 项目优势：

全平台支持：原生开发的 Windows、macOS、iOS、Android 客户端，无需第三方工具即可轻松同步照片。
高效照片管理：自动整理、分类照片，支持关键字搜索、人脸识别、地点标记等智能功能，让照片检索更加便捷。
隐私安全：自托管架构，所有照片和数据存储在自己的服务器，有效保障了数据隐私。
开源社区活跃：项目开源，持续快速迭代，拥有活跃的开发者和用户社区，可以及时获得新特性和技术支持。
现代化界面体验：操作界面简洁美观，操作流畅，带来与市售云相册同等甚至更优的用户体验。
易于部署：官方提供 Docker 部署方式，对于拥有 NAS 或服务器的用户来说安装和维护都非常简单。

总之，如果您需要一个支持全平台客户端、注重数据隐私、具有强大智能管理功能的自托管照片管理方案，Immich 会是目前非常值得推荐的选择。
目前此项目在 GitHub 上拥有 66.8K Star，GitHub 项目地址：https://github.com/immich-app/immich

部署 Immich

说明: 基于前期构建的 traefik 网关，详见: DIY NAS系列12 — Traefik 出口网关配置
在 docker-compose.yaml 文件中，会对重要的配置进行说明，因个人网络环境等不同，需要根据自身实际情况调整配置。

Immich 官方 Docker 部署方案，参考链接：immich/docker at main · immich-app/immich · GitHub
整个 Immich 会启动 4 个服务：

immich-server：immich 主程序
immich-machine-learning：大模型服务
redis：缓存服务
postgres：数据库（包含向量存储）

服务配置

# 创建两个文件
❯ ls -la
.rw-r--r--  639 root 26 May 14:02  .env # 环境变更设置
.rw-r--r-- 3.3k root 26 May 14:02  docker-compose.yml # 服务管理

# 环境变更配置文件
❯ cat .env
# 您可以在 https://immich.app/docs/install/environment-variables 找到所有受支持的环境变量的文档
# 上传文件存储路径
UPLOAD_LOCATION=/SSD/Picture
# 数据库文件的存储位置。该数据库不支持网络共享
DB_DATA_LOCATION=/SSD/Demo/immich/postgres
# 自定义的外部库存放路径，没有的话，可以不用挂载
PHOTOS_LOCATION=/SSD/Photo
#时区
TZ=Asia/Shanghai
# 要使用的 Immich 版本。您可以将其固定为特定版本，例如“v1.134.0”
IMMICH_VERSION=v1.134.0
# postgres 数据库密码(随机生成)
DB_PASSWORD=a4aA2e80imX7MQ
# 数据库用户名
DB_USERNAME=postgres
# 数据库库名
DB_DATABASE_NAME=immich

# immich 配置文件
❯ cat docker-compose.yml
name: immich
services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # 下面的参数开启核显转码加速，devices 与 extends 二选一
    devices:
      - /dev/dri:/dev/dri
    # extends:
      # 硬件转码参考链接：https://immich.app/docs/features/hardware-transcoding/
      # 设置为 [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] 之一以加速转码，默认为 CPU
      # service: quicksync
    volumes:
      # 通过环境亦量文件 .env 设置 UPLOAD_LOCATION 图片存储位置
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      # 导入外部图片，加 ro，防止图片被修改、删除
      - ${PHOTOS_LOCATION}:/usr/src/app/external
      # 时区设置
      - /etc/localtime:/etc/localtime:ro
      # 地图中文化配置
      - /SSD/Demo/immich/map/geodata:/build/geodata
      - /SSD/Demo/immich/map/i18n-iso-countries/langs:/usr/src/app/node_modules/i18n-iso-countries/langs
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false
    networks:
      - traefik_net
    labels:
      - traefik.enable=true
      - traefik.docker.network=traefik_net
      - traefik.http.routers.immich-server.rule=Host(`photo.rockylinux.cn`)
      - traefik.http.routers.immich-server.entrypoints=websecure
      - traefik.http.routers.immich-server.tls=true
      - traefik.http.routers.immich-server.service=immich-server
      - traefik.http.routers.immich-server.middlewares=SecHeaders@file,AllowIPList@file
      - traefik.http.services.immich-server.loadbalancer.server.port=2283

  immich-machine-learning:
    container_name: immich_machine_learning
    # 如需硬件加速，请在镜像标签中添加 [armnn, cuda, rocm, openvino, rknn]
    # 如: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # devices:
    #   - /dev/dri:/dev/dri
    # extends: # 如需硬件加速，请取消注释部份，详细参阅：https://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: openvino # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      # 大模型存放位置
      - /SSD/Demo/immich/model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false
    environment:
      - HF_ENDPOINT=https://hf-mirror.com
    networks:
      - traefik_net

  redis:
    container_name: immich_redis
    image: valkey/valkey:8.1.1-bookworm
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always
    networks:
      - traefik_net

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # 如果您的数据库未存储在 SSD 上，请取消注释 DB_STORAGE_TYPE: 'HDD' 变量。
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # 请勿编辑下一行。如果要更改系统上的数据库存储位置，请编辑 .env 文件中 DB_DATA_LOCATION 的值
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always
    networks:
      - traefik_net
networks:
  traefik_net:
    external: true

# 启动服务
❯ docker compose up -d

目录结构说明

在部署 Immich 时，有在 .env 环境变量配置文件中设置了图片的环境变量 UPLOAD_LOCATION，并在 docker-compose.yaml 中通过挂载方式将该路径映射到容器内 - ${UPLOAD_LOCATION}:/usr/src/app/upload。这个目录实际上存储的不仅仅是上传的照片，还有数据库备份、转码视频、图库、用户头像信息、缩略图等。

❯ tree -L 1
.
├── backups # 数据备份
├── encoded-video # 转码视频
├── library # 图库
├── profile # 用户头像信息
├── thumbs # 缩略图
└── upload # 上传文件夹

6 directories, 0 files

中文地图

Immich 默认使用英文地图，因此在查看照片元数据时，地址信息通常以英文或拼音显示，使用起来不够直观。为了解决这个问题，这里采用中文地理数据（参考链接：GitHub – ZingLix/immich-geodata-cn）。该项目为 Immich 提供了中文反向地理编码支持，不仅可以将照片的拍摄地点转换为我们熟悉的中文地名，还支持通过中文地名对照片进行搜索，大大提升了使用体验和检索效率。

部署地图

# 创建地图数据存放目录
❯ mkdir -p /SSD/Demo/immich/map
❯ cd /SSD/Demo/immich/map

# 下载最新的地图数据文件
❯ wget https://github.com/ZingLix/immich-geodata-cn/releases/download/release-2025-03-29/geodata_admin_2_admin_3_admin_4_full.zip
❯ wget https://github.com/ZingLix/immich-geodata-cn/releases/download/release-2025-03-29/i18n-iso-countries.zip

# 解压
❯ unzip geodata_admin_2_admin_3_admin_4_full.zip
❯ unzip i18n-iso-countries.zip

# 删除原文件
❯ rm -rf geodata_admin_2_admin_3_admin_4_full.zip
❯ rm -rf i18n-iso-countries.zip

# docker-compose.yaml 环境变量挂载至指定目录
❯ cat docker-compose.yaml | grep map
      - /SSD/Demo/immich/map/geodata:/build/geodata
      - /SSD/Demo/immich/map/i18n-iso-countries/langs:/usr/src/app/node_modules/i18n-iso-countries/langs

# 重启 immich-server 服务
❯ docker compose down && docker compose up

# 确保 immich-server 服务日志显示加载 geodata 即可
❯ docker logs -f immich-server
[Nest] 7  - 05/27/2025, 8:14:40 PM     LOG [Microservices:MapRepository] 10000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:40 PM     LOG [Microservices:MapRepository] 20000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:41 PM     LOG [Microservices:MapRepository] 30000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:41 PM     LOG [Microservices:MapRepository] 40000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:42 PM     LOG [Microservices:MapRepository] 50000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:42 PM     LOG [Microservices:MapRepository] 60000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:42 PM     LOG [Microservices:MapRepository] 70000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:42 PM     LOG [Microservices:MapRepository] 80000 geodata records imported
[Nest] 7  - 05/27/2025, 8:14:42 PM     LOG [Microservices:MapRepository] 90000 geodata records imported

启动 Immich 后，登录您的 Immich 管理后台，在系统管理 — 任务 — 提取元数据，点击“全部”，以触发所有照片的元数据刷新，等待任务完成后，所有照片的位置信息就都会显示成中文，后续新增的图片则无需任何额外操作，并且可以用中文进行搜索了。

更新地图版本

方式一：重新下载最新的 Release 中的文件，替换掉原有的文件，然后重启 Immich 即可。
方式二：为了方便快速更新，可以通过如下脚本自动更新：

# cd 到 geodata 目录下进行操作 
❯ cd /SSD/Demo/immich/map/geodata
# 下载脚本 
❯ curl -o update.sh https://raw.githubusercontent.com/ZingLix/immich-geodata-cn/refs/heads/main/geodata/update.sh 
# 运行 bash 
❯ ./update.sh

# 设置计划任务，在每个星期六的零点（00:00），会执行 /immich_data/geodata/update.sh 脚本，然后重启 immich_server 容器
❯ crontab -l | grep immich
0 0 * * 6 bash /SSD/Demo/immich/map/geodata/update.sh && docker restart immich_server

初始化 Immich

初始化的过程相对比较简单，基本上就是下一步的事情。

创建账户：安装完 Immich 启动后，创建的第一个用户默认是管理员账户。依次填入管理员邮箱、管理员密码、名称，点击 “注册” 按钮完成账户注册。

注册成功后，登录即可。

主题设置：按照提示设置主题颜色，目前只有浅色和深色两种模式可选。

隐私：设置地图、版本检查等服务。

存储模板：这个功能默认是关闭的，就是上传的图片基于怎么样的分类进行存放，木子这里未进行设置，当然也可以后期在“系统管理”中进行配置。

进入主界面如下所示：

账户设置

Immich 的设置分为两个维度：账户设置 与 系统管理。

账户设置：主要用于个人偏好设置，比如：语言、修改密码、共享相册等。
系统管理：只有管理员才有权限进行设置，主要设置一些与系统相关的配置，比如：人脸检测模型，存储模板管理等。

语言设置

点击右上角头像
点击账户设置（account setting ）
在应用设置（app setting）修改语言（language）为简体中文（Chinese(Simplified)）

侧边栏文件夹

设置完成以后，就可以通过侧边栏进行文件夹管理。

修改密码

系统管理

Immich 的系统管理涵盖了诸多模块，包括：认证设置、图片设置、任务调度、元数据配置、外部图库管理、日志查看、机器学习参数、地图与 GPS 配置、通知设置、服务器参数、存储模板、主题切换、回收站管理、用户管理、版本检测以及视频转码等功能。本文将重点介绍其中几个常用的设置，其他配置项可参考官方文档根据实际需求进行调整。

数据库备份

Immich 默认每天凌晨 2 点自动备份数据库，并保留最近 14 天的历史备份。这些备份文件存放在挂载路径 /usr/src/app/upload 下。需要注意，自动备份的仅为 Postgres 数据库本身，不包含其它文件数据。建议根据实际需求，定期对相关照片及其它重要配置文件做额外备份，以确保数据安全。

# 数据库备份
❯ pwd
/usr/src/app/upload
❯ ll
Permissions Size User Date Modified Name
.rw-r--r--   19M root 25 May 02:00   immich-db-backup-1748109600023.sql.gz
.rw-r--r--   19M root 26 May 02:00   immich-db-backup-1748196000048.sql.gz
.rw-r--r--   26M root 27 May 02:00   immich-db-backup-1748282400013.sql.gz
.rw-r--r--   66M root 28 May 02:00   immich-db-backup-1748368800012.sql.gz
.rw-r--r--   80M root 29 May 02:00   immich-db-backup-1748455200013.sql.gz

# 解压
❯ gzip -d immich-db-backup-1748455200013.sql.gz
❯ ll
Permissions Size User Date Modified Name
.rw-r--r--   19M root 25 May 02:00   immich-db-backup-1748109600023.sql.gz
.rw-r--r--   19M root 26 May 02:00   immich-db-backup-1748196000048.sql.gz
.rw-r--r--   26M root 27 May 02:00   immich-db-backup-1748282400013.sql.gz
.rw-r--r--   66M root 28 May 02:00   immich-db-backup-1748368800012.sql.gz
.rw-r--r--  258M root 29 May 02:00   immich-db-backup-1748455200013.sql

存储模板设置

存储模板：实际上就是对于上传的照片，按指定的规则创建文件夹进行分级管理。木子设置的存储方式是：{y}}/{{MM}}/{{filename} 年/月/文件名。
实际后端存放目录为 /usr/src/app/upload/library/{{username}}/{{y}}/{{MM}}/{{filename}}。

❯ tree -L 3 library
library # 图库目录
└── admin # 用户目录
    └── 2025 # 年
        ├── 02 # 月
        ├── 04
        └── 05

5 directories, 0 files

硬件加速

在 Immich 中，主要有两类场景会用到 GPU 硬件加速：视频转码加速 和 机器学习加速。这两项功能目前都处于实验性阶段。如果不启用硬件加速，相关任务会全部由 CPU 执行，可能造成较高的 CPU 占用率。因此，建议配备支持硬件加速的显卡。

视频转码加速

视频转码加速用于提升视频转码时的处理效率。如果没有相关硬件，则默认由 CPU 完成，消耗会明显增大。Immich 支持 NVIDIA、Intel、AMD 以及 Rockchip 等主流视频硬件加速。详细信息可参考官方文档：Hardware Transcoding | Immich。
以木子的设备为例，当前使用的是搭载 UHD 600 核显的 J4125 处理器。经实际测试，在 Immich 上进行视频转码没有问题。通常，如果硬件能支持 Jellyfin 等媒体系统的转码，Immich 也能兼容。

机器学习加速

机器学习加速主要用于提升图片识别相关模型（如：人脸检测、人脸识别）的处理速度。未配备相关硬件时，将由 CPU 执行，效率较低。Immich 支持 NVIDIA、Intel、AMD、Rockchip 等多种平台的硬件加速。详细配置方法见官方文档：Hardware-Accelerated Machine Learning | Immich。
在实际配置中，木子尝试启用 OpenVINO Intel GPU 加速处理。但在 J4125 平台上测试时，发现每当开启加速，GPU “Render/3D” 使用率会瞬间拉到 100%，随即下降至 0，并伴随着 immich-machine-learning 服务重启，最终导致代码崩溃报错。错误信息如下：

[05/26/25 13:52:34] INFO     Loading detection model 'buffalo_l' to memory      
[05/26/25 13:52:34] INFO     Setting execution providers to                     
                             ['OpenVINOExecutionProvider',                      
                             'CPUExecutionProvider'], in descending order of    
                             preference                                         
2025-05-26 13:52:42.223773222 [E:onnxruntime:, inference_session.cc:2045 operator()] Exception during initialization: /onnxruntime/onnxruntime/core/providers/openvino/ov_interface.cc:85 onnxruntime::openvino_ep::OVExeNetwork onnxruntime::openvino_ep::OVCore::CompileModel(std::shared_ptr<const ov::Model>&, std::__cxx11::string&, ov::AnyMap&, std::__cxx11::string) [OpenVINO-EP]  Exception while Loading Network for graph: OpenVINOExecutionProvider_OpenVINO-EP-subgraph_1_0Exception from src/inference/src/cpp/core.cpp:109:
Exception from src/inference/src/dev/plugin.cpp:54:
Exception from src/plugins/intel_gpu/src/runtime/ocl/ocl_stream.cpp:433:
[GPU] clWaitForEvents, error code: -14

从错误日志来看，是因为使用 ONNX Runtime 的 OpenVINOExecutionProvider （即尝试用英特尔的 OpenVINO 进行推理）加载模型时，底层 OpenVINO 库在 GPU 部分，通过 OpenCL 与驱动交互时出错。

可能的根本原因：

Intel GPU 驱动配置/权限/兼容性问题
OpenVINO 环境配置问题
显卡资源不可用或冲突
权限问题
硬件不支持或硬件故障

木子尝试了很多方法，包括：内核升级、更换 OpenVINO 版本等，都未能成功，有知道解决方案的同学，可以在下方留言。
从 OpenVINO 官方的资料来看，在硬件支持上，并不支持 Intel(R) Celeron(R) J4125 CPU，详细参考链接：System Requirements — OpenVINO™ documentation

GPU 资源监控

说到 GPU 加速，就不得不提到对 GPU 资源的监控。相比而言，NVIDIA 的显卡在这方面更为便捷，官方提供了完善的在线和离线监控工具。而在 Intel 平台下，GPU 资源监控则稍显繁琐。大多数 Linux 发行版默认未内置相关工具，通常需要手动编译安装 intel-gpu-top（Ubuntu 用户除外，因其可直接通过包管理器安装）。

# 克隆对应仓库
❯ git clone https://gitlab.freedesktop.org/drm/igt-gpu-tools.git
❯ cd igt-gpu-tools

# 安装开发工具包
❯ dnf groupinstall "Development Tools"
# 安装编译所需包
❯ dnf install meson ninja-build pkgconf-pkg-config kmod-devel procps-ng-devel systemd-devel libdrm-devel glib2-devel cairo-devel libpciaccess-devel zlib-devel libunwind-devel

# 开始编译安装
❯ meson build
❯ ninja -C build
❯ ninja -C build install

# 安装成功以后，确保 intel_gpu_top 可以执行
❯ intel_gpu_top
# 各 GPU 资源的使用情况
intel-gpu-top: Intel Geminilake (Gen9) @ /dev/dri/card0 -    0/   0 MHz; 100% RC6;  0.00/10.67 W;        0 irqs/s

         ENGINES     BUSY                                                                                  MI_SEMA MI_WAIT
       Render/3D    0.00% |                                                                           |      0%      0%
         Blitter    0.00% |                                                                           |      0%      0%
           Video    0.00% |                                                                           |      0%      0%
    VideoEnhance    0.00% |                                                                           |      0%      0%
# 查看哪些进程正在使用 GPU 资源
PID                           Render/3D                    Blitter            Video        VideoEnhance              NAME

大模型选型

Immich 所使用的大型模型均托管在 immich-app (Immich) 的 HuggingFace 模型仓库中。默认情况下，Immich 使用的检索模型为 ViT-B-32__openai，但该模型对中文支持较弱。因此，木子将模型更换为 XLM-Roberta-Large-Vit-B-16Plus，以提升对中文检索的体验与准确性。
XLM-Roberta-Large-Vit-B-16Plus 是一款多模态 Transformer 模型，结合了 自然语言处理（NLP） 与 计算机视觉（CV） 两大领域的技术，支持 100 多种语言。它不仅可以应用于文本分类、实体识别、文本生成等 NLP 任务，更能够联合建模图像与文本，实现跨模态检索、图文匹配、图像描述生成、视觉问答等多模态理解任务。该模型的强大之处在于，能够在图文检索、视觉问答、图文描述、多语言环境下的多模态应用等场景中，提供优秀的跨语言与跨模态处理能力。
注意：在拉取大模型之前，需要提前安装 git-lfs 工具，详细参考链接：Rocky Linux 9 AI 系列 012 — 安装大模型拉取工具 Git-LFS – Rocky Linux

# 进入大模型存储目录
❯ cd /SSD/Demo/immich/model-cache

❯ ll
Permissions Size User Date Modified Name
drwxr-xr-x     - root 26 May 11:50   clip # 存放对比语言-图像预训练模型
drwxr-xr-x     - root 26 May 13:42   facial-recognition # 存放人脸识别模型

# 进入对应目录，提前下载对应模型，避免程序自动拉取时超时
❯ cd clip
❯ git clone https://hf-mirror.com/immich-app/XLM-Roberta-Large-Vit-B-16Plus

❯ cd ../facial-recognition
❯ git clone https://hf-mirror.com/immich-app/buffalo_l

Buffalo_L：是 InsightFace 项目（世界知名的开源人脸识别库）中发布的人脸识别模型之一，用于从人脸图片生成高精度的人脸特征向量（embedding）。L 代表 Large，属于高精度大模型版本。它还有 m 和 s 两个版本，Immich 默认使用 Buffalo_L 模型。
antelopev2: Immich 还支持 antelopev2 模型，antelopev2 是一个开源的人脸识别模型，用于高效且准确地进行人脸特征提取和比对。它是 DeepInsight 团队在 2023 年开源的项目 antelope 系列模型的升级版本。

机器学习设置：系统管理 — 设置 — 机器学习设置选项。

回收站

默认启用回收站功能，相册中删除的图片不会立刻彻底删除，而是会先移动到回收站。回收站中的图片默认将在 30 天后被永久删除。

导入外部图库

在部署 Immich 时，有在 .env 环境变量配置文件中设置了外部图库的环境变量 PHOTOS_LOCATION，并在 docker-compose.yaml 中通过挂载方式将该路径映射到容器内 - ${PHOTOS_LOCATION}:/usr/src/app/external。完成配置后，需要在 Immich 的界面中创建新的图库，并指定对应的挂载路径，最后进行图库扫描，即可将外部照片资源导入 Immich 进行管理。

由于这是首次导入外部图库，因此需要手动执行外部图库扫描、缩略图生成、元数据提取、人脸检测、人脸识别和视频转码等操作，对照片进行系统化分类。特别需要注意，针对人脸检测、人脸识别和视频转码等计算密集型任务，建议提前配置好 GPU 加速，以显著提升处理效率。

客户端配置

CLI 命令行

iOS、Android、Windows 和 macOS 客户端的配置都非常简单，用户可根据指引快速完成设置。此外，Immich 还支持 CLI 命令行管理，适合有进阶需求的用户。只需在“账户设置”中创建一个 API 密钥（API Key），即可通过 immich 命令行工具进行照片管理，实现更灵活的操作与自动化管理。

# 安装 nodejs
❯ dnf install nodejs

# 安装 immich
❯ npm i -g @immich/cli

# 查看帮助信息
❯。immich -h
Usage: immich [options] [command]

Command line interface for Immich

Options:
  -V, --version                       output the version number
  -d, --config-directory <directory>  Configuration directory where auth.yml will be stored (default:
                                      "/root/.config/immich/", env: IMMICH_CONFIG_DIR)
  -u, --url [url]                     Immich server URL (env: IMMICH_INSTANCE_URL)
  -k, --key [key]                     Immich API key (env: IMMICH_API_KEY)
  -h, --help                          display help for command

Commands:
  login|login-key <url> <key>         Login using an API key
  logout                              Remove stored credentials
  server-info                         Display server information
  upload [options] [paths...]         Upload assets
  help [command]                      display help for command

# 登录服务器，API Key 后台生成
❯ immich login https://photo.rockylinux.cn GoM27gxxxxqDlcVdVWA
Logging in to https://photo.rockylinux.cn
Discovered API at https://photo.rockylinux.cn/api
Logged in as [email protected]
Wrote auth info to /root/.config/immich/auth.yml # 凭证存储目录

# 查看服务器信息
❯ immich server-info
Discovered API at https://photo.rockylinux.cn/api
Server Info (via [email protected])
  Url: https://photo.rockylinux.cn/api
  Version: 1.134.0
  Formats:
    Images: 3fr,ari,arw,cap,cin,cr2,cr3,crw,dcr,dng,erf,fff,iiq,k25,kdc,mrw,nef,nrw,orf,ori,pef,psd,raf,raw,rw2,rwl,sr2,srf,srw,x3f,avif,gif,jpeg,jpg,png,webp,bmp,heic,heif,hif,insp,jp2,jpe,jxl,svg,tif,tiff
    Videos: 3gp,3gpp,avi,flv,insv,m2t,m2ts,m4v,mkv,mov,mp4,mpe,mpeg,mpg,mts,vob,webm,wmv
  Statistics: # 数据统计
    Images: 8019
    Videos: 1112
    Total: 9131

# 退出登录，并删除凭证
❯ immich logout
Logging out...
Removed auth file: /root/.config/immich/auth.yml
Successfully logged out

# 上传指定照片
❯ immich upload img1.jpg img2.jpg

# 上传整个文件夹，默认不包括子文件夹，如需上传包含子文件夹的文件夹，需加上 --recursive 参数
❯ immich upload --recursive img/

# 参数 --dry-run 测试上传，不会真的上传
❯ immich upload --dry-run --recursive img/

# 在确定没有重复图片的前提下，可以使用 --skip-hash 跳过哈希检测
❯ immich upload --skip-hash --recursive img/

# 使用 --album 根据文件夹名称自动创建相册
❯ immich upload --album --recursive muzi/

# 使用 --album-name 上传到指定相册
❯ immich upload --album-name "muzi" --recursive muzi/

# 使用 glob 模式跳过上传某些特定名称的图片，例如：--ignore **/laozi/** 将跳过上传名为 laozi 的文件夹
❯ immich upload --ignore **/laozi/** --recursive muzi/

# 跳过指定后缀 .tif 文件
❯ immich upload --ignore **/loazi/** **/*.tif --recursive muzi/

GUI 客户端设置

以 iOS 客户端为例，其它客户端设置方式大同小异，这里就再赘述。
在 Immich 客户端中，依次点击“图库” — 右上角“上传”图标 — “选择”所需备份的相册 — “开始备份”，即可手动备份相册。
如果需要启用自动备份功能，只需点击“设置”图标，分别开启“前台备份”和“后台备份”选项，即可实现照片的自动同步备份。

图片上传管理

immich 的“照片”管理功能，兼顾了本地图片与云端图片的统一管理。在每张照片的右下角，会显示一个云形图标，用于直观标识该照片的存储状态，共有三种状态：

空心云图标：仅存在于 immich 云端，本地暂无此照片。
带勾云图标：本地与云端均有该照片。
带斜杠云图标：仅存在于本地，immich 云端暂无此照片。

通过这三种图标样式，用户可以轻松识别每张照片的存储情况，从而更高效地管理本地与云端的图片资源。

总结

Immich 是一款强大且易用的开源跨平台照片管理方案，支持 iOS、Android、Windows 和 macOS，便于多设备间的数据同步与互通。其多用户管理与共享机制适合个人、家庭及团队使用，保障数据隔离和访问安全。Immich 拥有人脸识别、地点标记等智能功能和现代化界面，支持自动、手动备份及高效检索，提升使用体验。采用完全自托管方式，用户可 100% 掌控数据，充分保护隐私，并支持本地化体验。项目具有活跃的开源生态和官方长期支持，稳定可靠。丰富的 RESTful API 及 CLI 工具，也为高级用户提供了良好的扩展与自动化能力。总之，Immich 是兼顾功能、隐私和可玩性的私有云照片管理优秀选择。

参考文献

[1] Welcome to Immich | Immich
[2] immich-app/immich · GitHub
[3] GitHub – ZingLix/immich-geodata-cn

用一杯咖啡支持我们，我们的每一篇[文档]都经过实际操作和精心打磨，而不是简单地从网上复制粘贴。期间投入了大量心血，只为能够真正帮助到您。

DIY NAS 系列 Docker NAS 开源

登录管理

标签云

前述

部署 Immich

服务配置

目录结构说明

中文地图

部署地图

更新地图版本

初始化 Immich

账户设置

语言设置

侧边栏文件夹

修改密码

系统管理

数据库备份

存储模板设置

硬件加速

视频转码加速

机器学习加速

GPU 资源监控

大模型选型

回收站

导入外部图库

客户端配置

CLI 命令行

GUI 客户端设置

图片上传管理

总结

参考文献

发送评论编辑评论

登 录 管 理

标 签 云

前述

部署 Immich

服务配置

目录结构说明

中文地图

部署地图

更新地图版本

初始化 Immich

账户设置

语言设置

侧边栏文件夹

修改密码

系统管理

数据库备份

存储模板设置

硬件加速

视频转码加速

机器学习加速

GPU 资源监控

大模型选型

回收站

导入外部图库

客户端配置

CLI 命令行

GUI 客户端设置

图片上传管理

总结

参考文献

发送评论 编辑评论

推荐文章

登录管理

标签云

发送评论编辑评论