配置说明
雷驼智能引擎使用混合配置系统，支持 TOML 配置文件和环境变量覆盖。本指南将详细介绍所有可用的配置选项。
配置优先级
配置按以下优先级生效（从高到低）：
- 环境变量 - 覆盖所有其他值
- TOML 配置文件 - 提供默认值和结构
- 内置默认值 - 兜底值
配置方法
方法一：环境变量（推荐用于生产环境）
在根目录下创建 .env 文件：
# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=dathor
DB_SSL=false
DB_MAX_CONNECTIONS=20
# 应用程序配置
APP_PORT=8000
ENABLE_DEBUG=false
BASE_URL=https://your-domain.com
DEFAULT_LANGUAGE=zh-Hans
# 缓存配置
CACHE_MODE=hybrid
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# 安全配置
COOKIE_SECURE=true
COOKIE_SAME_SITE=Strict
SESSION_TIMEOUT=604800
# 监控配置
METRICS_ENABLED=false
TRACING_ENABLED=false
LOG_LEVEL=info
# API配置
API_DEFAULT_TIMEOUT=30000
API_MAX_REQUEST_SIZE=10MB
API_CORS_ENABLED=true
# 邮件服务配置
EMAIL_ENABLED=false
EMAIL_PROVIDER=smtp
EMAIL_SMTP_HOST=localhost
EMAIL_SMTP_PORT=587
EMAIL_SMTP_SECURE=true
EMAIL_SMTP_USER=
EMAIL_SMTP_PASSWORD=
EMAIL_FROM_EMAIL=
EMAIL_FROM_NAME=Dathor
# 存储配置
STORAGE_PROVIDER=filesystem
FILE_BASE_URL=
方法二：TOML 配置文件
编辑 config.toml 文件：
[application]
port = 8000
enable_debug = false
base_url = ""
default_language = "zh-Hans"
[database]
host = "localhost"
port = 5432
user = "postgres"
password = ""
name = "dathor"
ssl = false
max_connections = 10
[cache]
mode = "memory"
redis_host = "localhost"
redis_port = 6379
redis_password = ""
redis_db = 0
[security]
cookie_secure = false
cookie_same_site = "lax"
session_timeout = 3600
[monitoring]
metrics_enabled = false
tracing_enabled = false
log_level = "info"
[api]
default_timeout = 30000
max_request_size = "10MB"
cors_enabled = true
[email]
enabled = false
provider = "smtp"
smtp_host = "localhost"
smtp_port = 587
smtp_secure = true
smtp_user = ""
smtp_password = ""
from_email = ""
from_name = "Dathor"
[storage]
provider = "filesystem"
file_base_url = ""
配置选项详解
数据库配置
| 变量名 | 替代变量 | 描述 | 默认值 | 必需 |
|---|---|---|---|---|
DB_HOST | PGHOST | 数据库主机地址 | localhost | 是 |
DB_PORT | PGPORT | 数据库端口 | 5432 | 否 |
DB_USER | PGUSER | 数据库用户名 | postgres | 否 |
DB_PASSWORD | PGPASSWORD | 数据库密码 | (空) | 是 |
DB_NAME | PGDATABASE | 数据库名称 | dathor | |
DB_SSL | 启用 SSL 连接 | false | ||
DB_MAX_CONNECTIONS | 最大数据库连接数 | 10 |
应用程序配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
APP_PORT | 应用程序端口 | 8000 | |
ENABLE_DEBUG | 启用调试模式 | false | |
BASE_URL | 应用基础 URL | (空) | |
DEFAULT_LANGUAGE | 默认语言设置 | zh-Hans |
缓存配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
CACHE_MODE | 缓存模式 | memory | |
REDIS_HOST | Redis 主机地址 | localhost | |
REDIS_PORT | Redis 端口 | 6379 | |
REDIS_PASSWORD | Redis 密码 | (空) | |
REDIS_DB | Redis 数据库索引 | 0 | |
MEMORY_CACHE_MAX_SIZE | 内存缓存最大条目数 | 50000 | |
MEMORY_CACHE_TTL | 内存缓存TTL(秒) | 300 |
缓存模式说明
memory: 仅使用内存缓存redis: 仅使用Redis缓存hybrid: 混合模式，L1内存缓存 + L2 Redis缓存
安全配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
COOKIE_SECURE | Cookie 安全标志 | false | |
COOKIE_SAME_SITE | Cookie SameSite 属性 | lax | |
SESSION_TIMEOUT | 会话超时时间(秒) | 3600 |
监控配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
METRICS_ENABLED | 启用指标收集 | false | |
TRACING_ENABLED | 启用链路追踪 | false | |
LOG_LEVEL | 日志级别 | info |
API配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
API_DEFAULT_TIMEOUT | API默认超时(毫秒) | 30000 | |
API_MAX_REQUEST_SIZE | 最大请求体大小 | 10MB | |
API_CORS_ENABLED | 启用跨域请求 | true |
邮件服务配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
EMAIL_ENABLED | 启用邮件服务 | false | |
EMAIL_PROVIDER | 邮件提供商 | smtp | |
EMAIL_SMTP_HOST | SMTP服务器地址 | localhost | |
EMAIL_SMTP_PORT | SMTP服务器端口 | 587 | |
EMAIL_SMTP_SECURE | 启用SMTP安全连接 | true | |
EMAIL_SMTP_USER | SMTP用户名 | (空) | |
EMAIL_SMTP_PASSWORD | SMTP密码 | (空) | |
EMAIL_FROM_EMAIL | 发件人邮箱地址 | (空) | |
EMAIL_FROM_NAME | 发件人姓名 | Dathor |
邮件提供商说明
smtp: 使用SMTP服务器发送邮件sendgrid: 使用SendGrid服务发送邮件ses: 使用AWS SES服务发送邮件
存储配置
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
STORAGE_PROVIDER | 存储提供商 | filesystem | |
FILE_BASE_URL | 文件基础URL | (空) |
存储提供商说明
filesystem: 使用本地文件系统存储minio: 使用MinIO对象存储服务
MinIO配置（当 STORAGE_PROVIDER=minio 时需要）
| 变量名 | 描述 | 默认值 | 必需 |
|---|---|---|---|
MINIO_ENDPOINT | MinIO服务器地址 | localhost | |
MINIO_PORT | MinIO服务器端口 | 9000 | |
MINIO_USE_SSL | 启用SSL连接 | false | |
MINIO_ACCESS_KEY | MinIO访问密钥 | (空) | |
MINIO_SECRET_KEY | MinIO私钥 | (空) | |
MINIO_BUCKET | 存储桶名称 | dathor | |
MINIO_REGION | 存储区域 | us-east-1 |
快速开始配置
对于本地开发，最简单的方式是创建 .env 文件，只设置数据库密码：
DB_PASSWORD=your_database_password
其他配置将使用 config.toml 中的默认值。
容器化部署配置
对于 Docker 或 Kubernetes 部署，推荐使用环境变量：
- Docker Compose: 参考
docker-compose.example.yml - Kubernetes: 参考
k8s-deployment.example.yaml - 云平台: 使用平台提供的环境变量设置功能
配置验证
启动服务后，可以通过以下方式验证配置：
- 查看启动日志中的配置信息
- 访问
/health端点检查服务状态 - 访问管理界面查看配置状态
常见配置问题
Q: 数据库连接失败
A: 检查数据库配置：
- 确认
DB_HOST和DB_PORT正确 - 验证
DB_USER和DB_PASSWORD - 确保数据库服务正在运行
Q: Redis 连接失败
A: 检查 Redis 配置：
- 确认
REDIS_HOST和REDIS_PORT正确 - 验证
REDIS_PASSWORD（如果设置了密码） - 确保 Redis 服务正在运行
Q: 邮件发送失败
A: 检查邮件配置：
- 确认 SMTP 服务器设置正确
- 验证用户名和密码
- 检查网络连接和防火墙设置