个人总结 docker搭建私人照片云相册Immich

`Immich`

Immich 可以理解成一个"自己的私人照片云相册系统"。

它不只是一个"看文件夹里照片"的网页，而是一整套系统：

负责保存照片和视频
负责记录这些照片属于谁、拍摄时间、地点、缩略图、人脸信息
负责在网页和手机上展示
负责搜索、时间轴、地图、人脸聚类、视频转码等功能

所以它不是"文件夹浏览器"，而是：

文件 + 数据库 + 后台处理任务 + 网页界面

共同组成的一套系统

9.1、部署

Immich 的目标是：

照片、视频主数据放在 NAS 上
数据库放在本地 NVMe 上
历史照片先放到 import 目录，再手动导入
网页访问地址为：
复制代码
```
http://设备IP:2283
```

分工是：

NAS：保存照片、视频
本地 NVMe：保存数据库和项目配置

9.1.1、创建项目目录

bash 复制代码

mkdir -p /mnt/nvme/my-project/project-docker/project-immich
mkdir -p /mnt/nvme/my-project/project-docker/project-immich/postgres
mkdir -p /mnt/nvme/my-project/project-docker/project-immich/model-cache
sudo chown -R 1001:1001 /mnt/nvme/my-project/project-docker/project-immich

mkdir -p /mnt/nas/docker-data/project-immich
mkdir -p /mnt/nas/docker-data/project-immich/library
mkdir -p /mnt/nas/docker-data/project-immich/import

sudo chown -R $USER:$USER /mnt/nvme/my-project/project-docker/project-immich
sudo chown -R $USER:$USER /mnt/nas/docker-data/project-immich

推荐项目目录结构：

bash 复制代码

# 本地 NVMe
/mnt/nvme/my-project/project-docker/
└── project-immich/
    ├── postgres                # PostgreSQL 数据库目录
    ├── model-cache             # AI 模型缓存目录
    ├── .env                    # 环境变量配置 下载官方配置然后修改
    ├── configuration.yml       # Immich 功能配置
    ├── docker-compose.yml      # Docker 编排文件 下载官方配置然后修改
    ├── hwaccel.ml.yml          # 机器学习硬件加速配置 下载官方配置然后修改
    └── hwaccel.transcoding.yml # 视频转码硬件加速配置 下载官方配置然后修改

# NAS（NFS 挂载）
/mnt/nas/docker-data/
└── project-immich/
    ├── library  # Immich 主存储根目录
    └── import   # 导入源目录

postgres：这是 Immich 的数据库目录。
作用：保存照片记录、用户、时间轴、元数据、人脸信息等。
必须放本地 NVMe，不要放 NAS。 .env 里也明确写了数据库不支持网络共享。
model-cache：这是 AI 模型缓存目录。
作用：保存机器学习模型缓存，避免每次重新下载。
.env：这是环境变量配置文件。
作用：统一写主存储位置、数据库位置、版本、密码等。
configuration.yml：这是 Immich 功能配置文件。
作用：定义转码方式、编码格式、分辨率等。当前使用 rkmpp。
docker-compose.yml：这是 Docker 启动配置文件。
作用：定义要启动哪些容器、挂载哪些目录、开放哪个端口。
hwaccel.ml.yml：这是机器学习加速配置。
作用：给 immich-machine-learning 提供 RKNN 相关设备。
hwaccel.transcoding.yml：这是视频转码加速配置。
作用：给 immich-server 提供 RKMPP 相关设备。
library：这是 Immich 的主存储根目录。
注意：它不是"原图目录"这个单独概念，而是 Immich 的整个数据根目录。
import：这是导入源目录。
作用：放历史照片，之后手动执行导入命令。
它不会自动转移到主存储里。

9.1.2、创建容器

9.1.2.1、官方配置说明

先从官方示例基础上下载，再按当前设备环境修改：

bash 复制代码

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
wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
ls

在实际部署中新增或定制的：

