Docker & Kubernetes 架构问题排查

Docker & Kubernetes 架构问题排查

1. 查看系统架构

（1）查看 Docker 主机架构

docker info | grep "Architecture"  # 输出：x86_64（amd64）或 aarch64（arm64）
uname -m                           # 输出：x86_64 / aarch64 / armv7l

（2）查看 Kubernetes 节点架构

kubectl get nodes -o wide  # 查看 ARCHITECTURE 列

---

2. 查看 Docker 镜像架构

（1）已拉取的镜像

docker inspect nginx:latest --format '{{.Architecture}}'  # 输出：amd64 / arm64

（2）远程仓库镜像（未拉取）

docker manifest inspect nginx:latest | grep architecture

输出示例：

"architecture": "amd64",  # 或 arm64

（3）运行容器检查

docker run --rm -it nginx:latest uname -m

输出：

• x86_64 → amd64
• aarch64 → arm64

---

3. 解决架构不匹配问题

（1）Docker 是 amd64，但需要 arm64 镜像

方法 A：强制拉取 ARM64 镜像

docker pull --platform linux/arm64 nginx:latest

方法 B：使用 buildx 构建 ARM64 镜像

docker buildx create --use --name multiarch  # 启用多架构构建
docker buildx build --platform linux/arm64 -t my-image:arm64 --push .

（2）Kubernetes 是 arm64，但镜像只有 amd64

方法 A：重新构建 ARM64 镜像并推送

docker buildx build --platform linux/arm64 -t private-registry/nginx:arm64 --push .

方法 B：使用 QEMU 模拟运行（仅测试）

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker run --rm -it private-registry/nginx:arm64 uname -m  # 测试能否运行

---

4. 常见架构对应表

uname -m	Docker 架构	常见设备
x86_64	amd64	Intel/AMD PC、大多数云服务器
aarch64	arm64	苹果 M1/M2、树莓派 4、AWS Graviton
armv7l	arm/v7	旧版树莓派（3B 及更早）

---

5. 关键命令总结

需求	命令
查看 Docker 主机架构	docker info | grep "Architecture"
查看镜像架构	docker inspect <IMAGE> --format '{{.Architecture}}'
查看远程镜像支持的架构	docker manifest inspect <IMAGE>
构建多架构镜像	docker buildx build --platform linux/arm64 -t <IMAGE> --push .
强制拉取指定架构镜像	docker pull --platform linux/arm64 <IMAGE>

---

6. 典型问题 & 解决方案

问题	原因	解决方案
exec format error	镜像架构与节点不匹配	使用 --platform 拉取正确架构镜像
私有仓库镜像无法运行	镜像可能不是多架构	用 buildx 重新构建并推送
Kubernetes 节点是 ARM，但镜像只有 AMD	架构不兼容	构建 ARM64 镜像并推送至私有仓库

---

✅ 最佳实践：

• 生产环境：使用 docker buildx 构建多架构镜像并推送至私有仓库。
• 测试环境：可用 --platform 或 QEMU 模拟运行。

📌 注意：

• arm64 镜像不能在 amd64 机器上直接运行（除非模拟，但性能差）。
• 如果私有仓库无法访问外网，需在 arm64 设备上构建或使用 buildx 交叉编译。