3 级日志排查法搞定 Immich 静默故障自托管照片管理排错实战【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich手机里的照片一直卡在正在备份…网页端点进去没有报错服务面板上所有绿灯也都亮着——Immich 自托管部署最容易让人崩溃的恰恰是这种不声不响的失败。本文用「快检 → 定向排查 → 深度定位」3 级排查法带你靠容器日志把备份失败、数据库连不上、ML 服务超时这 5 类高频故障一个个揪出来。问题地图先确认故障属于哪一类Immich 由多个独立容器组成immich_serverNestJS 后端、immich_machine_learningPython ML 服务、immich_webSvelteKit 前端、immich_postgres和immich_redis。日志分散在各自的 stdout 里所以排查前先把症状对号入座能省一半力气。故障类别典型表象涉及组件数据库连接失败网页一直转圈或 500备份请求无响应immich_server、immich_postgres存储路径异常媒体文件写入失败缩略图加载不出来immich_server UPLOAD_LOCATIONML 服务超时人脸聚类、CLIP 搜索不工作任务队列堆积immich_machine_learning前端 500 错误页面白屏浏览器控制台报 API 调用失败immich_web、immich_server排查工具箱先备好这三样确认部署方式。本文命令基于 docker compose 部署官方推荐路径如果你是用 install.sh 一键装的命令完全一致只是工作目录在 install.sh 所在目录。确认全部容器在运行。在部署目录执行docker compose ps --format table {{.Name}}\t{{.Status}}预期看到immich_server、immich_machine_learning、immich_web均显示Up。任何容器反复重启先单独docker compose logs 容器名看它自己的日志。确认媒体目录存在且有写权限。编辑.env把UPLOAD_LOCATION指向一个真实存在的目录docker/example.env 里有默认值./library然后验证test -w ./library echo OK预期输出OK。没有输出或提示 not a directory就是备份写入失败的常见根因之一。确认服务端口可访问。immich_server默认监听2283curl -I http://localhost:2283/api/server/ping预期返回HTTP/1.1 200 OK。404 说明后端活着只是路由不对Connection refused 才说明后端没起来。三级排查法从 5 分钟快检到深度定位第 1 级 · 快检5 分钟排除低级问题三个动作每个都只有正常 / 不正常两种结果。看后端最近 100 行日志扫一眼有没有ERRORdocker compose logs --tail100 immich_server预期滚动输出以WARN/LOG为主没有成片的ERROR。看到 ERROR 直接记下行首的时间戳跳去第 2 级按时间过滤。看 ML 服务是否在正常响应。ML 服务挂在3001端口curl -s http://localhost:3001/health预期返回一段 JSON 而非空响应或超时。超时说明 gunicorn 进程没就绪docker compose restart immich_machine_learning后再测一次。确认前端容器能连到后端。immich_web容器内部是通过服务名访问 API 的docker compose exec immich_web wget -qO- http://immich_server:2283/api/server/ping预期返回 JSON 字符串。失败的话说明容器网络有问题docker compose down docker compose up -d重建整个网络环境。第 2 级 · 定向排查按组件过滤日志快检没命中就按嫌疑组件逐条过滤每条命令对应一个明确嫌疑。嫌疑 A数据库连不上docker compose logs immich_server | grep -i ECONNREFUSED\|connect.*postgres关键含义如果出现 connection refused说明immich_postgres当时没启动或.env里DB_PASSWORD与数据库初始化时用的不一致——后者改密码没用得重建数据库目录。嫌疑 B媒体文件读写失败docker compose logs immich_server | grep -i EACCES\|permission\|ENOENT关键含义EACCES指向权限ENOENT指向目录不存在两者修法都是回.env核对UPLOAD_LOCATION和宿主机目录的实际属主权限。嫌疑 CML 服务超时或无响应docker compose logs immich_machine_learning | grep -i timeout\|error | tail -20关键含义大量超时通常意味着镜像里的模型没加载完或服务根本没起来docker compose pull immich-machine-learning docker compose up -d immich_machine_learning强制更新后观察启动日志是否走完加载流程。嫌疑 D主机内存不足journalctl -k --since 1 hour ago | grep -i oom关键含义出现 oom-killer 记录说明容器是被主机杀掉而不是自己崩溃的这是调大 swap 或降并发的问题不是代码问题。第 3 级 · 深度定位调高日志级别复现前面都排除了就打开显微镜。在.env里加一行IMMICH_LOG_LEVELdebug然后docker compose up -d immich_server重启后重新执行一次失败的操作比如点一次备份、触发一次人脸聚类把新产生的 debug 日志存下来docker compose logs --since 10m immich_server debug-server.log预期日志量明显变大能看到每次请求的入参和内部流转。注意级别可选值为verbose、debug、log、warn、error、fatalserver/src/enum.ts 中的LogLevel定义debug 已经够用。⚠️排查完记得回滚删掉IMMICH_LOG_LEVEL那行再重启一次恢复默认warn。debug 日志量大长期开着既耗磁盘也会把敏感信息写进日志。另外也可以不用改文件Web 端 Admin → System Settings 里同样能临时调整日志级别改完同样要复原。高频报错速查表日志关键字/报错片段大概率原因30 秒修法connect ECONNREFUSED 127.0.0.1:5432postgres 容器未起或.env端口/账号不匹配docker compose ps确认 postgres 状态核对.env数据库段EACCES: permission denied, open /usr/local/app/library/...媒体目录属主或权限不对修正宿主机目录属主或换一个新的UPLOAD_LOCATIONError connecting to the ML serviceML 容器没起来或模型仍在加载docker compose restart immich_machine_learning30 秒后重测/healthAddress already in use宿主机 2283 端口被旧实例或别的服务占用关掉占端口的旧容器或改 compose 里的端口映射Too many open files后端文件句柄没及时释放常见于大库重启immich_server并检查主机ulimit -n设置如果以上都没命中问题大概率比较罕见下一步去 Immich 官方社区Discord或仓库 Issue 区求助。发问前先贴三样东西出问题的精确时间窗口、对应时间段的日志片段、Immich 版本号docker compose exec immich_server npm run immich:version或直接看 compose 里的镜像 tag能省掉来回追问的时间。预防性维护清单升级前先记下当前版本号docker compose config --images方便出问题一键回退。定期清一下容器日志防止日志把磁盘写满docker compose exec immich_server npm run immich:cleanup预期无输出即执行成功这是 Immich 自带的媒体清理工具顺手也清掉了失效的缓存文件。把.env纳入你自己的定期备份——里面是DB_PASSWORD和存储路径丢了重建成本很高。每次重启/升级后跑一遍本文第 1 级快检的三条命令30 秒的事能拦下大部分升级后才发现的坑。日志不会撒谎它只是在等你问对问题。提示提交 Issue 时附上最小信息清单——脱敏后的.env配置、故障时间段的日志片段、Immich 版本号处理速度会快很多。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考