diff --git a/suite-developer/knowledge/script-dependencies.md b/suite-developer/knowledge/script-dependencies.md deleted file mode 100644 index 93f3b40..0000000 --- a/suite-developer/knowledge/script-dependencies.md +++ /dev/null @@ -1,245 +0,0 @@ -# 脚本依赖管理规范 - -> **归属：** 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: python - 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 秒以上的 - -**扩展镜像命名规则：** - -``` -gis-ext-{功能}:latest（自托管） -``` - -**已规划扩展镜像：** - -| 镜像名 | 包含依赖 | 典型脚本场景 | -|--------|---------|-------------| -| `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 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` 只能引用 `gis-base:*` 系列镜像 -- 不允许 `FROM` 外部镜像库（安全性） -- `RUN pip` 的来源 URL 必须在白名单内（PyPI 官方默认通过） -- `RUN apt` 来源必须在 `apt allowlist` 内 - -**CI 流水线（Cron 兜底）：** - -``` -脚本发布 → 检测到 Dockerfile.ext - → 合规检测通过 - → 构建自定义镜像 - → 推送到自建 Docker Registry 或 Gitea Packages OCI - → 将镜像 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. 通过 API 发布（详见套件发布指南） -``` - -**SuiteForge 应在初始化套件时根据脚本内容自动推断依赖**，无需开发者手动填写 metadata。开发者只需要告诉 SuiteForge "我想处理 Excel 文件"，剩下的由 Agent 完成。 - ---- - -## 9. 与相关服务的关系 - -| 服务 | 对接方式 | -|------|---------| -| **合规检测服务** | 读取 dependencies 字段 + Dockerfile.ext 进行安全校验 | -| **调度中心** | 根据依赖选择镜像层次（base / ext / custom） | -| **构建流水线（Cron）** | 检测到 Dockerfile.ext 时触发自定义镜像构建 | -| **镜像仓库（Registry）** | 存储 gis-base、扩展镜像、自定义镜像 |