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 23:01:19 +08:00
parent 0c67b3e8b5
commit 23bd737b82
88 changed files with 2214 additions and 2503 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Flask_NaiveVue/zh/volume1/backend.md
+22 -16
View File
@@ -37,16 +37,16 @@ cd djangoadmin
│ ├── core/ # 核心模块（数据库、缓存、认证、响应等）
│ ├── routes/ # 路由层（HTTP 接口定义）
│ ├── modules/ # 业务模块（模型、仓库、服务）
│ ├── middleware/ # 中间件（CORS、限流、日志、操作记录等）
│ ├── common/ # 公共模块（基类、常量、工具函数等）
│ └── utils/ # 工具函数
│ ├── middleware/ # 中间件（认证、事务、日志、操作记录等）
│ └── common/ # 公共模块（基类、常量、工具函数等）
├── ui/ # 前端源码（独立仓库或子目录）
├── config/ # 配置文件（base / database / redis / auth）
├── docker/ # Docker 部署配置（Dockerfile / docker-compose.yml）
├── scripts/ # 脚本工具（数据库初始化、数据迁移等）
├── migrations/ # Flask-Migrate 数据库迁移文件
├── tests/ # 测试代码
├── .env.example # 环境变量示例文件
├── requirements.txt # Python 依赖清单
├── docker-compose.yml # Docker 编排文件
└── Makefile # 常用命令集合
```
@@ -72,7 +72,7 @@ pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```bash
# 检查 Flask 是否安装成功
python -c "import flask; print(flask.__version__)"
3.1.1
3.1.3
# 检查 SQLAlchemy 是否安装成功
python -c "import sqlalchemy; print(sqlalchemy.__version__)"
@@ -101,7 +101,7 @@ copy .env.example .env # Windows CMD
# ============================================================
# 基础配置
# ============================================================
FLASK_NAME=DjangoAdmin Flask+EleVue旗舰版
FLASK_NAME=DjangoAdmin Flask+NaiveUI版
FLASK_VERSION=v3.0.0
FLASK_HOST=0.0.0.0
FLASK_PORT=8021
@@ -114,7 +114,7 @@ FLASK_DEBUG=True
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.flask.elevue
DB_DATABASE=djangoadmin.flask.naivevue
DB_USERNAME=root
DB_PASSWORD=your_mysql_password # 修改为真实密码
DB_PREFIX=flask_
@@ -155,10 +155,10 @@ python -c "import secrets; print(secrets.token_urlsafe(48))"
```bash
# 1. 登录 MySQL，创建数据库
mysql -uroot -p
CREATE DATABASE `djangoadmin.flask.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.flask.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
# 2. 导入数据库脚本（脚本位于 document/mysql/ 目录下）
mysql -uroot -p djangoadmin.flask.elevue < document/mysql/djangoadmin.flask.elevue.sql
mysql -uroot -p djangoadmin.flask.naivevue < document/mysql/djangoadmin.flask.naivevue.sql
```
:::tip 温馨提示
@@ -265,14 +265,20 @@ curl http://127.0.0.1:8021/api/v1/captcha
| 命令 | 对应命令 | 说明 |
|:----|:----|:----|
| `make install` | `pip install -r requirements.txt` | 安装运行时 + 开发依赖 |
| `make install` | `pip install -r requirements.txt` | 安装生产依赖 |
| `make install-dev` | `pip install -r requirements-dev.txt` | 安装开发依赖（含测试/规范工具） |
| `make dev` | `python app.py` | 启动开发服务 |
| `make test` | `pytest` | 运行全部测试（默认跳过 integration） |
| `make test-contract` | `pytest tests/contract` | 运行契约快照测试 |
| `make test-unit` | `pytest tests/unit` | 运行单元测试 |
| `make test-integration` | `pytest tests/integration` | 运行集成测试（需真实 MySQL/Redis） |
| `make db-init` | `python scripts/setup_db.py` | 初始化数据库 |
| `make seed-dict` | `python scripts/seed_dict.py` | 初始化业务字典数据 |
| `make lint` | `flake8 + black --check + isort --check-only` | 静态检查 |
| `make format` | `black + isort` | 自动格式化 |
| `make type-check` | `mypy src` | 类型检查 |
| `make test` | `pytest` | 运行全部测试 |
| `make test-cov` | `pytest --cov=src` | 带覆盖率运行测试 |
| `make db-migrate` | `flask db migrate` | 生成迁移脚本 |
| `make db-upgrade` | `flask db upgrade` | 应用迁移到最新 |
| `make db-downgrade` | `flask db downgrade` | 回滚一次迁移 |
| `make docker-up` | `cd docker && docker-compose up -d` | 启动 Docker 服务 |
| `make docker-down` | `cd docker && docker-compose down` | 停止 Docker 服务 |
| `make clean` | 清理 `__pycache__` / `.pyc` / `.pytest_cache` | 清理缓存与临时文件 |
## 常见问题
DjangoAdmin_Flask_NaiveVue/zh/volume1/database.md
+40 -40
View File
@@ -7,15 +7,15 @@
```
document/
├── mysql/ # MySQL 脚本
│ └── djangoadmin.flask.elevue.sql
│ └── djangoadmin.flask.naivevue.sql
├── postgresql/ # PostgreSQL 脚本
│ └── djangoadmin.flask.elevue.sql
│ └── djangoadmin.flask.naivevue.sql
├── sqlserver/ # SQL Server 脚本
│ └── djangoadmin.flask.elevue.sql
│ └── djangoadmin.flask.naivevue.sql
├── sqlite/ # SQLite 脚本
│ └── djangoadmin.flask.elevue.sql
│ └── djangoadmin.flask.naivevue.sql
└── oracle/ # Oracle 脚本
└── djangoadmin.flask.elevue.sql
└── djangoadmin.flask.naivevue.sql
```
:::tip 温馨提示
@@ -36,7 +36,7 @@ document/
**MySQL**：
```sql
CREATE DATABASE `djangoadmin.flask.elevue`
CREATE DATABASE `djangoadmin.flask.naivevue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
```
@@ -44,7 +44,7 @@ CREATE DATABASE `djangoadmin.flask.elevue`
**PostgreSQL**：
```sql
CREATE DATABASE "djangoadmin.flask.elevue"
CREATE DATABASE "djangoadmin.flask.naivevue"
WITH ENCODING 'UTF8'
LC_COLLATE = 'zh_CN.UTF-8'
LC_CTYPE = 'zh_CN.UTF-8'
@@ -54,7 +54,7 @@ CREATE DATABASE "djangoadmin.flask.elevue"
**SQL Server**：
```sql
CREATE DATABASE [djangoadmin.flask.elevue]
CREATE DATABASE [djangoadmin.flask.naivevue]
COLLATE Chinese_PRC_CI_AS;
```
@@ -87,27 +87,27 @@ GRANT CONNECT, RESOURCE, CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE T
```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.flask.elevue < document/mysql/djangoadmin.flask.elevue.sql
mysql -uroot -p djangoadmin.flask.naivevue < document/mysql/djangoadmin.flask.naivevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/mysql/djangoadmin.flask.elevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/mysql/djangoadmin.flask.naivevue.sql
```
**PostgreSQL**：
```bash
# 使用 psql 命令行导入
psql -U postgres -d djangoadmin.flask.elevue -f document/postgresql/djangoadmin.flask.elevue.sql
psql -U postgres -d djangoadmin.flask.naivevue -f document/postgresql/djangoadmin.flask.naivevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/postgresql/djangoadmin.flask.elevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/postgresql/djangoadmin.flask.naivevue.sql
```
**SQL Server**：
```bash
# 使用 sqlcmd 命令行导入
sqlcmd -S localhost -U sa -P your_password -d djangoadmin.flask.elevue -i document/sqlserver/djangoadmin.flask.elevue.sql
sqlcmd -S localhost -U sa -P your_password -d djangoadmin.flask.naivevue -i document/sqlserver/djangoadmin.flask.naivevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/sqlserver/djangoadmin.flask.elevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/sqlserver/djangoadmin.flask.naivevue.sql
# 或使用 SSMS（SQL Server Management Studio）：打开 SQL 文件 → 执行
```
@@ -115,18 +115,18 @@ sqlcmd -S localhost -U sa -P your_password -d djangoadmin.flask.elevue -i docume
```bash
# 使用 sqlite3 命令行导入
sqlite3 ./data/app.db < document/sqlite/djangoadmin.flask.elevue.sql
sqlite3 ./data/app.db < document/sqlite/djangoadmin.flask.naivevue.sql
# 或使用 Navicat 等工具：打开数据库文件 → 运行 SQL 文件 → 选择 document/sqlite/djangoadmin.flask.elevue.sql
# 或使用 Navicat 等工具：打开数据库文件 → 运行 SQL 文件 → 选择 document/sqlite/djangoadmin.flask.naivevue.sql
```
**Oracle**：
```bash
# 使用 sqlplus 命令行导入
sqlplus djangoadmin/your_password@127.0.0.1:1521/XE @document/oracle/djangoadmin.flask.elevue.sql
sqlplus djangoadmin/your_password@127.0.0.1:1521/XE @document/oracle/djangoadmin.flask.naivevue.sql
# 或使用 Navicat 等工具：打开连接 → 运行 SQL 文件 → 选择 document/oracle/djangoadmin.flask.elevue.sql
# 或使用 Navicat 等工具：打开连接 → 运行 SQL 文件 → 选择 document/oracle/djangoadmin.flask.naivevue.sql
```
:::tip 温馨提示
@@ -150,7 +150,7 @@ Oracle 用户需要有 CREATE TABLE、CREATE SEQUENCE、CREATE TRIGGER 权限。
DB_DRIVER=mysql # 数据库驱动类型
DB_HOST=127.0.0.1 # 数据库主机地址
DB_PORT=3306 # 数据库端口（MySQL 默认 3306）
DB_DATABASE=djangoadmin.flask.elevue # 数据库名称
DB_DATABASE=djangoadmin.flask.naivevue # 数据库名称
DB_USERNAME=root # 数据库用户名
DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
DB_PREFIX=flask_ # 数据表前缀
@@ -162,7 +162,7 @@ DB_PREFIX=flask_ # 数据表前缀
# DB_DRIVER=postgresql # 数据库驱动类型
# DB_HOST=127.0.0.1 # 数据库主机地址
# DB_PORT=5432 # 数据库端口（PostgreSQL 默认 5432）
# DB_DATABASE=djangoadmin.flask.elevue # 数据库名称
# DB_DATABASE=djangoadmin.flask.naivevue # 数据库名称
# DB_USERNAME=postgres # 数据库用户名
# DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
# DB_PREFIX=flask_ # 数据表前缀
@@ -174,7 +174,7 @@ DB_PREFIX=flask_ # 数据表前缀
# DB_DRIVER=mssql # 数据库驱动类型
# DB_HOST=127.0.0.1 # 数据库主机地址
# DB_PORT=1433 # 数据库端口（SQL Server 默认 1433）
# DB_DATABASE=djangoadmin.flask.elevue # 数据库名称
# DB_DATABASE=djangoadmin.flask.naivevue # 数据库名称
# DB_USERNAME=sa # 数据库用户名
# DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
# DB_PREFIX=flask_ # 数据表前缀
@@ -263,11 +263,11 @@ $ python scripts/setup_db.py --drop-first
[INFO] ============================================================
[INFO] 检测数据库驱动: mysql
[INFO] 连接 MySQL 服务器: 127.0.0.1:3306
[INFO] 数据库配置: root@127.0.0.1:3306/djangoadmin.flask.elevue
[INFO] 数据库配置: root@127.0.0.1:3306/djangoadmin.flask.naivevue
[INFO] 数据表前缀: flask_
[INFO] 删除已有数据库: djangoadmin.flask.elevue
[INFO] 创建数据库: djangoadmin.flask.elevue
[INFO] 查找数据库脚本: document\mysql\djangoadmin.flask.elevue.sql
[INFO] 删除已有数据库: djangoadmin.flask.naivevue
[INFO] 创建数据库: djangoadmin.flask.naivevue
[INFO] 查找数据库脚本: document\mysql\djangoadmin.flask.naivevue.sql
[INFO] 导入 SQL 脚本...
[INFO] SQL 脚本导入完成: 784510 条语句
[INFO] 创建数据表...
@@ -294,13 +294,13 @@ $ python scripts/setup_db.py --drop-first
| 数据库 | DB_DRIVER 值 | 默认端口 | 依赖包 | 脚本目录 |
|:----|:----|:----|:----|:----|
| MySQL | `mysql` | 3306 | PyMySQL | `document/mysql/` |
| PostgreSQL | `postgresql` | 5432 | psycopg[binary] | `document/postgresql/` |
| PostgreSQL | `postgresql` | 5432 | psycopg2-binary | `document/postgresql/` |
| SQL Server | `mssql` | 1433 | pymssql | `document/sqlserver/` |
| SQLite | `sqlite` | - | 内置 | `document/sqlite/` |
| Oracle | `oracle` | 1521 | oracledb | `document/oracle/` |
:::tip 温馨提示
切换数据库驱动后，需要安装对应的驱动包（如 `pip install psycopg[binary]`），然后按照上述步骤重新初始化数据库。
切换数据库驱动后，需要安装对应的驱动包（如 `pip install psycopg2-binary`），然后按照上述步骤重新初始化数据库。
:::
## 种子数据
@@ -380,13 +380,13 @@ flask db stamp head
| 命令 | 对应命令 | 说明 |
|:----|:----|:----|
| `make db-init` | `python scripts/setup_db.py` | 初始化数据库（建库 + 建表 + 种子数据 + flask db stamp） |
| `make seed-dict` | `python scripts/seed_dict.py` | 初始化业务字典数据（幂等，按 code 判重） |
| `make migrate-revision` | `flask db migrate` | 生成增量迁移脚本 |
| `make migrate-upgrade` | `flask db upgrade` | 应用所有待执行的迁移 |
| `make migrate-stamp` | `flask db stamp head` | 标记当前数据库为最新版本 |
| `make db-migrate ARGS="..."` | `python scripts/migrate_db.py ...` | 跨库数据迁移 |
| `make db-migrate-dry-run ARGS="..."` | `python scripts/migrate_db.py ... --dry-run` | 跨库迁移干跑（只核对计划，不写入目标库） |
| `make db-migrate` | `flask db migrate` | 生成增量迁移脚本 |
| `make db-upgrade` | `flask db upgrade` | 应用迁移到最新 |
| `make db-downgrade` | `flask db downgrade` | 回滚一次迁移 |
:::tip 数据库初始化
数据库初始化使用 `python scripts/setup_db.py`（非 Makefile 命令），详见上方「方式二：脚本初始化」章节。跨库数据迁移使用 `python scripts/migrate_db.py`。
:::
## 数据库备份与恢复
@@ -394,30 +394,30 @@ flask db stamp head
```bash
# 备份数据库
mysqldump -uroot -p djangoadmin.flask.elevue > backup.sql
mysqldump -uroot -p djangoadmin.flask.naivevue > backup.sql
# 恢复数据库
mysql -uroot -p djangoadmin.flask.elevue < backup.sql
mysql -uroot -p djangoadmin.flask.naivevue < backup.sql
```
+ PostgreSQL 备份
```bash
# 备份数据库
pg_dump -U postgres djangoadmin.flask.elevue > backup.sql
pg_dump -U postgres djangoadmin.flask.naivevue > backup.sql
# 恢复数据库
psql -U postgres djangoadmin.flask.elevue < backup.sql
psql -U postgres djangoadmin.flask.naivevue < backup.sql
```
+ SQL Server 备份
```bash
# 备份数据库
sqlcmd -S localhost -U sa -P your_password -Q "BACKUP DATABASE [djangoadmin.flask.elevue] TO DISK = 'backup.bak'"
sqlcmd -S localhost -U sa -P your_password -Q "BACKUP DATABASE [djangoadmin.flask.naivevue] TO DISK = 'backup.bak'"
# 恢复数据库
sqlcmd -S localhost -U sa -P your_password -Q "RESTORE DATABASE [djangoadmin.flask.elevue] FROM DISK = 'backup.bak'"
sqlcmd -S localhost -U sa -P your_password -Q "RESTORE DATABASE [djangoadmin.flask.naivevue] FROM DISK = 'backup.bak'"
# 或使用 Navicat 等工具进行备份恢复
# 或使用 SSMS（SQL Server Management Studio）：右键数据库 → 任务 → 备份 / 还原
DjangoAdmin_Flask_NaiveVue/zh/volume1/docker.md
+13 -13
View File
@@ -57,7 +57,7 @@ cp .env.example .env
# ============================================================
DB_HOST=127.0.0.1 # 数据库主机地址（本地容器）
DB_PORT=3306 # 数据库端口（MySQL 默认 3306）
DB_DATABASE=djangoadmin.flask.elevue # 数据库名称
DB_DATABASE=djangoadmin.flask.naivevue # 数据库名称
DB_USERNAME=root # 数据库用户名
DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
DB_PREFIX=flask_ # 数据表前缀
@@ -88,12 +88,12 @@ python -c "import secrets; print(secrets.token_urlsafe(48))"
## Docker Compose 配置
项目的 `docker-compose.yml` 文件定义了后端服务的容器编排：
项目的 `docker/docker-compose.yml` 文件定义了后端服务的容器编排：
```yaml
# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: Flask+EleVue 应用服务容器编排
# | 说明: Flask+NaiveUI 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
@@ -103,11 +103,11 @@ services:
# ------------------------------------------------------------
# 后端服务
# ------------------------------------------------------------
flask_elevue:
flask_naivevue:
# 构建镜像名称
image: flask_elevue
image: flask_naivevue
# 容器运行时名称
container_name: flask_elevue
container_name: flask_naivevue
# 镜像构建配置
build:
context: ./ # 构建上下文路径（项目根目录）
@@ -181,7 +181,7 @@ docker compose up -d
[+] Building 45.2s (12/12) FINISHED
[+] Running 2/2
✔ Network djangoadmin_default Created
✔ Container flask_elevue Started
✔ Container flask_naivevue Started
```
:::tip 访问服务
@@ -215,7 +215,7 @@ docker compose logs -f
docker compose logs --tail 100
# 查看指定服务日志
docker compose logs -f flask_elevue
docker compose logs -f flask_naivevue
```
+ 停止与重启
@@ -245,10 +245,10 @@ docker compose up --build
```bash
# 进入运行中的容器终端
docker compose exec flask_elevue bash
docker compose exec flask_naivevue bash
# 在容器内执行 Python 命令
docker compose exec flask_elevue python -c "print('hello')"
docker compose exec flask_naivevue python -c "print('hello')"
```
## 环境变量注入
@@ -257,10 +257,10 @@ Docker 模式下，环境变量通过 `env_file` 从 `.env` 文件注入到容
```bash
# 使用 --env-file 指定环境变量文件
docker run --env-file .env flask_elevue
docker run --env-file .env flask_naivevue
# 通过 -e 参数覆盖单个变量
docker run -e FLASK_PORT=9090 flask_elevue
docker run -e FLASK_PORT=9090 flask_naivevue
```
:::tip 温馨提示
@@ -315,7 +315,7 @@ ports:
```bash
# 查看容器日志排查原因
docker compose logs flask_elevue
docker compose logs flask_naivevue
```
常见原因：`JWT_SALT` 未配置、数据库连接失败、Redis 连接失败。
DjangoAdmin_Flask_NaiveVue/zh/volume1/env-vars.md
+46 -35
View File
@@ -12,17 +12,19 @@
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| FLASK_NAME | DjangoAdmin Flask+EleVue旗舰版 | 应用名称，用于界面显示和系统标识 |
| 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 | 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.naivevue | 文件访问域名，用于拼接上传文件的访问 URL |
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,.gif,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号） |
| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |
:::tip 安全提示
@@ -36,11 +38,15 @@
| 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_DATABASE | djangoadmin.flask.naivevue | 数据库名称。`sqlite` 时作为数据库文件完整路径 |
| 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 滥用。
:::
## 环境变量配置示例
@@ -164,7 +175,7 @@ CORS_ALLOWED_ORIGINS=http://localhost:8001,http://192.168.1.100:8001
# ============================================================
# 基础服务配置
# ============================================================
FLASK_NAME=DjangoAdmin Flask+EleVue旗舰版 # 应用名称
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 # 服务监听端口
@@ -172,7 +183,7 @@ FLASK_ENV=development # 运行环境（development / testin
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 # 文件服务地址（用于访问上传的文件）
FLASK_FILE_URL=http://file.flask.naivevue # 文件服务地址（用于访问上传的文件）
# ============================================================
# 数据库配置
@@ -180,7 +191,7 @@ 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_DATABASE=djangoadmin.flask.naivevue # 数据库名称
DB_USERNAME=root # 数据库用户名
DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
DB_PREFIX=flask_ # 数据表前缀（用于区分不同应用的同库表）
@@ -228,4 +239,4 @@ CORS_ALLOWED_ORIGINS=http://localhost:8001 # 允许跨域访问的前端地址
## 总结
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信和限流等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
DjangoAdmin_Flask_NaiveVue/zh/volume1/environment.md
+4 -4
View File
@@ -1,6 +1,6 @@
# 环境准备
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Flask` 后端、`Vue3` + `ElementPlus` 前端的分离架构，本地开发需准备以下软件。
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Flask` 后端、`Vue3` + `NaiveUI` 前端的分离架构，本地开发需准备以下软件。
安装软件：`Python(3.10+)`、`MySQL(8.0+)`、`Redis(3.2+)`、`Node.js(22+)`、`pnpm` 等。
@@ -187,7 +187,7 @@ mysql>
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.flask.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.flask.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
-- 查看数据库
SHOW DATABASES;
@@ -199,7 +199,7 @@ SHOW DATABASES;
## 安装 Redis
`Redis` 是必需的缓存服务，用于验证码存储、JWT 令牌黑名单、登录限流等功能。要求 `3.2` 或更高版本。
`Redis` 是必需的缓存服务，用于验证码存储、JWT 令牌黑名单、登录锁定等功能。要求 `3.2` 或更高版本。
+ 下载软件
@@ -265,7 +265,7 @@ OK
## 安装 Node.js
`Node.js` 是前端项目的运行环境，要求 `22` 或更高版本。前端基于 `Vue3` + `ElementPlus` 构建。
`Node.js` 是前端项目的运行环境，要求 `22` 或更高版本。前端基于 `Vue3` + `NaiveUI` 构建。
+ 下载 Node.js
DjangoAdmin_Flask_NaiveVue/zh/volume1/faq.md
+2 -2
View File
@@ -83,7 +83,7 @@ mysql -h127.0.0.1 -P3306 -uroot -p
# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.flask.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON `djangoadmin.flask.naivevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
```
@@ -382,7 +382,7 @@ ls static/fonts/Vera.ttf
# .env 中的上传配置
UPLOAD_ALLOWED_EXTS=.jpg,.jpeg,.png,.gif,.bmp,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z
UPLOAD_MAX_SIZE_MB=10
FLASK_FILE_URL=http://file.flask.elevue
FLASK_FILE_URL=http://file.flask.naivevue
```
:::tip 温馨提示
DjangoAdmin_Flask_NaiveVue/zh/volume1/frontend.md
+2 -2
View File
@@ -1,6 +1,6 @@
# 前端启动
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `NaiveUI` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
:::tip 温馨提示
启动前端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的 `Node.js` 和 `pnpm` 安装，并已启动后端服务（参见 [后端启动](/zh/volume1/backend)）。
@@ -23,7 +23,7 @@ ui/
│ ├── utils/ # 工具函数
│ ├── views/ # 页面视图
│ ├── App.vue # 根组件
│ └── main.js # 入口文件
│ └── main.ts # 入口文件
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── vite.config.ts # Vite 构建配置