205 lines
5.0 KiB
Markdown
205 lines
5.0 KiB
Markdown
# GasFlux 项目说明文档
|
|
|
|
## 项目概述
|
|
|
|
GasFlux 是一个基于 Flask 的气体通量分析 Web API 系统，专门用于处理无人机或飞行器采集的气体浓度数据，支持 CO₂、CH₄ 等温室气体通量的计算。
|
|
|
|
## 核心功能
|
|
|
|
### 🧪 数据处理
|
|
- **数据预处理**: Excel/CSV 文件解析，数据验证和清洗
|
|
- **背景校正**: 集成 FastChrom 算法的智能背景扣除
|
|
- **空间插值**: 克里金插值算法，支持多种半变异函数模型
|
|
- **通量计算**: 基于质量平衡法的气体通量计算
|
|
|
|
### 🌐 Web API 服务
|
|
- **RESTful API**: 完整的 HTTP API 接口
|
|
- **异步处理**: 支持大文件后台处理
|
|
- **实时监控**: 任务状态实时查询和进度跟踪
|
|
- **文件管理**: 自动上传、处理和下载管理
|
|
|
|
### 🔐 安全与认证
|
|
- **API 密钥认证**: 安全的密钥管理系统
|
|
- **权限控制**: 支持不同范围的 API 访问权限
|
|
- **引导密钥**: 初始管理员密钥配置
|
|
|
|
### 🧹 自动维护
|
|
- **任务清理**: 自动清理过期任务和文件
|
|
- **存储管理**: 智能的磁盘空间管理
|
|
- **日志记录**: 完整的操作日志和性能监控
|
|
|
|
## 技术架构
|
|
|
|
### 后端技术栈
|
|
- **框架**: Flask (Python Web 框架)
|
|
- **数据库**: SQLite (任务状态和配置存储)
|
|
- **部署**: Waitress (生产环境 WSGI 服务器)
|
|
- **认证**: 自定义 API 密钥系统
|
|
|
|
### 数据处理引擎
|
|
- **核心算法**: GasFlux 气体通量分析引擎
|
|
- **数据格式**: Excel, CSV, YAML 配置
|
|
- **输出格式**: CSV 数据, HTML 报告, PNG 图表
|
|
|
|
### 前端界面
|
|
- **Web 界面**: 内置 HTML/CSS/JavaScript 控制台
|
|
- **API 客户端**: 支持 cURL, Python requests 等
|
|
- **实时更新**: WebSocket 风格的任务状态轮询
|
|
|
|
## 快速开始
|
|
|
|
### 1. 环境准备
|
|
```bash
|
|
# Python 3.8+ 环境
|
|
python --version
|
|
|
|
# 安装依赖
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. 配置系统
|
|
```bash
|
|
# 编辑配置文件
|
|
notepad gasflux.ini
|
|
|
|
# 创建初始 API 密钥
|
|
python create_api_key.py
|
|
```
|
|
|
|
### 3. 启动服务
|
|
```bash
|
|
# 启动 Web API 服务
|
|
python -m src.gasflux.app
|
|
|
|
# 服务启动后访问: http://localhost:5001
|
|
```
|
|
|
|
### 4. 使用 API
|
|
```bash
|
|
# 上传处理文件
|
|
curl -X POST \
|
|
-H "X-API-Key: your-api-key" \
|
|
-F "file=@data.xlsx" \
|
|
http://localhost:5001/upload
|
|
```
|
|
|
|
## 配置文件说明
|
|
|
|
### gasflux.ini (主配置文件)
|
|
```ini
|
|
[server]
|
|
host = 0.0.0.0
|
|
port = 5001
|
|
debug = false
|
|
|
|
[paths]
|
|
uploads = ./web_api_data/uploads
|
|
outputs = ./web_api_data/outputs
|
|
|
|
[cleanup]
|
|
task_cleanup_interval = 30
|
|
successful_task_cleanup_age = 60
|
|
failed_task_cleanup_age = 60
|
|
janitor_dry_run = false
|
|
|
|
[security]
|
|
admin_bootstrap_key = bootstrap_key_2024
|
|
```
|
|
|
|
### gasflux_config.yaml (处理配置)
|
|
```yaml
|
|
output_dir: ./output
|
|
gases:
|
|
ch4: [1.5, 10.0]
|
|
co2: [300, 500]
|
|
strategies:
|
|
background: "algorithm"
|
|
spatial: "curtain"
|
|
interpolation: "kriging"
|
|
```
|
|
|
|
## API 接口列表
|
|
|
|
### 核心接口
|
|
- `POST /upload` - 文件上传和处理
|
|
- `GET /task/{task_id}` - 查询任务状态
|
|
- `GET /download/{path}` - 文件下载
|
|
- `GET /health` - 系统健康检查
|
|
|
|
### 管理接口
|
|
- `POST /api-keys` - 创建 API 密钥
|
|
- `GET /api-keys` - 列出 API 密钥
|
|
- `DELETE /api-keys/{key_id}` - 撤销 API 密钥
|
|
|
|
### 监控接口
|
|
- `GET /stats` - 系统统计信息
|
|
- `GET /config` - 配置信息查询
|
|
|
|
## 部署选项
|
|
|
|
### 开发环境
|
|
```bash
|
|
# 直接运行
|
|
python -m src.gasflux.app
|
|
```
|
|
|
|
### 生产环境 (Waitress)
|
|
```bash
|
|
# 使用 Waitress 服务器
|
|
python server_waitress.py
|
|
```
|
|
|
|
### Docker 部署
|
|
```bash
|
|
# 构建 Docker 镜像
|
|
docker build -t gasflux .
|
|
|
|
# 运行容器
|
|
docker run -p 5001:5001 gasflux
|
|
```
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
gasflux-develop/
|
|
├── src/gasflux/ # 核心源码
|
|
│ ├── app.py # Flask 应用主文件
|
|
│ ├── auth.py # 认证模块
|
|
│ ├── db.py # 数据库模块
|
|
│ ├── janitor.py # 自动清理模块
|
|
│ └── blueprints/ # API 蓝图
|
|
├── gasflux.ini # 主配置文件
|
|
├── create_api_key.py # API 密钥创建工具
|
|
├── requirements.txt # Python 依赖
|
|
├── web_api_data/ # 数据目录
|
|
│ ├── uploads/ # 上传文件
|
|
│ └── outputs/ # 输出文件
|
|
└── logs/ # 日志文件
|
|
```
|
|
|
|
## 常见问题
|
|
|
|
### Q: 如何创建 API 密钥？
|
|
A: 运行 `python create_api_key.py`，按照提示输入描述信息。
|
|
|
|
### Q: 如何查看任务处理状态？
|
|
A: 使用 `GET /task/{task_id}` 接口，或在 Web 界面中查看。
|
|
|
|
### Q: 如何修改清理策略？
|
|
A: 编辑 `gasflux.ini` 中的 `[cleanup]` 部分配置。
|
|
|
|
### Q: 系统支持哪些气体？
|
|
A: 目前支持 CO₂、CH₄ 等主要温室气体，可在配置中扩展。
|
|
|
|
## 技术支持
|
|
|
|
- **项目主页**: [GitHub Repository]
|
|
- **文档**: [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
|
|
- **配置指南**: [CONFIG_README.md](CONFIG_README.md)
|
|
- **部署指南**: [WAITRESS_DEPLOYMENT.md](WAITRESS_DEPLOYMENT.md)
|
|
|
|
## 版本信息
|
|
|
|
- **当前版本**: v0.2.1
|
|
- **Python 版本**: 3.8+
|
|
- **许可证**: AGPL v3.0 |