252 lines
7.6 KiB
Markdown
252 lines
7.6 KiB
Markdown
# 脚本依赖管理规范
|
||
|
||
> **归属：** 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、扩展镜像、自定义镜像 |
|