古籍

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

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

本文内容包括：

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

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

进入 Immich 目录：

cd /root/immich-Nov
docker compose pull

查看已拉取镜像：

docker images | grep immich

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

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

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

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

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

再次查看：

docker images

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

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

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。

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

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

登录群晖：

ssh admin@群晖IP

导入镜像：

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：

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

七、在群晖启动 Immich 服务#

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

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

http://群晖IP:2283

自动化脚本#

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

文件名：export-immich.sh

#!/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"

执行：

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

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

文件名：import-immich.sh

#!/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!"

运行：

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

✅ 部署完成#

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

如需我继续帮你写：

更完整的备份与恢复流程
群晖版自动备份脚本
配合 Nginx 反向代理的 HTTPS 部署

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

古籍