常规更新
This commit is contained in:
793
项目交接文档.md
Normal file
793
项目交接文档.md
Normal file
@ -0,0 +1,793 @@
|
||||
# GasFlux Web API 项目交接文档
|
||||
|
||||
> **文档版本**: 1.0
|
||||
> **最后更新**: 2026年4月13日
|
||||
> **项目路径**: `e:\code\CO2data\gasflux-develop\gasflux-develop-no-dockerV6`
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
### 1.1 项目简介
|
||||
GasFlux 是一个专业的气体通量处理系统，用于处理无人机或飞行器采集的气体浓度数据，计算气体通量（如 CO₂、CH₄ 等）。该系统集成了完整的数据处理流程，包括数据预处理、背景校正、空间插值和报告生成。
|
||||
|
||||
### 1.2 核心功能
|
||||
- **数据上传与处理**: 支持 Excel 文件 (.xlsx, .xls) 上传和异步处理
|
||||
- **气体通量计算**: 支持 CO₂、CH₄ 等温室气体的通量计算
|
||||
- **背景校正**: 集成 FastChrom 背景校正算法
|
||||
- **空间插值**: 克里金 (Kriging) 插值算法
|
||||
- **报告生成**: 自动生成 HTML 分析报告和数据导出
|
||||
- **实时监控**: 任务状态实时查询和监控
|
||||
- **RESTful API**: 完整的 Web API 接口
|
||||
|
||||
### 1.3 技术栈
|
||||
- **后端框架**: Flask + Waitress WSGI 服务器
|
||||
- **数据处理**: Pandas, NumPy, SciPy
|
||||
- **空间分析**: scikit-gstat (地质统计学)
|
||||
- **机器学习**: scikit-learn
|
||||
- **可视化**: Matplotlib
|
||||
- **数据库**: SQLite (任务状态持久化)
|
||||
- **配置管理**: INI 文件 + 环境变量
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目结构
|
||||
|
||||
```
|
||||
gasflux-develop-no-dockerV6/
|
||||
├── server_waitress.py # 生产服务器入口点 (★核心文件)
|
||||
├── run_api.py # 开发环境 API 启动脚本
|
||||
├── create_api_key.py # API 密钥管理工具
|
||||
├── requirements.txt # Python 依赖列表
|
||||
├── build_exe.bat/.sh # 可执行文件构建脚本
|
||||
│
|
||||
├── src/gasflux/ # 核心源代码
|
||||
│ ├── app.py # Flask 应用主入口
|
||||
│ ├── config_reader.py # INI 配置文件读取器
|
||||
│ ├── processing.py # 数据处理算法
|
||||
│ ├── processing_pipelines.py # 处理流程编排
|
||||
│ ├── data_processor.py # 数据预处理
|
||||
│ ├── background.py # 背景校正算法
|
||||
│ ├── interpolation.py # 空间插值算法
|
||||
│ ├── plotting.py # 可视化图表生成
|
||||
│ ├── reporting.py # 报告生成
|
||||
│ ├── gas.py # 气体属性计算
|
||||
│ ├── ml.py # 机器学习模块
|
||||
│ ├── db.py # 数据库管理
|
||||
│ ├── auth.py # 认证与授权
|
||||
│ ├── shared.py # 共享工具和常量
|
||||
│ ├── janitor.py # 后台清理任务
|
||||
│ ├── blueprints/ # Flask 蓝图 (API 端点)
|
||||
│ │ ├── upload.py # 文件上传处理
|
||||
│ │ ├── tasks.py # 任务管理
|
||||
│ │ ├── task_pool.py # 任务池管理
|
||||
│ │ ├── download.py # 文件下载
|
||||
│ │ ├── reports.py # 报告查询
|
||||
│ │ ├── health.py # 健康检查
|
||||
│ │ ├── stats.py # 统计信息
|
||||
│ │ ├── config.py # 配置信息
|
||||
│ │ ├── web.py # Web 界面
|
||||
│ │ └── api_keys.py # API 密钥管理
|
||||
│ └── gasflux_config.yaml # 默认 YAML 配置文件
|
||||
│
|
||||
├── web_api_data/ # 数据存储目录
|
||||
│ ├── uploads/ # 上传文件存储
|
||||
│ └── outputs/ # 处理结果输出
|
||||
│
|
||||
└── docs/ # 文档目录
|
||||
├── API_DOCUMENTATION.md # 完整 API 文档
|
||||
├── WAITRESS_DEPLOYMENT.md # Waitress 部署指南
|
||||
├── README.md # 项目说明
|
||||
└── *.md # 其他文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心组件详解
|
||||
|
||||
### 3.1 server_waitress.py (生产服务器入口)
|
||||
|
||||
**文件作用**: 使用 Waitress WSGI 服务器启动 GasFlux Web API 的生产环境入口点。
|
||||
|
||||
**关键特性**:
|
||||
- 支持完整 GasFlux 处理功能
|
||||
- 任务池管理和异步处理
|
||||
- 实时任务状态监控
|
||||
- 报告生成和文件下载
|
||||
- 健康监控和统计信息
|
||||
|
||||
**启动方式**:
|
||||
```bash
|
||||
# 直接运行
|
||||
python server_waitress.py
|
||||
|
||||
# 或使用 PyInstaller 打包
|
||||
pyinstaller --onefile --name GasFluxAPI server_waitress.py
|
||||
```
|
||||
|
||||
**启动后输出示例**:
|
||||
```
|
||||
Starting GasFlux Web API with Waitress...
|
||||
✓ GasFlux app imported successfully
|
||||
✓ Task pool management enabled
|
||||
✓ All blueprints loaded: upload, tasks, task_pool, download, reports, health, stats, config, web
|
||||
✓ Waitress WSGI server imported
|
||||
Starting Waitress server on 0.0.0.0:5000
|
||||
- Threads: 8
|
||||
- Connection limit: 100
|
||||
- Channel timeout: 300s
|
||||
- Base URL: http://localhost:5000
|
||||
```
|
||||
|
||||
**主要代码结构**:
|
||||
```python
|
||||
# 1. 环境设置
|
||||
os.environ['MPLBACKEND'] = 'Agg' # 避免 GUI 依赖
|
||||
sys.path.insert(0, str(project_root))
|
||||
sys.path.insert(0, str(src_dir))
|
||||
|
||||
# 2. 配置加载
|
||||
from src.gasflux.app import Config
|
||||
host = Config.HOST
|
||||
port = Config.PORT
|
||||
threads = Config.THREADS
|
||||
|
||||
# 3. 启动 Waitress 服务器
|
||||
from waitress import serve
|
||||
serve(app, host=host, port=port, threads=threads, ...)
|
||||
```
|
||||
|
||||
### 3.2 src/gasflux/app.py (Flask 应用核心)
|
||||
|
||||
**文件作用**: Flask 应用的主入口，定义了 Config 配置类和 API 统计收集器。
|
||||
|
||||
**核心类**:
|
||||
|
||||
#### Config 类
|
||||
```python
|
||||
class Config:
|
||||
"""配置管理，从 INI 文件读取，支持环境变量覆盖"""
|
||||
|
||||
# 服务器配置
|
||||
HOST = config_reader.host # 默认: 0.0.0.0
|
||||
PORT = config_reader.port # 默认: 5000
|
||||
DEBUG = config_reader.debug # 默认: false
|
||||
BASE_URL = config_reader.base_url # 默认: http://localhost:5000
|
||||
|
||||
# 目录配置
|
||||
UPLOAD_FOLDER = ... # 上传文件目录
|
||||
OUTPUT_FOLDER = ... # 输出文件目录
|
||||
|
||||
# 性能配置
|
||||
THREADS = config_reader.threads # 默认: 8
|
||||
CONNECTION_LIMIT = config_reader.connection_limit # 默认: 100
|
||||
CHANNEL_TIMEOUT = config_reader.channel_timeout # 默认: 300
|
||||
|
||||
# 任务清理配置
|
||||
TASK_CLEANUP_INTERVAL = 3600 # 清理间隔(秒)
|
||||
MAX_TASK_AGE = 86400 # 最大任务年龄
|
||||
SUCCESSFUL_TASK_CLEANUP_AGE = 3600 # 成功任务清理时间
|
||||
FAILED_TASK_CLEANUP_AGE = 604800 # 失败任务清理时间
|
||||
```
|
||||
|
||||
#### APIStatsCollector 类
|
||||
收集 API 统计信息，包括:
|
||||
- 请求统计 (按方法、端点、状态码)
|
||||
- 任务统计 (创建、完成、失败)
|
||||
- 性能指标 (响应时间、错误率)
|
||||
- 系统资源 (内存、磁盘使用)
|
||||
|
||||
### 3.3 src/gasflux/config_reader.py (配置读取器)
|
||||
|
||||
**文件作用**: 从 INI 文件读取配置，支持环境变量覆盖。
|
||||
|
||||
**配置文件优先级**:
|
||||
1. 当前目录 `gasflux.ini`
|
||||
2. 当前目录 `config.ini`
|
||||
3. 项目根目录 `gasflux.ini`
|
||||
|
||||
**默认配置项** (gasflux.ini 示例):
|
||||
```ini
|
||||
[server]
|
||||
host = 0.0.0.0
|
||||
port = 5000
|
||||
debug = false
|
||||
base_url = http://localhost:5000
|
||||
|
||||
[paths]
|
||||
uploads = ./web_api_data/uploads
|
||||
outputs = ./web_api_data/outputs
|
||||
|
||||
[limits]
|
||||
max_content_length = 104857600
|
||||
|
||||
[logging]
|
||||
level = INFO
|
||||
file = logs/gasflux_api.log
|
||||
|
||||
[performance]
|
||||
threads = 8
|
||||
connection_limit = 100
|
||||
channel_timeout = 300
|
||||
|
||||
[cleanup]
|
||||
task_cleanup_interval = 3600
|
||||
max_task_age = 86400
|
||||
successful_task_cleanup_age = 3600
|
||||
failed_task_cleanup_age = 604800
|
||||
|
||||
[security]
|
||||
admin_bootstrap_key = your_bootstrap_key_here
|
||||
|
||||
[database]
|
||||
path = web_api_data/outputs/gasflux.db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API 端点一览
|
||||
|
||||
### 4.1 监控和健康检查
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/health` | GET | 健康状态检查 |
|
||||
| `/stats` | GET | 系统统计信息 |
|
||||
| `/stats/reset` | POST | 重置统计信息 |
|
||||
| `/config` | GET | 配置信息 |
|
||||
|
||||
### 4.2 文件上传和任务管理
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/upload` | POST | 文件上传和处理 |
|
||||
| `/task/<task_id>` | GET | 查询任务状态 |
|
||||
| `/task/<task_id>` | PUT | 更新任务状态 |
|
||||
| `/task/<task_id>` | DELETE | 删除任务 |
|
||||
| `/tasks` | GET | 任务池列表 (分页) |
|
||||
| `/tasks/stats` | GET | 任务池统计 |
|
||||
| `/tasks/active` | GET | 活跃任务 |
|
||||
| `/tasks/queue` | GET | 队列任务 |
|
||||
|
||||
### 4.3 报告和下载
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/reports` | GET | 分页查询报告 |
|
||||
| `/download/<filename>` | GET | 下载文件 |
|
||||
| `/` | GET | Web 管理界面 |
|
||||
|
||||
### 4.4 API 密钥管理
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/api_keys` | GET | 列出 API 密钥 |
|
||||
| `/api_keys` | POST | 创建 API 密钥 |
|
||||
| `/api_keys/<key>` | DELETE | 撤销 API 密钥 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据流和业务流程
|
||||
|
||||
### 5.1 文件上传处理流程
|
||||
|
||||
```
|
||||
1. 客户端上传文件
|
||||
↓
|
||||
2. upload.py 验证文件类型和大小
|
||||
↓
|
||||
3. 生成 UUID 任务 ID
|
||||
↓
|
||||
4. 创建任务目录 (uploads/<task_id>/, outputs/<task_id>/)
|
||||
↓
|
||||
5. 保存上传文件
|
||||
↓
|
||||
6. 初始化任务状态 (SQLite 数据库)
|
||||
↓
|
||||
7. 启动后台线程处理 (process_data_async)
|
||||
↓
|
||||
8. 返回 202 Accepted，包含 task_id
|
||||
```
|
||||
|
||||
### 5.2 后台数据处理流程
|
||||
|
||||
```
|
||||
process_data_async(task_id, data_path, config_path, output_dir)
|
||||
↓
|
||||
1. 加载 YAML 配置文件
|
||||
↓
|
||||
2. 数据预处理 (data_processor.py)
|
||||
- 读取 Excel/CSV
|
||||
- 数据验证 (列名、类型、范围)
|
||||
- 单位转换
|
||||
↓
|
||||
3. GasFlux 核心分析 (processing_pipelines.py)
|
||||
- 背景校正 (background.py)
|
||||
- 空间处理 (平面拟合、航段提取)
|
||||
- 通量计算 (processing.py)
|
||||
- 克里金插值 (interpolation.py)
|
||||
↓
|
||||
4. 可视化生成 (plotting.py)
|
||||
- 浓度分布图
|
||||
- 风场图
|
||||
- 插值结果图
|
||||
↓
|
||||
5. 报告生成 (reporting.py)
|
||||
- HTML 报告
|
||||
- 输出变量 JSON
|
||||
↓
|
||||
6. 更新任务状态为 completed
|
||||
↓
|
||||
7. 客户端通过 /task/<id> 查询结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 配置管理
|
||||
|
||||
### 6.1 INI 配置文件 (推荐)
|
||||
|
||||
创建 `gasflux.ini` 文件:
|
||||
```ini
|
||||
[server]
|
||||
host = 0.0.0.0
|
||||
port = 5000
|
||||
|
||||
[paths]
|
||||
uploads = ./web_api_data/uploads
|
||||
outputs = ./web_api_data/outputs
|
||||
|
||||
[performance]
|
||||
threads = 8
|
||||
connection_limit = 100
|
||||
|
||||
[security]
|
||||
admin_bootstrap_key = your_secure_key_here
|
||||
```
|
||||
|
||||
### 6.2 环境变量覆盖
|
||||
|
||||
| 环境变量 | 说明 | 默认值 |
|
||||
|----------|------|--------|
|
||||
| `GASFLUX_HOST` | 监听地址 | 0.0.0.0 |
|
||||
| `GASFLUX_PORT` | 监听端口 | 5000 |
|
||||
| `GASFLUX_LOG_LEVEL` | 日志级别 | INFO |
|
||||
| `GASFLUX_THREADS` | 工作线程数 | 8 |
|
||||
| `GASFLMAX_CONTENT_LENGTH` | 最大文件大小 | 104857600 (100MB) |
|
||||
|
||||
### 6.3 YAML 配置文件 (处理参数)
|
||||
|
||||
处理数据时使用的配置 `gasflux_config.yaml`:
|
||||
```yaml
|
||||
output_dir: ./output
|
||||
|
||||
required_cols:
|
||||
latitude: [-90, 90]
|
||||
longitude: [-180, 180]
|
||||
height_ato: [0, 200]
|
||||
windspeed: [0, 20]
|
||||
temperature: [-50, 60]
|
||||
pressure: [900, 1100]
|
||||
|
||||
gases:
|
||||
ch4: [1.5, 10.0]
|
||||
co2: [300, 500]
|
||||
|
||||
strategies:
|
||||
background: "algorithm"
|
||||
spatial: "curtain"
|
||||
interpolation: "kriging"
|
||||
sensor: "insitu"
|
||||
|
||||
algorithmic_baseline_settings:
|
||||
# 背景校正算法参数
|
||||
smooth_half_window: 50
|
||||
num_std: 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 部署指南
|
||||
|
||||
### 7.1 开发环境部署
|
||||
|
||||
```bash
|
||||
# 1. 克隆仓库
|
||||
cd gasflux-develop-no-dockerV6
|
||||
|
||||
# 2. 创建虚拟环境
|
||||
python -m venv venv
|
||||
venv\Scripts\activate # Windows
|
||||
source venv/bin/activate # Linux/macOS
|
||||
|
||||
# 3. 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. 启动开发服务器
|
||||
python run_api.py
|
||||
```
|
||||
|
||||
### 7.2 生产环境部署 (Waitress)
|
||||
|
||||
```bash
|
||||
# 1. 安装 Waitress
|
||||
pip install waitress
|
||||
|
||||
# 2. 启动生产服务器
|
||||
python server_waitress.py
|
||||
```
|
||||
|
||||
### 7.3 打包为可执行文件
|
||||
|
||||
**Windows**:
|
||||
```cmd
|
||||
build_exe.bat
|
||||
```
|
||||
|
||||
**Linux/macOS**:
|
||||
```bash
|
||||
chmod +x build_exe.sh
|
||||
./build_exe.sh
|
||||
```
|
||||
|
||||
运行打包后的文件:
|
||||
```bash
|
||||
dist\GasFluxAPI.exe # Windows
|
||||
./dist/GasFluxAPI # Linux/macOS
|
||||
```
|
||||
|
||||
### 7.4 systemd 服务配置 (Linux)
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/gasflux.service
|
||||
[Unit]
|
||||
Description=GasFlux Web API
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=gasflux
|
||||
WorkingDirectory=/opt/gasflux
|
||||
ExecStart=/opt/gasflux/venv/bin/python server_waitress.py
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
Environment=GASFLUX_PORT=5000
|
||||
Environment=GASFLUX_LOG_LEVEL=INFO
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
启用和启动服务:
|
||||
```bash
|
||||
sudo systemctl enable gasflux
|
||||
sudo systemctl start gasflux
|
||||
sudo systemctl status gasflux
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 数据库和持久化
|
||||
|
||||
### 8.1 SQLite 数据库结构
|
||||
|
||||
**数据库文件**: `web_api_data/outputs/gasflux.db`
|
||||
|
||||
**表结构**:
|
||||
```sql
|
||||
-- 任务状态表
|
||||
CREATE TABLE tasks (
|
||||
task_id TEXT PRIMARY KEY,
|
||||
status TEXT NOT NULL, -- pending, processing, completed, failed
|
||||
message TEXT,
|
||||
error TEXT,
|
||||
results TEXT, -- JSON 格式
|
||||
output_dir TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- API 密钥表
|
||||
CREATE TABLE api_keys (
|
||||
key_id TEXT PRIMARY KEY,
|
||||
key_hash TEXT NOT NULL,
|
||||
name TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
last_used_at TIMESTAMP,
|
||||
revoked INTEGER DEFAULT 0
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 维护和故障排除
|
||||
|
||||
### 9.1 日志查看
|
||||
|
||||
**日志文件位置**: `logs/gasflux_api.log`
|
||||
|
||||
**实时查看**:
|
||||
```bash
|
||||
tail -f logs/gasflux_api.log # Linux
|
||||
Get-Content -Path logs/gasflux_api.log -Wait # PowerShell
|
||||
```
|
||||
|
||||
**过滤特定任务**:
|
||||
```bash
|
||||
tail -f logs/gasflux_api.log | grep "task:abc123"
|
||||
```
|
||||
|
||||
### 9.2 常见问题
|
||||
|
||||
#### 问题 1: 端口被占用
|
||||
```bash
|
||||
# Windows
|
||||
netstat -ano | findstr :5000
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# Linux
|
||||
netstat -tulpn | grep :5000
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
#### 问题 2: 权限问题
|
||||
```bash
|
||||
# 确保目录可写
|
||||
chmod -R 755 web_api_data/
|
||||
chmod -R 755 logs/
|
||||
```
|
||||
|
||||
#### 问题 3: 数据库锁定
|
||||
```bash
|
||||
# 如果 SQLite 数据库被锁定，检查是否有僵尸进程
|
||||
lsof gasflux.db
|
||||
# 重启服务解决
|
||||
```
|
||||
|
||||
### 9.3 性能优化
|
||||
|
||||
**调整 Waitress 参数** (server_waitress.py):
|
||||
```python
|
||||
serve(
|
||||
app,
|
||||
host=host,
|
||||
port=port,
|
||||
threads=16, # 根据 CPU 核心数增加
|
||||
connection_limit=200, # 增加连接限制
|
||||
channel_timeout=600, # 延长超时时间
|
||||
)
|
||||
```
|
||||
|
||||
**数据库优化**:
|
||||
```sql
|
||||
-- 定期清理旧任务
|
||||
DELETE FROM tasks
|
||||
WHERE status = 'completed'
|
||||
AND updated_at < datetime('now', '-7 days');
|
||||
|
||||
-- 重建索引
|
||||
VACUUM;
|
||||
```
|
||||
|
||||
### 9.4 备份策略
|
||||
|
||||
**需要备份的目录**:
|
||||
```
|
||||
web_api_data/uploads/ # 上传的原始数据
|
||||
web_api_data/outputs/ # 处理结果
|
||||
gasflux.ini # 配置文件
|
||||
logs/ # 日志文件 (可选)
|
||||
```
|
||||
|
||||
**自动备份脚本**:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# backup.sh
|
||||
DATE=$(date +%Y%m%d)
|
||||
tar -czf "backup_$DATE.tar.gz" web_api_data/ gasflux.ini
|
||||
# 上传到远程存储
|
||||
rsync -avz "backup_$DATE.tar.gz" user@backup-server:/backups/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. API 使用示例
|
||||
|
||||
### 10.1 Python 客户端示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
import time
|
||||
|
||||
class GasFluxClient:
|
||||
def __init__(self, base_url="http://localhost:5000"):
|
||||
self.base_url = base_url.rstrip('/')
|
||||
|
||||
def upload_and_process(self, data_file, config_file=None, api_key=None):
|
||||
"""上传文件并处理"""
|
||||
files = {'file': open(data_file, 'rb')}
|
||||
if config_file:
|
||||
files['config'] = open(config_file, 'rb')
|
||||
|
||||
headers = {}
|
||||
if api_key:
|
||||
headers['X-API-Key'] = api_key
|
||||
|
||||
# 上传文件
|
||||
response = requests.post(
|
||||
f"{self.base_url}/upload",
|
||||
files=files,
|
||||
headers=headers
|
||||
)
|
||||
result = response.json()
|
||||
task_id = result['data']['task_id']
|
||||
|
||||
# 轮询状态
|
||||
while True:
|
||||
status_resp = requests.get(f"{self.base_url}/task/{task_id}")
|
||||
status = status_resp.json()['data']
|
||||
|
||||
print(f"Status: {status['status']} - {status.get('message', '')}")
|
||||
|
||||
if status['status'] == 'completed':
|
||||
# 下载结果
|
||||
for file_info in status['results']:
|
||||
if 'download_url' in file_info:
|
||||
download_url = f"{self.base_url}{file_info['download_url']}"
|
||||
file_resp = requests.get(download_url)
|
||||
with open(file_info['name'], 'wb') as f:
|
||||
f.write(file_resp.content)
|
||||
print(f"Downloaded: {file_info['name']}")
|
||||
return status
|
||||
|
||||
elif status['status'] == 'failed':
|
||||
raise Exception(f"Task failed: {status.get('error', 'Unknown error')}")
|
||||
|
||||
time.sleep(3)
|
||||
|
||||
# 使用示例
|
||||
client = GasFluxClient()
|
||||
client.upload_and_process('data.xlsx', 'config.yaml', api_key='your-api-key')
|
||||
```
|
||||
|
||||
### 10.2 cURL 命令示例
|
||||
|
||||
```bash
|
||||
# 1. 检查健康状态
|
||||
curl http://localhost:5000/health
|
||||
|
||||
# 2. 上传文件
|
||||
curl -X POST -F "file=@data.xlsx" -F "config=@config.yaml" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
http://localhost:5000/upload
|
||||
|
||||
# 3. 查询任务状态
|
||||
curl http://localhost:5000/task/<task_id>
|
||||
|
||||
# 4. 下载结果文件
|
||||
curl -O http://localhost:5000/download/<task_id>/report.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 安全和认证
|
||||
|
||||
### 11.1 API 密钥管理
|
||||
|
||||
**创建 API 密钥**:
|
||||
```bash
|
||||
python create_api_key.py --name "Production Client"
|
||||
```
|
||||
|
||||
**使用 API 密钥**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:5000/upload
|
||||
```
|
||||
|
||||
### 11.2 Bootstrap Key
|
||||
|
||||
用于初始设置或管理员操作，在 `gasflux.ini` 中配置:
|
||||
```ini
|
||||
[security]
|
||||
admin_bootstrap_key = your_secure_bootstrap_key
|
||||
```
|
||||
|
||||
使用 Bootstrap Key:
|
||||
```bash
|
||||
curl -H "X-Admin-Bootstrap-Key: your_secure_bootstrap_key" \
|
||||
http://localhost:5000/api_keys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 开发指南
|
||||
|
||||
### 12.1 添加新的蓝图
|
||||
|
||||
1. 创建蓝图文件 `src/gasflux/blueprints/new_feature.py`:
|
||||
```python
|
||||
from flask import Blueprint
|
||||
from ..shared import _format_response
|
||||
|
||||
new_feature_bp = Blueprint('new_feature', __name__, url_prefix='/new-feature')
|
||||
|
||||
@new_feature_bp.route('', methods=['GET'])
|
||||
def get_feature():
|
||||
return _format_response(200, "Feature data", {"data": "value"})
|
||||
```
|
||||
|
||||
2. 在 `app.py` 中注册蓝图:
|
||||
```python
|
||||
from .blueprints.new_feature import new_feature_bp
|
||||
app.register_blueprint(new_feature_bp)
|
||||
```
|
||||
|
||||
### 12.2 代码规范
|
||||
|
||||
- 使用类型注解
|
||||
- 添加文档字符串
|
||||
- 使用 logger 而非 print
|
||||
- 错误处理使用 try-except 块
|
||||
- 性能敏感操作使用 `@log_performance` 装饰器
|
||||
|
||||
---
|
||||
|
||||
## 13. 联系和支持
|
||||
|
||||
### 13.1 相关文档
|
||||
- `API_DOCUMENTATION.md` - 完整 API 接口文档
|
||||
- `WAITRESS_DEPLOYMENT.md` - 生产部署指南
|
||||
- `README.md` - 项目概述和使用说明
|
||||
- `ENVIRONMENT_VARIABLES.md` - 环境变量配置
|
||||
|
||||
### 13.2 调试技巧
|
||||
|
||||
**启用 DEBUG 日志**:
|
||||
```bash
|
||||
set GASFLUX_LOG_LEVEL=DEBUG # Windows
|
||||
export GASFLUX_LOG_LEVEL=DEBUG # Linux/macOS
|
||||
python server_waitress.py
|
||||
```
|
||||
|
||||
**数据库查询**:
|
||||
```bash
|
||||
sqlite3 web_api_data/outputs/gasflux.db
|
||||
> SELECT * FROM tasks WHERE status = 'failed';
|
||||
> SELECT COUNT(*), status FROM tasks GROUP BY status;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 附录
|
||||
|
||||
### 14.1 版本历史
|
||||
|
||||
| 版本 | 日期 | 说明 |
|
||||
|------|------|------|
|
||||
| 0.2.1 | 2026-01 | 初始版本 |
|
||||
|
||||
### 14.2 依赖版本
|
||||
|
||||
```
|
||||
Flask>=2.0
|
||||
waitress>=2.0
|
||||
pandas>=2.0
|
||||
numpy>=1.24
|
||||
scipy>=1.10
|
||||
scikit-gstat>=1.0
|
||||
matplotlib>=3.7
|
||||
pyyaml>=6.0
|
||||
```
|
||||
|
||||
### 14.3 系统要求
|
||||
|
||||
- **Python**: 3.8+
|
||||
- **内存**: 4GB+ (推荐 8GB+)
|
||||
- **磁盘**: 1GB+ 可用空间
|
||||
- **操作系统**: Windows 10/11, Linux, macOS
|
||||
|
||||
---
|
||||
|
||||
**文档结束**
|
||||
|
||||
*本文档由 AI 助手根据项目代码自动生成，如有疑问请参考源代码或联系开发团队。*
|
||||
Reference in New Issue
Block a user