configuration.yml：这是为了当前 RK 平台转码策略单独加上的运行配置文件，当前实际内容为 rkmpp + h264 + aac + 1080p 等参数。
model-cache：不是配置文件，而是模型缓存目录。理论上可由容器自动下载模型，但实际部署中设备端下载不稳定，所以采用了"PC 端下载后手动复制到设备"的方式。

9.1.2.2、为什么需要修改官方配置

官方配置的目标是：

保证"尽可能多机器都能先跑起来"
默认走最通用的本地目录方案
默认不启用硬件加速
默认不为某一种具体 ARM 板卡做特别适配

而当前实际环境是：

设备：NanoPi M6
系统：Debian
主存储：NAS（NFS）
数据库：本地 NVMe
视频转码：RKMPP
机器学习：RKNN
还需要额外支持 /import 导入历史照片

所以必须对官方配置做有针对性的修改。

9.1.2.3、`.env` 文件修改说明

主存储目录 UPLOAD_LOCATION

修改前（官方）: 官方默认把照片主存储放在当前项目目录下的 ./library。
env 复制代码
```
UPLOAD_LOCATION=./library
```
修改后（当前实际）: 当前实际改为本地 NAS路径。
env 复制代码
```
# UPLOAD_LOCATION=/mnt/nvme/my-project/project-docker/project-immich/library
UPLOAD_LOCATION=/mnt/nas/docker-data/project-immich/library
```
官方默认适合：
- 本机测试
- 小规模使用
- 所有数据都放在同一块本地磁盘
当前实际环境希望：
- 大量照片和视频放到 NAS
- 减少本地 NVMe 占用
- 方便长期扩容和集中管理
  修改后，Immich 主存储从"本地项目目录"改成了"NAS 挂载目录"。
  
  也就是说：
  - 新上传照片
  - CLI 导入的历史照片
  - Immich 管理的数据目录
  都会落在 NAS 上
数据库目录 DB_DATA_LOCATION

修改前（官方）: 官方默认把数据库放当前项目目录下的 ./postgres。
env 复制代码
```
DB_DATA_LOCATION=./postgres
```
修改后（当前实际）: 当前实际改为本地 NVMe 路径。
env 复制代码
```
DB_DATA_LOCATION=/mnt/nvme/my-project/project-docker/project-immich/postgres
```
官方默认适合快速启动，数据库也放项目目录中。

但数据库不适合放在 NAS/NFS 上，官方注释里也明确写了"网络共享不支持数据库"。

当前实际环境里：
- 照片放 NAS
- 数据库放本地 NVMe
这是最合理的分工。
修改后：
- PostgreSQL 数据保留在本地 NVMe
- 数据库性能和稳定性更好
- 避免 NFS 带来的风险
时区 TZ

修改前（官方）: 默认不启用时区设置。
env 复制代码
```
# TZ=Etc/UTC
```
修改后（当前实际）:
env 复制代码
```
TZ=Asia/Shanghai
```
为了让：
- 日志时间
- 网页显示时间
- 时间轴时间
更符合当前使用习惯。
修改后时间显示更直观，不容易出现"为什么拍摄时间差了几个小时"的疑问。
- 时间显示更符合本地使用习惯
- 管理和排错更直观
数据库密码 DB_PASSWORD

修改前（官方）: 默认密码是演示用途。
env 复制代码
```
DB_PASSWORD=postgres
```
修改后（当前实际）:
env 复制代码
```
DB_PASSWORD=aaaaa
```
官方默认密码只是示例，不适合长期使用。

数据库不再使用官方示例密码，更适合实际部署。
数据库用户 DB_USERNAME

修改前（官方）: 默认密码是演示用途。
env 复制代码
```
DB_USERNAME=postgres
```
修改后（当前实际）:
env 复制代码
```
DB_USERNAME=my-immich
```
官方默认直接用 postgres 用户，适合简单演示。

