UAV-CO2/ENVIRONMENT_VARIABLES.md

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小时）

配置示例

开发环境

# 开发环境配置
export GASFLUX_HOST=127.0.0.1
export GASFLUX_PORT=5000
export GASFLUX_DEBUG=true
export GASFLUX_LOG_LEVEL=DEBUG

生产环境

# 生产环境配置
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 部署

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

@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:

[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 端点

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. 端口占用：

   # 检查端口使用
   netstat -tulpn | grep :5000
   

2. 权限问题：

   # 确保目录权限正确
   chmod -R 755 web_api_data/
   

3. 配置不生效：

   • 确保环境变量在应用启动前设置
   • 检查变量名拼写是否正确

调试配置

启用详细日志查看配置加载：

export GASFLUX_LOG_LEVEL=DEBUG
# 启动应用

配置验证脚本

创建一个验证脚本 check_config.py：

#!/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()

运行验证：

python check_config.py