# Immich 离线部署完整指南（美国服务器 pull，国内群晖部署）

本指南适用于国内设备（群晖 NAS、笔记本等）因网络受限无法正常拉取 Docker 镜像的情况。通过 **美国服务器负责拉取镜像**，再将镜像 **离线导入到群晖**，即可顺利部署 Immich。

本文内容包括：
- 完整部署文档
- 镜像 TAG 修复方法
- 镜像打包导出
- 群晖导入与启动
- 自动化脚本

---

## 一、在美国服务器拉取镜像

进入 Immich 目录：

```bash
cd /root/immich-Nov
docker compose pull
```

查看已拉取镜像：

```bash
docker images | grep immich
```

---

## 二、修复 TAG 为 `<none>` 的镜像（重要）

部分 Immich 依赖镜像可能显示为 `<none>` 标签，例如：

```
ghcr.io/immich-app/postgres <none>
valkey/valkey <none>
```

需要手动指定 TAG，方便后续导出：

```bash
docker tag 178719aeb38d ghcr.io/immich-app/postgres:14-vector
docker tag 84be4d718bb5 valkey/valkey:8
```

再次查看：

```bash
docker images
```

确认标签成功后继续下一步。

---

## 三、在美国服务器导出所有 Immich 镜像

```bash
docker save \
  ghcr.io/immich-app/immich-server:v2 \
  ghcr.io/immich-app/immich-machine-learning:v2 \
  ghcr.io/immich-app/postgres:14-vector \
  valkey/valkey:8 \
  -o immich-images.tar
```

生成文件约 4 至 5GB。

---

## 四、将导出的镜像传输到群晖 NAS

群晖需开启 SSH。

```bash
scp immich-images.tar admin@群晖IP:/volume1/docker/
```

---

## 五、在群晖导入离线镜像

登录群晖：

```bash
ssh admin@群晖IP
```

导入镜像：

```bash
docker load -i /volume1/docker/immich-images.tar
```

看到以下类似输出表示成功：

```
Loaded image: ghcr.io/immich-app/immich-server:v2
Loaded image: ghcr.io/immich-app/immich-machine-learning:v2
Loaded image: ghcr.io/immich-app/postgres:14-vector
Loaded image: valkey/valkey:8
```

---

## 六、复制 compose 文件到群晖

从美国服务器复制 `.env` 和 `docker-compose.yml`：

```bash
scp .env docker-compose.yml admin@群晖IP:/volume1/docker/immich/
```

---

## 七、在群晖启动 Immich 服务

```bash
cd /volume1/docker/immich
docker compose up -d
```

无需拉取镜像，因为镜像已在本地。部署完成后即可访问：

```
http://群晖IP:2283
```

---

# 自动化脚本

## ✅ 脚本 1：美国服务器自动导出镜像

文件名：`export-immich.sh`

```bash
#!/bin/bash
set -e

echo "Fixing tags for untagged images..."
docker tag 178719aeb38d ghcr.io/immich-app/postgres:14-vector || true
docker tag 84be4d718bb5 valkey/valkey:8 || true

echo "Exporting Immich docker images..."

docker save \
  ghcr.io/immich-app/immich-server:v2 \
  ghcr.io/immich-app/immich-machine-learning:v2 \
  ghcr.io/immich-app/postgres:14-vector \
  valkey/valkey:8 \
  -o immich-images.tar

echo "Done! File: immich-images.tar"
```

执行：

```bash
chmod +x export-immich.sh
./export-immich.sh
```

---

## ✅ 脚本 2：群晖自动导入并启动 Immich

文件名：`import-immich.sh`

```bash
#!/bin/bash
set -e

echo "Importing docker images..."
docker load -i immich-images.tar

echo "Starting Immich..."
docker compose up -d

echo "Immich deployed successfully!"
```

运行：

```bash
chmod +x import-immich.sh
./import-immich.sh
```

---

# ✅ 部署完成

此时 Immich 已成功部署在群晖 NAS 上，可以正常访问、上传、AI 自动整理等功能。

如需我继续帮你写：
- 更完整的备份与恢复流程
- 群晖版自动备份脚本
- 配合 Nginx 反向代理的 HTTPS 部署

告诉我即可，我帮你补全。