271 lines
5.6 KiB
Markdown
271 lines
5.6 KiB
Markdown
# 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 服务器环境
|
||
- 简单的生产部署需求
|
||
- 需要独立可执行文件的场景 |