docker buildx访问私有CA签名TLS证书仓库构建失败配置方法问询

当使用自签名私有CA签发TLS证书的私有镜像仓库作为基础镜像源构建Docker镜像时，若CA证书已导入macOS钥匙串或Windows受信任证书存储区，执行docker build命令可正常完成构建，但执行docker buildx build命令时，系统无法识别对应CA证书，会触发证书错误导致构建失败。

复现使用的示例Dockerfile内容如下：

FROM dockerhub.my.private.mirror.org/oraclelinux:8.6

执行docker build .可正常运行，典型输出如下：

% docker build .
...
 => CACHED [1/1] FROM dockerhub.my.private.mirror.org/oraclelinux:8.6
...

执行docker buildx build --load .会构建失败，典型报错信息如下：

% docker buildx build --load .
...
 => ERROR [internal] load metadata for dockerhub.my.private.mirror.org/oraclelinux:8.6
------
 > [internal] load metadata for dockerhub.my.private.mirror.org/oraclelinux:8.6:
------
Dockerfile:1
--------------------
   1 | >>> FROM dockerhub.my.private.mirror.org/oraclelinux:8.6
   2 |     
--------------------
error: failed to solve: dockerhub.my.private.mirror.org/oraclelinux:8.6: 
  failed to do request: Head "https://dockerhub.my.private.mirror.org/v2/oraclelinux/manifests/8.6": 
  x509: certificate signed by unknown authority

核心原因：普通docker build直接复用本地Docker Daemon的运行环境，会读取系统/Docker配置的信任证书；但docker buildx常用的docker-container驱动会启动独立的BuildKit容器运行构建流程，隔离环境默认不会复用宿主机或Docker Daemon的证书信任链，因此会报未知CA错误。

macOS #

• 若使用默认绑定本地Docker Daemon的builder（驱动为docker）：
  1. 执行命令创建对应私有仓库的证书配置目录：sudo mkdir -p /etc/docker/certs.d/dockerhub.my.private.mirror.org
  2. 将PEM格式的私有CA根证书拷贝到上述目录，命名为ca.crt
  3. 点击顶部菜单栏Docker图标，选择「Restart」重启Docker Desktop即可生效。
• 若使用docker-container驱动的独立builder（多架构构建默认使用该类型）：
  1. 先删除原有异常的builder实例：docker buildx rm <你的builder名称，可通过docker buildx ls查看>
  2. 本地创建BuildKit配置文件buildkitd.toml，内容如下：

     [registry."dockerhub.my.private.mirror.org"]
       ca = ["/certs/ca.crt"]
     

  3. 执行命令创建新的builder，挂载本地CA证书和配置文件：

     docker buildx create --name mybuilder --driver docker-container \
       --buildkitd-config ./buildkitd.toml \
       --mount type=bind,source=/本机存放私有CA证书的完整路径/ca.crt,target=/certs/ca.crt \
       --use
     

  4. 执行docker buildx inspect --bootstrap初始化builder，完成后即可正常构建。

Windows #

• 若使用默认绑定本地Docker Daemon的builder（驱动为docker）：
  1. 定位Docker证书配置目录，默认路径为C:\ProgramData\Docker\certs.d\
  2. 在该目录下新建与私有镜像仓库域名完全一致的文件夹，例如dockerhub.my.private.mirror.org
  3. 将PEM格式的私有CA根证书拷贝到新建的文件夹内，命名为ca.crt
  4. 重启Docker Desktop，等待服务启动完成即可。
• 若使用docker-container驱动的独立builder：
  配置逻辑与macOS一致，创建builder时通过--mount参数将Windows本地存放CA证书的路径挂载到BuildKit容器内，挂载时源路径使用WSL风格格式（例如/c/Users/xxx/certs/ca.crt）避免路径识别错误，再通过buildkitd.toml指定对应仓库的CA证书路径即可。

Linux #

• 若使用默认绑定本地Docker Daemon的builder（驱动为docker）：
  1. 执行命令创建证书配置目录：sudo mkdir -p /etc/docker/certs.d/dockerhub.my.private.mirror.org
  2. 将PEM格式的私有CA根证书拷贝到上述目录，命名为ca.crt，设置文件权限为644
  3. 执行sudo systemctl restart docker重启Docker服务即可生效。
• 若使用docker-container驱动的独立builder：
  配置逻辑与macOS完全一致，创建builder时通过--mount参数将宿主机上的CA证书挂载进BuildKit容器，再通过buildkitd.toml指定对应仓库的CA路径即可。也可以直接将CA证书拷贝到BuildKit容器的系统信任存储路径，执行系统证书更新命令后重启BuildKit容器生效。

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