zhanghuilai/UAV-CO2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加web_api

Browse Source
This commit is contained in:
zhanghuilai
2026-02-05 15:13:54 +08:00
parent 443ec09c5c
commit d5edbc0723
43 changed files with 7036 additions and 2640 deletions
Download Patch File Download Diff File Expand all files Collapse all files

782
API_ENDPOINTS.md Normal file
View File

@ -0,0 +1,782 @@
# GasFlux Web API 端点参考
## 概述
GasFlux Web API 是一个基于 Flask 的 RESTful API，用于上传数据文件、执行气体通量分析处理，并下载处理结果。
**基础信息:**
- **基础 URL**: `http://localhost:5000`
- **认证**: 无需认证
- **数据格式**: JSON
- **文件大小限制**: 100MB
- **支持的文件类型**: `.xlsx`, `.xls`, `.yaml`, `.yml`
---
## 🔍 监控和健康检查
### 1. 获取健康状态
**端点**: `GET /health`
**描述**: 获取 API 的健康状态、系统信息和性能指标。
**响应示例** (200):
```json
{
"code": 200,
"message": "健康检查完成",
"data": {
"status": "healthy",
"version": "1.0.0",
"timestamp": 1705257600.123,
"uptime": "2h 30m 15s",
"storage": {
"uploads_writable": true,
"outputs_writable": true
},
"tasks": {
"active_count": 2,
"total_tracked": 15,
"total_processed": 13,
"success_rate_percent": 92.31
},
"performance": {
"requests_per_second": 0.08,
"avg_response_time_ms": 234.56,
"error_rate_percent": 1.5
}
}
}
```
**响应示例** (503):
```json
{
"code": 503,
"message": "服务不可用",
"data": {
"status": "degraded",
"version": "1.0.0",
"timestamp": 1705257600.123,
"uptime": "1h 30m 45s",
"storage": {
"uploads_writable": true,
"outputs_writable": true
},
"tasks": {
"active_count": 0,
"total_tracked": 5,
"total_processed": 3,
"success_rate_percent": 60.0
},
"performance": {
"requests_per_second": 0.12,
"avg_response_time_ms": 145.67,
"error_rate_percent": 50.0
},
"issues": [
"错误率过高 (50.0%)",
"活跃任务数量过多 (25)"
]
}
}
```
**状态码**:
- `200`: API 健康
- `503`: API 不健康
---
### 2. 获取系统统计信息
**端点**: `GET /stats`
**描述**: 获取详细的 API 统计信息、性能指标和系统监控数据。
**响应示例** (200):
```json
{
"code": 200,
"message": "统计信息获取成功",
"data": {
"summary": {
"uptime_seconds": 3600.5,
"uptime_formatted": "1h 0m 0s",
"requests_total": 150,
"requests_per_second": 0.04,
"error_rate_percent": 2.0,
"active_tasks": 1
},
"requests": {
"by_method": {
"GET": 120,
"POST": 30
},
"by_status": {
"200": 145,
"400": 3,
"500": 2
},
"top_endpoints": {
"/task/abc123": 45,
"/health": 30,
"/": 25
}
},
"tasks": {
"total_created": 25,
"total_completed": 20,
"total_failed": 2,
"success_rate_percent": 90.91,
"by_status": {
"pending": 1,
"processing": 1,
"completed": 20,
"failed": 2
}
},
"performance": {
"avg_response_time_ms": 245.67,
"max_response_time_ms": 1250.34,
"min_response_time_ms": 12.45
},
"system": {
"memory_usage_percent": 45.2,
"memory_used_gb": 7.3,
"memory_total_gb": 16.0,
"disk_usage_percent": 23.1,
"disk_used_gb": 46.8,
"disk_total_gb": 203.2
},
"recent_tasks": [
{
"task_id": "abc123-def456",
"status": "completed",
"age_seconds": 45.2,
"message": "处理完成成功"
}
]
}
}
```
**状态码**:
- `200`: 成功
---
### 3. 重置统计信息
**端点**: `POST /stats/reset`
**描述**: 重置所有 API 统计数据（管理员功能）。
**响应示例** (200):
```json
{
"code": 200,
"message": "统计信息重置成功",
"data": {
"timestamp": 1705257600.123
}
}
```
**状态码**:
- `200`: 成功
---
### 4. 获取配置信息
**端点**: `GET /config`
**描述**: 获取当前应用配置信息和支持的环境变量。
**响应示例** (200):
```json
{
"code": 200,
"message": "配置信息获取成功",
"data": {
"configuration": {
"host": "0.0.0.0",
"port": 5000,
"debug": false,
"base_dir": "/app",
"upload_folder": "/app/web_api_data/uploads",
"output_folder": "/app/web_api_data/outputs",
"max_content_length": 104857600,
"log_level": "INFO",
"log_file": "logs/gasflux_api.log",
"cors_origins": ["*"],
"task_cleanup_interval": 3600,
"max_task_age": 86400,
"threads": 8,
"connection_limit": 100,
"channel_timeout": 300
},
"environment_variables": {
"supported": [
"GASFLUX_HOST", "GASFLUX_PORT", "GASFLUX_DEBUG",
"GASFLUX_UPLOAD_FOLDER", "GASFLUX_OUTPUT_FOLDER",
"GASFLUX_MAX_CONTENT_LENGTH", "GASFLUX_LOG_LEVEL",
"GASFLUX_LOG_FILE", "GASFLUX_CORS_ORIGINS",
"GASFLUX_TASK_CLEANUP_INTERVAL", "GASFLUX_MAX_TASK_AGE",
"GASFLUX_THREADS", "GASFLUX_CONNECTION_LIMIT",
"GASFLUX_CHANNEL_TIMEOUT"
],
"current_values": {
"GASFLUX_HOST": "0.0.0.0",
"GASFLUX_PORT": "5000",
"GASFLUX_DEBUG": "false"
}
}
}
}
```
**状态码**:
- `200`: 成功
---
## 📤 文件上传和管理
### 5. 文件上传和处理
**端点**: `POST /upload`
**描述**: 上传数据文件并启动异步处理任务。
**请求参数** (multipart/form-data):
- `file` (必需): 数据文件 (.xlsx 或 .xls 格式)
- `config` (可选): 配置文件 (.yaml 或 .yml 格式)
**响应示例** (202):
```json
{
"code": 202,
"message": "任务已接受并加入处理队列",
"data": {
"status": "accepted",
"job_id": "abc123-def456-ghi789",
"task_status_url": "/task/abc123-def456-ghi789"
}
}
```
**错误响应示例** (400):
```json
{
"code": 400,
"message": "无效的数据文件类型。只允许 .xlsx 和 .xls 格式。",
"data": {}
}
```
**错误响应示例** (413):
```json
{
"code": 413,
"message": "文件过大。最大尺寸为 100MB。",
"data": {}
}
```
**状态码**:
- `202`: 任务已接受
- `400`: 请求参数错误
- `413`: 文件过大
---
## 📊 任务管理和监控
### 6. 分页查询任务列表
**端点**: `GET /tasks`
**描述**: 分页查询所有任务，支持按状态过滤、排序和分页。返回体为前端友好的瘦身结构：仅包含任务状态信息；当任务已完成时会包含 `downloads` 直达下载链接。
**查询参数**:
- `page` (可选): 页码 (默认: 1)
- `page_size` (可选): 每页任务数量 (默认: 20, 最大: 100)
- `sort_by` (可选): 排序字段 ('created_at', 'updated_at', 'status') (默认: 'updated_at')
- `sort_order` (可选): 排序顺序 ('asc', 'desc') (默认: 'desc')
- `status` (可选): 按任务状态过滤，支持多个状态用逗号分隔
**响应示例** (200):
```json
{
"code": 200,
"message": "任务列表查询成功",
"data": {
"tasks": [
{
"task_id": "abc123-def456-ghi789",
"status": "completed",
"message": "Processing completed successfully",
"updated_at": 1705257700.456,
"downloads": {
"data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
"report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
"report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
"config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
"metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
}
},
{
"task_id": "xyz789-abc123-def456",
"status": "processing",
"message": "正在进行数据分析...",
"updated_at": 1705257650.321
}
],
"total": 25,
"page": 1,
"page_size": 20,
"total_pages": 2,
"has_next": true,
"has_prev": false
}
}
```
**状态码**:
- `200`: 成功
- `400`: 参数无效
---
### 7. 获取任务池统计信息
**端点**: `GET /tasks/stats`
**描述**: 获取任务池的统计信息，包括各状态任务数量、活跃任务数等。
**响应示例** (200):
```json
{
"code": 200,
"message": "任务池统计信息查询成功",
"data": {
"total_tasks": 25,
"status_counts": {
"pending": 3,
"processing": 2,
"completed": 18,
"failed": 2
},
"active_tasks": 2,
"queued_tasks": 3,
"completed_tasks": 18,
"failed_tasks": 2
}
}
```
**状态码**:
- `200`: 成功
---
### 8. 获取活跃任务列表
**端点**: `GET /tasks/active`
**描述**: 获取当前正在处理的任务列表（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。
**响应示例** (200):
```json
{
"code": 200,
"message": "活跃任务查询成功",
"data": {
"active_tasks": [
{
"task_id": "abc123-def456-ghi789",
"status": "processing",
"message": "正在生成报告...",
"updated_at": 1705257650.321
},
{
"task_id": "completed-task-123",
"status": "completed",
"message": "Processing completed successfully",
"updated_at": 1705257550.456,
"downloads": {
"data_xlsx": "/download/completed-task-123/processed_data.xlsx",
"report_html": "/download/completed-task-123/data_report.html"
}
}
],
"count": 2
}
}
```
**状态码**:
- `200`: 成功
---
### 9. 获取队列任务列表
**端点**: `GET /tasks/queue`
**描述**: 获取等待处理的任务队列（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。
**响应示例** (200):
```json
{
"code": 200,
"message": "队列任务查询成功",
"data": {
"queued_tasks": [
{
"task_id": "xyz789-abc123-def456",
"status": "pending",
"message": "等待处理",
"updated_at": 1705257400.123
},
{
"task_id": "completed-queued-task",
"status": "completed",
"message": "Processing completed successfully",
"updated_at": 1705257450.321,
"downloads": {
"data_xlsx": "/download/completed-queued-task/processed_data.xlsx",
"report_html": "/download/completed-queued-task/analysis_report.html"
}
}
],
"count": 2,
"queue_position_info": "任务按创建时间排序，较早的任务优先处理"
}
}
```
**状态码**:
- `200`: 成功
---
### 10. 查询任务状态
**端点**: `GET /task/{task_id}`
**描述**: 查询异步处理任务的当前状态和进度信息。
**路径参数**:
- `task_id`: 任务 ID (UUID 格式)
**响应示例** - 处理中 (200):
```json
{
"code": 200,
"message": "任务查询成功",
"data": {
"task_id": "abc123-def456-ghi789",
"status": "processing",
"message": "GasFlux 分析完成，正在生成报告...",
"updated_at": 1705257600.123
}
}
```
**响应示例** - 处理完成 (200):
```json
{
"code": 200,
"message": "任务查询成功",
"data": {
"task_id": "abc123-def456-ghi789",
"status": "completed",
"message": "处理完成成功",
"updated_at": 1705257600.123,
"results": [
{
"name": "08_34_01_5m.processed_ch4_report.html",
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
"size": 245760,
"type": "report"
},
{
"name": "08_34_01_5m.processed_data.xlsx",
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
"size": 153600,
"type": "data"
},
{
"name": "08_34_01_5m.processed_config.yaml",
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
"size": 2048,
"type": "config"
},
{
"name": "08_34_01_5m.processed_output_vars.json",
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
"size": 4096,
"type": "metadata"
}
],
"downloads": {
"data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
"report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
"report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
"config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
"metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
}
}
}
```
**响应示例** - 任务不存在 (404):
```json
{
"code": 404,
"message": "任务未找到",
"data": {}
}
```
**状态码**:
- `200`: 成功
- `404`: 任务不存在
---
### 11. 更新任务状态
**端点**: `PUT /task/{task_id}`
**描述**: 更新任务的状态、信息或优先级。
**路径参数**:
- `task_id`: 任务 ID (UUID 格式)
**请求参数** (JSON):
- `status` (可选): 新的任务状态
- `message` (可选): 状态消息或错误描述
- `priority` (可选): 任务优先级 (normal/high/low)
**响应示例** (200):
```json
{
"code": 200,
"message": "任务更新成功",
"data": {
"task_id": "abc123-def456-ghi789",
"status": "updated",
"task_info": {
"status": "completed",
"message": "手动标记为完成",
"updated_at": 1705257600.123,
"priority": "normal"
}
}
}
```
**错误响应示例** (404):
```json
{
"code": 404,
"message": "任务未找到",
"data": {}
}
```
**错误响应示例** (400):
```json
{
"code": 400,
"message": "无效状态。必须是以下之一: pending, processing, completed, failed",
"data": {}
}
```
**状态码**:
- `200`: 成功
- `400`: 无效请求
- `404`: 任务不存在
---
### 12. 删除任务
**端点**: `DELETE /task/{task_id}`
**描述**: 删除任务及其所有相关的文件和数据。
**路径参数**:
- `task_id`: 任务 ID (UUID 格式)
**响应示例** (200):
```json
{
"code": 200,
"message": "任务及相关文件删除成功",
"data": {
"task_id": "abc123-def456-ghi789",
"status": "deleted",
"details": {
"folders_deleted": 1,
"total_size_deleted": 307200,
"task_status": "completed"
}
}
}
```
**错误响应示例** (404):
```json
{
"code": 404,
"message": "任务未找到",
"data": {}
}
```
**错误响应示例** (409):
```json
{
"code": 409,
"message": "无法删除当前正在处理或等待处理的任务",
"data": {
"task_status": "processing"
}
}
```
**状态码**:
- `200`: 成功
- `404`: 任务不存在
- `409`: 任务正在处理
---
## 📋 报告管理和查询
### 13. 分页查询已生成报告
**端点**: `GET /reports`
**描述**: 分页查询所有已生成的处理报告，支持排序和过滤。
**查询参数**:
- `page` (可选): 页码 (默认: 1)
- `per_page` (可选): 每页报告数量 (默认: 20, 最大: 100)
- `sort_by` (可选): 排序字段 (默认: created_at)
- `sort_order` (可选): 排序顺序 (默认: desc)
- `status` (可选): 按任务状态过滤
**响应示例** (200):
```json
{
"code": 200,
"message": "报告列表获取成功",
"data": {
"reports": [
{
"task_id": "abc123-def456-ghi789",
"report_name": "08_34_01_5m",
"status": "completed",
"created_at": 1705257600.123,
"file_count": 4,
"total_size": 307200,
"processing_time_seconds": 125.67,
"main_report": {
"name": "08_34_01_5m.processed_ch4_report.html",
"size": 245760,
"type": "report",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
},
"all_files": [
{
"name": "08_34_01_5m.processed_ch4_report.html",
"size": 245760,
"type": "report",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
},
{
"name": "08_34_01_5m.processed_data.csv",
"size": 153600,
"type": "data",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_data.csv"
},
{
"name": "08_34_01_5m.processed_config.yaml",
"size": 2048,
"type": "config",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_config.yaml"
},
{
"name": "08_34_01_5m.processed_output_vars.json",
"size": 4096,
"type": "metadata",
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_output_vars.json"
}
],
"run_directory": "abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total_reports": 45,
"total_pages": 3,
"has_next": true,
"has_prev": false
},
"filters": {
"sort_by": "created_at",
"sort_order": "desc",
"status": null
}
}
}
```
**错误响应示例** (400):
```json
{
"code": 400,
"message": "Invalid parameter: per_page must be between 1 and 100",
"data": {}
}
```
**状态码**:
- `200`: 成功
- `400`: 参数无效
---
## 📁 文件下载
### 14. 下载处理结果
**端点**: `GET /download/{filename}`
**描述**: 下载处理后的结果文件，支持传入完整文件路径。
**路径参数**:
- `filename`: 文件的完整路径或相对路径 (包含任务ID)
**状态码**:
- `200`: 成功下载文件
- `403`: 访问被拒绝
- `404`: 文件不存在
- `400`: 路径不是文件
---
## 🌐 Web 界面
### 15. Web 管理界面
**端点**: `GET /`
**描述**: 访问用户友好的 Web 界面，支持文件上传、任务监控和结果下载。
**状态码**:
- `200`: 成功
---
*最后更新: 2026年1月29日*
*GasFlux Web API 版本: 1.0.0*