DataMate/scripts/offline/README.md

BuildKit 离线构建方案

本方案使用 Docker BuildKit 的缓存机制，实现在弱网/无网环境下的镜像构建。

方案概述

┌─────────────────────────────────────────────────────────────────┐
│  有网环境 (Build Machine)                                       │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ 基础镜像    │    │ BuildKit    │    │ 外部资源            │ │
│  │ docker pull │ +  │ 缓存导出    │ +  │ (模型/源码)         │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│           │                  │                  │               │
│           └──────────────────┼──────────────────┘               │
│                              ▼                                  │
│                    ┌──────────────────┐                         │
│                    │ build-cache.tar.gz│                        │
│                    └────────┬─────────┘                         │
└─────────────────────────────┼───────────────────────────────────┘
                              │ 传输到无网环境
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  无网环境 (Offline Machine)                                     │
│                    ┌──────────────────┐                         │
│                    │ build-cache.tar.gz│                        │
│                    └────────┬─────────┘                         │
│                             ▼                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ docker load │    │ BuildKit    │    │ 本地资源挂载        │ │
│  │ 基础镜像    │ +  │ 缓存导入    │ +  │ (模型/源码)         │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│           │                  │                  │               │
│           └──────────────────┼──────────────────┘               │
│                              ▼                                  │
│                         构建成功！                              │
└─────────────────────────────────────────────────────────────────┘

快速开始

方法一：使用 Makefile 扩展（推荐）

1. 合并 Makefile

将 Makefile.offline.mk 追加到主 Makefile：

# Linux/Mac
cat Makefile.offline.mk >> Makefile

# Windows (PowerShell)
Get-Content Makefile.offline.mk | Add-Content Makefile

2. 有网环境导出缓存

# 导出所有缓存（包括基础镜像、BuildKit 缓存、外部资源）
make offline-export

# 或者指定输出目录
make offline-export CACHE_DIR=/path/to/cache

执行完成后，会生成压缩包：build-cache-YYYYMMDD.tar.gz

3. 传输到无网环境

# 使用 scp 或其他方式传输
scp build-cache-20250202.tar.gz user@offline-server:/opt/datamate/

# 或者使用 U 盘等物理介质

4. 无网环境构建

# 解压缓存
tar -xzf build-cache-20250202.tar.gz

# 设置环境并构建
make offline-setup
make offline-build

# 或者指定版本号
make offline-build OFFLINE_VERSION=v1.0.0

方法二：使用独立脚本

导出缓存

cd scripts/offline
./export-cache.sh /path/to/output

离线构建

cd scripts/offline
./build-offline.sh /path/to/cache [version]

详细说明

缓存内容

缓存目录结构：

build-cache/
├── buildkit/                  # BuildKit 缓存
│   ├── backend-cache/
│   ├── backend-python-cache/
│   ├── database-cache/
│   ├── frontend-cache/
│   ├── gateway-cache/
│   ├── runtime-cache/
│   ├── deer-flow-backend-cache/
│   ├── deer-flow-frontend-cache/
│   └── mineru-cache/
├── images/
│   └── base-images.tar       # 基础镜像集合
└── resources/                 # 外部资源
    ├── models/
    │   ├── ch_ppocr_mobile_v2.0_cls_infer.tar    # PaddleOCR 模型
    │   └── zh_core_web_sm-3.8.0-py3-none-any.whl # spaCy 模型
    ├── DataX/                # DataX 源码
    └── deer-flow/            # deer-flow 源码

单个服务构建

# 仅构建 backend
make backend-offline-build

# 仅构建 runtime
make runtime-offline-build

# 仅构建 deer-flow-backend
make deer-flow-backend-offline-build

增量更新

如果只有部分服务代码变更，可以只导出该服务的缓存：

# 重新导出 backend 缓存
docker buildx build \
  --cache-to type=local,dest=./build-cache/buildkit/backend-cache,mode=max \
  -f scripts/images/backend/Dockerfile \
  -t datamate-backend:cache .

# 传输并重新构建
tar -czf build-cache-partial.tar.gz build-cache/buildkit/backend-cache
# ... 传输到无网环境 ...
make backend-offline-build

故障排查

问题 1: 缓存导入失败

ERROR: failed to solve: failed to read cache metadata

解决: 缓存目录可能损坏，重新在有网环境导出。

问题 2: 基础镜像不存在

ERROR: pull access denied

解决: 先执行 make offline-setup 加载基础镜像。

问题 3: 网络连接错误（无网环境）

ERROR: failed to do request: dial tcp: lookup ...

解决: 检查 Dockerfile 中是否还有网络依赖，可能需要修改 Dockerfile 使用本地资源。

问题 4: 内存不足

BuildKit 缓存可能占用大量内存，可以设置资源限制：

# 创建带资源限制的 buildx 构建器
docker buildx create --name offline-builder \
  --driver docker-container \
  --driver-opt memory=8g \
  --use

限制说明

1. 镜像版本: 基础镜像版本必须与缓存导出时一致
2. Dockerfile 变更: 如果 Dockerfile 发生较大变更，可能需要重新导出缓存
3. 资源文件: mineru 镜像中的模型下载（mineru-models-download）仍需要网络，如果需要在完全无网环境使用，需要预先将模型文件挂载到镜像中

高级用法

自定义缓存位置

make offline-export CACHE_DIR=/mnt/nas/build-cache
make offline-build CACHE_DIR=/mnt/nas/build-cache

导出特定平台缓存

# 导出 ARM64 平台的缓存
docker buildx build \
  --platform linux/arm64 \
  --cache-to type=local,dest=./build-cache/buildkit/backend-cache,mode=max \
  -f scripts/images/backend/Dockerfile .

使用远程缓存（有网环境）

# 导出到 S3/MinIO
docker buildx build \
  --cache-to type=s3,region=us-east-1,bucket=mybucket,name=backend-cache \
  -f scripts/images/backend/Dockerfile .

# 从 S3 导入
docker buildx build \
  --cache-from type=s3,region=us-east-1,bucket=mybucket,name=backend-cache \
  -f scripts/images/backend/Dockerfile .

参考

• Docker BuildKit Documentation
• Cache Storage Backends