常规更新
This commit is contained in:
214
快速参考指南.md
Normal file
214
快速参考指南.md
Normal file
@ -0,0 +1,214 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user