276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# 环境变量速查表
|
||
|
||
本章节汇总了项目 `.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` 文件示例：
|
||
|
||
```bash
|
||
# ============================================================
|
||
# 应用配置
|
||
# ============================================================
|
||
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()` 的第二个参数
|
||
|
||
```python
|
||
# 示例：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 | `"操作失败"` | 统一的失败响应消息 |
|
||
|
||
### 使用方式
|
||
|
||
```python
|
||
# 在 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 的连接信息即可快速启动项目。
|