当前环境中使用专门的 Immich 数据库用户，更利于区分用途。

数据库身份更明确，后续维护时更容易区分。
新增 IMMICH_CONFIG_FILE

修改前（官方）: 官方 .env 中没有这一项。

修改后（当前实际）:
env 复制代码
```
IMMICH_CONFIG_FILE=/config/configuration.yml
```
当前实际部署中，增加了单独的 configuration.yml，并在 docker-compose.yml 中挂载到了容器里。

要让 Immich 正确读取这个配置，就需要在 .env 中显式指定。

这条变量和 docker-compose.yml 里的挂载配合后，Immich 才能正确读取自定义转码配置。
新增 MACHINE_LEARNING_RKNN_THREADS

修改前（官方）: 官方 .env 中没有这一项。

修改后（当前实际）:
env 复制代码
```
MACHINE_LEARNING_RKNN_THREADS=3
```
为了适配 RKNN 机器学习服务，显式指定线程数，避免完全使用默认值。

让 RKNN 相关任务的资源占用更可控。

9.1.2.4、`docker-compose.yml` 文件修改说明

immich-server 是否启用硬件转码扩展

修改前（官方）: 默认不启用硬件转码扩展。
yml 复制代码
```
# extends:
#   file: hwaccel.transcoding.yml
#   service: cpu
```
修改后（当前实际）:
yml 复制代码
```
extends:
  file: hwaccel.transcoding.yml
  service: rkmpp
```
官方默认用 CPU 模式，兼容性最好，但是当前设备是 RK 平台，希望利用：
- /dev/rga
- /dev/mpp_service
- /dev/dri
- /dev/mali0
等硬件能力进行视频转码，而不是单纯用 CPU。
修改后：
- immich-server 会继承 rkmpp 的设备挂载
- 视频转码尽量走硬件，而不是纯 CPU
immich-machine-learning 镜像是否启用 RKNN

修改前（官方）: 官方使用普通镜像
yml 复制代码
```
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
```
修改后（当前实际）:
yml 复制代码
```
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-rknn
```
官方默认用通用 CPU 版镜像。当前设备是 RK 平台，所以使用 -rknn 版本。

机器学习服务更贴合 RK 平台硬件推理环境。
immich-machine-learning 是否启用 rknn 扩展

修改前（官方）: 注释状态
yml 复制代码
```
# extends:
#   file: hwaccel.ml.yml
#   service: cpu
```
修改后（当前实际）:
yml 复制代码
```
extends:
  file: hwaccel.ml.yml
  service: rknn
```
官方默认不启用任何机器学习硬件加速。当前设备环境是 RK，所以要显式启用 rknn。

机器学习容器能获得 RKNN 所需的设备与权限。与 -rknn 镜像配合使用
是否挂载 /import

修改前（官方）: 官方只有
yml 复制代码
```
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
```
修改后（当前实际）:
yml 复制代码
```
- ${UPLOAD_LOCATION}:/data
- /mnt/nas/docker-data/project-immich/import:/import:ro
- /etc/localtime:/etc/localtime:ro
```
官方默认只考虑：
- 手机上传
- 网页上传
- 直接进入 Immich 主存储
而当前环境中还有"历史照片批量导入"的需求，所以需要单独挂载 /import。
可以执行：
bash 复制代码
```
docker exec -it immich_server immich upload --recursive /import
```
来导入 NAS 中已有照片
是否挂载 configuration.yml

修改前（官方）: 官方没有这一项。

修改后（当前实际）:
yml 复制代码
```
- ${UPLOAD_LOCATION}:/data
- /mnt/nas/docker-data/project-immich/import:/import:ro
- /etc/localtime:/etc/localtime:ro
- ./configuration.yml:${IMMICH_CONFIG_FILE}
```
因为当前部署中新增了 configuration.yml，希望对视频转码策略进行明确控制，而不是完全使用默认行为。
- 容器可以读取自定义的转码配置
- rkmpp、编码格式、分辨率等参数生效
model-cache 的挂载方式

