三股水
Immich 自托管相册：安装、配置与使用完整教程
2446 字 约 7 分钟
本文从 Obsidian 撰写发布
本教程基于实际部署过程整理，涵盖 Docker Compose 安装、反向代理配置、大文件上传问题排查、手机 App 使用等完整流程。

一、Immich 是什么

Immich 是一个开源的自托管照片和视频备份方案，定位是“自己的 Google Photos”。核心特点：

  • 私有部署：所有数据存在自己的服务器上，不经过第三方云
  • 自动备份：手机 App 可自动同步相册
  • AI 能力：智能搜索、人脸识别、重复照片检测
  • 时间线浏览：按拍摄时间组织照片，支持地图视图
  • 多用户：可为家人创建独立账号并共享相册
  • 原始文件存储：默认不压缩，保留原始画质和 EXIF 信息

注意：Immich 是照片管理工具，不是备份工具。建议额外做异地备份，遵循“3-2-1”原则。

二、部署前准备

服务器要求

  • 一台 Linux 服务器
  • 已安装 Docker 和 Docker Compose
  • 建议内存 4GB 以上（AI 功能较吃内存）

目录规划

在服务器上新建一个专用文件夹，所有配置和数据都放在里面：

mkdir -p /www/wwwroot/Immich
cd /www/wwwroot/Immich

三、Docker Compose 安装

1. 创建 docker-compose.yml

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:8-bookworm
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always
    healthcheck:
      disable: false

volumes:
  model-cache:

2. 创建 .env

# 上传文件存放位置（当前文件夹下的 library 目录）
UPLOAD_LOCATION=./library

# 数据库文件存放位置（不要放网络共享盘）
DB_DATA_LOCATION=./postgres

# 时区
TZ=Asia/Shanghai

# Immich 版本
IMMICH_VERSION=v3

# 数据库密码（建议改为随机字符串，仅限 A-Za-z0-9）
DB_PASSWORD=postgres

# 以下无需修改
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

3. 启动

docker compose up -d

首次启动会自动拉取镜像并创建 library 和 postgres 文件夹。

镜像拉取慢的解决办法

ghcr.io 在国内或部分网络环境下可能很慢。可以把镜像地址换成国内镜像源：

# 原来
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
# 改为
image: ghcr.nju.edu.cn/immich-app/immich-server:${IMMICH_VERSION:-release}

machine-learning 镜像同理。改完重新 docker compose up -d。

四、首次访问与注册

浏览器打开：

http://服务器IP:2283

没有默认账号密码。点击 “Getting Started” 注册第一个用户，这个账号自动成为管理员。

五、反向代理配置（域名 + HTTPS）

如果需要用域名访问并启用 HTTPS，以宝塔面板 Nginx 为例。

关键配置项

在站点配置文件的 server 块内添加：

client_max_body_size 50000M;
client_body_buffer_size 1024k;

在 location ^~ / 块内添加：

proxy_request_buffering off;

重要：如果上传大文件时 Nginx 报 client intended to send too large body，说明某处仍有较小的 client_max_body_size 在生效。最直接的修复是在 location ^~ / 块内部再次强制写入：

location ^~ / {
    client_max_body_size 50000M;
    proxy_pass http://服务器IP:2283;
    # ... 其他配置 ...
}

因为 Nginx 的作用域优先级是 location > server > http，location 内设置会覆盖所有上层配置。

手机 App 连接问题

如果 App 提示“检查网址或密码”但网页端能登录，尝试在 App 的服务器地址末尾加上 /api：

https://你的域名/api

这是因为反向代理可能拦截了 /.well-known/immich 自动发现路径，加 /api 可绕过。

六、手机 App 安装

Android（含华为等无 Google Play 设备）

推荐渠道：GitHub Releases

https://github.com/immich-app/immich/releases

选择对应架构的 APK：

  • app-arm64-v8a-release.apk：近几年的 64 位手机（包括华为 P30 等麒麟芯片机型），首选
  • app-armeabi-v7a-release.apk：很老的 32 位手机
  • app-release.apk：通用版，体积最大但万能
  • app-x86_64-release.apk：仅用于电脑模拟器

GitHub 下载慢/中断：可用代理前缀加速，例如：

https://ghproxy.net/https://github.com/immich-app/immich/releases/download/.../app-arm64-v8a-release.apk

或使用 F-Droid 等官方认可的开源商店渠道。

自动同步说明

  • App 支持自动备份，但需在备份设置里手动开启
  • Android 后台同步可能被系统电池优化杀掉。建议在手机设置里把 Immich 的电池优化设为“不允许限制”
  • 最可靠的同步触发方式是打开或切回 App
  • 默认仅 Wi-Fi 上传，可在设置中允许移动数据

七、上传文件大小问题排查

典型现象

手机 App 上传大文件失败，提示“文件太大”。

