djangoadmin/djangoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40ebd017706c9c8b65b2640944953ebeec4c40a9
djangoadmin-wiki/DjangoAdmin_Django_NaiveVue/zh/volume1/env-vars.md
T
gitadmin d7a081e8b7 优化更新
2026-09-13 18:12:07 +08:00

11 KiB
Raw Blame History

环境变量速查表

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

:::tip 温馨提示

  1. .env 文件包含项目的敏感配置信息，已被 .gitignore 忽略，不会提交到版本控制。
  2. 环境变量通过 config/env.py 加载，使用 python-dotenv 库从 .env 文件读取。
  3. .env 中的值会覆盖 config/env.py 中的默认值。 :::

应用基础配置

变量名 默认值 说明
DJANGO_NAME Django+NaiveUI旗舰版 应用名称，用于界面显示和系统标识
DJANGO_VERSION v3.0.0 应用版本号
DJANGO_DEBUG True 是否开启调试模式。True 时输出详细错误堆栈，生产环境务必设为 False
DJANGO_DEMO True 是否开启演示模式。True 时所有写操作（add/update/delete/status）返回"演示环境，暂无操作权限"。开发调试时请设为 False
DJANGO_UPLOAD_DIR 项目根目录/public/uploads 文件上传存储路径
DJANGO_FILE_URL http://file.django.naivevue 文件访问域名，用于拼接上传文件的访问 URL

:::tip 安全提示

  1. 生产环境务必设置 DJANGO_DEBUG=False，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
  2. DJANGO_DEMO 代码默认值为 True（演示模式），开发调试时需设为 False 才能执行写操作。 :::

数据库配置

变量名 默认值 说明
DATABASE_ENGINE django.db.backends.mysql 数据库引擎。支持：mysql、postgresql、sqlite3、oracle、mssql
DATABASE_NAME djangoadmin.django.naivevue 数据库名称。SQLite 时作为数据库文件路径
DATABASE_HOST 127.0.0.1 数据库地址
DATABASE_PORT 3306 数据库端口
DATABASE_USER root 数据库账号
DATABASE_PASSWORD root 数据库密码
DATABASE_PREFIX django_ 数据表前缀，便于识别和多应用共存

:::tip 多数据库支持 DATABASE_ENGINE 支持 Django 原生数据库引擎和第三方引擎（mssql-django）。切换引擎后需安装对应的 Python 驱动包。 :::

Redis 缓存配置

变量名 默认值 说明
REDIS_HOST 127.0.0.1 Redis 服务地址
REDIS_PORT 6379 Redis 服务端口
REDIS_PASSWORD 123456 Redis 密码
REDIS_DB 0 Redis 库索引（0-15）

:::tip 温馨提示 Redis 用于存储验证码、JWT 令牌黑名单等功能，是项目正常运行的必需服务。缓存 Key 前缀为 djangoadmin。 :::

IP 地理位置配置

变量名 默认值 说明
IP_LOCATION_SOURCE api IP 地理位置信息来源。local - 本地数据库，api - 在线 API
IP_DATABASE_PATH data/qqwry.ipdb 本地 IP 数据库文件路径。支持格式：.ipdb、.dat、.mmdb
IP_API_TIMEOUT 5 IP 查询 API 超时时间（秒）
IP_CACHE_ENABLED True 是否启用 IP 地理位置缓存
IP_CACHE_TIMEOUT 86400 IP 缓存时间（秒），默认 1 天

短信服务配置

变量名 默认值 说明
SMS_PROVIDER mock 短信服务商：mock（模拟）、aliyun（阿里云）、tencent（腾讯云）、huawei（华为云）

阿里云短信

变量名 默认值 说明
ALIYUN_ACCESS_KEY_ID （空） 阿里云 AccessKey ID
ALIYUN_ACCESS_SECRET （空） 阿里云 AccessKey Secret
ALIYUN_SMS_SIGN （空） 阿里云短信签名
ALIYUN_REGION cn-hangzhou 阿里云短信区域
ALIYUN_SMS_TEMPLATE_CODE （空） 阿里云短信模板 ID

腾讯云短信

变量名 默认值 说明
TENCENT_SECRET_ID （空） 腾讯云 SecretId
TENCENT_SECRET_KEY （空） 腾讯云 SecretKey
TENCENT_SMS_APP_ID （空） 腾讯云短信应用 ID
TENCENT_SMS_SIGN （空） 腾讯云短信签名
TENCENT_SMS_TEMPLATE_ID （空） 腾讯云短信模板 ID
TENCENT_REGION ap-guangzhou 腾讯云区域

华为云短信

变量名 默认值 说明
HUAWEI_ACCESS_KEY （空） 华为云 AccessKey
HUAWEI_SECRET_KEY （空） 华为云 SecretKey
HUAWEI_SMS_APP_KEY （空） 华为云短信应用 Key
HUAWEI_SMS_SIGN （空） 华为云短信签名
HUAWEI_SMS_CHANNEL default 华为云短信通道
HUAWEI_REGION cn-north-4 华为云区域

:::tip 温馨提示 短信功能为预留扩展配置，默认使用 mock 模式（不实际发送短信）。 :::

邮件服务配置

变量名 默认值 说明
EMAIL_PROVIDER console 邮件服务商：console（控制台输出）、smtp（真实发送）
EMAIL_HOST （空） SMTP 服务器地址
EMAIL_PORT 587 SMTP 服务端口
EMAIL_USE_TLS True 是否启用 TLS 加密
EMAIL_HOST_USER （空） 发件邮箱账号
EMAIL_HOST_PASSWORD （空） 邮箱授权码（不是登录密码）
DEFAULT_FROM_EMAIL （空） 默认发件人邮箱