修改前（官方）: 也就是 Docker 自己管理的匿名/命名 volume。
yml 复制代码
```
- model-cache:/cache
```
修改后（当前实际）:
yml 复制代码
```
- ./model-cache:/cache
```
因为官方方式适合：
- 容器能自己在线下载模型
- 不需要用户手动接管模型目录
而当前环境中，设备端下载模型不稳定，所以改为本地目录后，可以：
- 在 PC 上下载模型
- 手动复制到 model-cache
- 由容器直接读取
模型缓存从"Docker 内部 volume"变成"本地可见目录"，更容易维护和备份。

9.1.2.5、`hwaccel.transcoding.yml` 文件修改说明

修改前（官方）: 官方版本里，rkmpp 已经给出了大部分 RK 设备，但以下几项默认是注释掉的：

yml 复制代码

#- /dev/mali0:/dev/mali0
#- /etc/OpenCL:/etc/OpenCL:ro
#- /usr/lib/aarch64-linux-gnu/libmali.so.1:/usr/lib/aarch64-linux-gnu/libmali.so.1:ro

修改后（当前实际）: 实际版本把这些打开了

yml 复制代码

- /dev/mali0:/dev/mali0
- /etc/OpenCL:/etc/OpenCL:ro
- /usr/lib/aarch64-linux-gnu/mali/libmali.so.1:/usr/lib/aarch64-linux-gnu/libmali.so.1:ro

当前设备环境中，为了让 RK 平台的相关图形OpenCL/Mali 能力更完整可用，需要把这些额外挂进去。

修改前效果

官方默认配置更保守
兼容性更稳
但不一定能完整使用当前板子上的相关能力

修改后效果

容器能访问更多 RK 相关设备与库
更适合当前 NanoPi M6 实际环境

修改后：

容器能访问 mali0 设备。

更完整地支持当前平台相关图形/计算能力。

容器中的相关硬件能力调用更完整。

9.1.2.6、`hwaccel.ml.yml` 文件修改说明

这一份文件的变化不在于"内容大量修改"，而在于"从官方提供但未启用，变成了实际启用"。

修改前（官方）: 虽然官方文件里已经提供 rknn，但官方 docker-compose.yml 默认并没有启用它。

yml 复制代码

rknn:
  security_opt:
    - systempaths=unconfined
    - apparmor=unconfined
  devices:
    - /dev/dri:/dev/dri

修改后（当前实际）: 当前使用版本与官方提供的 rknn 方案基本一致，但是在 docker-compose.yml 里实际启用了：

yml 复制代码

extends:
  file: hwaccel.ml.yml
  service: rknn

并配合 -rknn 镜像。

几乎无本质改动，从"未启用"变成"已启用"，机器学习推理不再只是默认 CPU 方式，而是切换为更贴合当前设备的硬件推理路径。

9.1.2.6、`configuration.yml` 文件编写说明

这份文件不属于官方基础四件套之一，而是当前实际部署中新增的"运行策略文件"。

官方默认情况

官方基础 compose 并没有要求你单独准备这一份文件。

如果不加，Immich 会使用默认运行行为。

当前实际文件：

yml 复制代码

ffmpeg:
  accel: rkmpp
  accelDecode: true
  targetVideoCodec: h264
  targetAudioCodec: aac
  targetResolution: "1080"
  crf: 18
  preset: ultrafast

各项参数说明

accel: rkmpp：转码使用 RKMPP。
accelDecode: true：解码也尽量使用硬件加速。
targetVideoCodec: h264：视频转为 h264。
targetAudioCodec: aac：音频转为 aac。
targetResolution: "1080"：目标分辨率为 1080p。
crf: 18：控制视频质量。数值越小质量越高。
preset: ultrafast：优先速度，降低转码耗时。

当前环境希望：

明确使用 RKMPP
明确输出编码
明确目标分辨率
明确压缩质量与速度策略

