UAV-CO2/WAITRESS_DEPLOYMENT.md

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