Tolan/backend/ENV_CONFIG.md

环境变量配置说明

配置文件

在 backend/ 目录创建 .env 文件，配置以下环境变量。

必需配置

豆包API配置

# 豆包API密钥（必需）
DOUBAO_API_KEY=your_api_key_here

# 豆包APP ID（必需）
DOUBAO_APP_ID=your_app_id_here

获取方式:

1. 访问豆包开放平台
2. 创建应用
3. 获取API Key和App ID

可选配置

豆包API高级配置

# 豆包API地址（可选，默认使用官方地址）
DOUBAO_API_URL=wss://openspeech.bytedance.com/api/v3/realtime/dialogue

# 输出音频格式（可选，默认ogg_opus）
# 选项: ogg_opus 或 pcm
DOUBAO_OUTPUT_FORMAT=ogg_opus

服务器配置

# 服务器地址（可选，默认0.0.0.0）
HOST=0.0.0.0

# 服务器端口（可选，默认8000）
PORT=8000

# 调试模式（可选，默认False）
DEBUG=False

连接池配置

# 连接池大小（可选，默认10）
CONNECTION_POOL_SIZE=10

# 最大空闲时间-秒（可选，默认300）
CONNECTION_MAX_IDLE_TIME=300

# 健康检查间隔-秒（可选，默认60）
CONNECTION_HEALTH_CHECK_INTERVAL=60

日志配置

# 日志级别（可选，默认INFO）
# 选项: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# 日志目录（可选，默认logs）
LOG_DIR=logs

SSL配置

# SSL密钥文件路径（可选）
SSL_KEYFILE=../ssl/key.pem

# SSL证书文件路径（可选）
SSL_CERTFILE=../ssl/cert.pem

完整示例

开发环境 (.env)

# 豆包API（必填）
DOUBAO_API_KEY=70G0Dky0P24Ai2VsizJQ5bDLHIkKzLNt
DOUBAO_APP_ID=9775523795

# 服务器
HOST=0.0.0.0
PORT=8000
DEBUG=True

# 日志
LOG_LEVEL=DEBUG

# 连接池
CONNECTION_POOL_SIZE=5

生产环境 (.env.production)

# 豆包API（必填）
DOUBAO_API_KEY=your_production_api_key
DOUBAO_APP_ID=your_production_app_id

# 服务器
HOST=0.0.0.0
PORT=8443
DEBUG=False

# 日志
LOG_LEVEL=INFO
LOG_DIR=/var/log/tolan

# 连接池
CONNECTION_POOL_SIZE=20
CONNECTION_MAX_IDLE_TIME=600

# SSL
SSL_KEYFILE=/etc/ssl/tolan/key.pem
SSL_CERTFILE=/etc/ssl/tolan/cert.pem

测试模式（无需豆包API）

如果暂时没有豆包API密钥，可以留空或不配置，系统会自动使用模拟API：

# .env（留空或注释）
# DOUBAO_API_KEY=
# DOUBAO_APP_ID=

系统会输出：

[WARNING] 豆包API密钥未配置，创建模拟连接

模拟模式下：

• ✅ 可以测试前后端通信
• ✅ 可以测试WebSocket流式传输
• ✅ 会返回模拟的音频数据
• ❌ 无法获得真实的AI回复

验证配置

启动服务后，查看日志输出：

配置正确:

[SUCCESS] 连接 #0 创建成功 (真实API)
[SUCCESS] 连接 #1 创建成功 (真实API)
...
[SUCCESS] 豆包会话已建立: session_abc123

配置错误或未配置:

[WARNING] 连接 #0: 豆包API密钥未配置，创建模拟连接
[WARNING] 连接 #0: 回退到模拟连接

配置优先级

1. 环境变量 (.env 文件)
2. 系统环境变量
3. 默认值 (config.py)

注意事项

1. 保密: .env 文件包含敏感信息，不要提交到Git
2. 权限: 确保 .env 文件权限为 600
3. 路径: 所有相对路径都是相对于 backend/ 目录

# 设置文件权限
chmod 600 .env

故障排查

问题: 配置未生效

解决:

1. 确认 .env 文件在 backend/ 目录下
2. 重启服务
3. 检查环境变量名是否正确（区分大小写）

问题: 豆包API连接失败

解决:

1. 验证API Key和App ID是否正确
2. 检查网络连接
3. 查看详细日志

# 启用调试日志
LOG_LEVEL=DEBUG python main.py