视频转码策略更可控，不再完全依赖默认参数，相当于把"运行策略"单独抽出来。

9.1.2.7、`model-cache` 目录说明

理论上，模型缓存可以由容器第一次启动时自动下载，但是在国内网络不稳定，经常需要手动下载，然后手动复制到指定目录

复制代码

/mnt/nvme/my-project/project-docker/project-immich/model-cache

模型目录变成可见、可管理、可备份

更适合当前环境长期维护

9.1.2.8、下载模型导入设备

win系统下载模型
- 打开 PowerShell，执行：
  复制代码
```
py -m pip install -U "huggingface_hub[cli]"
```
- 然后执行
  复制代码
```
mkdir D:\immich-models
cd D:\immich-models

hf download immich-app/buffalo_l --local-dir .\buffalo_l
hf download immich-app/ViT-B-32__openai --local-dir .\ViT-B-32__openai
```
  这两条命令的意思是：把 immich-app/buffalo_l 和 immich-app/ViT-B-32__openai 整个仓库下载到本地文件夹。hf download 官方支持下载整个仓库，--local-dir 官方支持直接下载到你指定的目录。
  
  如果 hf 命令提示找不到，就把 PowerShell 关掉重新开一次。如果你遇到限流或需要登录，再给命令补一个 --token 你的HF令牌，这是官方支持的参数。
确认 Windows 上下载出来的关键文件

下载完后，在 Windows 上检查这两个文件是否存在：
复制代码
```
dir D:\immich-models\buffalo_l\detection\rknpu\rk3588\model.rknn
dir D:\immich-models\ViT-B-32__openai\visual\model.onnx
```
这两个路径是按当前 M6 的日志来的：

buffalo_l 需要用到 detection\rknpu\rk3588\model.rknn，

ViT-B-32__openai 需要 visual\model.onnx。

把文件夹拷到设备

先在设备上准备目录：

复制代码

mkdir -p /mnt/nvme/my-project/project-docker/project-immich/model-cache/facial-recognition
mkdir -p /mnt/nvme/my-project/project-docker/project-immich/model-cache/clip
rm -rf /mnt/nvme/my-project/project-docker/project-immich/model-cache/facial-recognition/buffalo_l
rm -rf /mnt/nvme/my-project/project-docker/project-immich/model-cache/clip/ViT-B-32__openai

然后在 Windows PowerShell 里用 scp 复制：

复制代码

scp -r D:\immich-models\buffalo_l mo@你的M6IP:/mnt/nvme/my-project/project-docker/project-immich/model-cache/facial-recognition/
scp -r D:\immich-models\ViT-B-32__openai mo@你的M6IP:/mnt/nvme/my-project/project-docker/project-immich/model-cache/clip/

复制完成后，设备上应该变成这样：

复制代码

/mnt/nvme/my-project/project-docker/project-immich/model-cache/
├── facial-recognition/
│   └── buffalo_l/
└── clip/
    └── ViT-B-32__openai/

重启机器学习容器

回到设备上执行：
复制代码
```
cd /mnt/nvme/my-project/project-docker/project-immich
docker compose up -d --force-recreate immich-machine-learning
docker compose logs -f immich-machine-learning
```
如果目录放对了，接下来它应该优先从 /cache 读本地模型，而不是继续去连 huggingface.co。Immich 官方也明确说，手动下载后放进 cache folder 是支持的处理方式。

9.1.3、启动容器

9.1.3.1、启动前检查

在真正启动之前，先检查：

检查 NAS 是否已挂载

bash 复制代码

findmnt /mnt/nas

如果没挂载成功，不要启动 Immich。

检查项目文件是否齐全

bash 复制代码

cd /mnt/nvme/my-project/project-docker/project-immich
ls -la

应看到：

.env
configuration.yml
docker-compose.yml
hwaccel.ml.yml
hwaccel.transcoding.yml

