必须显式声明所有目标平台并启用--push，否则仅构建宿主机架构且无manifest list；基础镜像须带平台后缀，final-stage须最小化；qemu模拟后必须真机验证，manifest list须整体cosign签名。
多架构镜像本身不提供安全能力，安全一致性必须靠构建过程的显式约束来保障——漏掉 --platform、用错基础镜像、跳过真机验证，任何一个环节都会让“全平台一致”变成幻觉。
必须显式声明所有目标平台，不能依赖默认行为
不写 --platform，docker buildx build 就只构建宿主机架构；只写 linux/arm64 却漏掉 linux/amd64，manifest list 就不会生成。这会导致其他平台用户拉取失败，或更糟：静默 fallback 到错误架构镜像（比如 ARM 设备拉到 x86_64 镜像后报 exec format error）。
- 始终用完整、标准的平台标识：例如
linux/amd64,linux/arm64,linux/arm/v7 - 避免模糊别名（如
arm或arm64单独出现），Docker 不识别 - CI/CD 中从环境变量注入平台列表时，必须校验非空，空值会导致单架构构建且无提示
--push 必须与 --platform 同步启用，不可拆分
docker buildx build --push 是原子操作：只有全部架构子镜像构建成功，才会向 registry 提交 manifest list。如果先 build 再手动 docker push，registry 里只会存一堆孤立镜像，没有清单——docker pull your-app:latest 就无法自动选架构。
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 常见错误现象：
docker manifest inspect your-app:latest报 “no such manifest”，或仓库页面显示多个独立 tag（如:latest-amd64、:latest-arm64） - 验证必须用
docker buildx imagetools inspect your-registry/your-app:latest，检查输出中manifests字段是否包含全部预期架构，且每个platform.architecture值准确（如arm64，不是arm） - 本地
docker images看到的只是缓存，不代表远程 registry 已聚合成功
基础镜像必须带平台后缀，运行时镜像必须最小化
用 python:3.11-slim 这类无平台后缀的基础镜像，可能在不同构建节点上解析为不同架构（比如 x86_64 机器拉到 amd64 镜像，ARM 机器拉到 arm64 镜像），导致构建结果不可复现。更危险的是 final-stage 残留构建工具，会扩大攻击面。
- 基础镜像必须显式指定平台后缀：例如
arm64v8/python:3.11-slim、amd64/debian:bookworm-slim - 强制使用多阶段构建：编译阶段用
golang:1.23-bookworm等完整镜像，final-stage 严格限定为scratch或distroless/base，仅COPY二进制 - 对每个目标架构，在 CI 中执行
ldd your-binary（应为空）、apk list或dpkg -l（应无残留包）
QEMU 模拟不能替代真机验证，关键路径必须实机跑通
Buildx 在 x86_64 机器上构建 linux/arm64 镜像时依赖 QEMU 用户态模拟，它能处理大部分编译任务，但无法反映真实 ARM64 设备上的运行时行为：浮点异常处理差异、原子指令语义偏差、SVE 加密指令缺失却未报错……这些都可能绕过硬件级安全检查。
- CI 流水线中，buildx 构建完成后，立即用
docker run --platform linux/arm64启动容器，执行轻量健康检查（如curl http://localhost:8080/health） - 对安全关键服务，至少保留一台真实 ARM64 设备（如树莓派 4 或 AWS Graviton 实例），定期拉取最新镜像跑端到端测试
- BuildKit 的
--provenance=true和--sbom=true只能保证构建证据链一致，不能代替运行时行为验证
最易被忽略的一点：manifest list 签名必须作用于整个清单，而不是单个架构镜像；否则 docker pull 时无法自动校验架构匹配性——这意味着你签了名，但用户在 ARM 设备上拉取的仍是未经验证的 x86_64 镜像。
