7.5 KiB
7.5 KiB
脚本依赖管理规范
归属： SuiteForge 知识库 |
knowledge/script-dependencies.md版本： 1.0.0 关联： 脚本数据类型分类规范
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 中声明
# 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 中声明
当在套件中直接引用脚本时，也可以在步骤级别声明：
- id: parse-excel
type: script
script_id: run
dependencies:
pip:
- openpyxl>=3.0
步骤级声明会覆盖脚本自带的依赖声明。
4. 依赖分级处理机制
4.1 级别一：轻量运行时依赖（pip）
适用场景：
- 纯 Python 包，无编译依赖
- 体积小，安装快（< 30 秒）
- 非高频调用（偶尔使用）
处理流程：
# 容器启动时自动安装
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.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、扩展镜像、自定义镜像 |