docker-compose配置ssh构建报Additional property ssh is not allowed

出现services.build-tester.build Additional property ssh is not allowed报错，本质是你当前使用的Docker Compose V1（Python编写的旧稳定版） 配置解析逻辑本身不识别build层级下的ssh属性。哪怕手动开启BuildKit相关环境变量也无法解决，因为配置在校验阶段就会被拦截，根本不会进入构建流程。

你的Dockerfile写法完全符合BuildKit SSH挂载的规范，直接用docker build --ssh default可以正常构建也印证了这一点，问题完全出在Compose版本对配置的支持度上。

按可维护性优先级排序：

方案1：升级到Docker Compose V2（首选） #

Compose V2是目前官方主推的维护版本，采用Go语言重写，原生支持所有BuildKit构建特性，包括构建时SSH挂载，不需要额外注入环境变量：

• 先卸载旧版V1的docker-compose，安装V2版本，安装完成后执行命令验证版本：

  docker compose version
  

  输出版本号为v2.10.0及以上即可正常支持ssh配置项。注意V2的命令格式为docker compose（docker和compose之间是空格），和旧版的docker-compose（横杠连接）写法有区别
• 现有docker-compose.yml里的ssh配置段不需要做任何修改，保留原有写法即可：

  services:
    build-tester:
      container_name: build-tester
      image: build-tester
      build: 
        context: build_files
        dockerfile: Dockerfile
        ssh:
          - default
  

• 直接执行带构建的启动命令即可，V2默认开启BuildKit支持：

  docker compose up --build
  

方案2：无法升级Compose时的绕过方案 #

如果短期内不能升级Compose版本，可以拆分构建和启动流程，绕开Compose的配置校验：

• 先删除docker-compose.yml里build段下的ssh配置，避免配置校验报错
• 提前手动执行docker build命令完成带SSH挂载的镜像构建，构建的镜像名要和compose配置里的image字段完全一致：

  # 进入build_files目录执行构建
  cd build_files
  docker build --ssh default -t build-tester .
  

• 回到docker-compose.yml所在目录执行启动命令即可，因为本地已经存在对应tag的镜像，Compose不会重新触发构建流程：

  docker-compose up
  

  注意：这种方式的缺点是后续如果Dockerfile、requirements.txt或者应用代码有变更，需要手动重新执行上面的docker build命令，Compose不会自动完成带SSH挂载的构建流程

不管用哪种方案，构建前请确认本地SSH配置正常：

• 本地ssh-agent已经启动
• 访问私有Git仓库需要的私钥已经通过ssh-add添加到agent中，执行ssh-add -l可以看到对应密钥条目
• Dockerfile中需要提前添加私有Git仓库的主机公钥到known_hosts（现有写法里已经配置了github.com的密钥，这部分无需修改）

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