92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
---
|
||
tags: [docker, multi-arch, buildx, cross-platform]
|
||
create time: 2026-05-18 00:45
|
||
---
|
||
|
||
# 多架构构建 — Buildx 实战
|
||
|
||
## 概述
|
||
|
||
随着 Apple Silicon 和 ARM 服务器普及，一个平台只能构建一种架构的镜像已无法满足需求。Docker Buildx 让我们**一次构建、全平台运行**。本文档讲解多架构构建的核心操作和原理。
|
||
|
||
## Buildx 快速上手
|
||
|
||
```bash
|
||
# 启用 buildx 并创建 multi-platform builder
|
||
docker buildx create --name mybuilder --use
|
||
docker buildx inspect --bootstrap
|
||
```
|
||
|
||
## 跨平台构建推送
|
||
|
||
```bash
|
||
# 为 amd64 + arm64 同时构建并推送到仓库
|
||
docker buildx build \
|
||
--platform linux/amd64,linux/arm64 \
|
||
-t harbor.example.com/app/server:v1.2.3 \
|
||
--push \
|
||
.
|
||
```
|
||
|
||
> [!note] manifest list 原理
|
||
>
|
||
> 多架构镜像本质上是一个 **manifest list**——它不直接包含二进制文件，而是记录每个架构对应的镜像 digest。拉取时，客户端根据自身平台自动选择正确的变体。可以用 `docker buildx imagetools inspect <image>` 查看完整列表。
|
||
|
||
## 不同场景的构建策略
|
||
|
||
| 场景 | 策略 | 命令 |
|
||
|------|------|------|
|
||
| 开发阶段 | 只构建本机架构 (`linux/arm64`)，速度最快 | `docker buildx build --platform linux/arm64 .` |
|
||
| CI 流水线 | 构建全平台 (`linux/amd64,linux/arm64`)，统一推送 | `--platform linux/amd64,linux/arm64 --push` |
|
||
| 临时调试 | `--load` 仅构建本地可用 | `docker buildx build --load .` |
|
||
|
||
## Go 跨平台编译提示
|
||
|
||
在 Dockerfile 中使用 `ARG TARGETARCH`（Buildx 自动传入）：
|
||
|
||
```dockerfile
|
||
FROM golang:1.22-alpine AS builder
|
||
|
||
ARG TARGETARCH
|
||
ARG TARGETPLATFORM
|
||
|
||
RUN echo "Building for: $TARGETARCH ($TARGETPLATFORM)"
|
||
|
||
WORKDIR /app
|
||
COPY go.mod go.sum ./
|
||
RUN go mod download
|
||
|
||
COPY . .
|
||
RUN CGO_ENABLED=0 GOOS=linux GOARCH=$TARGETARCH \
|
||
go build -a -ldflags "-s -w" -o server-$TARGETARCH .
|
||
```
|
||
|
||
> [!info] 环境变量对照
|
||
>
|
||
> | 变量 | 示例值 | 说明 |
|
||
> |------|--------|------|
|
||
> | `TARGETARCH` | `amd64`, `arm64` | CPU 架构 |
|
||
> | `TARGETOS` | `linux`, `darwin` | 操作系统 |
|
||
> | `TARGETPLATFORM` | `linux/amd64`, `linux/arm64` | 完整平台标识 |
|
||
|
||
## 补充：QEMU 模拟（CI 中的备用方案）
|
||
|
||
当你的 CI 环境不支持 Buildx QEMU 插件时，可以手动安装：
|
||
|
||
```bash
|
||
# 注册 QEMU 模拟器
|
||
docker run --privileged --rm tonistiigi/binfmt --install all
|
||
|
||
# 之后即可通过 qemu 模拟不同平台构建（速度较慢）
|
||
docker buildx build --platform linux/arm64 -t my-app:arm64 .
|
||
```
|
||
|
||
> [!warning] 模拟构建 vs 原生交叉编译
|
||
>
|
||
> QEMU 模拟可以运行在其他架构上，但构建速度极慢（通常比原生慢 5~10 倍）。生产环境推荐使用 **Go 原生交叉编译**（`GOOS=linux GOARCH=arm64`），零依赖且秒级完成。只在需要 C 扩展的场景才考虑 QEMU 模拟。
|
||
|
||
## 关联笔记
|
||
|
||
- [[../01-容器化/01-Dockerfile最佳实践]] — 多阶段构建 + BuildKit 特性
|
||
- [[../hhs/MS/05-部署运维/02-Kubernetes]] — K8s 节点混合架构时的调度考量
|