搭建 Immich 私有照片管理系统

发表于 分类于 阅读次数： Waline：

1. 简介：什么是 Immich？

Immich 是一个功能强大的开源自托管照片和视频备份系统，支持自动同步、AI 智能分类、面部识别等功能，是 Google Photos 等商业云服务的绝佳替代方案，特别适合个人与家庭用户使用。

Immich 截图

2. 部署 Immich

推荐使用 Docker 方式进行部署，简单高效。

项目地址：GitHub - imagegenius/docker-immich

docker pull ghcr.io/imagegenius/immich:latest
# 国内用户可使用镜像代理：
# docker pull ghcr.dockerproxy.net/imagegenius/immich:latest

2.1 使用 Docker Compose 启动服务

services:
  immich:
    image: ghcr.io/imagegenius/immich:latest
    container_name: immich
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - DB_HOSTNAME=192.168.1.x
      - DB_USERNAME=postgres
      - DB_PASSWORD=postgres
      - DB_DATABASE_NAME=immich
      - REDIS_HOSTNAME=192.168.1.x
      - DB_PORT=5432
      - REDIS_PORT=6379
      - REDIS_PASSWORD=
      - SERVER_HOST=0.0.0.0
      - SERVER_PORT=8080
      - MACHINE_LEARNING_HOST=0.0.0.0
      - MACHINE_LEARNING_PORT=3003
      - MACHINE_LEARNING_WORKERS=1
      - MACHINE_LEARNING_WORKER_TIMEOUT=120
    volumes:
      - path_to_appdata:/config
      - path_to_photos:/photos
      - path_to_libraries:/libraries
    ports:
      - 8080:8080
    restart: unless-stopped

  valkey:
    image: valkey/valkey:8-bookworm
    ports:
      - 6379:6379
    container_name: valkey

  postgres14:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
    ports:
      - 5432:5432
    container_name: postgres14
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: immich
    volumes:
      - path_to_postgres:/var/lib/postgresql/data

2.2 参数说明

参数 功能
-p 8080:8080 映射 Web UI 端口
-e PUID/PGID 设置容器权限对应的用户/组 ID
-e TZ 设置时区
-e DB_* PostgreSQL 数据库配置
-e REDIS_* Redis/Valkey 配置
-e SERVER_* Immich 服务端监听配置
-e MACHINE_LEARNING_* AI 模型配置参数
-v /config 存放应用配置及模型数据（默认模型约 1.5GB）
-v /photos 存放用户上传的照片
-v /libraries 挂载已有的照片库目录

2.3 用户权限设置

为避免容器与宿主机之间的权限冲突，建议设置 PUID 和 PGID，确保挂载目录的权限一致。
查询当前用户的 UID/GID：

id 用户名
# 示例输出：
# uid=1000(dockeruser) gid=1000(dockergroup) groups=1000(dockergroup)

3. Immich 功能配置

3.1 添加现有照片库

  1. 将本地已有照片目录挂载至 /libraries。
  2. 在管理后台设置 /libraries（或 /libraries/用户名）为外部库路径。
  3. 在用户设置中添加新库，路径设为 /libraries 或相应子目录。

3.2 配置地理信息（Geodata）

为解决 Immich 默认地理反编码结果为英文的问题，可以使用社区项目 immich-geodata-cn 实现中文地址显示。

特点：

  • 国内地址全面汉化（含港澳台）
  • 实验性支持海外地址（如日本）
  • 地址规范化为标准四级行政区格式（通过高德/Nominatim API）

挂载方式示例：

/volume1/Docker/immich/geo/geodata:/app/immich/server/geodata:rw  
/volume1/Docker/immich/geo/i18n-iso-countries:/app/immich/server/node_modules/i18n-iso-countries:rw

Geodata 效果图

3.3 配置 AI 模型（支持中文搜索）

Immich 默认使用的 ViT-B-32__openai 模型不支持中文搜索，可改为 XLM-Roberta-Large-Vit-B-16Plus。

⚠️ 模型体积较大，推荐使用代理网络进行下载。

步骤如下：

1. 安装 Git LFS

  • Windows 可通过 官网 或使用 Scoop 安装：
scoop install git-lfs
  • 群晖 NAS：
wget https://github.com/git-lfs/git-lfs/releases/download/v3.5.1/git-lfs-linux-amd64-v3.5.1.tar.gz
tar -zxvf git-lfs-linux-amd64-v3.5.1.tar.gz
cd git-lfs-3.5.1
sudo ./install.sh
git lfs install

2. 下载模型

  • 假设模型目录为 /config/machine-learning/models/clip：
cd /volume1/docker/immich/config/machine-learning/models/clip
git clone https://huggingface.co/immich-app/XLM-Roberta-Large-Vit-B-16Plus

3. 在 Immich 管理界面中设置新的 CLIP 模型路径，并重启相关任务。

效果图示例：

从此，用户即可通过中英文关键词搜索照片，实现更智能的图像管理体验。

The Why·Liam·Blog by WhyLiam is licensed under a Creative Commons BY-NC-ND 4.0 International License.

由WhyLiam创作并维护的Why·Liam·Blog采用创作共用保留署名-非商业-禁止演绎4.0国际许可证。

本文首发于Why·Liam·Blog (https://blog.naaln.com)，版权所有，侵权必究。

本文永久链接：https://blog.naaln.com/2025/06/immich/