UAV-CO2/快速参考指南.md

GasFlux Web API 快速参考指南

快速启动命令

# 开发环境
python run_api.py

# 生产环境
python server_waitress.py

# 创建 API 密钥
python create_api_key.py --name "Client Name"

---

常用 API 端点

操作	端点	示例
健康检查	GET /health	curl http://localhost:5000/health
上传文件	POST /upload	curl -F "file=@data.xlsx" http://localhost:5000/upload
任务状态	GET /task/{id}	curl http://localhost:5000/task/abc-123
下载文件	GET /download/{path}	curl -O http://localhost:5000/download/abc-123/report.html
统计信息	GET /stats	curl http://localhost:5000/stats

---

项目结构速览

.
├── server_waitress.py      # ★ 生产服务器入口
├── src/gasflux/
│   ├── app.py               # Flask 应用核心
│   ├── config_reader.py     # 配置读取器
│   ├── processing.py        # 数据处理算法
│   ├── processing_pipelines.py  # 处理流程
│   └── blueprints/          # API 端点
│       ├── upload.py        # 文件上传
│       ├── tasks.py         # 任务管理
│       ├── download.py      # 文件下载
│       └── health.py        # 健康检查
└── web_api_data/
    ├── uploads/             # 上传文件
    └── outputs/             # 处理结果 + gasflux.db

---

配置文件模板 (gasflux.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

[database]
path = web_api_data/outputs/gasflux.db

---

环境变量

# 常用环境变量
GASFLUX_PORT=5000
GASFLUX_LOG_LEVEL=INFO
GASFLUX_THREADS=8
GASFLUX_MAX_CONTENT_LENGTH=104857600

# Windows
set GASFLUX_LOG_LEVEL=DEBUG

# Linux/macOS
export GASFLUX_LOG_LEVEL=DEBUG

---

故障排查

查看日志

# 实时查看日志
tail -f logs/gasflux_api.log

# 过滤特定任务
grep "task:abc123" logs/gasflux_api.log

数据库查询

sqlite3 web_api_data/outputs/gasflux.db

-- 查看所有任务
SELECT task_id, status, message FROM tasks;

-- 查看失败任务
SELECT * FROM tasks WHERE status = 'failed';

-- 查看统计
SELECT status, COUNT(*) FROM tasks GROUP BY status;

端口占用

# Windows
netstat -ano | findstr :5000

# Linux
netstat -tulpn | grep :5000
lsof -i :5000

---

部署检查清单

• 安装依赖: pip install -r requirements.txt
• 创建 gasflux.ini 配置文件
• 创建目录: web_api_data/uploads, web_api_data/outputs, logs/
• 设置权限: 确保目录可写
• 创建 API 密钥: python create_api_key.py
• 测试启动: python server_waitress.py
• 健康检查: curl http://localhost:5000/health
• 防火墙: 开放所需端口
• 日志轮转: 配置日志清理策略
• 备份策略: 定期备份 web_api_data/ 目录

---

性能调优参数

# server_waitress.py 中的 Waitress 配置
serve(
    app,
    host='0.0.0.0',
    port=5000,
    threads=16,              # 根据 CPU 核心数调整
    connection_limit=200,    # 最大并发连接
    channel_timeout=600,     # 长请求超时
)

---

Python 客户端示例

import requests
import time

# 上传文件
files = {'file': open('data.xlsx', 'rb')}
response = requests.post('http://localhost:5000/upload', files=files)
task_id = response.json()['data']['task_id']

# 轮询状态
while True:
    resp = requests.get(f'http://localhost:5000/task/{task_id}')
    data = resp.json()['data']
    print(f"{data['status']}: {data.get('message', '')}")
    
    if data['status'] == 'completed':
        # 下载文件
        for f in data['results']:
            if 'download_url' in f:
                r = requests.get(f"http://localhost:5000{f['download_url']}")
                open(f['name'], 'wb').write(r.content)
        break
    elif data['status'] == 'failed':
        raise Exception(data.get('error', 'Failed'))
    
    time.sleep(3)

---

文档索引

文档	内容
项目交接文档.md	完整项目文档
API_DOCUMENTATION.md	API 接口详细文档
WAITRESS_DEPLOYMENT.md	生产部署指南
README.md	项目概述
ENVIRONMENT_VARIABLES.md	环境变量配置

---

联系方式

• 问题反馈: 查看 logs/gasflux_api.log
• 数据库问题: sqlite3 web_api_data/outputs/gasflux.db
• 配置问题: 检查 gasflux.ini 或环境变量

---

最后更新: 2026-04-13