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 21:53:16 +08:00
parent 8548fe9ea1
commit 3f8626fb10
84 changed files with 2058 additions and 2594 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Flask_AntdVue/zh/volume1/backend.md
+18 -12
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__)"
@@ -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_AntdVue/zh/volume1/database.md
+9 -9
View File
@@ -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`。
:::
## 数据库备份与恢复
DjangoAdmin_Flask_AntdVue/zh/volume1/docker.md
+1 -1
View File
@@ -88,7 +88,7 @@ python -c "import secrets; print(secrets.token_urlsafe(48))"
## Docker Compose 配置
项目的 `docker-compose.yml` 文件定义了后端服务的容器编排：
项目的 `docker/docker-compose.yml` 文件定义了后端服务的容器编排：
```yaml
# +======================================================================
DjangoAdmin_Flask_AntdVue/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` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
DjangoAdmin_Flask_AntdVue/zh/volume1/environment.md
+3 -3
View File
@@ -1,6 +1,6 @@
# 环境准备
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Flask` 后端、`Vue3` + `ElementPlus` 前端的分离架构，本地开发需准备以下软件。
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Flask` 后端、`Vue3` + `AntDesign Vue` 前端的分离架构，本地开发需准备以下软件。
安装软件：`Python(3.10+)`、`MySQL(8.0+)`、`Redis(3.2+)`、`Node.js(22+)`、`pnpm` 等。
@@ -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` + `AntDesign Vue` 构建。
+ 下载 Node.js
DjangoAdmin_Flask_AntdVue/zh/volume1/frontend.md
+2 -2
View File
@@ -1,6 +1,6 @@
# 前端启动
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `AntDesign Vue` + `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 构建配置