排查步骤

  1. 确认 Nginx 实际生效的限制

    nginx -T | grep client_max_body_size

    输出里不应该出现任何小于 50000M 的值。

  2. 查看 Nginx 错误日志定位

    tail -50 /www/wwwlogs/你的域名.error.log

    如果看到 client intended to send too large body: XXXXX bytes，说明 Nginx 仍在拦截。

  3. 检查所有配置文件

    grep -rn "client_max_body_size" /www/server/nginx/conf/ /www/server/panel/vhost/nginx/ 2>/dev/null

    注意宝塔面板的 include 目录和 WAF 配置可能有独立的限制。

  4. 终极方案：在 location ^~ / 块内部直接写 client_max_body_size 50000M;，强制覆盖。
  5. 检查是否有 Cloudflare 代理：如果 DNS 开了小黄云，免费版有约 100MB 上传限制，需改为“仅 DNS”或绕开。
  6. 确认 proxy_request_buffering off; 已生效：Immich 官方推荐，可避免大文件缓冲导致的问题。

  7. 改完配置后：

    nginx -t && nginx -s reload

八、S3 存储配置（以七牛云为例）

重要提示：实际测试中，Immich 原生 S3 支持与七牛云 S3 兼容层存在适配问题，配置后 Immich 可能静默回退到本地存储，日志中无 S3 痕迹。以下配置供参考，若无效建议改用本地存储 + 外部同步方案。

.env 中的 S3 配置

IMMICH_STORAGE_ENGINE=s3

S3_ENDPOINT=https://s3.cn-south-1.qiniucs.com
S3_BUCKET=你的S3空间名
S3_REGION=cn-south-1
S3_ACCESS_KEY_ID=你的AccessKey
S3_SECRET_ACCESS_KEY=你的SecretKey
S3_FORCE_PATH_STYLE=false

确认 S3 是否真的生效

进容器检查变量：

docker exec -it immich_server env | grep -E "S3|STORAGE"

上传一张新照片后看日志：

docker compose logs --tail=50 immich-server

如果日志里没有任何 S3 相关输出，说明 Immich 没有进入 S3 分支，文件仍存本地。

七牛 S3 的已知兼容性问题

  • 七牛分块上传要求除最后一块外，每块必须是 4MB 的整数倍，Immich 内部 SDK 可能不满足此规则
  • Immich 启动日志可能完全不提 S3，静默回退到本地
  • 建议先用 AWS CLI 验证桶可访问：aws s3 ls s3://你的桶名/ --endpoint-url https://s3.cn-south-1.qiniucs.com

替代方案

如果 Immich 原生 S3 走不通，可以：

  1. 继续用本地存储，用 rclone 定期把 library 目录同步到七牛（Immich 不管同步，七牛只做备份）
  2. 换用 Immich 社区验证过的 S3 服务商（如 Backblaze B2、MinIO）

九、地理位置中文化

Immich 默认用英文 GeoNames 数据，地点显示为英文。可借助社区项目 immich-geodata-cn 实现中文地名。

操作步骤

  1. 下载 geodata.zip 和 i18n-iso-countries.zip 并解压到 Immich 文件夹下的 geodata 和 i18n-iso-countries 目录。

  2. 在 docker-compose.yml 的 immich-server 服务 volumes: 下增加挂载：

    - ./geodata:/build/geodata
- ./i18n-iso-countries/langs:/usr/src/app/server/node_modules/i18n-iso-countries/langs

    （Immich 低于 1.136.0 时，第二行目标路径改为 /usr/src/app/node_modules/i18n-iso-countries/langs）

  3. 重启容器后，进入 系统管理 → 任务 → 提取元数据，点击“全部”触发刷新。之后地点会显示中文，并支持中文地名搜索。

该方案主要针对国内地点（含港澳台）完整汉化，海外地点目前仅实验性支持日本。

十、常用管理命令

# 进入 Immich 目录
cd /www/wwwroot/Immich

# 启动
docker compose up -d

# 停止
docker compose down

# 强制重建（修改 .env 后必须用这个）
docker compose up -d --force-recreate

# 查看服务状态
docker compose ps

# 查看服务器日志
docker compose logs --tail=50 immich-server

# 进入容器检查环境变量
docker exec -it immich_server env | grep -E "S3|STORAGE"

# 重载 Nginx（修改代理配置后）
nginx -t && nginx -s reload

十一、使用技巧

  • 搜索：支持自然语言，可组合时间、地点、人物、相机型号、星级筛选。中文语义搜索可换多语言 CLIP 模型。
  • 批量导入：大量历史照片可用官方 immich-cli 或社区工具 immich-go 批量上传，支持按文件夹自动建相册。
  • 小内存服务器调优：在 .env 加 MACHINE_LEARNING_REQUEST_THREADS=2、MACHINE_LEARNING_MODEL_TTL=120，限制 AI 并发并让模型闲置后释放内存。
  • 分享：可生成带密码和有效期的相册分享链接，适合临时给他人查看，默认图库仍为私有。
  • EXIF：Immich 不修改原始文件，下载的照片保留原始 EXIF；在界面里改的日期/地点不会写回文件。

十二、重要提醒

  1. 密钥安全：.env 里的 S3 密钥、数据库密码不要泄露。如果曾经贴到公开对话中，建议去服务商控制台重新生成。
  2. 备份：Immich 不是备份工具。定期备份 ./library 和 ./postgres，最好再有一份离线或异地副本。
  3. 版本匹配：手机 App 与服务端大版本需大致匹配，避免连接异常。
😊
提交