Docker-Compose：部署堆栈失败：服务指向未定义的卷 – 解决方案

有时，本机或通过 Portainer 启动 Docker Compose Stack 时会出现以下错误信息：

Failed to deploy a stack: service "docker" refers to undefined volume mnt/docker: invalid compose project

如果 Docker Compose 文件中定义的卷未正确指定或指向的目录不存在，就会出现错误 “Failed to deploy a stack: service ‘docker’ refers to undefined volumemnt/docker: invalid compose project”。

错误描述

出现该错误的原因通常是Docker Compose 文件(docker-compose.yml) 中的卷路径或卷标签有误：

• 格式不正确、
• 不存在或
• 没有明确界定。

错误信息显示卷mnt/docker未正确定义或引用。这意味着 Docker Compose 无法解析或创建指定路径。

可能的原因

1. 缺少前导斜线：卷的路径不是以”/“开头。这会导致 Docker 将路径解释为相对路径，这是不正确的。
2. 目录不存在： 主机系统上不存在指定的目录路径(/mnt/docker)。
3. 输入错误或语法错误：路径或组成文件中的输入错误导致定义不正确。
4. 卷定义丢失或位置不正确：如果使用命名加密卷，则必须在组成文件中的volumes:下进行定义。

解决方案步骤

1. 检查并更正音量路径

• Docker Compose 文件中的路径应绝对正确。
• 确保主机系统中存在该路径。

例如

services:
  my_service:
    image: my_image:latest
    volumes:
      - /mnt/docker:/data

确保/mnt/docker存在。如果不存在，请使用命令创建：

sudo mkdir -p /mnt/docker

2. 检查路径是否有输入错误

注意音量规范中可能存在的打字错误，并予以纠正。

错了

无前导”/”

volumes:
  - mnt/docker:/data

正确：

前导”/”

volumes:
  - /mnt/docker:/data  

3. 正确使用命名卷

如果要使用命名卷，必须在 Compose 文件的volumes:下明确定义：

已命名卷的示例

version: '3'

services:
  app:
    image: my_image:latest
    volumes:
      - mydata:/data

volumes:
  mydata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/docker

这里定义了名为mydata的卷，并链接到路径/mnt/docker。设备字段应指向现有目录。

4. 确保目录存在，并有正确的授权

检查授权和目录是否存在。Docker 必须能够访问指定路径并向其写入内容：

ls -ld /mnt/docker

应确保路径存在且可读/可写。如果不存在，则相应设置授权：

sudo chmod 755 /mnt/docker
sudo chown $USER:$USER /mnt/docker

5. 检查 Docker Compose 版本

确保使用的 Docker Compose 文件与安装的 Docker Compose 版本一致。使用第 3 版或更高版本才能使用命名卷和其他高级功能。

如果没有正确定义卷或路径不正确，就会出现 “service ‘docker’ refers to undefined volumemnt/docker“（服务’docker‘指向未定义的卷mnt/docker）错误。通常，只要仔细检查并更正 Docker Compose 文件和目录结构，确保正确定义了已命名的卷，就能解决这个问题。