在容器化或 CI 构建过程中，项目经常需要从私有 Git 仓库拉取依赖，比如 Go 模块、npm 包或 Python 包。如果直接使用 HTTPS 地址并携带 token，或者把 SSH 私钥复制进构建镜像，都会带来凭证泄漏风险。一个更安全的思路是让构建过程临时借用宿主机的 SSH 代理能力，使私钥不出现在镜像层和最终产物中。下面将围绕 Docker BuildKit 提供的 ssh 挂载功能，剖析这条链路的具体配置与注意事项。
构建阶段为什么需要 SSH 代理
私有依赖拉取通常有几种方式。HTTPS 方式需要在 URL 中附加用户名和令牌，比如 https://oauth2:token@git.ipipp.com/org/repo.git，这样的地址可能会出现在 shell 历史、构建日志或环境变量里。SSH 方式虽然不需要在 URL 中暴露凭证，但传统做法要求把私钥拷贝到构建容器内，这会让镜像层永久包含私钥。哪怕后续用 RUN rm 删除文件，私钥仍然存在于之前的层中，任何人只要拿到镜像就能通过 docker history 或 layer 解包恢复出来。因此，构建阶段的凭证管理必须从层持久化转向临时会话。
ssh-agent 机制恰好能够满足这个需求。ssh-agent 进程持有解密后的私钥，对外只暴露一个 Unix socket，任何进程只要获得 socket 路径和权限，就能请求签名但拿不到私钥本身。构建时把这个 socket 挂载进去，既能完成认证，又不会把私钥写入镜像。与 HTTPS token 对比，SSH agent 的另一个优势是私钥可以设置口令保护，即使文件被误拷贝，没有口令也无法直接使用。并且 agent 会话是短暂的，构建完成后 socket 自动失效。在 Docker 中，实现这一机制的核心是 BuildKit 提供的 SSH 挂载类型，它允许在 RUN 指令执行期间，把宿主机上某个 SSH agent socket 挂载到容器内的临时位置，构建结束后不保留任何痕迹。
Docker BuildKit 的 ssh 挂载实战
要使用 SSH 挂载，需要先确保 Docker 使用 BuildKit 后端。新版 Docker 默认启用，也可以在执行 docker build 时通过环境变量 DOCKER_BUILDKIT=1 显式开启。宿主机的 SSH agent 需要处于运行状态，并且已经添加了用于访问私有仓库的私钥。典型命令如下：
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519 export SSH_AUTH_SOCK docker build --ssh default=$SSH_AUTH_SOCK -t myapp .
其中 default 是挂载的 ID，后面的 $SSH_AUTH_SOCK 需要替换成实际 socket 路径，或者直接使用变量。如果本机有多个 agent，可以用不同 ID 挂载多个。在 Dockerfile 中，需要把 RUN 指令改成带挂载参数的写法。以 Go 项目拉取私有模块为例，可以这样写：
# syntax=docker/dockerfile:1.4 FROM golang:1.22 AS builder WORKDIR /src COPY go.mod go.sum ./ RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts ENV GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=accept-new" RUN --mount=type=ssh go mod download COPY . . RUN --mount=type=ssh go build -o /app .
这里的 --mount=type=ssh 默认使用 default ID，它会在 RUN 执行时创建一个临时 socket，并注入 SSH_AUTH_SOCK 环境变量。构建过程通过 Git 访问私有仓库时，Git 会读取 GIT_SSH_COMMAND，使用该 socket 完成认证。需要特别注意的是，known_hosts 的生成必须在挂载命令之前完成，否则首次连接会因为主机校验失败而中断。也可以使用 StrictHostKeyChecking=accept-new 让 Git 自动接受新主机，但这在生产环境可能引入中间人风险，建议在 CI 中显式管理 known_hosts。
如果私有依赖不是通过 Git 直接克隆，而是通过 npm、pip 等包管理器访问，仍然可以借助 SSH 包装。例如，npm 包源指向 Git 地址时，npm 会调用 git 命令，只要 git 能使用 SSH 挂载的 socket，就能顺利拉取。对于 pip 的 VCS 依赖，也是同样道理。关键是确保子进程继承了 SSH_AUTH_SOCK 环境变量，这一点由 BuildKit 自动完成。
CI/CD 流水线中的 SSH agent 配置
在持续集成环境里，私钥通常存储在平台的加密变量中，比如 GitHub Actions 的 secrets。直接写 docker build --ssh default 时，需要先启动一个 ssh-agent 并把私钥加载进去。以 GitHub Actions 为例，常用 webfactory/ssh-agent 这个 action 简化流程：
- name: Setup SSH agent
uses: webfactory/ssh-agent@v0.9.0
with:
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
- name: Build image
run: |
export DOCKER_BUILDKIT=1
docker build --ssh default=$SSH_AUTH_SOCK -t image:tag .
这个 action 会启动一个独立的 ssh-agent，导出 SSH_AUTH_SOCK，并在后续步骤中保持运行。构建命令直接复用该变量，无需手动处理私钥文件。注意不要在 workflow 中执行 ssh-add 后打印环境变量，以免泄漏 socket 路径。如果是 Jenkins、GitLab CI 等其他平台，原理相同：先启动 ssh-agent，把私钥通过标准输入或文件加载，然后让 Docker 构建命令继承 SSH_AUTH_SOCK。
对于没有直接提供 SSH agent 的环境，也可以在 Docker 容器外部启动一个临时 agent，把私钥解密后加入，完成后终止 agent。脚本模板如下：
#!/usr/bin/env bash
set -euo pipefail
eval "$(ssh-agent -s)"
trap 'ssh-agent -k' EXIT
ssh-add - <<< "${SSH_PRIVATE_KEY}"
docker build --ssh default="${SSH_AUTH_SOCK}" -t app .
这里用 here-string 从变量加载私钥，避免写到磁盘。trap 确保脚本结束时 agent 退出，清理干净。如果私钥有口令保护，需要提前用 ssh-add 交互式添加或使用 expect 类工具处理，但尽量不要在 CI 中使用交互式口令。多阶段构建是防止凭证泄漏的重要补充。即使使用了 ssh 挂载，构建阶段会留下一些临时文件，如 go mod cache 中可能包含私有仓库的元数据。通过多阶段构建，最终镜像只从 builder 阶段拷贝编译产物，不会包含 SSH socket、known_hosts 或凭据残留。示例如下：
# syntax=docker/dockerfile:1.4 FROM golang:1.22 AS builder WORKDIR /src COPY go.mod go.sum ./ RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts RUN --mount=type=ssh go mod download COPY . . RUN --mount=type=ssh CGO_ENABLED=0 go build -o /app ./cmd/server FROM alpine:3.20 RUN adduser -D app USER app COPY --from=builder /app /usr/local/bin/app ENTRYPOINT ["/usr/local/bin/app"]
最终运行阶段没有任何 SSH 相关文件，攻击者即使拿到镜像也无法提取私钥。这样的组合方案同时兼顾了认证便利性和安全性。
常见问题与排错思路
构建时遇到 Host key verification failed 是最常见的问题。这通常是因为容器内 ~/.ssh/known_hosts 缺少目标主机记录。解决方式是在 Dockerfile 中显式执行 ssh-keyscan github.com >> ~/.ssh/known_hosts，或者设置 GIT_SSH_COMMAND 为 ssh -o StrictHostKeyChecking=no。后者会跳过校验，仅建议在临时环境中使用。生产构建应使用预先维护的 known_hosts 文件，可以从宿主机复制或通过基础镜像注入。
另一个典型报错是 Could not open a connection to your authentication agent。这说明 SSH_AUTH_SOCK 没有在 RUN 指令中生效，可能原因包括：docker build 命令中 --ssh 参数拼写错误、Docker 版本过低不支持 BuildKit、或者宿主机的 agent socket 权限不允许容器访问。可以先检查 docker build --ssh default=$SSH_AUTH_SOCK 是否被正确解析，并确认 DOCKER_BUILDKIT=1 环境变量已设置。使用 docker buildx build 通常更可靠，因为它强制使用 BuildKit。
还有一类问题是私有依赖的 CA 证书或代理设置。如果企业 Git 服务器使用自签名证书，需要在构建阶段导入企业 CA，并配置 Git 的 http.sslCAInfo 或 GIT_SSL_NO_VERIFY。不过本文讨论的是 SSH 方式，这些 HTTPS 相关配置可以避开。但如果 Git 服务器通过 HTTP 代理转发 SSH 连接，可能需要在容器内配置 SSH ProxyCommand。具体命令可写入 ~/.ssh/config 并复制到构建阶段。示例：
RUN mkdir -p -m 0700 ~/.ssh && printf 'Host git.internal\n ProxyCommand nc -X connect -x proxy.internal:8080 %h %p\n' >> ~/.ssh/config
实际代理地址需要根据企业网络环境替换。只要把代理配置和 ssh 挂载配合使用，构建过程中的私有依赖拉取就能在安全与效率之间取得平衡。