增加web_api

2026-02-05 15:13:54 +08:00
parent 443ec09c5c
commit d5edbc0723
43 changed files with 7036 additions and 2640 deletions
--- a/WAITRESS_DEPLOYMENT.md
+++ b/WAITRESS_DEPLOYMENT.md
@ -0,0 +1,271 @@
+# GasFlux Web API - Waitress WSGI 部署指南
+
+本文档介绍如何使用 Waitress WSGI 服务器打包和部署 GasFlux Web API 为独立可执行文件。
+
+## 概述
+
+Waitress 是一个纯 Python WSGI 服务器，适合生产环境使用。本部署方案将 Flask 应用与 Waitress 打包为单个可执行文件，无需额外安装 Python 环境。
+
+## 文件说明
+
+### 核心文件
+
+- **`server_waitress.py`** - Waitress 服务器入口点
+- **`src/gasflux/app.py`** - Flask 应用定义
+- **`build_exe.bat`** - Windows 构建脚本
+- **`build_exe.sh`** - Linux/macOS 构建脚本
+- **`EXE_BUILD_README.md`** - 详细构建和部署指南
+
+### 构建产物
+
+- **`dist/GasFluxAPI.exe`** (Windows) 或 **`dist/GasFluxAPI`** (Linux/macOS) - 独立可执行文件
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r requirements.txt
+pip install pyinstaller waitress
+```
+
+### 2. 构建可执行文件
+
+**Windows:**
+```cmd
+build_exe.bat
+```
+
+**Linux/macOS:**
+```bash
+chmod +x build_exe.sh
+./build_exe.sh
+```
+
+### 3. 运行服务器
+
+```bash
+# Windows
+dist\GasFluxAPI.exe
+
+# Linux/macOS
+./dist/GasFluxAPI
+```
+
+服务器将在 `http://localhost:5000` 启动。
+
+## 服务器配置
+
+### 默认配置
+
+```python
+host = '0.0.0.0'      # 监听所有接口
+port = 5000            # 默认端口
+threads = 8            # 工作线程数
+connection_limit = 100 # 最大并发连接
+timeout = 300          # 请求超时（秒）
+```
+
+### 自定义配置
+
+修改 `server_waitress.py` 中的参数：
+
+```python
+# 自定义端口
+port = 8080
+
+# 增加线程数
+threads = 16
+
+# 调整超时时间
+timeout = 600  # 10分钟
+```
+
+## 部署架构
+
+### 单文件部署
+
+```
+部署目录/
+├── GasFluxAPI(.exe)     # 可执行文件
+├── web_api_data/        # 数据目录（自动创建）
+│   ├── uploads/        # 上传文件
+│   └── outputs/        # 处理结果
+├── logs/               # 日志文件（自动创建）
+└── gasflux_config.yaml # 配置文件（可选）
+```
+
+### 生产部署建议
+
+#### 使用反向代理
+
+```nginx
+# nginx 配置示例
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+#### 使用进程管理器
+
+**systemd (Linux):**
+
+```ini
+[Unit]
+Description=GasFlux Web API
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/path/to/deployment
+ExecStart=/path/to/deployment/GasFluxAPI
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Windows 服务:**
+
+使用 NSSM (Non-Sucking Service Manager) 将 exe 注册为 Windows 服务。
+
+## 性能优化
+
+### Waitress 参数调优
+
+```python
+serve(
+    app,
+    host='0.0.0.0',
+    port=5000,
+    threads=16,              # 根据 CPU 核心数调整
+    connection_limit=200,    # 最大并发连接
+    timeout=300,             # 长请求超时
+    backlog=2048,           # 连接队列长度
+    recv_bytes=8192,        # 接收缓冲区
+    send_bytes=8192,        # 发送缓冲区
+)
+```
+
+### 监控和日志
+
+- **访问日志**: `logs/gasflux_api.log`
+- **控制台输出**: 启动时显示的控制台信息
+- **健康检查**: `GET /health` 端点
+
+### 资源使用
+
+- **内存**: 每个工作进程约 50-200MB（取决于数据处理量）
+- **CPU**: 多线程处理，建议 4+ 核心
+- **磁盘**: 日志和临时文件存储
+
+## 安全考虑
+
+### 基本安全措施
+
+1. **防火墙配置**: 只开放必要端口
+2. **用户权限**: 以非 root 用户运行
+3. **文件权限**: 数据目录限制访问权限
+
+### 生产环境建议
+
+1. **HTTPS**: 使用反向代理配置 SSL
+2. **认证**: 添加 API 密钥或 JWT 认证
+3. **限流**: 实现请求频率限制
+4. **监控**: 设置日志监控和告警
+
+## 故障排除
+
+### 常见问题
+
+1. **端口占用**
+   ```bash
+   # 检查端口使用
+   netstat -tulpn | grep :5000
+   # 或 Windows: netstat -ano | findstr :5000
+   ```
+
+2. **权限问题**
+   ```bash
+   # 确保可执行文件有执行权限
+   chmod +x GasFluxAPI
+   # 确保数据目录可写
+   chmod -R 755 web_api_data/
+   ```
+
+3. **构建失败**
+   ```bash
+   # 清理旧构建
+   rm -rf build/ dist/
+   # 重新安装依赖
+   pip install --upgrade pyinstaller waitress
+   ```
+
+4. **内存不足**
+   - 减少线程数
+   - 增加服务器内存
+   - 优化数据处理流程
+
+### 调试模式
+
+临时启用详细日志：
+
+```bash
+# 修改 server_waitress.py
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## 维护和更新
+
+### 更新部署
+
+1. 构建新版本可执行文件
+2. 备份数据目录
+3. 停止旧服务
+4. 替换可执行文件
+5. 启动新服务
+
+### 备份策略
+
+- **数据**: `web_api_data/` 目录
+- **配置**: `gasflux_config.yaml`
+- **日志**: `logs/` 目录
+
+## API 使用
+
+部署完成后，API 端点与开发环境相同：
+
+- **健康检查**: `GET /health`
+- **文件上传**: `POST /upload`
+- **任务状态**: `GET /task/{task_id}`
+- **文件下载**: `GET /download/{filename}`
+- **Web 界面**: `GET /`
+
+详细 API 文档请参考 `API_DOCUMENTATION.md`。
+
+## 总结
+
+使用 Waitress 打包的方案提供了：
+
+- ✅ **零依赖部署**: 单文件可执行
+- ✅ **生产就绪**: WSGI 服务器，适合高并发
+- ✅ **跨平台**: 支持 Windows/Linux/macOS
+- ✅ **易于维护**: 简单的部署和更新流程
+- ✅ **完整功能**: 保留所有 Flask 应用功能
+
+这种部署方式特别适合：
+- Windows 服务器环境
+- 简单的生产部署需求
+- 需要独立可执行文件的场景