docs(offline): 更新离线构建文档添加传统构建方式和故障排查指南

- 添加传统 docker build 方式作为推荐方案
- 新增离线环境诊断命令 make offline-diagnose
- 扩展故障排查章节，增加多个常见问题解决方案
- 添加文件清单和推荐工作流说明
- 为 BuildKit 构建器无法使用本地镜像问题提供多种解决方法
- 更新构建命令使用说明和重要提示信息

scripts/offline/README.md

@@ -74,20 +74,29 @@ scp build-cache-20250202.tar.gz user@offline-server:/opt/datamate/
 # 或者使用 U 盘等物理介质
 ```
 
-#### 4. 无网环境构建
+#### 4. 无网环境构建（推荐使用传统方式）
 
 ```bash
 # 解压缓存
 tar -xzf build-cache-20250202.tar.gz
 
-# 设置环境并构建
+# 诊断环境（检查基础镜像等）
+make offline-diagnose
+
+# 方法 A：传统 docker build（推荐，更稳定）
+make offline-setup
+make offline-build-classic
+
+# 方法 B：BuildKit 构建（如果方法 A 失败）
 make offline-setup
 make offline-build
 
 # 或者指定版本号
-make offline-build OFFLINE_VERSION=v1.0.0
+make offline-build-classic OFFLINE_VERSION=v1.0.0
 ```
 
+**⚠️ 重要提示**：如果遇到镜像拉取问题，请使用 `make offline-build-classic` 而不是 `make offline-build`。
+
 ### 方法二：使用独立脚本
 
 #### 导出缓存
@@ -164,7 +173,48 @@ make backend-offline-build
 
 ## 故障排查
 
-### 问题 1: 缓存导入失败
+### 问题 1: 构建时仍然尝试拉取镜像（最常见）
+
+**现象**:
+```
+ERROR: failed to solve: pulling from host ...
+或
+ERROR: pull access denied, repository does not exist or may require authorization
+```
+
+**原因**: 
+- 基础镜像未正确加载
+- BuildKit 尝试验证远程镜像
+
+**解决方案**:
+
+1. **使用传统构建方式（推荐）**:
+```bash
+make offline-build-classic
+```
+
+2. **手动加载基础镜像**:
+```bash
+# 加载基础镜像
+docker load -i build-cache/images/base-images.tar
+
+# 验证镜像存在
+docker images | grep -E "(maven|eclipse-temurin|mysql|node|nginx)"
+```
+
+3. **使用 Docker 守护进程的离线模式**:
+```bash
+# 编辑 /etc/docker/daemon.json
+{
+  "registry-mirrors": [],
+  "insecure-registries": []
+}
+
+# 重启 Docker
+sudo systemctl restart docker
+```
+
+### 问题 2: 缓存导入失败
 
 ```
 ERROR: failed to solve: failed to read cache metadata
@@ -172,23 +222,26 @@ ERROR: failed to solve: failed to read cache metadata
 
 **解决**: 缓存目录可能损坏，重新在有网环境导出。
 
-### 问题 2: 基础镜像不存在
+### 问题 3: 基础镜像不存在
 
 ```
 ERROR: pull access denied
 ```
 
-**解决**: 先执行 `make offline-setup` 加载基础镜像。
+**解决**: 
+1. 先执行 `make offline-setup` 加载基础镜像
+2. 运行 `make offline-diagnose` 检查缺失的镜像
+3. 重新导出缓存时确保包含所有基础镜像
 
-### 问题 3: 网络连接错误（无网环境）
+### 问题 4: 网络连接错误（无网环境）
 
 ```
 ERROR: failed to do request: dial tcp: lookup ...
 ```
 
-**解决**: 检查 Dockerfile 中是否还有网络依赖，可能需要修改 Dockerfile 使用本地资源。
+**解决**: 检查 Dockerfile 中是否还有网络依赖（如 `git clone`、`wget`、`pip install` 等），可能需要修改 Dockerfile 使用本地资源。
 
-### 问题 4: 内存不足
+### 问题 5: 内存不足
 
 BuildKit 缓存可能占用大量内存，可以设置资源限制：
 
@@ -200,6 +253,39 @@ docker buildx create --name offline-builder \
   --use
 ```
 
+### 问题 6: BuildKit 构建器无法使用本地镜像
+
+**现象**: 即使镜像已加载，BuildKit 仍提示找不到镜像
+
+**解决**: BuildKit 的 `docker-container` 驱动无法直接访问本地镜像。使用以下方法之一：
+
+**方法 A**: 使用传统 Docker 构建（推荐）
+```bash
+make offline-build-classic
+```
+
+**方法 B**: 将镜像推送到本地 registry
+```bash
+# 启动本地 registry
+docker run -d -p 5000:5000 --name registry registry:2
+
+# 标记并推送镜像到本地 registry
+docker tag maven:3-eclipse-temurin-21 localhost:5000/maven:3-eclipse-temurin-21
+docker push localhost:5000/maven:3-eclipse-temurin-21
+
+# 修改 Dockerfile 使用本地 registry
+# FROM localhost:5000/maven:3-eclipse-temurin-21
+```
+
+**方法 C**: 使用 `docker` 驱动的 buildx 构建器（不需要推送镜像，但有其他限制）
+```bash
+# 创建使用 docker 驱动的构建器
+docker buildx create --name offline-builder --driver docker --use
+
+# 但这种方式无法使用 --cache-from type=local
+# 仅适用于简单的离线构建场景
+```
+
 ## 限制说明
 
 1. **镜像版本**: 基础镜像版本必须与缓存导出时一致
@@ -239,6 +325,42 @@ docker buildx build \
   -f scripts/images/backend/Dockerfile .
 ```
 
+## 文件清单
+
+```
+scripts/offline/
+├── export-cache.sh                    # 有网环境导出缓存脚本
+├── build-offline.sh                   # 基础离线构建脚本（BuildKit）
+├── build-offline-v2.sh                # 增强版离线构建脚本
+├── build-offline-classic.sh           # 传统 docker build 脚本（推荐）
+├── diagnose.sh                        # 环境诊断脚本
+├── Dockerfile.backend-python.offline  # backend-python 离线 Dockerfile
+├── Dockerfile.runtime.offline         # runtime 离线 Dockerfile
+├── Dockerfile.deer-flow-backend.offline   # deer-flow-backend 离线 Dockerfile
+├── Dockerfile.deer-flow-frontend.offline  # deer-flow-frontend 离线 Dockerfile
+├── Makefile.offline                   # 独立离线构建 Makefile
+└── README.md                          # 本文档
+
+Makefile.offline.mk                    # Makefile 扩展（追加到主 Makefile）
+```
+
+## 推荐工作流
+
+对于遇到镜像拉取问题的用户，推荐以下工作流：
+
+```bash
+# 有网环境
+make offline-export
+
+# 传输到无网环境
+scp build-cache-*.tar.gz offline-server:/path/
+
+# 无网环境
+tar -xzf build-cache-*.tar.gz
+make offline-diagnose        # 检查环境
+make offline-build-classic   # 使用传统构建
+```
+
 ## 参考
 
 - [Docker BuildKit Documentation](https://docs.docker.com/build/buildkit/)