9.1.3.2、启动

进入项目目录：

bash 复制代码

cd /mnt/nvme/my-project/project-docker/project-immich

启动：

bash 复制代码

docker compose down && docker compose up -d

查看运行状态：

bash 复制代码

docker ps

查看日志：

bash 复制代码

docker compose logs -f immich-server

9.1.3.3、运行后的目录理解

真正保存照片的目录在哪里：

这是最容易搞错的地方，当前设置的是：

复制代码

UPLOAD_LOCATION=/mnt/nas/docker-data/project-immich/library

这个目录被挂进容器里的 /data。

所以 Immich 会在这个目录下面自己创建结构，类似这样：

复制代码

/mnt/nas/docker-data/project-immich/library/
├── library
├── upload
├── thumbs
├── encoded-video
├── profile
└── backups

注意：

原始照片实际保存在 upload/
不是 library/library

也就是说，真正的照片路径通常在：

复制代码

/mnt/nas/docker-data/project-immich/library/upload

这些子目录说明：

upload：保存原始照片和视频。
这是最重要的目录。
thumbs：保存缩略图。
encoded-video：保存转码视频。
profile：保存 AI 相关数据。
backups：保存备份相关内容。
library：这个目录不是你直觉中的"主照片目录"，通常不要自己手动碰。

9.1.4、配置文件内容

docker-compose.yml

yml 复制代码

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: rkmpp
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /mnt/nas/docker-data/project-immich/import:/import:ro
      - /etc/localtime:/etc/localtime:ro
      - ./configuration.yml:${IMMICH_CONFIG_FILE}
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-rknn
    extends:
      file: hwaccel.ml.yml
      service: rknn
    volumes:
      - ./model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:aaaaaaaaaaaaaaaaaa
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:aaaaaaaaaaaaaaaaaaaaaa
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      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:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    healthcheck:
      disable: false

volumes:
  model-cache:

.env

env 复制代码

UPLOAD_LOCATION=/mnt/nas/docker-data/project-immich/library
DB_DATA_LOCATION=/mnt/nvme/my-project/project-docker/project-immich/postgres
TZ=Asia/Shanghai
IMMICH_VERSION=v2
DB_PASSWORD=aaaaaa
DB_USERNAME=my-immich
DB_DATABASE_NAME=immich
IMMICH_CONFIG_FILE=/config/configuration.yml
MACHINE_LEARNING_RKNN_THREADS=3

hwaccel.ml.yml

yml 复制代码

services:
  armnn:
    devices:
      - /dev/mali0:/dev/mali0
    volumes:
      - /lib/firmware/mali_csffw.bin:/lib/firmware/mali_csffw.bin:ro 
      - /usr/lib/libmali.so:/usr/lib/libmali.so:ro 
  
  rknn:
    security_opt:
      - systempaths=unconfined
      - apparmor=unconfined
    devices:
      - /dev/dri:/dev/dri

  cpu: {}

  cuda:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities:
                - gpu

  rocm:
    group_add:
      - video
    devices:
      - /dev/dri:/dev/dri
      - /dev/kfd:/dev/kfd

  openvino:
    device_cgroup_rules:
      - 'c 189:* rmw'
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /dev/bus/usb:/dev/bus/usb

  openvino-wsl:
    devices:
      - /dev/dri:/dev/dri
      - /dev/dxg:/dev/dxg
    volumes:
      - /dev/bus/usb:/dev/bus/usb
      - /usr/lib/wsl:/usr/lib/wsl

hwaccel.transcoding.yml

yml 复制代码

