You've already forked DataMate
feat(build): 添加离线构建支持
- 新增 build-offline.sh 脚本实现无网环境构建 - 添加离线版 Dockerfiles 使用本地资源替代网络下载 - 创建 export-cache.sh 脚本在有网环境预下载依赖 - 集成 Makefile.offline.mk 提供便捷的离线构建命令 - 添加详细的离线构建文档和故障排查指南 - 实现基础镜像、BuildKit 缓存和外部资源的一键打包
This commit is contained in:
245
scripts/offline/README.md
Normal file
245
scripts/offline/README.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user