215 lines
4.6 KiB
Markdown
215 lines
4.6 KiB
Markdown
# GasFlux Web API 快速参考指南
|
|
|
|
## 快速启动命令
|
|
|
|
```bash
|
|
# 开发环境
|
|
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)
|
|
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## 环境变量
|
|
|
|
```bash
|
|
# 常用环境变量
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## 故障排查
|
|
|
|
### 查看日志
|
|
```bash
|
|
# 实时查看日志
|
|
tail -f logs/gasflux_api.log
|
|
|
|
# 过滤特定任务
|
|
grep "task:abc123" logs/gasflux_api.log
|
|
```
|
|
|
|
### 数据库查询
|
|
```bash
|
|
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;
|
|
```
|
|
|
|
### 端口占用
|
|
```bash
|
|
# 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/` 目录
|
|
|
|
---
|
|
|
|
## 性能调优参数
|
|
|
|
```python
|
|
# server_waitress.py 中的 Waitress 配置
|
|
serve(
|
|
app,
|
|
host='0.0.0.0',
|
|
port=5000,
|
|
threads=16, # 根据 CPU 核心数调整
|
|
connection_limit=200, # 最大并发连接
|
|
channel_timeout=600, # 长请求超时
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Python 客户端示例
|
|
|
|
```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*
|