services:
  cpu: {}

  nvenc:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities:
                - gpu
                - compute
                - video

  quicksync:
    devices:
      - /dev/dri:/dev/dri

  rkmpp:
    security_opt:
      - systempaths=unconfined
      - apparmor=unconfined
    group_add:
      - video
    devices:
      - /dev/rga:/dev/rga
      - /dev/dri:/dev/dri
      - /dev/dma_heap:/dev/dma_heap
      - /dev/mpp_service:/dev/mpp_service
      - /dev/mali0:/dev/mali0 
    volumes:
      - /etc/OpenCL:/etc/OpenCL:ro 
      - /usr/lib/aarch64-linux-gnu/mali/libmali.so.1:/usr/lib/aarch64-linux-gnu/libmali.so.1:ro

  vaapi:
    devices:
      - /dev/dri:/dev/dri

  vaapi-wsl: 
    devices:
      - /dev/dri:/dev/dri
      - /dev/dxg:/dev/dxg
    volumes:
      - /usr/lib/wsl:/usr/lib/wsl
    environment:
      - LIBVA_DRIVER_NAME=d3d12

configuration.yml

yml 复制代码

ffmpeg:
  accel: rkmpp
  accelDecode: true
  targetVideoCodec: h264
  targetAudioCodec: aac
  targetResolution: "1080"
  crf: 18
  preset: ultrafast

9.2、使用

9.2.1、首次访问

浏览器访问：

复制代码

http://设备IP:2283

例如设备 IP 是 111.111.0.11，那么访问：

复制代码

http://111.111.0.11:2283

首次进入后按页面提示创建管理员账号。

9.2.2、日常正常使用

最简单的使用方式是：

手机安装 Immich App
登录 Immich 服务器
手机照片直接上传

这样照片会直接进入 Immich 的主存储，不需要经过 import。

9.2.3、历史照片批量导入

如果有很多已经存在 NAS 上的历史照片，正确做法是 CLI upload 导入，webui中的 "外部库" 选项不会复制到指定的目录：

功能	外部库	`CLI upload`
是否复制文件	❌ 不复制	✅ 会复制
文件存放位置	原地（`import`）	`/library/upload`
是否占用双倍空间	❌	✅
是否受 `Immich` 管控	部分	完全
删除行为	不影响原文件	受 `Immich` 控制

9.2.3.1、把照片先放进 `import`

例如：

复制代码

/mnt/nas/docker-data/project-immich/import

里面可以按你的习惯分目录，例如：

复制代码

import/
└── test/
    ├── 2018/
    ├── 2019/
    ├── 2020/
    └── ...

9.2.3.2、导入前先清理垃圾文件

有些 NAS 会生成缩略图目录和无效链接文件。

建议先清理：

复制代码

find /mnt/nas/docker-data/project-immich/import -type d -name ".@__thumb" -exec rm -rf {} +
find /mnt/nas/docker-data/project-immich/import -type f -name "*.link" -delete

9.2.3.3、`CLI`登录

获取 Immich API Key
- 打开网页"http://你的设备IP:2283"
- 登录账号 -> 点击右上角头像 -> 进入
  复制代码
```
Account Settings → API Keys
```
- 点击：
  复制代码
```
Create API Key
```

在容器里登录

复制代码

docker exec -it immich_server immich login-key http://localhost:2283 YOUR_API_KEY

9.2.3.4、先 dry-run 预检查

先不要直接正式导入，先测试一次：

复制代码

docker exec -it immich_server immich upload --dry-run --recursive /import

这里必须记住：

一定要加 --recursive
因为历史照片都在多层子目录里
不加的话会提示 No files found

9.2.3.5、正式导入

确认 dry-run 没问题后，执行：

复制代码

docker exec -it immich_server immich upload --recursive /import

这条命令会做这些事：

递归扫描 /import
识别图片和视频
去重
复制到 Immich 主存储
写入数据库
后续生成缩略图、元数据、AI 信息

注意：

它不是简单复制
也不会自动删除 import 里的原文件

9.2.3.6、导入后如何确认成功

查看容量：

复制代码

du -sh /mnt/nas/docker-data/project-immich/library/upload

查看文件数量：

复制代码

find /mnt/nas/docker-data/project-immich/library/upload -type f | wc -l

网页里查看：

