# 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*