# Python依赖库离线部署指南

本文档提供了 QAUP-Management 项目中 tools 目录下 Python 脚本的离线部署指南。

## 📋 概述

通过对 tools 目录下 4 个 Python 文件的依赖分析，除了 Flask 之外，还需要安装以下外部库用于完整功能支持。

## 📂 分析的文件

- `tools/mock_airport.py` - 机场管理系统模拟服务
- `tools/mock_traffic_light.py` - 红绿灯设备模拟器
- `tools/mock_unmanned_vehicle.py` - 无人车厂商平台模拟服务
- `tools/aircraft_routes_from_api.py` - 航空器路由数据定义

## 📦 依赖库清单

### 🚀 必需的外部库

| 库名 | 用途 | 使用文件 | 关键功能 |
|-----|------|---------|----------|
| **Flask** | Web服务框架 | 所有mock_*.py文件 | API服务、HTTP路由 |
| **pyproj** | 坐标系转换 | mock_airport.py | CGCS2000↔WGS84精确转换 |
| **Shapely** | 几何操作 | mock_airport.py | 路径合并(linemerge)、几何计算 |

### 📚 内置库（无需安装）

以下库为 Python 标准库，无需额外安装：
```
time, math, logging, os, threading, atexit, socket, json,
argparse, datetime, signal, typing, collections.abc, copy
```

### 🔄 回退机制

- **pyproj**: 不可用时自动回退到简化坐标转换算法
- **Shapely**: 不可用时跳过路径合并，基本功能仍可用

## 🛠️ 离线部署步骤

### 步骤1：在联网机器上下载依赖包

```bash
# 创建依赖包目录
mkdir offline_packages
cd offline_packages

# 下载所有依赖包（包含依赖的依赖）
pip download Flask pyproj Shapely

# 或者如果有requirements.txt
pip download -r ../requirements.txt
```

### 步骤2：打包传输

```bash
# 打包下载的文件
tar -czf python_packages.tar.gz offline_packages/

# 传输到离线机器
scp python_packages.tar.gz user@offline-server:/path/to/destination/
```

### 步骤3：在离线机器上安装

```bash
# 解压依赖包
tar -xzf python_packages.tar.gz

# 离线安装
pip install --find-links ./offline_packages --no-index Flask pyproj Shapely

# 或者如果有requirements.txt
pip install --find-links ./offline_packages --no-index -r requirements.txt
```

## ✅ 安装验证

### 验证脚本

创建 `test_dependencies.py` 文件：

```python
#!/usr/bin/env python3
"""
依赖库安装验证脚本
"""
import sys

def test_imports():
    """测试所有必需库的导入"""
    success = True

    # 测试基础库
    try:
        import flask
        print("✅ Flask: OK")
    except ImportError as e:
        print(f"❌ Flask: FAILED - {e}")
        success = False

    # 测试坐标转换库
    try:
        import pyproj
        print("✅ pyproj: OK")
    except ImportError as e:
        print(f"⚠️  pyproj: MISSING - 将使用简化坐标转换算法")

    # 测试几何库
    try:
        import shapely
        print("✅ Shapely: OK")
    except ImportError as e:
        print(f"⚠️  Shapely: MISSING - 路径合并功能将被跳过")

    # 测试标准库
    standard_libs = [
        'time', 'math', 'logging', 'os', 'threading', 'atexit',
        'socket', 'json', 'argparse', 'datetime', 'signal', 'typing'
    ]

    for lib in standard_libs:
        try:
            __import__(lib)
        except ImportError as e:
            print(f"❌ {lib}: FAILED - {e}")
            success = False

    print("✅ 所有标准库: OK")

    return success

def test_functionality():
    """测试关键功能"""
    print("\n🧪 测试关键功能...")

    # 测试坐标转换
    try:
        from pyproj import CRS, Transformer
        wgs84_crs = CRS.from_epsg(4326)
        print("✅ 坐标系转换功能: OK")
    except ImportError:
        print("⚠️  坐标系转换功能: 使用简化算法")
    except Exception as e:
        print(f"❌ 坐标系转换功能: ERROR - {e}")

    # 测试几何操作
    try:
        from shapely.geometry import LineString
        from shapely.ops import linemerge
        lines = [LineString([(0,0), (1,1)]), LineString([(1,1), (2,2)])]
        merged = linemerge(lines)
        print("✅ 几何操作功能: OK")
    except ImportError:
        print("⚠️  几何操作功能: 路径合并将被跳过")
    except Exception as e:
        print(f"❌ 几何操作功能: ERROR - {e}")

if __name__ == "__main__":
    print("🔍 验证Python依赖库安装...")
    print("=" * 50)

    if test_imports():
        print("\n✅ 核心依赖库验证通过")
        test_functionality()
        print("\n🎉 系统准备就绪，可以运行tools目录下的Python脚本")
        sys.exit(0)
    else:
        print("\n❌ 依赖库验证失败，请检查安装")
        sys.exit(1)
```

运行验证：
```bash
python test_dependencies.py
```

## 📄 requirements.txt

建议创建 `requirements.txt` 文件：

```txt
# QAUP-Management Tools Dependencies
Flask>=2.0.0
pyproj>=3.0.0
Shapely>=1.8.0
```

## 🔧 故障排除

### 常见问题

1. **pyproj 安装失败**
   ```bash
   # 可能需要系统级依赖
   # Ubuntu/Debian
   sudo apt-get install libproj-dev proj-data proj-bin

   # CentOS/RHEL
   sudo yum install proj-devel
   ```

2. **Shapely 安装失败**
   ```bash
   # 可能需要 GEOS 库
   # Ubuntu/Debian
   sudo apt-get install libgeos-dev

   # CentOS/RHEL
   sudo yum install geos-devel
   ```

3. **权限问题**
   ```bash
   # 使用用户安装
   pip install --user --find-links ./offline_packages --no-index Flask pyproj Shapely
   ```

### 验证服务启动

```bash
# 测试启动各个模拟服务
cd tools

# 机场管理服务 (端口8090)
python3 mock_airport.py

# 红绿灯模拟器 (端口8082)
python3 mock_traffic_light.py

# 无人车平台服务 (端口8091)
python3 mock_unmanned_vehicle.py
```

## 📝 注意事项

1. **Python版本**: 建议使用Python 3.7+
2. **网络隔离**: 确保 `--no-index` 参数防止联网下载
3. **依赖版本**: 固定版本号避免兼容性问题
4. **回退机制**: pyproj和Shapely不可用时会自动降级，基本功能仍可用
5. **日志目录**: 确保运行目录有写权限创建logs目录

## 🆘 技术支持

如果遇到安装问题：

1. 检查Python版本: `python --version`
2. 检查pip版本: `pip --version`
3. 运行验证脚本: `python test_dependencies.py`
4. 查看错误日志: `logs/mock_server.log`

---
*文档生成时间: 2024年*
*适用于: QAUP-Management 项目 tools 目录*