时间轴里是否出现照片
随机点开几张能否正常显示

9.2.3.7、导入后是否会自动清空 `import`

不会。

import 只是导入源目录。

导入后原文件还会继续保留在 import。

如果确认导入成功、网页显示正常，再手动清空：

复制代码

rm -rf /mnt/nas/docker-data/project-immich/import/*

第一次导入时，建议不要急着删，先确认没问题。

9.3、维护

9.3.1、常用运维命令

bash 复制代码

# 查看容器状态
docker ps
docker compose ps

# 查看日志
docker compose logs -f immich-server
docker compose logs -f database
docker compose logs -f immich-machine-learning

# 重启
docker compose restart

# 停止
docker compose down

# 启动
docker compose up -d

9.3.2、检查挂载是否正确

检查主存储映射：

bash 复制代码

docker inspect immich_server | grep /data

应看到类似：

bash 复制代码

/mnt/nas/docker-data/project-immich/library:/data:rw

检查导入目录映射：

bash 复制代码

docker inspect immich_server | grep /import
docker exec -it immich_server ls -lah /import

9.3.3、查看实际照片是否在增长

bash 复制代码

du -sh /mnt/nas/docker-data/project-immich/library/upload
find /mnt/nas/docker-data/project-immich/library/upload -type f | wc -l

9.3.4、彻底重建时怎么做

如果以后要彻底从零开始：

停服务
bash 复制代码
```
docker compose down
```

删除数据库目录

bash 复制代码

sudo rm -rf /mnt/nvme/my-project/project-docker/project-immich/postgres
mkdir -p /mnt/nvme/my-project/project-docker/project-immich/postgres

删除主存储目录

bash 复制代码

sudo rm -rf /mnt/nas/docker-data/project-immich/library
mkdir -p /mnt/nas/docker-data/project-immich/library

重新启动
bash 复制代码
```
docker compose up -d
```

注意：

不要只删照片文件不删数据库
否则会出现数据库里还有记录、实际文件没了的问题

个人总结 docker搭建私人照片云相册Immich

Immich

9.1、部署

9.1.1、创建项目目录

9.1.2、创建容器

9.1.2.1、官方配置说明

9.1.2.2、为什么需要修改官方配置

9.1.2.3、.env 文件修改说明

9.1.2.4、docker-compose.yml 文件修改说明

9.1.2.5、hwaccel.transcoding.yml 文件修改说明

9.1.2.6、hwaccel.ml.yml 文件修改说明

9.1.2.6、configuration.yml 文件编写说明

9.1.2.7、model-cache 目录说明

9.1.2.8、下载模型导入设备

9.1.3、启动容器

9.1.3.1、启动前检查

9.1.3.2、启动

9.1.3.3、运行后的目录理解

9.1.4、配置文件内容

9.2、使用

9.2.1、首次访问

9.2.2、日常正常使用

9.2.3、历史照片批量导入

9.2.3.1、把照片先放进 import

9.2.3.2、导入前先清理垃圾文件

9.2.3.3、CLI登录

9.2.3.4、先 dry-run 预检查

9.2.3.5、正式导入

9.2.3.6、导入后如何确认成功

9.2.3.7、导入后是否会自动清空 import

9.3、维护

9.3.1、常用运维命令

9.3.2、检查挂载是否正确

9.3.3、查看实际照片是否在增长

9.3.4、彻底重建时怎么做

`Immich`

9.1.2.3、`.env` 文件修改说明

9.1.2.4、`docker-compose.yml` 文件修改说明

9.1.2.5、`hwaccel.transcoding.yml` 文件修改说明

9.1.2.6、`hwaccel.ml.yml` 文件修改说明

9.1.2.6、`configuration.yml` 文件编写说明

9.1.2.7、`model-cache` 目录说明

9.2.3.1、把照片先放进 `import`

9.2.3.3、`CLI`登录

9.2.3.7、导入后是否会自动清空 `import`