数据库死锁？Immich 环境变量 DB_PASSWORD 随机化导致的登录失败复盘。

很多开发者在第一次部署 Immich 时，为了图省事，往往直接从官方示例里拷贝 docker-compose.yml 和 .env。但就在你满心欢喜地看到所有容器都显示 Up，准备打开 Web 页面登录时，现实会给你一记响亮的耳光：网页提示 Invalid Credentials，或者后台日志疯狂报错 PostgreSQL: password authentication failed for user "postgres"。

作为一名在数据库坑里摸爬滚打多年的架构师，我得告诉你：这通常不是你密码记错了，而是被 Immich 初始安装脚本中那个“自作聪明”的 DB_PASSWORD 随机化逻辑 给坑了。

💡 报错现象总结：容器启动正常，但 immich_server 无法连接数据库。后台日志显示 Error: connect ECONNREFUSED 或 password authentication failed。即便你手动修改了 .env 里的密码并重启，报错依然持续，整个系统处于“半死不活”的数据库连接死锁状态。

---

随机密码的“单向协议”：为什么改了 .env 也没用？

在 Immich 的推荐安装脚本中，系统为了安全性，会在初次生成 .env 时随机产生一个 DB_PASSWORD。

问题的核心在于：PostgreSQL 容器仅在 vols 文件夹（持久化数据卷）第一次初始化时读取这个密码。 一旦数据库文件夹被创建，密码就被固化在了 PG 的系统表里。此时，如果你觉得随机密码太难记，手动去修改了 .env 文件，那么恭喜你，你制造了一个无法对齐的“鉴权断层”。

# 典型的报错现场：.env 里的密码与 PG 镜像内存储的密码不一致
immich_server | [Nest] 7 - 04/28/2026, 11:47:39 AM ERROR [TypeOrmModule] 
Unable to connect to the database. Retrying (1)...
Error: password authentication failed for user "postgres"

状态阶段	.env 文件中的密码	PG 数据卷内的密码	结果
初次启动	random_pw_123	(空) -> 写入 random_pw_123	成功连接
手动修改后	my_easy_password	random_pw_123	401 Unauthorized
删除容器重启	my_easy_password	random_pw_123	持续失败

---

深度排雷：pg_hba.conf 与环境变量的错位

Immich 的微服务高度依赖 immich_postgres。当 immich_server 尝试连接时，它通过环境变量获取密码。如果这两者脱节，由于 Immich 的重试机制非常激进，高频的失败连接尝试有时甚至会触发数据库的连接保护，导致即便你改回了正确密码，短时间内依然无法连接。

此外，如果你在同一个宿主机上多次尝试部署，残留的 docker volume 会带着旧密码阴魂不散地挂载到新容器上，这就是为什么很多小白“删了重装”十几次依然无解。

---

填坑实战：如何暴力打通数据库认证？

如果你已经陷入了这个密码陷阱，硬核开发者常用的“原生态”抢救手段极其繁琐：

1. 物理清除数据卷：执行 docker compose down -v。注意，这会彻底抹除你的所有配置。如果你的照片已经导进去了，这一步等同于自杀。
2. 进入容器内部修库：你需要使用 docker exec -it immich_postgres psql -U postgres。但讽刺的是，因为密码不对，你可能连进都进不去。
3. 临时修改 trust 模式：你得手动挂载一个自定义的 pg_hba.conf 到容器内，将认证模式改为 trust 以免密进入，修改完密码后再改回来。这种操作对非 DBA 玩家来说简直是噩梦。

---

降维打击：领取“Immich 配置安全自检工具”

与其在各种配置冲突中反复折磨自己的硬盘和血压，不如在部署前就给系统做个体检。

我已经针对环境变量冲突和数据库初始化问题，在 GitCode 维护了一个**《Immich 配置安全自检工具》**。这个脚本可以在你启动容器前，自动比对 .env 变量与持久化卷的一致性，并能一键修复那些因“随机密码”导致的连接死锁，无需删除任何照片数据。

直接前往 GitCode 领取这份自检工具。别让一个小小的密码变量毁了你一整天的心情，用最稳妥的架构逻辑，守护你的相册数据库。

[领取 GitCode 《Immich 配置安全自检工具》]