docker_buildx_local
Docker 多架构镜像构建与推送到 Docker Hub
补充说明
docker buildx 是 Docker 官方提供的多架构镜像构建插件，它利用 QEMU 模拟器在单台机器上同时构建不同 CPU 架构的镜像（如 amd64 + arm64），无需多台物理机器。docker buildx build --load 将构建结果直接加载到本地 Docker 镜像库，适用于本地测试验证；结合 --push 或 -o type=registry 可直接推送到远程仓库。
工作原理
- 通过
docker buildx create创建 Builder 实例 - Builder 内部使用 QEMU binfmt 注册处理器解析器，实现跨架构构建
- 构建时通过
--platform指定目标架构，builder 自动拉起对应架构的构建容器
本地构建 vs 远程推送
| 构建方式 | 命令 | 结果 |
|---|---|---|
| 本地加载 | --load 或 -o type=docker |
镜像出现在 docker images |
| 远程推送 | --push 或 -o type=registry |
镜像直接推送到 registry |
| 同时执行 | --load --push（仅单架构支持同时） |
本地 + 远程 |
⚠️ 注意：
--load一次只能加载一个架构的镜像到本地（不能同时--loadamd64 和 arm64）。如果需要构建多架构并保存到本地，需分别单独构建。
克隆项目
cd /vol1/1000/compose
rm -rf /vol1/1000/compose/cmdbox
git clone https://github.com/meimolihan/cmdbox.git
cd cmdbox
开启 Docker 多架构支持
构建支持 amd64 / arm64 双架构的镜像。
docker buildx create只需执行一次，之后每次构建直接使用即可。
# 启用 experimental 模式（Docker 旧版本需要，新版本可省略）
export DOCKER_CLI_EXPERIMENTAL=enabled
# 创建新的 buildx builder
docker buildx create --name mybuilder --use
# 启动并检查 builder
docker buildx inspect mybuilder --bootstrap
构建并推送多架构镜像
需要先执行
docker login登录 Docker Hub。
完整构建命令
# 首先进入项目源码目录
cd /vol1/1000/compose/cmdbox
# 先登录 Docker Hub
docker login -u mobufan
# 构建 amd64 + arm64 双架构镜像,并推送到 Docker Hub
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t mobufan/cmdbox:latest \
-t mobufan/cmdbox:2026.04.19 \
--push \
.
参数说明
| 参数 | 说明 |
|---|---|
--platform |
指定目标架构，支持 linux/amd64、linux/arm64、linux/arm/v7 |
--push |
构建完成后自动推送到镜像仓库 |
--load |
将镜像加载到本地 Docker（仅构建不推送时使用） |
-t |
镜像标签，可同时指定多个（:latest + 版本号） |
-o type=docker |
输出为本地 Docker 镜像格式（不推送） |
-o type=registry |
直接推送到 registry |
💡 如果只想本地构建不推送，去掉
--push，改为加-o type=docker：docker buildx build --platform linux/amd64,linux/arm64 -t mobufan/cmdbox:latest -o type=docker .
单独构建某一架构
构建 amd64 到本地并推送
# 首先进入项目源码目录
cd /vol1/1000/compose/cmdbox
# 先登录 Docker Hub
docker login -u mobufan
# 构建单架构 amd64 到本地
docker buildx build \
--platform linux/amd64 \
-t mobufan/cmdbox:amd64 \
-t mobufan/cmdbox:2026.04.13-amd64 \
--load \
.
# amd64 架构镜像，推送到 Docker Hub
docker push mobufan/cmdbox:amd64
docker push mobufan/cmdbox:2026.04.13-amd64
构建 arm64 到本地并推送
# 首先进入项目源码目录
cd /vol1/1000/compose/cmdbox
# 先登录 Docker Hub
docker login -u mobufan
# 构建单架构 arm64 到本地
docker buildx build \
--platform linux/arm64 \
-t mobufan/cmdbox:arm64 \
-t mobufan/cmdbox:2026.04.13-arm64 \
--load \
.
# arm64 架构镜像，推送到 Docker Hub
docker push mobufan/cmdbox:arm64
docker push mobufan/cmdbox:2026.04.13-arm64
架构与镜像标签对照
| 架构 | 镜像标签示例 |
|---|---|
| amd64 | mobufan/cmdbox:amd64 |
| arm64 | mobufan/cmdbox:arm64 |
| 双架构（默认） | mobufan/cmdbox:latest |
⚠️ 单独构建后拉取时必须指定对应标签：
docker pull mobufan/cmdbox:amd64 # 仅 amd64 机器 docker pull mobufan/cmdbox:arm64 # 仅 arm64 机器（如 Mac M系列） docker pull mobufan/cmdbox:latest # 自动匹配当前架构
运行容器
docker run -d \
--name cmdbox \
--restart always \
-p 9665:80 \
-e TZ=Asia/Shanghai \
mobufan/cmdbox:latest
运行参数说明
| 参数 | 说明 |
|---|---|
-d |
后台运行 |
--name |
容器名称 |
--restart always |
开机自启 |
-p 9665:80 |
端口映射（主机端口:容器端口） |
-e TZ=Asia/Shanghai |
设置时区 |
常见问题
Q: 构建失败怎么办？
# 检查 builder 状态
docker buildx inspect mybuilder
# 重新创建 builder
docker buildx rm mybuilder
docker buildx create --name mybuilder --use
docker buildx inspect mybuilder --bootstrap
Q: 推送失败怎么办？
# 确认登录状态
docker login -u mobufan
# 检查镜像标签
docker images | grep cmdbox
Q: 如何查看构建日志？
docker buildx build --progress=plain .
相关命令速查
# 创建 builder（首次）
docker buildx create --name mybuilder --use
# 构建 amd64 + arm64 并推送
docker buildx build --platform linux/amd64,linux/arm64 -t mobufan/cmdbox:latest --push .
# 本地构建测试
docker buildx build --platform linux/amd64 -t mobufan/cmdbox:latest -o type=docker .
# 运行
docker run -d --name cmdbox -p 9665:80 mobufan/cmdbox:latest