Immich-NAS-部署-绿联

以下是在NAS上部署Immich的详细步骤说明，结合了多个来源的最佳实践，并针对新手用户进行了简化与解释：

---

### 一、准备工作
1. 安装Docker
- 为什么需要Docker？
Immich基于容器化技术部署，Docker能隔离应用环境，简化依赖管理。
- 如何安装？
登录NAS后台（如QNAP的“Container Station”或群晖的“Docker”套件），搜索并安装Docker。若NAS无图形界面，可通过SSH连接后执行命令安装（参考各NAS厂商文档）。

2. 创建部署目录
- 目的：集中管理Immich的配置文件和存储数据。
- 操作示例：
```bash
mkdir /volume1/docker/immich # 假设NAS存储卷为volume1
cd /volume1/docker/immich
```

---

### 二、配置Docker Compose文件
1. 下载配置文件
- 作用：Docker Compose定义了Immich服务及其依赖（数据库、Redis等）。
- 操作：
在部署目录中下载官方`docker-compose.yml`和`.env`文件：
```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
```

2. 修改环境变量（.env文件）
- 关键配置项：
```env
UPLOAD_LOCATION=/photos # 照片存储路径，需映射到NAS实际目录（如/volume1/immich/photos）
DB_PASSWORD=your_secure_password # 数据库密码，自定义
TZ=Asia/Shanghai # 时区
```
- 注意：确保`UPLOAD_LOCATION`对应的NAS目录存在且有写入权限。

3. 调整Docker Compose（可选）
- 修改端口：若默认端口`2283`冲突，可修改`docker-compose.yml`中的端口映射（如`8080:2283`）。
- 模型路径（高级）：若需中文搜索，需替换CLIP模型（参考后续步骤）。

---

### 三、启动Immich服务
1. 启动容器
```bash
docker-compose up -d # -d表示后台运行
```
- 等待启动：首次启动会下载镜像并初始化数据库，耗时约5-10分钟。

2. 验证服务状态
```bash
docker-compose ps # 查看容器是否全部运行（正常应包含server, machine-learning, redis, postgres）
```

---

### 四、访问Immich
1. Web界面
- 浏览器输入`http://NAS内网IP:2283`（如`http://192.168.1.100:2283`）。
- 首次登录：注册管理员账号，后续可创建多用户。

2. 移动端应用
- iOS/Android应用商店搜索“Immich”，安装后输入NAS的IP和端口即可连接。

---

### 五、常见问题与优化
1. 模型下载失败
- 现象：人脸识别或搜索功能报错，日志显示无法连接HuggingFace。
- 解决方案：
手动下载模型（如`XLM-Roberta-Large-Vit-B-16Plus`），通过`kubectl cp`或Docker卷映射到`/mlcache`目录（需进入容器命令行操作）。

2. 公网访问
- 内网穿透工具：使用Cpolar或Tailscale，配置隧道将本地端口映射到公网域名（需注册服务并设置固定子域名）。

3. 外部图库整合
- 步骤：在`docker-compose.yml`中添加外部目录映射，并在Web界面“外部图库”中导入路径。

volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload # 默认上传目录
- /path/to/external/media:/usr/src/app/external # 新增外部目录映射
```
示例：若NAS上的照片目录是`/volume1/Photos`，则映射为`- /volume1/Photos:/usr/src/app/external`。
- 步骤2：重启容器
保存文件后执行：
```bash
docker-compose up -d
```
- 步骤3：在Web界面导入路径
登录Immich Web管理界面，进入【管理】→【外部图库】，输入容器内的映射路径（如`/usr/src/app/external`），Immich会自动扫描该目录下的媒体文件。
---

### 六、后续管理
1. 数据备份
- 定期备份`UPLOAD_LOCATION`目录及PostgreSQL数据库（通过NAS的备份工具或`pg_dump`命令）。

2. 更新版本
```bash
docker-compose pull # 拉取最新镜像
docker-compose up -d # 重启服务
```

---

### 示例命令汇总
```bash
# 进入部署目录
cd /volume1/docker/immich

# 下载配置文件
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

# 修改.env文件后启动
nano .env # 编辑配置
docker-compose up -d
```

通过以上步骤，即使新手也能在NAS上成功部署Immich。若遇到具体问题（如权限错误），可结合日志（`docker-compose logs`）排查。