Ubuntu主机Docker构建时克隆私有Git仓库失败求助

我之前切换到Ubuntu作为Docker主机时，碰到过几乎一模一样的问题——本地Mac上用build-arg传SSH密钥完全正常，换到Ubuntu就报错，明明主机本身能正常克隆私有仓库。结合我的排查经验，给你几个靠谱的解决方向：

1. 先搞定SSH密钥的权限问题（Ubuntu对这个更严格） #

Mac上对文件权限的校验没那么苛刻，但Ubuntu和大多数Linux系统一样，SSH会直接拒绝使用权限大于600的私钥。所以在Dockerfile里一定要显式设置密钥权限：

ARG SSH_PRIVATE_KEY
# 创建.ssh目录并设置正确权限
RUN mkdir -p /root/.ssh/ && chmod 700 /root/.ssh
# 写入私钥并严格限制权限为600
RUN echo "$SSH_PRIVATE_KEY" > /root/.ssh/id_rsa && chmod 600 /root/.ssh/id_rsa
# 提前添加Git服务器的主机密钥，避免构建时弹出确认提示中断流程
RUN ssh-keyscan github.com >> /root/.ssh/known_hosts

构建命令也要确保正确读取密钥：

docker build --build-arg SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" -t your-image-name .

👉 注意：如果用sudo执行docker命令，要换成sudo cat /home/your-user/.ssh/id_rsa，避免读取root的密钥文件。

2. 排查构建上下文的干扰 #

如果你的项目目录里恰好有.ssh文件夹，Docker构建时会把它打包到构建上下文里，可能覆盖你通过build-arg添加的密钥。解决方法很简单：在项目根目录创建.dockerignore文件，加上：

.ssh/

这样就不会把主机的SSH目录带入镜像构建流程了。

3. 更安全的替代方案：用SSH代理转发 #

直接传递密钥到镜像里有安全风险（镜像中会残留密钥），Ubuntu环境下更推荐用Docker的SSH代理转发功能，不需要传递密钥，直接复用主机的SSH代理：

首先确保主机的SSH代理是开启的（执行echo $SSH_AUTH_SOCK能看到路径就说明正常），然后修改Dockerfile：

# 提前添加Git服务器主机密钥
RUN mkdir -p /root/.ssh/ && ssh-keyscan github.com >> /root/.ssh/known_hosts
# 用--mount=type=ssh挂载SSH代理，然后克隆仓库
RUN --mount=type=ssh git clone git@github.com:your-username/your-private-repo.git

构建命令改成：

docker build --ssh default=$SSH_AUTH_SOCK -t your-image-name .

这种方式不仅避免了权限问题，还不用把密钥写入镜像，更安全。

4. 加调试步骤定位具体错误 #

如果上面的方法都不行，就在Dockerfile里加几个调试命令，看看构建时到底哪里出问题：

# 打印SSH连接详细日志，排查连接问题
RUN ssh -vT git@github.com
# 查看Git配置，确认是否有异常
RUN git config --list

构建时会输出详细的SSH连接日志，能直接看到是密钥无效、主机密钥不匹配，还是其他权限问题，针对性解决就好。

5. 确认密钥内容没被破坏 #

有时候传递build-arg时，换行符会被终端或脚本转义，导致写入镜像的密钥不全。可以在Dockerfile里临时输出密钥内容对比：

RUN echo "$SSH_PRIVATE_KEY" > /tmp/test_key && cat /tmp/test_key

构建后看看输出的密钥和主机上的~/.ssh/id_rsa是不是完全一致，包括开头的-----BEGIN OPENSSH PRIVATE KEY-----和结尾的-----END OPENSSH PRIVATE KEY-----以及中间的换行。

内容的提问来源于stack exchange，提问作者Jonathan N. Thinh