点击展开更新日志

2025

08-11

Created

nexttime

会有些什么呢(❁´◡`❁)

¶源起

因为~~想折腾~~不想用威联通自带的相册管理软件，因此经过浅浅的搜索，决定部署 immich。

本文所用的 docker-compose.yml 是实际跑过的，因此基本不会存在什么大问题（如果遇到了其它问题，那就遇到了吧。。），请善用搜索引擎及大模型，特别是 GitHub issue，会很有帮助。

¶部署环境

硬件环境
- CPU：n7505 2C4T，核显
- 内存：32G
- 硬盘：100G
软件环境
- 底层系统：PVE9.0.3
- OS：Debian13 trixie
- 虚拟化容器：LXC 非特权模式
- Docker：28.3.3

¶部署

¶创建数据目录

根据你的喜好决定数据目录位置！

1 2	mkdir -p /data/docker/immich cd /data/docker/immich

¶下载部署文件

docker-compose.yml

官方 docker-compose.yml：

1	wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

建议调整项：

immich-machine-learning 开启硬件加速
- 更新镜像
- 取消 hwaccl 注释
添加自定义网络，如 immich
如果是 HDD，取消 database 相关注释

🍀：关于模型如果有条件是建议在 immich 后台修改直接下载的，如果不行就只能找一下网上第三方的下载地址，然后拷贝到挂载目录。

.env

1	wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

修改时区：TZ=Asia/Shanghai
修改数据库密码：注意建议仅使用大小写字母和数字

hwaccel.ml.yml

如果需要使用 GPU 加速机器学习，还需要进行额外配置。

以 Intel 核显为例：

下载配置：

1	wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml

在 immich-machine-learning 下的 docker-compose.yml 中，取消注释 extends 部分并将 cpu 更改为适当的后端，这里是 openvino
immich-machine-learning 中，在镜像末尾添加 -openvino 以使用硬件加速镜像

如果配置了智能搜索检查日志存在错误：

No GPU device found in OpenVINO. Falling back to CPU.

可能需要修改 hwaccel.ml.yml，在 openvino 下新增环境变量和 group_add ：

openvino:
    environment:
      - NEOReadDebugKeys=1
      - OverrideGpuAddressSpace=48
    device_cgroup_rules:
      - 'c 189:* rmw'
    group_add:
      - "44"
      - "104"
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /dev/bus/usb:/dev/bus/usb

¶部署

# 建议先用这个命令检查启动是否正常
docker compose up 

# 后台运行
docker compose up -d

¶immich cli

官方文档在这里：Immich CLI

简单使用：

¶安装

1
2
3

# 卸载旧版本
npm uninstall -g immich
npm i -g @immich/cli

¶登录认证：

# 1. 从账户设置获取 API Key

# 2. 登录
immich login http://localhost:2283/api <API_KEY>

¶命令行参数

$ immich
Usage: immich [options] [command]

Command line interface for Immich

Options:
  -V, --version                       output the version number
  -d, --config-directory <directory>  Configuration directory where auth.yml will be stored (default: "~/.config/immich/", env:
                                      IMMICH_CONFIG_DIR)
  -u, --url [url]                     Immich server URL (env: IMMICH_INSTANCE_URL)
  -k, --key [key]                     Immich API key (env: IMMICH_API_KEY)
  -h, --help                          display help for command

Commands:
  login|login-key <url> <key>         Login using an API key
  logout                              Remove stored credentials
  server-info                         Display server information
  upload [options] [paths...]         Upload assets
  help [command]                      display help for command

上传命令选项

Usage: immich upload [paths...] [options]

Upload assets

Arguments:
  paths                       One or more paths to assets to be uploaded

Options:
  -r, --recursive             Recursive (default: false, env: IMMICH_RECURSIVE)
  -i, --ignore <pattern>      Pattern to ignore (env: IMMICH_IGNORE_PATHS)
  -h, --skip-hash             Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH)
  -H, --include-hidden        Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN)
  -a, --album                 Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM)
  -A, --album-name <name>     Add all assets to specified album (env: IMMICH_ALBUM_NAME)
  -n, --dry-run               Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN)
  -c, --concurrency <number>  Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY)
  -j, --json-output           Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT)
  --delete                    Delete local assets after upload (env: IMMICH_DELETE_ASSETS)
  --no-progress               Hide progress bars (env: IMMICH_PROGRESS_BAR)
  --watch                     Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES)
  --help                      display help for command```

¶迁移备份

20250817: 已实际测试可以使用以下操作完成数据完整迁移。

¶数据库备份

进入 docker 容器

1	pg_dumpall -U postgres -h localhost -p 5432 2> "/tmp/error.log" \| gzip > immich_postgres_dump_$(date +%Y%m%d).sql.gz

¶文件备份

打包 library 目录即可：

1	tar -zcvf library.tar.gz library/

¶传输数据

将以上备份的数据库和文件拷贝到新的服务器 immich 数据目录下
将 docker-compose.yml、.env、hwaccel.ml.yml 拷贝到新的服务器 immich 数据目录下

¶恢复数据备份

执行以下命令恢复备份（注意操作及顺序）：

# 此时应该还没有创建容器，有的话就删除，包括数据
docker compose down -v

# 拉取镜像
docker compose pull

# 创建容器，先不启动
docker compose create

# 启动 postgres
docker start immich_postgres

# 导入数据
gunzip --stdout "dump.sql.gz" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | docker exec -i immich_postgres psql --dbname=postgres --username=postgre

# 恢复文件
tar -zxvf library.tar.gz

# 启动容器
docker compose up -d

¶问题处理

¶openvino 不工作

解决方案是修改 hwaccel.ml.yml ，增加相关环境变量配置。

参考 issue

¶

报错信息：

1	pthread_setaffinity_np failed for thread: 19, index: 0, mask: {2, 3, }, error code: 22 error msg: Invalid argument. Specify the number of threads explicitly so the affinity is not set

解决方案是 .env 添加一个环境变量：