第二章：安装与环境配置

2.1 系统要求

在安装 GeoPipeAgent 之前，请确认你的环境满足以下要求：

要求	最低版本	推荐版本
Python	3.10	3.11+
pip	21.0	最新版
操作系统	Windows / macOS / Linux	Ubuntu 22.04+ / macOS 13+

2.2 安装方式

GeoPipeAgent 通过 pip 安装，支持基础安装和带可选依赖的扩展安装。

2.2.1 从源码安装（推荐）

# 克隆仓库
git clone https://github.com/znlgis/GeoPipeAgent.git
cd GeoPipeAgent

# 基础安装（仅核心功能：IO、矢量、栅格步骤）
pip install -e .

# 安装全部可选依赖（推荐开发者使用）
pip install -e ".[dev,analysis,network]"

2.2.2 可选依赖组说明

GeoPipeAgent 将可选依赖划分为三个组，按需安装：

依赖组	包含的包	启用的功能
`dev`	pytest, pytest-cov	开发与测试工具
`analysis`	scipy, scikit-learn, matplotlib	空间分析步骤（泰森多边形、热力图、插值、聚类）
`network`	networkx, geopy	网络分析步骤（最短路径、服务区、地理编码）

# 仅安装空间分析依赖
pip install -e ".[analysis]"

# 仅安装网络分析依赖
pip install -e ".[network]"

# 同时安装空间分析和网络分析
pip install -e ".[analysis,network]"

2.3 核心依赖说明

基础安装会自动安装以下核心依赖（已在 pyproject.toml 中定义）：

依赖包	版本要求	用途
`click`	>=8.0	CLI 命令行接口框架
`pyyaml`	>=6.0	YAML 流水线解析
`numpy`	>=1.24	数值计算（栅格分析依赖）
`geopandas`	>=0.14	矢量数据处理引擎
`shapely`	>=2.0	几何运算库
`pyproj`	>=3.5	坐标参考系转换
`rasterio`	>=1.3	栅格数据读写

注意：geopandas 本身依赖 fiona（或 pyogrio）、pyproj、shapely，这些会随 geopandas 自动安装。

2.4 验证安装

安装完成后，运行以下命令验证：

# 查看版本
geopipe-agent --version

# 列出所有内置步骤（应显示 33 个步骤）
geopipe-agent list-steps

# 查看可用后端（显示各后端的可用状态）
geopipe-agent backends

预期输出示例：

# geopipe-agent list-steps
ID                             Name                 Category     Backends
--------------------------------------------------------------------------------
io.read_vector                 读取矢量数据         io           -
io.write_vector                写入矢量数据         io           -
io.read_raster                 读取栅格数据         io           -
io.write_raster                写入栅格数据         io           -
vector.buffer                  矢量缓冲区分析       vector       native_python, qgis_process
vector.clip                    矢量裁剪             vector       native_python, qgis_process
...

Total: 33 steps

// geopipe-agent backends
[
  {"name": "native_python", "available": true},
  {"name": "gdal_cli",      "available": false},
  {"name": "gdal_python",   "available": false},
  {"name": "qgis_process",  "available": false},
  {"name": "pyqgis",        "available": false},
  {"name": "generic_cli",   "available": true},
  {"name": "curl_api",      "available": true}
]

2.5 推荐使用虚拟环境

强烈建议在虚拟环境中安装，避免与系统包产生冲突：

# 使用 venv（标准库）
python -m venv geopipe-env
source geopipe-env/bin/activate      # Linux / macOS
geopipe-env\Scripts\activate.bat     # Windows

# 在激活的虚拟环境中安装
pip install -e ".[dev,analysis,network]"

或使用 conda：

# 创建 conda 环境（geopandas 在 conda-forge 上依赖更完整）
conda create -n geopipe python=3.11
conda activate geopipe
conda install -c conda-forge geopandas rasterio pyproj shapely
pip install -e ".[dev,analysis,network]"

提示：在 Windows 上，推荐使用 conda 安装 geopandas，避免 GDAL/Fiona 的编译问题。在 Linux/macOS 上，pip 直接安装通常无问题。

2.6 安装外部后端工具（可选）

基础安装只需 Python 环境即可使用 native_python 后端。如需使用其他后端，需要额外安装：

GDAL CLI 后端（`gdal_cli`）

# Ubuntu
sudo apt-get install gdal-bin

# macOS (Homebrew)
brew install gdal

# 验证
ogr2ogr --version

GDAL Python 后端（`gdal_python`）

# Ubuntu
sudo apt-get install python3-gdal

# 或通过 pip（需要先安装系统 GDAL）
pip install GDAL==$(gdal-config --version)

QGIS 后端（`qgis_process` / `pyqgis`）

参考 QGIS 官方安装指南安装 QGIS Desktop，安装后 qgis_process 命令行工具会自动注册到系统 PATH。

2.7 开发环境配置

如果你计划为 GeoPipeAgent 贡献代码或开发自定义步骤，需要安装开发依赖：

# 安装包括测试工具在内的所有依赖
pip install -e ".[dev,analysis,network]"

# 运行完整测试套件
python -m pytest -v

# 运行带覆盖率的测试
python -m pytest -v --cov=geopipe_agent --cov-report=term-missing

2.8 常见安装问题

问题 1：`shapely` 版本冲突

GeoPipeAgent 要求 shapely>=2.0。如果系统中安装了旧版 shapely，升级：

pip install --upgrade "shapely>=2.0"

问题 2：`geopandas` 安装失败（Windows）

Windows 上 geopandas 可能因 GDAL/Fiona 编译失败。推荐方案：

# 方案一：使用 conda-forge
conda install -c conda-forge geopandas

# 方案二：使用预编译的 wheel（从 Christoph Gohlke 的网站）
pip install pipwin
pipwin install gdal fiona geopandas

问题 3：`rasterio` 安装失败

类似 geopandas，rasterio 在 Windows 上建议使用 conda：

conda install -c conda-forge rasterio

问题 4：`geopipe-agent` 命令找不到

这通常是因为 Python scripts 目录不在 PATH 中。解决方案：

# 方案一：使用 python -m 方式运行
python -m geopipe_agent.cli --version

# 方案二：找到 scripts 目录并加入 PATH
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
# 将输出的路径加入系统 PATH

问题 5：`scipy` / `scikit-learn` 安装慢

空间分析依赖较大，如果 pip 安装较慢，可以使用国内镜像：

pip install -e ".[analysis,network]" -i https://pypi.tuna.tsinghua.edu.cn/simple/

2.9 本章小结

本章介绍了 GeoPipeAgent 的安装与环境配置：

系统要求：Python 3.10+，推荐使用虚拟环境
安装命令：pip install -e ".[dev,analysis,network]" 安装全部依赖
可选依赖组：analysis（空间分析）和 network（网络分析）按需安装
安装验证：通过 geopipe-agent list-steps 和 geopipe-agent backends 验证
外部后端：GDAL、QGIS 等外部工具按需安装，默认 native_python 后端无需额外安装

下一章将编写并运行你的第一个 GeoPipeAgent 流水线。

导航：← 第一章：概述与核心理念｜第三章：快速上手 →