如何调试docker build克隆私有GitHub仓库时SSH公钥权限报错问题

1. 解决BuildKit构建失败无法调试的问题 #

BuildKit模式下默认不保留中间容器，可通过以下两种方式调试：

• 开启详细构建日志：执行构建命令时添加--progress=plain参数，可输出每一步的完整执行日志
• 拆分Dockerfile定位问题：注释掉git clone、go build等失败步骤后构建镜像，再通过docker run -it --entrypoint sh <镜像ID>进入容器，手动执行对应命令复现问题并排查

2. SSH权限问题核心排查步骤 #

1. 先验证宿主机侧SSH配置有效性，宿主机执行以下命令确认权限正常：

# 确认私钥已添加到SSH agent
ssh-add ~/.ssh/id_rsa
# 测试GitHub访问，正常会返回认证成功提示
ssh -T git@github.com

2. 在Dockerfile中添加SSH调试命令，输出详细校验日志：
   在git clone或go build的RUN指令前添加：

RUN --mount=type=ssh ssh -v git@github.com

执行构建后查看日志，可定位是known_hosts配置错误、密钥无法访问还是agent转发失效。

3. 你当前配置的问题修复 #

核心问题1：SSH挂载作用域仅对当前RUN指令生效 #

你当前仅给手动执行git clone的RUN指令加了--mount=type=ssh，但报错是go build阶段go mod拉取私有依赖时触发，该步骤的RUN指令未挂载SSH，自然无法访问私有仓库。

核心问题2：自定义SSH挂载ID需对应 #

如果你构建命令使用--ssh github=$SSH_AUTH_SOCK指定了挂载ID为github，则Dockerfile中的mount参数需要同步指定ID：--mount=type=ssh,id=github，否则会找不到对应的SSH挂载。

补充配置：Go强制走SSH拉私有仓库 #

Go默认会通过HTTPS拉取GitHub仓库，需添加git配置强制走SSH协议：

RUN git config --global url."git@github.com:".insteadOf "https://github.com/"

4. 最终可用配置示例 #

Dockerfile #

# syntax=docker/dockerfile:1.2
FROM golang:alpine AS build-env

RUN apk add --no-cache build-base git openssh-client

RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
RUN git config --global url."git@github.com:".insteadOf "https://github.com/"

RUN --mount=type=ssh git clone git@github.com:myorg/myproject.git myproject

# go build步骤同步添加SSH挂载
RUN --mount=type=ssh cd cmd/service/ && go build -o service

构建命令 #

ssh-add ~/.ssh/id_rsa
export DOCKER_BUILDKIT=1
docker build --no-cache --progress=plain --ssh default --file ./Dockerfile \
       --build-arg GO_VERSION=1.16.3 --tag app:main .

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