Immich项目机器学习容器启动失败的排查与解决

问题现象

在Immich项目升级到v1.131.x版本后，用户报告机器学习容器(Immich-Learning)无法正常启动。容器日志显示重复出现[FATAL tini (7)] exec ./start.sh failed: No such file or directory错误，而此前v1.130.x版本运行正常。

环境背景

该问题出现在Synology DSM 7.2.1系统上，通过Portainer管理容器。相关组件包括：

• Redis数据库容器
• PostgreSQL数据库容器(pgvecto-rs扩展)
• Immich主服务容器
• Immich机器学习容器

根本原因分析

从错误信息判断，容器启动时无法找到start.sh脚本文件。这种情况通常由以下几种原因导致：

1. 镜像文件损坏或不完整
2. 容器文件系统权限问题
3. 镜像版本与启动脚本不兼容
4. 缓存导致的旧版本残留

解决方案

经过验证，完整的解决步骤如下：

1. 停止整个服务栈
   必须确保所有相关容器都已停止，避免文件锁定或资源冲突。

2. 删除机器学习镜像
   使用docker rmi ghcr.io/immich-app/immich-machine-learning:release命令彻底移除旧镜像。

3. 重新拉取镜像
   在docker-compose up时会自动拉取最新版本的镜像。

4. 重启服务栈
   使用docker-compose up -d重新启动所有服务。

技术原理

该问题的本质在于Docker的层缓存机制。当仅重新创建容器而不删除镜像时，Docker可能会重用缓存的旧镜像层。完全删除镜像可以确保获取全新的文件系统结构，包含正确的启动脚本。

预防措施

为避免类似问题，建议：

1. 在升级前先停止相关服务
2. 使用docker-compose pull确保获取最新镜像
3. 定期清理未使用的镜像和容器
4. 重要升级前备份关键数据

总结

Immich作为多媒体管理项目，其机器学习组件对系统环境较为敏感。遇到容器启动失败时，完整的镜像更新流程往往能解决大多数文件缺失或版本不兼容问题。此案例也提醒我们，在容器化部署中，完整的生命周期管理(停止→清理→更新→重启)比简单的重启操作更可靠。