djangoadmin-wiki/DjangoAdmin_Flask_AntdVue/zh/volume1/env-vars.md

环境变量速查表

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

:::tip 温馨提示

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

基础配置

变量名	默认值	说明
FLASK_NAME	DjangoAdmin Flask+EleVue旗舰版	应用名称，用于界面显示和系统标识
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.elevue	文件访问域名，用于拼接上传文件的访问 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.elevue	数据库名称。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 是安全关键配置，必须设置。推荐使用以下命令生成：

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）。如果有多个前端地址，用逗号分隔：

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 模板修改）：

# ============================================================
# 基础服务配置
# ============================================================
FLASK_NAME=DjangoAdmin Flask+EleVue旗舰版   # 应用名称
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.elevue    # 文件服务地址（用于访问上传的文件）

# ============================================================
# 数据库配置
# ============================================================
DB_DRIVER=mysql                            # 数据库类型（mysql / postgresql / mssql / sqlite / oracle）
DB_HOST=127.0.0.1                          # 数据库主机地址
DB_PORT=3306                               # 数据库端口（MySQL 默认 3306）
DB_DATABASE=djangoadmin.flask.elevue       # 数据库名称
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 为模板，仅修改必需项，其余保持默认值即可快速启动项目。