部署Portainer堆栈时提示镜像不存在但实际镜像已存在的异常

问题详情 #

• 通过Portainer部署来自GitHub的docker-compose堆栈时，触发镜像拉取操作就会报错Error: No such image，但镜像已存在本地时部署正常
• 已确认涉及的镜像均存在于Docker Hub
• 可通过Portainer对应环境的「images」标签手动成功拉取这些镜像
• 开发机器上手动运行该docker-compose文件完全正常，删除本地镜像后会自动重新下载
• 问题今日突发，此前Portainer运行正常
• 3个差异较大的环境均出现此问题，SSH登录环境后手动拉取GitHub的docker-compose运行无异常，问题仅出在Portainer操作流程中

可能的解决方案 #

1. 重启Portainer容器 #

Portainer可能出现临时进程异常，直接重启容器尝试恢复：

docker restart portainer

2. 清理Portainer缓存 #

Portainer的缓存可能出现识别异常，可通过以下操作清理：

• 进入Portainer的「Settings」页面，找到并清理应用缓存
• 若缓存清理无效，可删除Portainer数据卷后重新部署（注意备份重要配置）：

  docker stop portainer
  docker rm portainer
  docker volume rm portainer_data
  # 重新启动Portainer
  docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest
  

3. 检查镜像名称规范 #

确认docker-compose文件中的镜像名称完全符合Docker Hub规范：

• 避免遗漏镜像标签（默认latest但部分镜像需明确指定）
• 检查是否存在大小写错误（Docker Hub不区分大小写，但Portainer可能存在识别偏差）

4. 回退Portainer版本 #

若近期Portainer自动更新过版本，可能存在兼容性问题，可回退到之前正常运行的版本：

# 替换为之前正常的版本号，比如2.19.0
docker stop portainer
docker rm portainer
docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:2.19.0

内容的提问来源于stack exchange，提问作者melchoir55