Docker BuildKit用SSH挂载私有仓库

Docker BuildKit 访问私有 Git 仓库时，关键不是把私钥 COPY 进镜像，而是让某一条 RUN 指令临时挂载 SSH agent。最小闭环是：Dockerfile 写 RUN --mount=type=ssh,id=github，构建命令写 --ssh github=$SSH_AUTH_SOCK，两边的 id 必须一致。挂载只服务于构建步骤，不把私钥作为镜像文件保存。

官方地址：https://docs.docker.com/

Build secrets 与 SSH mounts：https://docs.docker.com/build/building/secrets/

1. 先把 SSH 身份和构建目录对齐

把项目目录、Dockerfile 和构建上下文先分清。本文假设私有仓库地址是示意值 git@github.com:example/private-lib.git，不会要求你把真实仓库名、用户名或私钥写进镜像。构建前，在宿主机的 SSH agent 中准备身份，并确认当前身份源可被 Docker 客户端引用。

# 只列出 agent 中的公钥指纹，避免把私钥内容写入终端或构建上下文
ssh-add -L

# 为本次构建固定一个可读的身份名称，名称稍后要复用
export BUILDKIT_SSH_ID=github

如果 ssh-add -L 没有身份，先在本机按团队流程加载对应私钥；不要把 id_rsa 或其他私钥复制到项目目录。此时的可见状态是：项目文件树中只有 Dockerfile、构建上下文和必要源码，敏感身份仍在宿主机 agent 边界内。

2. 在 Dockerfile 的单个 RUN 步骤声明 SSH 挂载

打开项目根目录的 Dockerfile，把需要访问私有仓库的动作放进同一条 RUN。id=github 是挂载名称，不是 GitHub 账号；它必须与稍后的 --ssh github=... 使用同一个 ID。

# 使用支持 RUN --mount=type=ssh 的 Dockerfile 语法
# syntax=docker/dockerfile:1

FROM alpine:3.20

# 安装示例依赖；这里只保留构建所需的 Git 和 SSH 客户端
RUN apk add --no-cache git openssh-client

# SSH agent 只在这条 RUN 内可见，不把私钥复制到镜像文件系统
RUN --mount=type=ssh,id=github \
    mkdir -p -m 0700 /root/.ssh && \
    ssh-keyscan github.com >> /root/.ssh/known_hosts && \
    git clone git@github.com:example/private-lib.git /opt/private-lib

# 后续层只使用已经取回的源码，不再假设 SSH 挂载持续存在
WORKDIR /opt/private-lib

保存后的可见状态是：编辑器中能看到 --mount=type=ssh,id=github 紧邻真正需要私有仓库访问的命令。不要把 --mount 独立写成一层，也不要用 ARG PRIVATE_KEY 或环境变量传私钥；那会改变凭据进入构建的方式。

示例里的 ssh-keyscan 只为演示主机信任文件的准备位置。生产环境应按组织的 SSH 主机指纹管理方式处理 known_hosts，不能因为构建方便就关闭主机密钥检查。

3. 用 buildx 传入 agent，并核对构建结果

回到项目根目录执行构建命令。客户端通过 --ssh 把 agent 暴露给构建器，Dockerfile 再用同名的 id=github 接收它：

# 把宿主机的 SSH agent 以 github 这个 ID 交给 BuildKit
docker buildx build \
  --ssh "github=${SSH_AUTH_SOCK}" \
  --tag private-lib-consumer:dev \
  .

# 用非敏感的构建结果确认镜像已经生成
docker image inspect private-lib-consumer:dev \
  --format '{{.RepoTags}}'

构建界面中应能看到带有 RUN --mount=type=ssh 的步骤完成，最后的镜像检查应返回目标标签。这里核对的是“构建步骤获得了身份且镜像产物存在”，不是把私钥内容打印出来。即使构建成功，也不要在后续层执行 cat ~/.ssh/* 之类排查。

4. 在 Compose 中复用同一个 SSH 身份

如果项目通过 Compose 构建服务，不需要把私钥改成 Compose 顶层文件。给目标服务的 build 节点增加 ssh，并让 Dockerfile 继续使用相同的 id=github：

services:
  worker:
    # 构建上下文相对于 compose.yaml 所在目录
    build:
      context: .
      dockerfile: Dockerfile
      # default 表示连接当前 SSH agent；自定义 ID 时使用 github=路径或 socket
      ssh:
        - github
    image: private-lib-consumer:dev

如果使用 Compose 的默认身份，Dockerfile 也可以把挂载 ID 改成 default，同时命令和 Compose 都使用 default；不要一边写 ssh: ["default"]，另一边仍然写 id=github。配置保存后，验收重点是服务的 build 配置里出现 ssh，并且私有仓库访问命令确实位于带挂载的 RUN 中。

出现“Compose 看到了 ssh，但构建仍然拒绝访问”时，按这个顺序处理：先确认 agent 中有身份，再确认 Compose 的 ID 与 Dockerfile 的 ID 相同，接着确认远端仓库授权和 known_hosts，最后才检查 Docker Desktop 或构建器本身的运行状态。不要把整个 .ssh 目录挂进构建上下文，也不要把密钥写入 ARG、ENV 或镜像标签。

常见问题

SSH 挂载会不会出现在最终镜像里？

挂载是某条构建指令的临时输入，正确使用时不会把私钥作为普通文件复制进镜像；但你仍需避免在该指令中把私钥内容写入日志、生成文件或下一层。

为什么本机能 git clone，BuildKit 却提示公钥拒绝？

优先比较两个边界：本机命令使用的 agent 身份，以及 --ssh 传给构建器的身份 ID。两者未必相同；之后再检查仓库授权用户和主机信任。

可以用环境变量直接传私钥吗？

不建议。BuildKit 官方为 SSH agent 或 SSH key source 提供了专用的 SSH mount；不要把私钥当普通构建参数处理。

撤销本次配置时，删除 Dockerfile 中的 SSH 挂载和 Compose 的 build.ssh 条目，并保留项目原有的构建上下文。最后再次确认：私有仓库访问只发生在需要它的构建步骤，身份 ID 在命令、Dockerfile 和 Compose 三处一致，镜像产物检查不涉及任何敏感内容。