# 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：

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

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

#### 2. 有网环境导出缓存

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

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

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

#### 3. 传输到无网环境

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

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

#### 4. 无网环境构建

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

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

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

### 方法二：使用独立脚本

#### 导出缓存

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

#### 离线构建

```bash
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 源码
```

### 单个服务构建

```bash
# 仅构建 backend
make backend-offline-build

# 仅构建 runtime
make runtime-offline-build

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

### 增量更新

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

```bash
# 重新导出 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 缓存可能占用大量内存，可以设置资源限制：

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

## 限制说明

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

## 高级用法

### 自定义缓存位置

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

### 导出特定平台缓存

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

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

```bash
# 导出到 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](https://docs.docker.com/build/buildkit/)
- [Cache Storage Backends](https://docs.docker.com/build/cache/backends/)