本教程是根据实际部署和调试过程整理的最终版本，旨在指导您在 OEC-T (Armbian) 设备上，从零开始，完整部署一套经过优化的、具备 NPU/VPU 硬件加速功能的 Immich 私人照片管理系统。
### **最终架构**
* **操作系统**: Armbian (存放 eMMC)，ophub 9.15编译的6.1.115内核trixie-armbian
* **应用与数据库**: 高速 SATA SSD (挂载于 `/mnt/mydisk`)
* **照片与视频库**: 大容量 USB HDD (挂载于 `/mnt/library`)
* **核心功能**: 启用 Rockchip NPU 进行 AI 识别，启用 VPU 进行视频硬件转码。
—–
## 第一部分：准备存储硬盘
此阶段将精确配置您的双硬盘环境，为高性能运行打下坚实基础。
#### **第 1 步: 识别硬盘**
通过 SSH 登录您的 OEC-T，运行 `fdisk -l` 来识别硬盘盘符。
* 通常 `/dev/sda` 是您的 SATA SSD。
* 通常 `/dev/sdb` 是您的 USB HDD。
#### **第 2 步: 格式化大容量硬盘 (HDD)**
**警告：此操作将彻底清除该硬盘所有数据。**
“`bash
# 请务必将 /dev/sdb 替换为您的 HDD 实际盘符
parted /dev/sdb mklabel gpt
parted /dev/sdb mkpart primary ext4 1MiB 100%
mkfs.ext4 /dev/sdb1
“`
#### **第 3 步: 配置开机自动挂载**
1. **获取硬盘 UUID**:
“`bash
# 分别获取 SSD 和 HDD 的 UUID 并记录下来
blkid /dev/sda1
blkid /dev/sdb1
“`
2. **创建挂载点**:
“`bash
mkdir -p /mnt/mydisk
mkdir -p /mnt/library
“`
3. **编辑 fstab 文件**:
`nano /etc/fstab`
在文件末尾添加以下两行 (请将 UUID 替换为您自己硬盘的真实值):
“`fstab
# Mount SATA SSD for Apps & Data
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx /mnt/mydisk ext4 defaults,nofail 0 2
# Mount USB HDD for Media Library
UUID=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy /mnt/library ext4 defaults,nofail 0 2
“`
4. **验证挂载**:
“`bash
mount -a
df -h | grep -E ‘mydisk|library’
“`
*检查输出，确保 `/mnt/mydisk` 和 `/mnt/library` 都已正确挂载。*
—–
## 第二部分：准备 Immich 环境与配置文件
此阶段我们将创建所有必需的目录，并下载最终确认可用的配置文件。
#### **第 1 步: 创建目录结构**
“`bash
# 在 SSD 上为 Immich 的 Docker 配置文件创建一个专属目录
mkdir -p /mnt/mydisk/appdata/immich-stack
# 在 SSD 上为 Immich 的程序数据 (数据库、缓存、AI模型) 创建目录
mkdir -p /mnt/mydisk/appdata/immich/postgres
mkdir -p /mnt/mydisk/appdata/immich/model-cache
# 在 HDD 上为照片库创建一个目录
mkdir -p /mnt/library/immich_photos
“`
#### **第 2 步: 下载所有必需的配置文件**
这是我们最终确认的、可以成功下载所有正确文件的命令集。
“`bash
# 进入配置目录
cd /mnt/mydisk/appdata/immich-stack
# 下载 docker-compose.yml
curl -L -o docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
# 下载 .env 模板
curl -L -o .env https://github.com/immich-app/immich/releases/latest/download/example.env
# 下载 transcoding 硬件加速文件
curl -L -o hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
# 下载 machine learning 硬件加速文件
curl -L -o hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
“`
#### **第 3 步: 验证下载**
运行 `ls -la` 命令检查文件。您应该能看到包括隐藏的 `.env` 在内的四个文件，并且它们的大小都应该是几百或几千字节，而不是个位数。
—–
## 第三部分：核心配置修改
为了确保 100% 正确，我们将采用**完整内容替换**的方式，而不是手动修改，以杜绝任何格式或缩进错误。
#### **第 1 步: 写入正确的 `.env` 文件内容**
1. 删除旧的模板文件: `rm .env`
2. 创建新文件: `nano .env`
3. 将以下**全部内容**复制并粘贴到 `nano` 编辑器中。**您唯一需要修改的是 `DB_PASSWORD` 的值**。
“`env
# The location where your uploaded files are stored
UPLOAD_LOCATION=/mnt/library/immich_photos
# The location where your database files are stored
DB_DATA_LOCATION=/mnt/mydisk/appdata/immich/postgres
# Set a timezone
TZ=Asia/Shanghai
# The Immich version to use.
IMMICH_VERSION=release
# Connection secret for postgres.
DB_PASSWORD=你的自定义强密码
# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
“`
4. 按 `Ctrl + X` -\> `Y` -\> `Enter` 保存退出。
#### **第 2 步: 写入正确的 `docker-compose.yml` 文件内容**
这是我们共同调试出的最终版本，解决了所有缩进和配置问题。
1. 删除旧的模板文件: `rm docker-compose.yml`
2. 创建新文件: `nano docker-compose.yml`
3. 将以下**全部内容**复制并粘贴到 `nano` 编辑器中。
“`yaml
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
– /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
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-rknn
extends:
file: hwaccel.ml.yml
service: rknn
volumes:
– /mnt/mydisk/appdata/immich/model-cache:/cache
env_file:
– .env
restart: always
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
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:c44be5f2871c59362966d71eab4268170eb6f5653c0e6170184e72b38ffdf107
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: ‘–data-checksums’
volumes:
– ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: always
“`
4. 按 `Ctrl + X` -\> `Y` -\> `Enter` 保存退出。
—–
## 第四部分：启动、设置与最终验证
#### **第 1 步: 启动 Immich**
确认您位于 `/mnt/mydisk/appdata/immich-stack` 目录下，执行启动命令：
“`bash
docker compose up -d
“`
*首次启动会下载大量镜像，请耐心等待。*
#### **第 2 步: 初始化 Immich**
1. 在电脑浏览器访问: `http://192.168.31.211:2283`
2. 注册您的管理员账户。
3. 在设置向导中，**强烈建议开启 “存储模板” (Storage Template)** 功能。
#### **第 3 步: 验证 NPU 硬件加速**
1. 登录 Immich 后，进入 **管理 -\> 任务设置**，确保 **智能搜索** 和 **人脸识别** 的开关都已打开，并点击“运行任务”。
2. 通过手机 App 或网页，**上传 10-20 张新照片**。
3. 在 SSH 终端中，反复运行以下命令：
“`bash
cat /sys/kernel/debug/rknpu/load
“`
当您看到 `NPU load: 71%` 这样的非零输出时，即代表 NPU 已成功启用。
—–
## 第五部分：日常使用与维护
#### **1. 客户端使用**
* **手机**: 在应用商店搜索 **Immich** 下载 App。服务器地址填写 `http://192.168.31.211:2283`。
* **电脑**: 直接通过浏览器访问 `http://192.168.31.211:2283` 进行管理。
#### **2. 未来如何升级**
* **升级 Armbian 系统**: `sudo apt update && sudo apt upgrade -y`
* **升级 Immich 应用**:
“`bash
cd /mnt/mydisk/appdata/immich-stack
docker compose pull && docker compose up -d
“`
希望这份精修版的最终教程能为您提供最准确的指导。
