255 lines
5.6 KiB
Markdown
255 lines
5.6 KiB
Markdown
# 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
|
||
``` |