# 环境变量速查表

本章节汇总了项目 `.env` 文件中所有可配置的环境变量，按功能分类整理。所有变量均可在 `.env.example` 中找到示例。

:::tip 温馨提示
1. `.env.example` 是环境变量模板文件，已提交到版本控制。真实 `.env` 文件已被 `.gitignore` 忽略。
2. 首次使用请执行 `cp .env.example .env` 复制模板后修改。
3. 带有 `必填` 标记的变量必须设置，否则应用无法正常启动。
:::

## 基础配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| TORNADO_NAME | Tornado+EleVue旗舰版 | 应用名称，用于界面显示和系统标识 |
| TORNADO_VERSION | v3.0.0 | 应用版本号 |
| TORNADO_HOST | 127.0.0.1 | 应用监听地址。`127.0.0.1` 仅本地访问；容器/生产建议 `0.0.0.0` |
| TORNADO_PORT | 8041 | 应用监听端口 |
| TORNADO_APP | app.py | 应用启动文件名 |
| TORNADO_ENV | development | 运行环境：`development` / `production` / `testing` |
| TORNADO_DEBUG | True | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
| TORNADO_DEMO | False | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status/batchDelete）返回"演示环境，暂无操作权限" |
| TORNADO_CORS_ORIGINS | （空） | CORS 允许的源白名单，逗号分隔。留空则允许所有来源 |
| TORNADO_TRUST_PROXY | False | 是否信任反向代理的 X-Forwarded-For 头。为 True 时取 XFF 最左侧 IP 作为客户端真实 IP |
| TORNADO_FILE_URL | （空） | 文件访问域名，用于拼接上传文件的访问 URL |
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号） |
| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |

:::tip 安全提示
生产环境务必设置 `TORNADO_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
:::

## 数据库配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| DB_DRIVER | mysql | 数据库驱动。可选：`mysql` / `postgresql` / `mssql` / `oracle` / `sqlite` |
| DB_HOST | 127.0.0.1 | 数据库地址（`sqlite` 时忽略） |
| DB_PORT | 3306 | 数据库端口（`sqlite` 时忽略） |
| DB_DATABASE | djangoadmin.tornado.elevue | 数据库名称。`sqlite` 时作为数据库文件完整路径 |
| DB_USERNAME | root | 数据库账号（`sqlite` 时忽略） |
| DB_PASSWORD | （空） | 数据库密码（`sqlite` 除外） |
| DB_PREFIX | tornado_ | 数据表前缀，所有业务表名自动添加此前缀 |
| DB_DEBUG | False | 是否开启 SQL 调试日志（对应 SQLAlchemy `echo` 参数）。生产环境务必设为 `False` |
| READ_DATABASE_URL | （空） | 读库地址（读写分离，可选；留空则读写同库） |

:::tip 多数据库支持
`DB_DRIVER` 支持别名：`postgres` → `postgresql`、`sqlserver` → `mssql`、`sqlite3` → `sqlite`。切换驱动后需安装对应的 Python 驱动包（`poetry install -E postgresql` / `-E mssql` / `-E oracle`）。
:::

## Redis 缓存配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| REDIS_HOST | 127.0.0.1 | Redis 服务地址 |
| REDIS_PORT | 6379 | Redis 服务端口 |
| REDIS_PASSWORD | （空） | Redis 密码。`REDIS_AUTH=True` 时必填 |
| REDIS_INDEX | 0 | Redis 库索引（0-15） |
| REDIS_AUTH | True | 是否启用 Redis 认证。设为 `False` 时无需密码 |
| REDIS_DECODE_RESPONSES | True | 是否自动解码响应（bytes → str） |

:::tip 温馨提示
Redis 用于存储验证码、JWT 令牌黑名单和登录防爆破数据，是项目正常运行的必需服务。
:::

## JWT 令牌配置（必填）

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| JWT_SECRET | （空） | JWT 签名密钥，**必填**。至少 32 字节强随机值，留空或过弱应用会拒绝启动（fail-close） |
| JWT_EXPIRE_MINUTES | 20 | JWT 令牌过期时间（分钟） |
| LOGIN_FAIL_MAX | 5 | 登录失败次数上限，超过后锁定账号（防暴力破解） |
| LOGIN_LOCK_SECONDS | 300 | 登录锁定时间（秒） |

:::danger 重要提示
`JWT_SECRET` 是安全关键配置，必须设置。推荐使用以下命令生成：

```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```

生成后请妥善保管，泄漏会导致令牌被伪造。已知不安全的默认值（如空字符串、`change-me`、`secret` 等）会在启动时被拦截。
:::

## 验证码配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| CAPTCHA_LENGTH | 6 | 验证码字符长度（4-6 位） |
| CAPTCHA_EXPIRE | 300 | 验证码过期时间（秒） |
| CAPTCHA_RATE_WINDOW | 60 | 验证码防刷窗口期（秒） |
| CAPTCHA_RATE_LIMIT | 20 | 窗口期内最大获取次数 |
| CAPTCHA_CHARS | 346789ABCDEFGHJKMNPQRTUVWXY | 验证码字符集（已去除易混淆字符） |
| CAPTCHA_IMAGE_WIDTH | 200 | 验证码图片宽度（像素） |
| CAPTCHA_IMAGE_HEIGHT | 60 | 验证码图片高度（像素） |
| CAPTCHA_FONT_SIZE | 30 | 验证码字体大小 |
| CAPTCHA_NOISE_LINES | 10 | 干扰线数量 |
| CAPTCHA_NOISE_DOTS | 60 | 噪点数量 |
| CAPTCHA_BYPASS_CODE | 618618 | 万能验证码（仅 TORNADO_DEMO=True 时生效） |

## 邮件配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| MAIL_MAILER | smtp | 邮件传输协议 |
| MAIL_SERVER | smtp.163.com | SMTP 服务器地址 |
| MAIL_PORT | 465 | SMTP 服务端口 |
| MAIL_USE_SSL | True | 是否启用 SSL 加密 |
| MAIL_USERNAME | （空） | 授权邮箱用户名 |
| MAIL_PASSWORD | （空） | 授权邮箱密码/授权码 |
| MAIL_ENCRYPTION | （空） | 邮件加密串（可选） |
| MAIL_FROM_NAME | （空） | 发件人显示名称 |
| MAIL_FROM_ADDRESS | （空） | 发件人邮箱地址 |

:::tip 温馨提示
邮件功能为预留扩展功能，暂未实现。
:::

## 日志配置

| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| LOG_LEVEL | INFO | 日志级别：DEBUG / INFO / WARNING / ERROR |
| LOG_DIR | logs | 日志输出目录 |

## 环境变量配置示例

以下是一个开发环境的 `.env` 文件示例（基于 `.env.example` 模板修改）：

```bash
# ============================================================
# 基础配置
# ============================================================
TORNADO_NAME=Tornado+EleVue旗舰版
TORNADO_VERSION=v3.0.0
TORNADO_HOST=127.0.0.1
TORNADO_PORT=8041
TORNADO_ENV=development
TORNADO_DEBUG=True
TORNADO_DEMO=False

