增加web_api

2026-02-05 15:13:54 +08:00
parent 443ec09c5c
commit d5edbc0723
43 changed files with 7036 additions and 2640 deletions
--- a/ENVIRONMENT_VARIABLES.md
+++ b/ENVIRONMENT_VARIABLES.md
@ -0,0 +1,255 @@
+# GasFlux Web API - 环境变量配置指南
+
+本文档介绍如何使用环境变量来配置 GasFlux Web API 的行为。
+
+## 概述
+
+GasFlux 支持通过环境变量进行灵活配置，无需修改代码即可适应不同的部署环境和需求。
+
+## 环境变量列表
+
+### 服务器配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_HOST` | `0.0.0.0` | 服务器监听主机地址 |
+| `GASFLUX_PORT` | `5000` | 服务器监听端口 |
+| `GASFLUX_DEBUG` | `false` | 是否启用调试模式 (true/false) |
+
+### 目录配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_UPLOAD_FOLDER` | `web_api_data/uploads` | 上传文件存储目录 |
+| `GASFLUX_OUTPUT_FOLDER` | `web_api_data/outputs` | 处理结果输出目录 |
+
+### 文件和性能配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_MAX_CONTENT_LENGTH` | `104857600` (100MB) | 最大上传文件大小（字节） |
+| `GASFLUX_THREADS` | `8` | Waitress 服务器线程数 |
+| `GASFLUX_CONNECTION_LIMIT` | `100` | 最大并发连接数 |
+| `GASFLUX_CHANNEL_TIMEOUT` | `300` | 连接超时时间（秒） |
+
+### 日志配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_LOG_LEVEL` | `INFO` | 日志级别 (DEBUG/INFO/WARNING/ERROR/CRITICAL) |
+| `GASFLUX_LOG_FILE` | `logs/gasflux_api.log` | 日志文件路径 |
+
+### 安全和跨域配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_CORS_ORIGINS` | `*` | 允许的 CORS 源，用逗号分隔 |
+
+### 任务管理配置
+
+| 变量名 | 默认值 | 描述 |
+|--------|--------|------|
+| `GASFLUX_TASK_CLEANUP_INTERVAL` | `3600` | 任务清理检查间隔（秒） |
+| `GASFLUX_MAX_TASK_AGE` | `86400` | 任务最大保留时间（秒，24小时） |
+
+## 配置示例
+
+### 开发环境
+
+```bash
+# 开发环境配置
+export GASFLUX_HOST=127.0.0.1
+export GASFLUX_PORT=5000
+export GASFLUX_DEBUG=true
+export GASFLUX_LOG_LEVEL=DEBUG
+```
+
+### 生产环境
+
+```bash
+# 生产环境配置
+export GASFLUX_HOST=0.0.0.0
+export GASFLUX_PORT=80
+export GASFLUX_DEBUG=false
+export GASFLUX_LOG_LEVEL=INFO
+export GASFLUX_THREADS=16
+export GASFLUX_CONNECTION_LIMIT=200
+export GASFLUX_MAX_CONTENT_LENGTH=524288000  # 500MB
+```
+
+### Docker 部署
+
+```bash
+# Docker 环境变量
+docker run -p 80:5000 \
+  -e GASFLUX_HOST=0.0.0.0 \
+  -e GASFLUX_PORT=5000 \
+  -e GASFLUX_LOG_LEVEL=INFO \
+  gasflux-api
+```
+
+### Windows 服务
+
+创建 `start_gasflux.bat`:
+
+```batch
+@echo off
+set GASFLUX_HOST=0.0.0.0
+set GASFLUX_PORT=80
+set GASFLUX_LOG_LEVEL=INFO
+set GASFLUX_THREADS=8
+
+GasFluxAPI.exe
+```
+
+### Linux systemd
+
+创建 `/etc/systemd/system/gasflux.service`:
+
+```ini
+[Unit]
+Description=GasFlux Web API
+After=network.target
+
+[Service]
+Type=simple
+User=gasflux
+Environment=GASFLUX_HOST=0.0.0.0
+Environment=GASFLUX_PORT=80
+Environment=GASFLUX_LOG_LEVEL=INFO
+Environment=GASFLUX_THREADS=8
+ExecStart=/path/to/GasFluxAPI
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## 运行时配置检查
+
+启动应用后，可以通过以下方式检查当前配置：
+
+### API 端点
+
+```bash
+curl http://localhost:5000/config
+```
+
+### 启动日志
+
+应用启动时会输出当前配置信息：
+
+```
+Configuration: {
+  'host': '0.0.0.0',
+  'port': 5000,
+  'debug': False,
+  ...
+}
+```
+
+## 最佳实践
+
+### 安全考虑
+
+1. **生产环境**：
+   - 设置 `GASFLUX_DEBUG=false`
+   - 配置适当的 `GASFLUX_CORS_ORIGINS`
+   - 使用防火墙限制访问
+
+2. **文件权限**：
+   - 确保上传和输出目录有适当的权限
+   - 定期清理旧文件
+
+### 性能调优
+
+1. **线程数**：根据 CPU 核心数设置 `GASFLUX_THREADS`
+2. **连接限制**：根据服务器容量设置 `GASFLUX_CONNECTION_LIMIT`
+3. **文件大小**：根据实际需求调整 `GASFLUX_MAX_CONTENT_LENGTH`
+
+### 日志管理
+
+1. **日志轮转**：定期备份和清理日志文件
+2. **日志级别**：
+   - 开发环境：`DEBUG`
+   - 生产环境：`INFO` 或 `WARNING`
+
+## 故障排除
+
+### 常见问题
+
+1. **端口占用**：
+   ```bash
+   # 检查端口使用
+   netstat -tulpn | grep :5000
+   ```
+
+2. **权限问题**：
+   ```bash
+   # 确保目录权限正确
+   chmod -R 755 web_api_data/
+   ```
+
+3. **配置不生效**：
+   - 确保环境变量在应用启动前设置
+   - 检查变量名拼写是否正确
+
+### 调试配置
+
+启用详细日志查看配置加载：
+
+```bash
+export GASFLUX_LOG_LEVEL=DEBUG
+# 启动应用
+```
+
+## 配置验证脚本
+
+创建一个验证脚本 `check_config.py`：
+
+```python
+#!/usr/bin/env python3
+"""Configuration validation script"""
+
+import os
+from pathlib import Path
+
+def check_config():
+    """Check current configuration."""
+    print("GasFlux Configuration Check")
+    print("=" * 40)
+
+    # Server config
+    print(f"Host: {os.getenv('GASFLUX_HOST', '0.0.0.0')}")
+    print(f"Port: {os.getenv('GASFLUX_PORT', '5000')}")
+    print(f"Debug: {os.getenv('GASFLUX_DEBUG', 'false')}")
+    print(f"Log Level: {os.getenv('GASFLUX_LOG_LEVEL', 'INFO')}")
+
+    # Directory config
+    base_dir = Path.cwd()
+    upload_dir = base_dir / os.getenv('GASFLUX_UPLOAD_FOLDER', 'web_api_data/uploads')
+    output_dir = base_dir / os.getenv('GASFLUX_OUTPUT_FOLDER', 'web_api_data/outputs')
+
+    print(f"Upload Folder: {upload_dir}")
+    print(f"Output Folder: {output_dir}")
+
+    # Check directories
+    print("
+Directory Status:")
+    print(f"Upload dir exists: {upload_dir.exists()}")
+    print(f"Output dir exists: {output_dir.exists()}")
+
+    # Performance config
+    print("
+Performance Config:")
+    print(f"Threads: {os.getenv('GASFLUX_THREADS', '8')}")
+    print(f"Connection Limit: {os.getenv('GASFLUX_CONNECTION_LIMIT', '100')}")
+
+if __name__ == "__main__":
+    check_config()
+```
+
+运行验证：
+```bash
+python check_config.py
+```