多阶段构建本身不自动支持跨主机缓存共享，必须通过显式配置远程缓存后端并确保构建上下文一致才能实现复用；推荐使用 registry 类型缓存（如 Harbor/ECR），需同时指定 --cache-from 和 --cache-to 且 ref 一致，并启用 mode=max 与固定基础镜像 digest、稳定层序和显式 --platform 才能保障跨阶段缓存命中。
多阶段构建本身不自动支持跨主机缓存共享，必须通过显式配置远程缓存后端，并确保构建上下文一致，才能实现真正意义上的跨主机复用。
选对缓存后端类型是前提
本地缓存（local）只在单机生效，挂载 NFS 或 SMB 共享目录虽可行，但存在并发写冲突风险，不推荐用于 CI 环境。真正可靠的方式是使用支持 OCI artifacts 的镜像仓库作为缓存源：
- registry 类型：最常用，复用现有 Harbor / ECR / Docker Hub 基础设施，所有构建节点都能拉取同一份缓存元数据
- s3/azblob/minio 类型：适合中大型团队，权限精细、跨云稳定，需额外维护对象存储服务
- inline 类型：缓存嵌入镜像层，随镜像一起推送，但会增大镜像体积，且仅对完全相同的 Dockerfile 有效
构建命令必须同时指定 cache-from 和 cache-to
仅写 --cache-from 不会上传新缓存，仅写 --cache-to 不会尝试复用旧缓存。两者需成对出现，且 ref 保持一致：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
- 首次构建会将中间层哈希和构建图推送到指定 registry tag（如
myreg/app:buildcache） - 后续任意节点执行相同命令时，先拉取该 tag 的缓存索引，命中则跳过对应 RUN 步骤
- 务必加上
mode=max参数，否则默认只复用部分层（如仅复用 FROM 和 COPY，不复用 RUN）
多阶段下缓存复用的关键一致性控制
即使用了远程缓存，以下任一变化都会导致某阶段缓存失效，进而影响后续阶段：
-
基础镜像 digest 必须固定：避免
FROM ubuntu:22.04因镜像更新而改变底层层哈希；应改用FROM ubuntu@sha256:... -
Dockerfile 层序要稳定：把
COPY go.mod go.sum和RUN go mod download放在COPY . .之前，确保依赖不变时该层始终命中 -
构建平台需显式声明：跨架构（amd64/arm64）复用缓存时，
--platform参数必须一致，Buildx 会自动将平台信息纳入 cache key
CI 环境中要启用 BuildKit 并预设全局配置
BuildKit 是远程缓存能力的基础，普通 Docker daemon 默认不启用：
- 在 CI 脚本开头设置
export DOCKER_BUILDKIT=1 - 提前创建 builder 实例并设为默认：
docker buildx create --use --name ci-builder --driver docker-container - 可选：在
~/.docker/buildx/config.json中预设常用 cache-to 地址与超时参数，避免每次重复传参