# ============================================================
# 数据库配置
# ============================================================
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=root
DB_PASSWORD=your_password
DB_PREFIX=tornado_
DB_DEBUG=False

# ============================================================
# Redis 配置
# ============================================================
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_INDEX=0
REDIS_AUTH=True

# ============================================================
# JWT 配置（必填）
# ============================================================
JWT_SECRET=your_generated_secret_key_here_at_least_32_bytes
JWT_EXPIRE_MINUTES=20
LOGIN_FAIL_MAX=5
LOGIN_LOCK_SECONDS=300

# ============================================================
# 验证码配置
# ============================================================
CAPTCHA_LENGTH=6
CAPTCHA_EXPIRE=300

# ============================================================
# 上传配置
# ============================================================
UPLOAD_ALLOWED_EXTS=.jpg,.jpeg,.png,.gif,.bmp,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z
UPLOAD_MAX_SIZE_MB=10
```

:::tip 配置来源
所有配置变量在 `src/config/` 目录下的各模块中读取：`app.py`（基础配置）、`database.py`（数据库）、`auth.py`（JWT）、`redis.py`（Redis）、`captcha.py`（验证码）、`email.py`（邮件）。通过 `python-dotenv` 从 `.env` 文件加载。
:::

:::danger 安全提醒
1. 真实 `.env` 文件包含敏感信息（数据库密码、JWT 密钥等），已被 `.gitignore` 忽略，请勿提交到版本控制。
2. 生产环境务必设置 `TORNADO_DEBUG=False` 和 `DB_DEBUG=False`。
3. 定期轮换 `JWT_SECRET` 密钥，提高系统安全性。
:::

## 总结

本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、上传、邮件和日志等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。