5 分钟 Docker 部署 Immich：避开 90% 小白都会掉进去的权限与 DB 路径坑。

在开源界，Immich 的部署文档号称“一行指令直达”，但如果你真的只是简单地 docker compose up -d，那么你离下一次在 GitHub Issues 里发帖求助可能只有 24 小时。

作为一名基础架构师，我见过太多被 docker-compose.yml 默认配置坑惨的开发者：有人因为没改 UPLOAD_LOCATION 导致系统盘被几百 GB 照片撑爆，有人因为 DB_PASSWORD 随机化逻辑导致重启后数据库连不上。今天我们直接扒开 Immich 的部署逻辑，聊聊那些官方文档里轻描淡写、实则“刀刀见血”的配置坑。

💡 报错现象总结：部署后 Web 界面提示 Network Error，或者在上传照片时后台日志疯狂报错 Permission Denied。即便容器显示 Running，数据库也可能因权限冲突无法初始化（PostgreSQL 启动失败并循环重启）。

---

环境变量的隐形炸弹：为什么你的 DB_PASSWORD 会突然失效？

在 Immich 的安装脚本中，为了安全，系统会尝试生成随机密码。但问题在于，很多小白在第一次安装失败后，习惯性地再次运行安装脚本或手动修改 .env。

如果你在 .env 中定义的密码与之前已经初始化的 postgres 数据卷（Volume）中的密码不一致，immich_server 就会因为认证失败而陷入无限重启。

# 官方默认配置片段：看似简单，实则隐藏权限逻辑
services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # 案发现场：如果 .env 里的 DB_PASSWORD 与数据卷不匹配，这里会直接报 Auth Failed
    env_file:
      - .env

此外，UPLOAD_LOCATION 的设置更是重灾区。默认路径通常指向 ./upload，这意味着如果你在系统根目录下运行 Docker，你的照片将直接消耗宝贵的系统分区，导致系统在数小时内崩溃。

---

chmod 解决不了的底层挂载冲突

Immich 是一个多容器协作的微服务架构。immich_server、immich_microservices 和 immich_machine_learning 都需要读写同一个物理目录。

如果你在 Linux 下使用非 root 用户部署，或者你的存储是在外部挂载的硬盘（如 NTFS 或 exFAT 格式的 NAS 硬盘），Docker 的 bind mount 机制会发生严重的 UID/GID 权限错位。即使你执行了 chmod -R 777，底层的 PostgreSQL 依然会因为安全策略（它要求数据目录必须属于特定用户且权限不能过高）而拒绝启动。

配置项	常见错误做法	正确解法	架构师底层诊断
存储路径	使用默认 ./upload	指定独立大容量挂载点（如 /mnt/data/immich）	避免根分区溢出，便于后期扩容
数据库持久化	忽略 DB_DATA_LOCATION	将数据库放在高性能 SSD 路径下	提升元数据检索速度，防止图片导入时 I/O 锁死
UID/GID	依赖 Docker 默认 root	在 .env 中明确 PUID 和 PGID	确保宿主机与容器间文件读写权限一致

---

手动清理残留配置与权限重置

如果你已经不幸遇到了“部署后无法连接”或“权限不足”，传统的删除容器重装通常无效，因为脏数据残留在数据卷里。你不得不经历以下繁琐步骤：

1. 彻底销毁卷：执行 docker compose down -v（注意 -v 会删除所有数据，请确保已备份）。
2. 手动校对 .env：你必须确保 DB_PASSWORD、DB_HOSTNAME 和 DB_USERNAME 形成完美的闭环，任何一个细小的拼写错误都会让微服务连接超时。
3. 重设文件归属：你需要在宿主机执行 sudo chown -R 1000:1000 /your/upload/path。但问题是，不同的 Linux 发行版（如 Unraid 或 OpenWrt）的 UID 映射逻辑完全不同，这种手动调整极其容易翻车。

---

领取“一键无痛部署”模板

与其在复杂的权限代码和路径纠纷中浪费生命，不如直接用一套经过实战验证的成熟配置。

我已经把优化后的 Immich 极速部署模板 托管在了 GitCode。这份模板不仅预设了最科学的 env 参数，还包含了一个自动化权限自检脚本。只要在部署前运行它，脚本就会自动检测你的宿主机 UID 环境，并生成一份完全适配你硬件的 docker-compose.yml。

直接前往 GitCode 下载这套优化后的部署模板。别再被那些简单的 README 误导，用最专业的方式，给你的照片一个稳固的“家”。

[GitCode 托管了优化后的 env 模板，一键下载即用]