Immich 日志调试速查手册：5 步定位 90% 的自托管问题
Immich 日志调试速查手册5 步定位 90% 的自托管问题【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich手机 App 弹出备份失败网页端却一片祥和docker compose logs一刷几百行看不懂的堆栈滚过去——这个坑我踩过当时浪费了一整个晚上。这套 Immich 日志调试流程覆盖数据库、存储权限、机器学习服务、备份卡点四类高频故障每条分支都给了可直接粘贴的命令跟着走大部分问题 10 分钟内能定位。Immich 排查全景一张决策路径先别翻代码按症状对号入座从对应分支开始查日志刷Connection refused/ECONNREFUSED→ 数据库连通分支 A约 2 分钟出现EACCES: permission denied或备份卡 0% 且 upload 目录是空的 → 存储路径权限分支 B约 3 分钟ML 容器反复重启、日志见Timeout人脸/OCR 集体失效 → 机器学习服务分支 C约 5 分钟备份失败但日志干净得可疑 → 主动调高 Immich 日志级别再复现分支 D约 5 分钟以上全排除、页面变卡 → 查资源占用与日志级别残留工具节 自查清单约 3 分钟看到 Connection refused三步恢复 Immich 数据库连通最小复现docker compose ps docker compose logs immich-server --tail50 | grep -iE refused|ECONNREFUSED docker compose logs immich-postgres --tail30 | grep -i ready to accept判定标准server 侧出现ECONNREFUSED 127.0.0.1:5432而 postgres 侧迟迟没有ready to accept connections问题确认两者都正常则排除本分支。修复绝大多数情况是 server 容器先于 postgres 就绪、启动即退出调整重启顺序即可docker compose up -d immich-postgres docker compose up -d immich-server同时核对docker/example.env里DB_POSTGRES_PASSWORD与.env是否一致——这个坑我踩过改密码只改了一边报的也是同一个 refused。原因是 server 用.env凭据握手密码不匹配时 postgres 直接断开日志表象和端口不通一模一样。看到 permission denied修复 Immich 存储路径权限最小复现docker compose exec immich-server id ls -ld /path/to/your/upload # 换成 .env 中 UPLOAD_LOCATION 的主机路径判定标准主机目录的属主与容器内进程 uid 不一致且日志有EACCES: permission denied问题确认。修复sudo chown -R uid:gid /path/to/your/uploaduid和gid取自第一步id命令的输出。原因容器以固定 uid 写盘宿主机目录归属不符时缩略图和原图都写不进去备份进度永远停在个位数百分比。不想动权限的话也可以在 compose 里把绑定挂载换成命名卷让 Docker 自己管权限代价是目录位置不透明。看到 ML 超时恢复 Immich 机器学习服务最小复现docker compose ps immich-machine-learning docker compose logs immich-machine-learning --tail50 | grep -iE error|timeout|exiting判定标准容器状态反复Restarting或日志出现WORKER TIMEOUT/Worker exiting问题确认容器Up且日志干净则排除。修复低配机器加载模型超过默认 300 秒超时是最高频原因在.env中新增MACHINE_LEARNING_WORKER_TIMEOUT900 MACHINE_LEARNING_WORKERS1然后docker compose up -d immich-machine-learning。原因是 worker 加载 CLIP/人脸模型时内存吃紧会被 gunicorn 直接杀掉加宽超时、单 worker 运行先保命跑通后再调回默认值。若日志是model download失败那是网络拉不到模型给容器配代理或预热缓存目录即可别再调参数。备份失败无报错调高 Immich 日志级别定位卡点最小复现docker compose logs immich-server --tail200 | grep -iE backup|asset判定标准默认级别下 grep 不到任何相关输出、日志干净到可疑说明当前级别不够需要调高后复现一次备份。修复在.env中临时设置IMMICH_LOG_LEVELdebug IMMICH_LOG_FORMATjson MACHINE_LEARNING_IMMICH_LOG_LEVELdebugdocker compose up -d immich-server后复现操作。JSON 格式里level:3就是 error直接 grep 这个字段比翻彩色文本快得多。管理面板的系统设置里也有日志入口可以不重启容器改级别适合只调 server 的场景。排查完务必改回warn——debug 日志量是正常值的数倍跑一天能把磁盘 IO 拖垮这个坑我踩过。Immich 横向工具与调试技巧日志 grep 三件套过滤错误docker compose logs immich-server | grep -E ERROR|FATAL只看真正错误行。导出归档docker compose logs --tail1000 immich-debug-logs.txt报 issue 前一步到位。盯实时docker compose logs -f immich-server改完配置立刻看下一行输出是否符合预期。健康检查端点不登界面、不翻日志的快速判活curl http://localhost:2283/server/ping返回 JSON 即 server 存活ML 侧用ss -ltnp | grep 3003确认 3003 端口在监听。两个端点都通而功能仍异常问题基本落在数据层。管理面板日志入口server 的日志级别除了环境变量还能在管理面板系统设置里在线修改。注意一旦.env里写了IMMICH_LOG_LEVEL面板设置会被锁定这是设计如此避免两处配置打架。✅ Immich 自查清单改完配置重启后逐条打勾.env中DB_POSTGRES_PASSWORD与 postgres 容器实际密码一致UPLOAD_LOCATION主机路径存在、可写、属主正确2283server、3003ML端口均在监听且无冲突ML 模型缓存目录可写宿主内存余量足够无 OOM 记录dmesg | grep -i oom排查结束后日志级别已改回warn复现一次备份并确认 App 端进度 100%清单全部打勾仍未解决带着immich-debug-logs.txtserver ML 两侧和.env脱敏片段去提 issue附上 Immich 版本、部署方式和上面对应的分支编号基本不会再被反问日志呢。注提交 issue 前请移除.env中的密码、密钥与内网 IP日志导出文件里可能含相册路径与设备名同样需要脱敏。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
