zhanghuilai/UAV-CO2

Fork 0

Files

zhanghuilai d5edbc0723 增加web_api

2026-02-05 15:13:54 +08:00

5.6 KiB

Raw Blame History

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. 安装依赖

pip install -r requirements.txt
pip install pyinstaller waitress

2. 构建可执行文件

Windows:

build_exe.bat

Linux/macOS:

chmod +x build_exe.sh
./build_exe.sh

3. 运行服务器

# Windows
dist\GasFluxAPI.exe

# Linux/macOS
./dist/GasFluxAPI

服务器将在 http://localhost:5000 启动。

服务器配置

默认配置

host = '0.0.0.0'      # 监听所有接口
port = 5000            # 默认端口
threads = 8            # 工作线程数
connection_limit = 100 # 最大并发连接
timeout = 300          # 请求超时（秒）

自定义配置

修改 server_waitress.py 中的参数：

# 自定义端口
port = 8080

# 增加线程数
threads = 16

# 调整超时时间
timeout = 600  # 10分钟

部署架构

单文件部署

部署目录/
├── GasFluxAPI(.exe)     # 可执行文件
├── web_api_data/        # 数据目录（自动创建）
│   ├── uploads/        # 上传文件
│   └── outputs/        # 处理结果
├── logs/               # 日志文件（自动创建）
└── gasflux_config.yaml # 配置文件（可选）

生产部署建议

使用反向代理

# 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):

[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 参数调优

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+ 核心
磁盘: 日志和临时文件存储

安全考虑

基本安全措施

防火墙配置: 只开放必要端口
用户权限: 以非 root 用户运行
文件权限: 数据目录限制访问权限

生产环境建议

HTTPS: 使用反向代理配置 SSL
认证: 添加 API 密钥或 JWT 认证
限流: 实现请求频率限制
监控: 设置日志监控和告警

故障排除

常见问题

端口占用

# 检查端口使用
netstat -tulpn | grep :5000
# 或 Windows: netstat -ano | findstr :5000

权限问题

# 确保可执行文件有执行权限
chmod +x GasFluxAPI
# 确保数据目录可写
chmod -R 755 web_api_data/

构建失败

# 清理旧构建
rm -rf build/ dist/
# 重新安装依赖
pip install --upgrade pyinstaller waitress

内存不足
- 减少线程数
- 增加服务器内存
- 优化数据处理流程

调试模式

临时启用详细日志：

# 修改 server_waitress.py
import logging
logging.basicConfig(level=logging.DEBUG)

维护和更新

更新部署

构建新版本可执行文件
备份数据目录
停止旧服务
替换可执行文件
启动新服务

备份策略

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

5.6 KiB Raw Blame History Unescape Escape