手把手教你用Docker搭建本地图片档案系统Immich

一、环境准备与依赖安装

在开始搭建之前，你需要准备一台Linux服务器（推荐Ubuntu 20.04或更高版本）或本地电脑。Immich基于Docker容器化部署，因此必须先安装Docker和Docker Compose。以下命令可直接复制执行，无需任何额外配置。

1. 安装Docker

执行以下脚本自动安装最新版Docker：

curl -fsSL https://get.docker.com | sh

安装完成后，将当前用户添加到docker组，避免每次使用sudo：

sudo usermod -aG docker $USER
newgrp docker

2. 安装Docker Compose

虽然新版Docker集成了compose插件，但为了确保兼容性，建议单独安装独立版Compose：

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

验证安装是否成功：

docker-compose --version

二、创建项目目录结构

为了规范管理，我们在/usr/local/目录下创建immich专属文件夹，并规划好数据存储路径。这一步非常重要，直接关系到后续数据的持久化。

cd /usr/local/
mkdir immich
cd immich

创建必要的子目录用于存放上传的照片、数据库文件和日志：

mkdir -p {library,upload,postgres,redis,backup}

三、编写配置文件

这是整个搭建过程的核心。我们将创建docker-compose.yml和.env两个文件。请务必严格按照以下内容复制，不要遗漏任何配置项。

1. 创建环境变量文件 .env

在/usr/local/immich目录下创建.env文件，填入以下内容。这些变量定义了数据库密码、上传路径等关键信息：

 你可以自行修改数据库密码，请务必保存好
DB_PASSWORD=immich_admin_password_change_me
设置上传文件的存储目录，对应刚才创建的upload文件夹
UPLOAD_LOCATION=./upload
设置日志级别
LOG_LEVEL=info
禁用遥测数据上报（可选，建议关闭）
DISABLE_TELEMETRY=true

2. 创建编排文件 docker-compose.yml

在同级目录下创建docker-compose.yml文件。该文件定义了Immich运行所需的所有服务组件（Web、Server、Microservices、Database、Redis）。为了确保稳定性，这里使用固定的镜像版本标签：

version: "3.8"
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:v1.118.0
command: ["start-server", "sleep", "9999"]  保持容器运行
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
depends_on:
- redis
- database
restart: always
immich-microservices:
container_name: immich_microservices
image: ghcr.io/immich-app/immich-server:v1.118.0
command: ["start-microservices"]
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
depends_on:
- redis
- database
restart: always
immich-web:
container_name: immich_web
image: ghcr.io/immich-app/immich-web:v1.118.0
env_file:
- .env
restart: always
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:v1.118.0
volumes:
- model-cache:/cache
env_file:
- .env
restart: always
database:
container_name: immich_postgres
image: tensorchord/pgvecto-rs:pg14-v0.2.0
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: immich
POSTGRES_DB: immich
volumes:
- ./postgres:/var/lib/postgresql/data
restart: always
redis:
container_name: immich_redis
image: redis:6.2-alpine
restart: always
proxy:
container_name: immich_proxy
image: ghcr.io/immich-app/immich-proxy:v1.118.0
environment:
- SERVER_URL=http://immich-server:3001
ports:
- 2283:8080
depends_on:
- immich-server
- immich-web
restart: always
volumes:
model-cache:

四、启动服务与初始化

配置文件准备好后，即可拉取镜像并启动服务。首次启动需要下载约1GB左右的镜像文件，请耐心等待。

1. 启动所有容器

在/usr/local/immich目录下执行：

docker-compose up -d

使用以下命令查看容器状态，确保所有服务均为Up (healthy)状态：

docker-compose ps

2. 访问Web界面

打开浏览器，访问http://服务器IP:2283。如果是本地服务器，则访问 http://localhost:2283。

3. 注册管理员账号

首次访问会提示创建管理员账号。输入你的邮箱和密码，点击Sign Up即可完成初始化。此时，Immich已经完全就绪，可以开始使用了。

五、核心功能实操配置

登录系统后，为了获得最佳体验，建议立即进行以下几项关键设置。

1. 启用外部库（可选）

如果你已经在NAS或服务器上存储了大量照片，无需手动上传，可以使用外部库功能直接索引。

操作步骤：

• 点击左下角Administration -> External Libraries。
• 点击Create New Library。
• 在Name处输入库名（如“NAS_Photos”）。
• 在Import Paths处填入服务器上的绝对路径，例如：/mnt/nas/photos。
• 注意：必须确保Docker容器有权限访问该路径。通常需要在docker-compose.yml的volumes中添加映射：- /mnt/nas/photos:/mnt/nas/photos:ro（只读模式更安全）。
• 保存后，点击Scan Files开始导入。

2. 配置存储路径与备份

默认情况下，所有上传的照片都存储在/usr/local/immich/upload目录。为了防止数据丢失，建议定期备份该目录以及PostgreSQL数据库。

数据库备份命令：

docker exec immich_postgres pg_dump -U immich immich > backup_$(date +%Y%m%d).sql

3. 开启AI智能分类

Immich内置了机器学习模型，可自动识别照片中的人脸、物体和场景。确保immich-machine-learning容器正常运行后，系统会自动在后台处理新上传的照片。你可以在Explore页面查看自动分类好的结果（如“风景”、“动物”、“建筑”）。

六、常见维护与故障排查

1. 更新Immich版本

当有新版本发布时，执行以下命令更新。注意更新前务必备份数据。

cd /usr/local/immich
docker-compose pull
docker-compose up -d

2. 重置管理员密码

如果忘记密码，可以通过命令行重置。首先进入server容器：

docker exec -it immich_server /bin/sh

然后执行：

npx immich-cli admin-reset-password

按照提示输入新邮箱和密码即可。

3. 端口被占用处理

如果2283端口被其他程序占用，需要修改docker-compose.yml中proxy服务的ports配置，例如改为8080:8080，然后重启服务：

docker-compose down
docker-compose up -d