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