:::tip 温馨提示 邮件功能为预留扩展配置，默认使用 console 模式（输出到控制台）。常见邮箱 SMTP 配置：

  • QQ 邮箱：smtp.qq.com，端口 587（TLS）或 465（SSL）
  • 163 邮箱：smtp.163.com，端口 465（SSL）
  • Gmail：smtp.gmail.com，端口 587（TLS） :::

定时任务配置

变量名 默认值 说明
JOB_THREAD_POOL_SIZE 10 定时任务线程池大小（同时处理的异步任务数量）
JOB_EXECUTE_TIMEOUT 30 任务执行超时时间（秒）
JOB_LOG_ENABLED True 是否记录任务执行日志
JOB_RETRY_TIMES 3 任务执行失败重试次数
JOB_RETRY_INTERVAL 60 任务执行失败重试间隔（秒）

环境变量配置示例

以下是一个开发环境的 .env 文件示例：

# ============================================================
# 应用配置
# ============================================================
DJANGO_NAME=Django+NaiveUI旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False                    # 代码默认True（演示模式），开发环境设为False以启用写操作
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_NaiveVue\public\uploads"
DJANGO_FILE_URL='http://file.django.naivevue'

# ============================================================
# 数据库配置
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.naivevue'
DATABASE_HOST="127.0.0.1"
DATABASE_PORT=3306
DATABASE_USER="root"
DATABASE_PASSWORD="your_password"        # 请修改为实际密码
DATABASE_PREFIX="django_"

# ============================================================
# Redis 配置
# ============================================================
REDIS_HOST="127.0.0.1"
REDIS_PORT=6379
REDIS_PASSWORD="your_redis_password"     # 请修改为实际密码
REDIS_DB=0

# ============================================================
# 站点域名配置
# ============================================================
SITE_DOMAIN="http://localhost:8000"

:::danger 安全提醒

  1. 真实 .env 文件包含敏感信息（数据库密码等），已被 .gitignore 忽略，请勿提交到版本控制。
  2. 生产环境务必设置 DJANGO_DEBUG=False。
  3. DJANGO_DEMO 代码默认值为 True（演示模式），开发调试时需设为 False 才能执行写操作。 :::

.env 加载机制

项目通过 extends/extends_dotenv.py 模块实现 .env 文件的自动加载。该模块在 Django 启动时最先执行，将 .env 中的键值对注入到系统环境变量中，后续 config/env.py 通过 os.getenv() 读取。

加载流程

Django 启动
    │
    ▼
application/settings.py
    │ from extends.extends_dotenv import env_path   ← 触发加载
    │ from config.env import *                      ← 读取环境变量
    ▼
extends/extends_dotenv.py
    │ 1. 定位项目根目录
    │ 2. 拼接 .env 文件路径
    │ 3. 调用 load_dotenv(env_path) 注入环境变量
    ▼
config/env.py
    │ os.getenv('DJANGO_NAME', 'Django+NaiveUI旗舰版')
    │ os.getenv('DATABASE_HOST', '127.0.0.1')
    │ ...（所有配置项）
    ▼
各模块通过 from config.env import * 使用配置

加载优先级

配置值的优先级从高到低为：

  1. 系统环境变量：操作系统级别设置的环境变量
  2. .env 文件：项目根目录下的 .env 文件
  3. 代码默认值：config/env.py 中 os.getenv() 的第二个参数
# 示例：DJANGO_DEBUG 的优先级
# 1. 系统环境变量 DJANGO_DEBUG（最高优先级）
# 2. .env 文件中的 DJANGO_DEBUG=True
# 3. 代码默认值 'True'（最低优先级）
DJANGO_DEBUG = (os.getenv('DJANGO_DEBUG', 'True') == 'True')

:::tip 温馨提示 extends/extends_dotenv.py 使用 python-dotenv 库的 load_dotenv() 函数，默认不会覆盖已存在的系统环境变量。如果需要强制覆盖，可使用 load_dotenv(env_path, override=True)。 :::

应用常量配置

除了 .env 环境变量外，项目还在 constant/constants.py 中定义了一些全局常量，用于控制应用的默认行为。

常量列表

常量名 类型 默认值 说明
PAGE_SIZE int 10 分页查询默认每页记录数
DEFAULT_PASSWORD str "123456" 新建用户或重置密码时的默认密码
MESSAGE_OK str "操作成功" 统一的成功响应消息
MESSAGE_FAIL str "操作失败" 统一的失败响应消息

使用方式

# 在 services.py 中使用分页常量
from constant.constants import PAGE_SIZE

def get_example_page(request):
    page_size = int(request.GET.get('pageSize', PAGE_SIZE))
    ...

# 在 R.py 中使用消息常量
from constant.constants import MESSAGE_OK, MESSAGE_FAIL

def ok(data=None, msg=MESSAGE_OK, code=0, **kwargs):
    ...

与环境变量的区别

维度 环境变量（.env） 应用常量（constants.py）
配置方式 .env 文件或系统环境变量 直接修改 Python 源码
是否需要重启 修改 .env 后需重启服务 修改后需重启服务
适用场景 数据库连接、密钥、服务地址等部署相关配置 分页大小、默认密码、消息文本等业务相关常量
安全性 .env 已被 .gitignore 忽略 代码内，提交到版本控制

:::tip 温馨提示 如果需要修改常量值，直接编辑 constant/constants.py 文件即可。修改后需重启 Django 服务才能生效。 :::

总结

本章节汇总了项目所有可配置的环境变量，涵盖应用基础配置、数据库、Redis、IP 地理位置、短信、邮件和定时任务等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。首次使用时仅修改数据库和 Redis 的连接信息即可快速启动项目。

Reference in New Issue View Git Blame Copy Permalink