Docker Compose执行报错：未知锚点'mayan-container'引用问题排查

可能的错误原因 #

• 锚点定义顺序颠倒：如果引用锚点的服务写在x-mayan-container扩展字段之前，YAML解析器还未读取到锚点定义，就会抛出未知锚点错误。
• 锚点语法错误：定义锚点时必须使用&前缀（如&mayan-container），若漏写或引用时误用符号（比如用&代替*），会导致解析失败。
• 扩展字段引用方式错误：docker-compose中引用扩展字段的锚点，需用<<: *mayan-container来合并配置，直接使用*mayan-container仅适用于单个值的引用，不适用于配置块。
• 缩进格式问题：YAML对缩进敏感，混用空格与Tab、缩进层级不匹配，会导致解析器无法识别锚点定义。
• docker-compose版本兼容问题：旧版本docker-compose对YAML锚点的支持存在bug，可能无法正确解析扩展字段中的锚点。

解决步骤 #

1. 调整锚点定义顺序：将x-mayan-container扩展字段移至所有引用它的服务之前，确保解析器优先读取锚点。
2. 校验锚点语法：
   • 定义锚点示例：

     x-mayan-container: &mayan-container
       image: mayan-edms:latest
       volumes:
         - mayan_data:/var/lib/mayan
       environment:
         - DB_HOST=postgres
     

   • 引用锚点示例：

     services:
       mayan-web:
         <<: *mayan-container
         ports:
           - "8000:8000"
     

3. 检查文件格式：使用统一的2个空格缩进，避免混用Tab与空格。可通过yamllint docker-compose.yaml命令检测格式问题。
4. 升级docker-compose版本：执行docker-compose --version查看当前版本，升级至最新稳定版（如通过pip install --upgrade docker-compose或系统包管理器升级）。
5. 分段测试配置：先保留x-mayan-container和一个引用它的服务，执行docker-compose config验证配置是否能正常解析，确认无误后再逐步添加其他服务。

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