使用ssh-agent调用docker-compose拉取私有GitHub仓库失败排查

这个问题我之前帮不少开发者排查过，核心原因是Docker构建过程默认不会继承你当前shell的SSH代理会话——手动操作时你的密钥在本地ssh-agent里，但docker-compose build跑起来后，构建容器是一个隔离的环境，没法直接访问主机的ssh-agent。下面给你几个靠谱的解决办法：

这是最安全且常用的方案，让Docker在构建时挂载主机的SSH代理套接字：

• 先确认当前shell的SSH_AUTH_SOCK环境变量有效，手动执行echo $SSH_AUTH_SOCK能看到类似/run/user/1000/keyring/ssh或/tmp/ssh-XXXXXX/agent.1234的路径。
• 修改你的docker-compose.yml，在需要拉取私有仓库的服务的build块里添加ssh配置：

services:
  your-service:
    build:
      context: .
      ssh:
        - default=${SSH_AUTH_SOCK}

• 运行构建命令时，必须带上--ssh default参数（Docker 18.09+支持该特性）：

docker-compose build --ssh default

如果你的脚本里原本是直接调用docker-compose build，把命令替换成上面带参数的版本即可。

如果你的Docker版本过低不支持上述特性，可以临时把密钥复制到构建环境，但绝对要避免把密钥提交到代码仓库：

• 在Dockerfile中添加如下步骤：

# 复制本地私钥到容器（构建完成后会清理）
COPY id_rsa /root/.ssh/id_rsa
RUN chmod 600 /root/.ssh/id_rsa
# 拉取私有仓库
RUN git clone git@github.com:your-username/your-private-repo.git
# 构建完成后立即删除密钥，降低安全风险
RUN rm /root/.ssh/id_rsa

• 将你的私钥id_rsa放到和Dockerfile同目录的构建上下文里，同时务必在.gitignore中添加id_rsa，防止误提交。
• 运行docker-compose build即可，注意这个方法有安全隐患，密钥会短暂存在于构建临时层中，建议配合多阶段构建彻底清理。

有时候脚本运行的环境和你手动操作的环境不一致：

• 如果脚本是用sudo或其他用户执行的，它的环境变量（比如SSH_AUTH_SOCK）会和当前用户不同，导致无法访问ssh-agent。可以在脚本里加一行echo $SSH_AUTH_SOCK，和手动执行的结果对比。
• 如果脚本是通过cron或后台服务运行的，它不会加载你的shell配置（比如.bashrc、.zshrc），这时候需要在脚本里手动设置SSH_AUTH_SOCK的路径，或者确保ssh-agent在后台运行并导出变量。

• 确认你的GitHub公钥已经正确添加到私有仓库的部署密钥，或者你的个人账号SSH密钥列表中。
• 可以手动测试容器内的SSH代理连通性：运行docker run -it --rm --volume $SSH_AUTH_SOCK:/ssh-agent --env SSH_AUTH_SOCK=/ssh-agent alpine sh，然后在容器内执行ssh -T git@github.com，看能否成功认证，以此排查代理传递是否正常。

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