Immich .env 配置详解：UPLOAD_LOCATION 数据库密码与版本锁定

.env 文件是 Immich 部署的「控制面板」，改动它比改 compose 文件安全得多。这一页把官方示例里每个值得关心的变量讲透。

必须改的变量

UPLOAD_LOCATION —— 照片库的家。所有原始照片、视频、缩略图、数据库备份都放这里。给它的三点建议：指向一个新建的空目录；确保空间按照片库规模的 1.2 倍估算（缩略图与转码占 10–20%）；放在本地大容量盘上。日后照片库迁移，搬的就是这个目录。

DB_DATA_LOCATION —— Postgres 数据文件位置。要求非常苛刻：必须是支持用户/组权限的 Unix 式文件系统（EXT4、ZFS、APFS、BTRFS、XFS），绝不能是 NTFS/exFAT，也不能是网络挂载盘。数据库文件通常 1–3GB，放本地 SSD 最理想。

Windows/WSL2 专改：上面这条规则在 WSL2 里会撞墙——/mnt/c/... 这类宿主挂载路径都不满足条件。官方给出的解法是改用 Docker 命名卷：

# .env 里：
- DB_DATA_LOCATION=./postgres
+ DB_DATA_LOCATION=pgdata

# docker-compose.yml 末尾 volumes 段加一行：
+ pgdata:

DB_PASSWORD —— 数据库密码，装好后立刻改掉。官方特别提醒：只用字母和数字（A–Z、a–z、0–9），不加特殊字符或空格——Docker 解析环境变量时特殊字符容易出幺蛾子。这个密码只用于容器内部认证，不对外暴露，但规范起见也别用默认值。

建议顺手改的变量

TZ —— 时区。默认注释状态（UTC），建议去掉 # 改成 TZ=Asia/Shanghai。时区影响回忆页「当年今日」的划分和任务计划时间。

IMMICH_VERSION —— 版本线。v3 表示自动跟随 v3 的最新小版本；也可以钉死成具体号（如 v3.2.0）求稳。改大版本时就是改这一行，见 版本升级。

不用动的变量

DB_USERNAME=postgres
DB_DATABASE_NAME=immich

这两个保持默认即可，改动反而容易和 compose 文件里的引用对不上。

改完之后

每次修改 .env 都要重启容器生效：docker compose up -d（会自动重建受影响的容器）。如果想进阶，Immich 还支持用 immich.json 配置文件覆盖更多系统设置，以及 硬件转码 时要加的 hwaccel.transcoding.yml——那些都属于部署跑通之后的优化项，第一遍部署别碰。

配置就绪后回到 Docker Compose 部署 完成启动，或继续看 注册首个管理员。