From 18165a24a973ca3e5698f3aeaefeccc3cdc69d84 Mon Sep 17 00:00:00 2001 From: Huawei Date: Fri, 10 Jul 2026 03:06:44 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E8=84=9A=E6=9C=AC?= =?UTF-8?q?=E4=BE=9D=E8=B5=96=E7=AE=A1=E7=90=86=E8=A7=84=E8=8C=83=EF=BC=88?= =?UTF-8?q?knowledge/script-dependencies.md=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../knowledge/script-dependencies.md | 251 ++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 suite-developer/knowledge/script-dependencies.md diff --git a/suite-developer/knowledge/script-dependencies.md b/suite-developer/knowledge/script-dependencies.md new file mode 100644 index 0000000..aecc839 --- /dev/null +++ b/suite-developer/knowledge/script-dependencies.md @@ -0,0 +1,251 @@ +# 脚本依赖管理规范 + +> **归属：** SuiteForge 知识库 | `knowledge/script-dependencies.md` +> **版本：** 1.0.0 +> **关联：** [脚本数据类型分类规范](./script-data-types.md) + +--- + +## 1. 核心原则 + +- **gis-base 保持精干** — 只放所有脚本绝对需要的核心库 +- **依赖按需加载** — 不允许在基础镜像预装所有可能的依赖 +- **依赖类型决定加载策略** — 轻量运行时装、中量预构建镜像、重型发布时构建 + +--- + +## 2. gis-base 内置依赖（开箱即有） + +以下库在 `gis-base` 镜像中预置，脚本无需额外声明依赖即可使用： + +| 类别 | 库 | 用途 | +|------|----|------| +| Python 标准库 | `os`, `sys`, `json`, `csv`, `math`, `re`, `pathlib`, `shutil`, `subprocess`, `tempfile`, `zipfile`, `tarfile`, `uuid`, `datetime`, `logging` | 基础操作 | +| 数值计算 | `numpy` | 核心数组运算 | +| GIS 核心 | `gdal`（含 `ogr`, `osr`, `gdalconst`）, `osgeo` | 栅格/矢量读写 | +| GIS 扩展 | `shapely`, `geopandas`, `pyproj`, `fiona` | 空间分析 | +| 序列化 | `orjson` | 高性能 JSON | + +> **注意：** gis-base 镜像内容由平台团队维护。需要新增内置库时，请通过 Issue 提出，交 Admin 处理。 + +--- + +## 3. 依赖声明方式 + +### 3.1 脚本 metadata 中声明 + +```yaml +# scripts/run.py 同目录的 metadata.yaml +name: 读取 Excel 坐标转 Shapefile +version: 1.0.0 +data_type: document/xlsx +dependencies: + # 轻量运行时依赖 + pip: + - openpyxl>=3.0 + - python-docx>=0.8 + + # 系统级依赖（apt 包） + system: + - libpdal-dev # 点云处理库 + + # 构建时依赖（必须通过 Dockerfile.ext 安装） + build: + # 空数组表示无构建时依赖 +``` + +### 3.2 workflow.yaml 中声明 + +当在套件中直接引用脚本时，也可以在步骤级别声明： + +```yaml +- id: parse-excel + type: script + script_id: run + dependencies: + pip: + - openpyxl>=3.0 +``` + +> 步骤级声明会覆盖脚本自带的依赖声明。 + +--- + +## 4. 依赖分级处理机制 + +### 4.1 级别一：轻量运行时依赖（pip） + +**适用场景：** +- 纯 Python 包，无编译依赖 +- 体积小，安装快（< 30 秒） +- 非高频调用（偶尔使用） + +**处理流程：** +```bash +# 容器启动时自动安装 +docker run --rm gis-base \ + pip install openpyxl python-docx --no-cache-dir \ + && python /tmp/scripts/run.py +``` + +**限速规则：** 单次任务安装的 pip 包不超过 10 个，总安装时间不超过 60 秒。 + +### 4.2 级别二：中量扩展镜像（预构建） + +**适用场景：** +- 经常被调用的扩展依赖 +- 有编译环节的包（C 扩展） +- 安装需要 30 秒以上的 + +**扩展镜像命名规则：** + +``` +registry.mercator.cn/agentgis/gis-ext-{功能}:{版本} +``` + +**已规划扩展镜像：** + +| 镜像名 | 包含依赖 | 典型脚本场景 | +|--------|---------|-------------| +| `gis-ext-doc` | `openpyxl`, `python-docx`, `pypdf2`, `python-pptx` | Office 文档处理 | +| `gis-ext-pointcloud` | `laspy`, `pdal`, `open3d-python` | 点云处理 | +| `gis-ext-raster` | `rioxarray`, `rasterio`, `xarray`, `scipy` | 高级栅格分析 | +| `gis-ext-geoanalysis` | `scipy`, `scikit-learn`, `statsmodels` | 空间统计分析 | +| `gis-ext-ml` | `scikit-learn`, `xgboost`, `lightgbm` | 地理空间机器学习 | +| `gis-ext-web` | `requests`, `httpx`, `aiohttp`, `beautifulsoup4` | 网络数据抓取 | +| `gis-ext-db` | `psycopg2-binary`, `sqlalchemy`, `sqlite-utils` | 数据库连接 | + +**匹配逻辑（调度中心）：** + +``` +脚本声明的 pip 依赖 + ↓ +调度中心匹配 → 命中扩展镜像 → 使用扩展镜像运行 + → 未命中 → 回退级别一（运行时安装） +``` + +匹配是取**最小子集**——如果脚本只需要 `openpyxl`，就用 `gis-ext-doc`，而不是选所有包含 `openpyxl` 的镜像。 + +### 4.3 级别三：重型自定义镜像（构建时） + +**适用场景：** +- 深度学习框架（PyTorch, TensorFlow） +- 需要 GPU 加速（CUDA 依赖） +- 专有库/商业许可库（选装） +- 安装时间 > 120 秒的 + +**处理方式：** + +脚本发布时附带 `Dockerfile.ext`： + +```dockerfile +# Dockerfile.ext +FROM registry.mercator.cn/agentgis/gis-base:latest + +# 安装系统依赖 +RUN apt-get update && apt-get install -y --no-install-recommends \ + libgl1-mesa-glx \ + && rm -rf /var/lib/apt/lists/* + +# 安装 Python 依赖 +RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu \ + opencv-python-headless \ + --no-cache-dir +``` + +**合规检测规则：** +- `FROM` 只能引用 `registry.mercator.cn/agentgis/*` 系列镜像 +- 不允许 `FROM` 外部镜像库（安全性） +- `RUN pip` 的来源 URL 必须在白名单内（PyPI 官方默认通过） +- `RUN apt` 来源必须在 `apt allowlist` 内 + +**CI 流水线（Cron 兜底）：** + +``` +脚本发布 → 检测到 Dockerfile.ext + → 合规检测通过 + → 构建自定义镜像 + → 推送到 registry.mercator.cn/agentgis/custom/{suite_id}:{version} + → 将镜像 ID 写入脚本 metadata +``` + +--- + +## 5. 依赖来源安全白名单 + +### 5.1 Python 包 + +| 来源 | 状态 | 说明 | +|------|------|------| +| `pypi.org`（官方） | ✅ 白名单 | 默认允许 | +| `download.pytorch.org` | ✅ 白名单 | ML 框架 | +| `github.com/releases` | ⚠️ 需审核 | 非标准包需要人工审核 | + +### 5.2 系统包（apt） + +| 来源 | 状态 | 说明 | +|------|------|------| +| `archive.ubuntu.com` | ✅ 白名单 | Ubuntu 官方源 | +| `security.ubuntu.com` | ✅ 白名单 | 安全更新 | +| `ppa.launchpad.net` | ❌ 禁止 | PPA 源不稳定 | + +--- + +## 6. 常见场景参考 + +| 脚本要做什么 | 推荐方案 | 依赖示例 | +|------------|---------|---------| +| 读取 Excel 坐标转点 | 级别一 | `openpyxl` | +| PDF 空间信息提取 | 级别一 | `pypdf2` | +| 点云格式转换（LAS → LAZ）| 级别二 | 预置 `gis-ext-pointcloud` | +| 地形分析（坡度/坡向）| 内置 | `numpy` + `gdal` 已内置 | +| 地理空间分类模型 | 级别二 | 预置 `gis-ext-geoanalysis` | +| 遥感影像深度学习分类 | 级别三 | `torch`, `opencv` | +| 企业微信消息推送 | 级别一 | `requests` 已内置 | +| 大量 GeoJSON 合并 | 内置 | `geopandas` 已内置 | + +--- + +## 7. 镜像更新策略 + +### 扩展镜像 +- 每月重建一次（拉取最新安全更新） +- 有 CVE 时立即重建 +- 版本锁定的包如无必要不升级大版本 + +### gis-base +- 仅在有架构级更新时重建 +- 版本变更需经过完整回归测试 +- 历史版本保留至少 3 个次要版本 + +### 自定义镜像 +- 由脚本开发者管理版本 +- 重新发布脚本时自动重建 +- 无自动更新，需要开发者主动重新发布 + +--- + +## 8. 开发者工作流（供 SuiteForge 参考） + +``` +1. 想清脚本需要什么依赖 +2. 查 gis-base 内置列表 → 已有的不声明 +3. 查扩展镜像列表 → 匹配的用级别二 +4. 都不行 → 看看能不能用轻量安装（级别一） +5. 真不行 → 写 Dockerfile.ext（级别三） +6. 完成 metadata.yaml 声明 +7. agc publish → 合规检测自动处理 +``` + +**SuiteForge 应在初始化套件时根据脚本内容自动推断依赖**，无需开发者手动填写 metadata。开发者只需要告诉 SuiteForge "我想处理 Excel 文件"，剩下的由 Agent 完成。 + +--- + +## 9. 与相关服务的关系 + +| 服务 | 对接方式 | +|------|---------| +| **合规检测服务** | 读取 dependencies 字段 + Dockerfile.ext 进行安全校验 | +| **调度中心** | 根据依赖选择镜像层次（base / ext / custom） | +| **构建流水线（Cron）** | 检测到 Dockerfile.ext 时触发自定义镜像构建 | +| **镜像仓库（Registry）** | 存储 gis-base、扩展镜像、自定义镜像 |