djangoadmin/djangoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化更新

Browse Source
This commit is contained in:
gitadmin
2026-09-13 20:29:19 +08:00
parent d7a081e8b7
commit 74f41f651f
65 changed files with 1061 additions and 1321 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Flask_EleVue/zh/volume1/env-vars.md
+41 -30
View File
@@ -17,12 +17,14 @@
| FLASK_HOST | 0.0.0.0 | 应用监听地址。`127.0.0.1` 仅本地访问；容器/生产建议 `0.0.0.0` |
| FLASK_PORT | 8021 | 应用监听端口 |
| FLASK_APP | app.py | 应用启动文件名 |
| FLASK_ENV | production | 运行环境：`development` / `production` / `testing` |
| FLASK_DEBUG | False | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
| FLASK_ENV | development | 运行环境：`development` / `production` / `testing` |
| FLASK_DEBUG | True | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
| FLASK_DEMO | False | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status/batchDelete）返回"演示环境，暂无操作权限" |
| FLASK_SECRET_KEY | （空） | Flask 应用密钥，用于 Session 加密和 CSRF 保护，**必填**且至少 16 字符 |
| FLASK_FILE_URL | http://file.flask.elevue | 文件访问域名，用于拼接上传文件的访问 URL。`BaseService._enrich_file_urls()` 会自动为文件字段补此前缀 |
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,.gif,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号）。`upload_size_limit_middleware` 按 `Content-Length` 提前拦截超大请求 |
| FLASK_USE_RELOADER | False | 是否禁用自动重启。仅在 `FLASK_DEBUG=True` 时生效 |
| FLASK_SECRET_KEY | `<必填>` | Flask 应用密钥，用于 Session 加密和 CSRF 保护，**必填**且至少 16 字符 |
| FLASK_UPLOAD_DIR | ./uploads | 文件上传存储目录 |
| FLASK_FILE_URL | http://file.flask.elevue | 文件访问域名，用于拼接上传文件的访问 URL |
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,.gif,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号） |
| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |
:::tip 安全提示
@@ -40,7 +42,11 @@
| DB_USERNAME | root | 数据库账号（`sqlite` 时忽略） |
| DB_PASSWORD | CHANGE_ME_DB_PASSWORD | 数据库密码，**必填**（`sqlite` 除外） |
| DB_PREFIX | flask_ | 数据表前缀，所有业务表名自动添加此前缀。模型中通过 `DB_PREFIX + "position"` 拼接表名 |
| DB_DEBUG | False | 是否开启 SQL 调试日志（对应 SQLAlchemy `echo` 参数）。生产环境务必设为 `False` |
| 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 驱动包。
@@ -58,17 +64,32 @@
| REDIS_DECODE_RESPONSES | True | 是否自动解码响应（bytes → str） |
:::tip 温馨提示
Redis 用于存储验证码、JWT 令牌黑名单和登录限流数据，是项目正常运行的必需服务。
Redis 用于存储验证码、JWT 令牌黑名单和登录锁定数据，是项目正常运行的必需服务。
:::
## JWT 令牌配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| JWT_SALT | （空） | JWT 签名密钥，**必填**。至少 16 字符强随机值，留空应用会拒绝启动 |
| JWT_EXPIRE_MINUTES | 20 | 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` 是安全关键配置，必须设置。推荐使用以下命令生成：
@@ -101,8 +122,7 @@ python -c "import secrets; print(secrets.token_urlsafe(48))"
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| CORS_ALLOWED_ORIGINS | http://localhost:8001 | CORS 允许的源，多个用逗号分隔 |
| TRUSTED_PROXY_COUNT | 0 | 可信代理层数。`0` = 不信任 X-Forwarded-For；部署在 Nginx 等反代后设为 `>=1` |
| TRUSTED_PROXY_IPS | （空） | 可信代理 IP 白名单，逗号分隔 |
| PROXY_NUM | 0 | 可信代理层数。`0` = 不信任 X-Forwarded-For；部署在 Nginx 等反代后设为 `1` |
:::tip 温馨提示
本地开发时，`CORS_ALLOWED_ORIGINS` 需包含前端开发服务器地址（默认 `http://localhost:8001`）。如果有多个前端地址，用逗号分隔：
@@ -130,31 +150,22 @@ CORS_ALLOWED_ORIGINS=http://localhost:8001,http://192.168.1.100:8001
邮件功能为预留扩展功能，暂未实现。
:::
## 短信配置
## 短信配置（阿里云）
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| SMS_URL | （空） | 短信服务 API 地址 |
| SMS_API_KEY | （空） | 短信服务 API 密钥 |
| SMS_SIGN | （空） | 短信签名 |
| SMS_TEMPLATE_ID | （空） | 短信模板 ID |
| 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。
:::
## 请求限流配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| RATE_LIMIT_ENABLED | False | 是否启用请求限流。在 `.env.example` 中默认被注释，需手动取消注释并设为 `True` |
| RATE_LIMIT_LIMIT | 100 | 窗口期内最大请求数 |
| RATE_LIMIT_WINDOW_SECONDS | 60 | 限流窗口时间（秒） |
| RATE_LIMIT_KEY_PREFIX | rl: | Redis 限流键前缀 |
:::tip 温馨提示
请求限流功能默认关闭。启用后由 `src/middleware/rate_limit.py` 基于 Redis 滑动窗口计数器实现，按客户端 IP 维度统计。超出限制后直接返回 `{"code": 1, "msg": "请求过于频繁"}` 响应，不进入后续中间件链（避免 DoS 攻击时日志表与 DB 连接不降反增）。Redis 不可用时降级放行（fail-open）。生产环境建议启用此功能以防止 API 滥用。
:::
## 环境变量配置示例
@@ -228,4 +239,4 @@ CORS_ALLOWED_ORIGINS=http://localhost:8001 # 允许跨域访问的前端地址
## 总结
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信和限流等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。