243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
# 环境变量速查表
|
||
|
||
本章节汇总了项目 `.env` 文件中所有可配置的环境变量，按功能分类整理。所有变量均可在 `.env.example` 中找到示例。
|
||
|
||
:::tip 温馨提示
|
||
1. `.env.example` 是环境变量模板文件，已提交到版本控制。真实 `.env` 文件已被 `.gitignore` 忽略。
|
||
2. 首次使用请执行 `cp .env.example .env` 复制模板后修改。
|
||
3. 带有 `必填` 标记的变量必须设置，否则应用无法正常启动。
|
||
:::
|
||
|
||
## 基础配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| FLASK_NAME | DjangoAdmin Flask+NaiveUI版 | 应用名称，用于界面显示和系统标识 |
|
||
| FLASK_VERSION | v3.0.0 | 应用版本号 |
|
||
| FLASK_HOST | 0.0.0.0 | 应用监听地址。`127.0.0.1` 仅本地访问；容器/生产建议 `0.0.0.0` |
|
||
| FLASK_PORT | 8021 | 应用监听端口 |
|
||
| FLASK_APP | app.py | 应用启动文件名 |
|
||
| FLASK_ENV | development | 运行环境：`development` / `production` / `testing` |
|
||
| FLASK_DEBUG | True | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
|
||
| FLASK_DEMO | False | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status/batchDelete）返回"演示环境，暂无操作权限" |
|
||
| FLASK_USE_RELOADER | False | 是否禁用自动重启。仅在 `FLASK_DEBUG=True` 时生效 |
|
||
| FLASK_SECRET_KEY | `<必填>` | Flask 应用密钥，用于 Session 加密和 CSRF 保护，**必填**且至少 16 字符 |
|
||
| FLASK_UPLOAD_DIR | ./uploads | 文件上传存储目录 |
|
||
| FLASK_FILE_URL | http://file.flask.naivevue | 文件访问域名，用于拼接上传文件的访问 URL |
|
||
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,.gif,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号） |
|
||
| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |
|
||
|
||
:::tip 安全提示
|
||
生产环境务必设置 `FLASK_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
|
||
:::
|
||
|
||
## 数据库配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| DB_DRIVER | mysql | 数据库驱动。可选：`mysql` / `postgresql` / `mssql` / `oracle` / `sqlite` |
|
||
| DB_HOST | 127.0.0.1 | 数据库地址（`sqlite` 时忽略） |
|
||
| DB_PORT | 3306 | 数据库端口（`sqlite` 时忽略） |
|
||
| DB_DATABASE | djangoadmin.flask.naivevue | 数据库名称。`sqlite` 时作为数据库文件完整路径 |
|
||
| DB_USERNAME | root | 数据库账号（`sqlite` 时忽略） |
|
||
| DB_PASSWORD | CHANGE_ME_DB_PASSWORD | 数据库密码，**必填**（`sqlite` 除外） |
|
||
| DB_PREFIX | flask_ | 数据表前缀，所有业务表名自动添加此前缀。模型中通过 `DB_PREFIX + "position"` 拼接表名 |
|
||
| DB_DEBUG | True | 是否开启 SQL 调试日志（对应 SQLAlchemy `echo` 参数）。生产环境务必设为 `False` |
|
||
| DB_SSL | False | 是否启用数据库 SSL 加密连接 |
|
||
| DB_SSL_CA | （空） | SSL CA 证书路径（验证服务端证书） |
|
||
| DB_SSL_CERT | （空） | SSL 客户端证书路径（双向认证） |
|
||
| DB_SSL_KEY | （空） | SSL 客户端私钥路径（双向认证） |
|
||
|
||
:::tip 多数据库支持
|
||
`DB_DRIVER` 支持别名：`postgres` → `postgresql`、`sqlserver` → `mssql`、`sqlite3` → `sqlite`。切换驱动后需安装对应的 Python 驱动包。
|
||
:::
|
||
|
||
## Redis 缓存配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| REDIS_HOST | 127.0.0.1 | Redis 服务地址 |
|
||
| REDIS_PORT | 6379 | Redis 服务端口 |
|
||
| REDIS_PASSWORD | CHANGE_ME_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_SALT | `<必填>` | JWT 签名密钥，**必填**。至少 16 字符强随机值，留空应用会拒绝启动 |
|
||
| JWT_EXPIRE_MINUTES | 20 | 滑动会话空闲超时（分钟），无请求则过期，活跃自动续期 |
|
||
| JWT_ABSOLUTE_TIMEOUT_MINUTES | 1440 | 令牌绝对有效期（分钟），防止无限续期，须 ≥ JWT_EXPIRE_MINUTES |
|
||
| LOGIN_FAIL_MAX | 5 | 登录失败次数上限，超过后锁定账号（防暴力破解） |
|
||
| LOGIN_LOCK_SECONDS | 300 | 登录锁定时间（秒） |
|
||
| PERMISSION_ENABLED | True | 权限校验总开关。`False` 时所有请求放行（开发调试可用） |
|
||
| INTERNAL_API_KEY | `<必填>` | 内部调用密钥（定时任务等无用户场景，通过 `X-Scheduler-Key` / `X-Internal-API-Key` 传递） |
|
||
| INTERNAL_ALLOWED_IPS | 127.0.0.1 | 内部调用白名单 IP，逗号分隔 |
|
||
|
||
## 登录白名单配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| LOGIN_WHITELIST_EXACT | /api/v1/login,/api/v1/captcha,/favicon.ico,/health | 精确匹配白名单，逗号分隔 |
|
||
| LOGIN_WHITELIST_PREFIX | /api/v1/job/sendSms,/public,/static,/api/webhook | 前缀匹配白名单，逗号分隔 |
|
||
| LOGIN_WHITELIST_WILDCARD | /api/v1/job/*/send*,/api/v1/*/public* | 通配符匹配白名单，支持 `*` 和 `?` |
|
||
| LOGIN_WHITELIST_DEBUG | True | 是否启用白名单调试日志 |
|
||
| LOGIN_WHITELIST_LOG_ACCESS | True | 白名单路径是否记录访问日志 |
|
||
| CAPTCHA_BYPASS_CODE | （空） | 万能验证码，仅 `FLASK_DEMO=True` 时生效 |
|
||
|
||
:::danger 重要提示
|
||
`JWT_SALT` 是安全关键配置，必须设置。推荐使用以下命令生成：
|
||
|
||
```bash
|
||
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||
```
|
||
|
||
生成后请妥善保管，泄漏会导致令牌被伪造。
|
||
:::
|
||
|
||
## 验证码配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| CAPTCHA_LENGTH | 6 | 验证码字符长度（4-6 位） |
|
||
| CAPTCHA_EXPIRE | 300 | 验证码过期时间（秒） |
|
||
| CAPTCHA_RATE_WINDOW | 60 | 验证码防刷窗口期（秒） |
|
||
| CAPTCHA_RATE_LIMIT | 10 | 窗口期内最大获取次数 |
|
||
| CAPTCHA_CHARS | ABCDEFGHJKLMNPQRSTUVWXYZ2346789 | 验证码字符集（已去除易混淆字符） |
|
||
| CAPTCHA_FONT_PATH | static/fonts/Vera.ttf | 验证码字体文件路径 |
|
||
| CAPTCHA_IMAGE_WIDTH | 160 | 验证码图片宽度（像素） |
|
||
| CAPTCHA_IMAGE_HEIGHT | 50 | 验证码图片高度（像素） |
|
||
| CAPTCHA_FONT_SIZE | 28 | 验证码字体大小 |
|
||
| CAPTCHA_NOISE_LINES | 6 | 干扰线数量 |
|
||
| CAPTCHA_NOISE_DOTS | 30 | 噪点数量 |
|
||
|
||
## 跨域与代理配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| CORS_ALLOWED_ORIGINS | http://localhost:8001 | CORS 允许的源，多个用逗号分隔 |
|
||
| PROXY_NUM | 0 | 可信代理层数。`0` = 不信任 X-Forwarded-For；部署在 Nginx 等反代后设为 `1` |
|
||
|
||
:::tip 温馨提示
|
||
本地开发时，`CORS_ALLOWED_ORIGINS` 需包含前端开发服务器地址（默认 `http://localhost:8001`）。如果有多个前端地址，用逗号分隔：
|
||
|
||
```bash
|
||
CORS_ALLOWED_ORIGINS=http://localhost:8001,http://192.168.1.100:8001
|
||
```
|
||
:::
|
||
|
||
## 邮件配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| MAIL_MAILER | smtp | 邮件传输协议 |
|
||
| MAIL_SERVER | smtp.163.com | SMTP 服务器地址 |
|
||
| MAIL_PORT | 465 | SMTP 服务端口 |
|
||
| MAIL_USE_SSL | True | 是否启用 SSL 加密 |
|
||
| MAIL_USERNAME | CHANGE_ME_MAIL_USERNAME | 授权邮箱用户名 |
|
||
| MAIL_PASSWORD | CHANGE_ME_MAIL_PASSWORD | 授权邮箱密码/授权码 |
|
||
| MAIL_ENCRYPTION | （空） | 邮件加密串（可选） |
|
||
| MAIL_FROM_NAME | （空） | 发件人显示名称 |
|
||
| MAIL_FROM_ADDRESS | （空） | 发件人邮箱地址 |
|
||
|
||
:::tip 温馨提示
|
||
邮件功能为预留扩展功能，暂未实现。
|
||
:::
|
||
|
||
## 短信配置（阿里云）
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|:----|:----|:----|
|
||
| SMS_PROVIDER | aliyun | 短信服务商（当前仅支持 aliyun） |
|
||
| SMS_ALIYUN_ACCESS_KEY_ID | `<必填>` | 阿里云 AccessKey ID |
|
||
| SMS_ALIYUN_ACCESS_KEY_SECRET | `<必填>` | 阿里云 AccessKey Secret |
|
||
| SMS_ALIYUN_SIGN_NAME | `<必填>` | 短信签名（需在阿里云控制台审核通过） |
|
||
| SMS_ALIYUN_ENDPOINT | dysmsapi.aliyuncs.com | 短信服务接入点 |
|
||
| SMS_ALIYUN_CONNECT_TIMEOUT | 10000 | 连接超时（毫秒） |
|
||
| SMS_ALIYUN_READ_TIMEOUT | 10000 | 读取超时（毫秒） |
|
||
|
||
:::tip 温馨提示
|
||
短信功能基于阿里云短信服务，需在阿里云控制台开通短信服务并获取 AccessKey。
|
||
:::
|
||
|
||
|
||
## 环境变量配置示例
|
||
|
||
以下是一个开发环境的 `.env` 文件示例（基于 `.env.example` 模板修改）：
|
||
|
||
```bash
|
||
# ============================================================
|
||
# 基础服务配置
|
||
# ============================================================
|
||
FLASK_NAME=DjangoAdmin Flask+NaiveUI版 # 应用名称
|
||
FLASK_VERSION=v3.0.0 # 应用版本号
|
||
FLASK_HOST=127.0.0.1 # 服务监听地址（127.0.0.1 仅本地访问，0.0.0.0 允许外部访问）
|
||
FLASK_PORT=8021 # 服务监听端口
|
||
FLASK_ENV=development # 运行环境（development / testing / production）
|
||
FLASK_DEBUG=True # 调试模式开关（True 开启，生产环境请设为 False）
|
||
FLASK_DEMO=False # 演示模式开关（True 开启后将限制部分写操作）
|
||
FLASK_SECRET_KEY=your_secret_key_at_least_16_chars # Flask 应用密钥（必填，至少 16 字符）
|
||
FLASK_FILE_URL=http://file.flask.naivevue # 文件服务地址（用于访问上传的文件）
|
||
|
||
# ============================================================
|
||
# 数据库配置
|
||
# ============================================================
|
||
DB_DRIVER=mysql # 数据库类型（mysql / postgresql / mssql / sqlite / oracle）
|
||
DB_HOST=127.0.0.1 # 数据库主机地址
|
||
DB_PORT=3306 # 数据库端口（MySQL 默认 3306）
|
||
DB_DATABASE=djangoadmin.flask.naivevue # 数据库名称
|
||
DB_USERNAME=root # 数据库用户名
|
||
DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
|
||
DB_PREFIX=flask_ # 数据表前缀（用于区分不同应用的同库表）
|
||
DB_DEBUG=False # 数据库调试模式（True 会输出 SQL 日志）
|
||
|
||
# ============================================================
|
||
# Redis 配置
|
||
# ============================================================
|
||
REDIS_HOST=127.0.0.1 # Redis 主机地址
|
||
REDIS_PORT=6379 # Redis 端口（默认 6379）
|
||
REDIS_PASSWORD=your_redis_password # Redis 密码（请修改为实际密码）
|
||
REDIS_INDEX=0 # Redis 数据库索引（默认 0，可设为 1-15 隔离不同业务）
|
||
REDIS_AUTH=True # 是否启用密码认证（True/False）
|
||
REDIS_DECODE_RESPONSES=True # 是否自动解码响应为字符串（True 自动将 bytes 转为 str）
|
||
|
||
# ============================================================
|
||
# JWT 认证配置（必填）
|
||
# ============================================================
|
||
JWT_SALT=your_generated_secret_key_here_at_least_16_chars # JWT 加密盐值（建议 16 位以上随机字符串，务必修改）
|
||
JWT_EXPIRE_MINUTES=20 # JWT Token 过期时间（单位：分钟）
|
||
LOGIN_FAIL_MAX=5 # 登录失败最大尝试次数（超过后锁定账户）
|
||
LOGIN_LOCK_SECONDS=300 # 登录锁定持续时间（单位：秒，300=5分钟）
|
||
|
||
# ============================================================
|
||
# 验证码配置
|
||
# ============================================================
|
||
CAPTCHA_LENGTH=6 # 验证码字符长度
|
||
CAPTCHA_EXPIRE=300 # 验证码有效期（单位：秒，300=5分钟）
|
||
|
||
# ============================================================
|
||
# 跨域配置
|
||
# ============================================================
|
||
CORS_ALLOWED_ORIGINS=http://localhost:8001 # 允许跨域访问的前端地址（多个地址用逗号分隔，生产环境请精确配置）
|
||
```
|
||
|
||
:::tip 配置来源
|
||
所有配置变量在 `config/__init__.py` 中通过 `python-dotenv` 从 `.env` 文件加载，然后由各子模块（`app.py`、`database.py`、`redis.py`、`auth.py`、`captcha.py` 等）读取并导出。例如 `DB_DRIVER` 在 `config/database.py` 中读取并构建 SQLAlchemy 连接 URL。
|
||
:::
|
||
|
||
:::danger 安全提醒
|
||
1. 真实 `.env` 文件包含敏感信息（数据库密码、JWT 密钥等），已被 `.gitignore` 忽略，请勿提交到版本控制。
|
||
2. 生产环境务必设置 `FLASK_DEBUG=False` 和 `DB_DEBUG=False`。
|
||
3. 定期轮换 `JWT_SALT` 密钥，提高系统安全性。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
|