签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,341 @@
+# 后端启动
+
+本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 `Python`  + `FastAPI` 框架，采用分层架构设计（API 层 → Service 层 → Repository 层 → Model 层）。
+
+:::tip 温馨提示
+启动后端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的所有软件安装。
+:::
+
+## 获取源码
+
+前往 [官方网站](https://www.djangoadmin.cn) 购买授权后，按以下步骤获取源码：
+
+```
+1. 登录官方网站，进入「个人中心」→「我的订单」页面。
+2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
+3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
+4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。
+```
+
+```bash
+# 进入项目根目录（以实际解压路径为准）
+cd djangoadmin
+```
+
+:::tip 温馨提示
+1. 源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
+2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
+3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
+4. 如需使用 Git 管理代码，可在解压后自行初始化仓库：`git init && git add . && git commit -m "init"`。
+:::
+
+项目目录结构如下：
+
+```
+├── src/               # 后端源码
+│ ├── main.py          # 启动入口
+│ ├── core/            # 核心模块（数据库、缓存、认证、响应等）
+│ ├── api/             # 路由层（HTTP 接口定义）
+│ ├── modules/         # 业务模块（模型、仓库、服务）
+│ ├── middleware/      # 中间件（CORS、限流、日志、操作记录等）
+│ ├── constants/       # 常量与枚举
+│ └── utils/           # 工具函数
+├── ui/                # 前端源码（独立仓库或子目录）
+├── scripts/           # 脚本工具（数据库初始化、数据迁移等）
+├── migrations/        # Alembic 数据库迁移文件
+├── tests/             # 测试代码
+├── .env.example       # 环境变量示例文件
+├── requirements.txt   # Python 依赖清单
+├── docker-compose.yml # Docker 编排文件
+└── Makefile           # 常用命令集合
+```
+
+## 安装依赖
+
+进入项目根目录，使用 `pip` 安装后端依赖包：
+
+```bash
+# 安装运行时依赖
+pip install -r requirements.txt
+```
+
+:::tip 温馨提示
+如果网络较慢，可先配置 pip 镜像源（参见 [环境准备](/zh/volume1/environment)），或使用国内镜像临时安装：
+
+```bash
+pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
+```
+:::
+
+ 验证依赖安装
+
+```bash
+# 检查 FastAPI 是否安装成功
+python -c "import fastapi; print(fastapi.__version__)"
+0.141.1
+
+# 检查 SQLAlchemy 是否安装成功
+python -c "import sqlalchemy; print(sqlalchemy.__version__)"
+2.0.51
+```
+
+:::tip 温馨提示
+依赖安装完成后，如果上述命令输出版本号，说明核心依赖已正确安装。
+:::
+
+## 配置环境变量
+
+项目通过 `.env` 文件管理所有配置参数。首次使用需要从示例文件复制并修改：
+
+```bash
+# 复制环境变量示例文件
+cp .env.example .env # Linux / macOS
+copy .env.example .env # Windows CMD
+```
+
+ 编辑 `.env` 文件
+
+使用文本编辑器打开 `.env` 文件，修改以下关键配置：
+
+```bash
+# ============================================================
+# 基础配置
+# ============================================================
+FASTAPI_NAME=
+FASTAPI_VERSION=v3.0.0
+FASTAPI_HOST=0.0.0.0
+FASTAPI_PORT=8031
+FASTAPI_ENV=development
+FASTAPI_DEBUG=True
+
+# ============================================================
+# 数据库配置（根据实际情况修改）
+# ============================================================
+DB_DRIVER=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=djangoadmin.fastapi.elevue
+DB_USERNAME=root
+DB_PASSWORD=your_mysql_password # 修改为真实密码
+DB_PREFIX=fastapi_
+
+# ============================================================
+# Redis 缓存配置（根据实际情况修改）
+# ============================================================
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=your_redis_password # 修改为真实密码
+REDIS_AUTH=True
+
+# ============================================================
+# JWT 令牌配置（必填项）
+# ============================================================
+# 生成方式：python -c "import secrets; print(secrets.token_urlsafe(48))"
+JWT_SALT=your_jwt_secret_key_at_least_32_bytes
+JWT_EXPIRE_MINUTES=20
+```
+
+:::danger 重要提示
+1. `JWT_SALT` 是 JWT 令牌的签名密钥，**必须设置**且至少 32 字节。留空会导致应用拒绝启动。可使用以下命令生成：
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+2. `DB_PASSWORD` 和 `REDIS_PASSWORD` 请填写真实的服务密码。
+3. 生产环境务必设置 `FASTAPI_DEBUG=False`，避免泄漏内部错误信息。
+:::
+
+## 初始化数据库
+
+首次启动前，需要初始化数据库结构和种子数据。
+
+### 方式一：手动导入（推荐）
+
+```bash
+# 1. 登录 MySQL，创建数据库
+mysql -uroot -p
+CREATE DATABASE `djangoadmin.fastapi.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
+
+# 2. 导入数据库脚本（脚本位于 document/mysql/ 目录下）
+mysql -uroot -p djangoadmin.fastapi.elevue < document/mysql/djangoadmin.fastapi.elevue.sql
+```
+
+:::tip 温馨提示
+项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等数据库，对应的 SQL 脚本分别存放在 `document/` 目录下的对应文件夹中（`mysql/`、`postgresql/`、`sqlserver/`、`sqlite/`、`oracle/`）。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考 [数据库初始化](/zh/volume1/database) 章节。
+:::
+
+### 方式二：脚本初始化（备选）
+
+```bash
+# 自动完成建库、建表、导入种子数据
+python scripts/init_db.py
+```
+
+:::tip 温馨提示
+脚本初始化会根据 `.env` 中的 `DB_DRIVER` 配置，自动查找 `document/{driver}/` 目录下的 SQL 脚本并执行，同时完成建库、建表、导入种子数据和 Alembic 版本标记。
+:::
+
+:::danger 注意事项
+执行初始化前，请确保数据库服务已启动，并且 `.env` 中的数据库连接信息正确。
+:::
+
+## 启动后端服务
+
+一切准备就绪后，执行以下命令启动后端服务：
+
+```bash
+# 方式一：直接运行（推荐，适用于所有操作系统）
+python src/main.py
+
+# 方式三：使用 uvicorn 直接启动（需指定 --app-dir src）
+uvicorn main:app --app-dir src --host 0.0.0.0 --port 8031
+```
+
+:::tip 启动入口说明
+`src/main.py` 是应用入口，核心代码如下：
+
+```python
+# src/main.py
+import os, sys
+_MAIN_DIR = os.path.dirname(os.path.abspath(__file__))
+if _MAIN_DIR not in sys.path:
+    sys.path.insert(0, _MAIN_DIR)
+
+from core.app import create_app
+from core.config import FASTAPI_HOST, FASTAPI_PORT
+
+app = create_app()
+
+if __name__ == '__main__':
+    import uvicorn
+    uvicorn.run(app, host=FASTAPI_HOST, port=int(FASTAPI_PORT), reload=False)
+```
+
+`create_app()` 是应用工厂函数（位于 `src/core/app.py`），负责组装中间件链、注册路由、配置全局异常处理器和 lifespan（Redis 连接池 + 定时任务调度器）。
+:::
+
+启动成功后，终端将输出类似以下信息：
+
+```
+INFO: uvicorn main:app --app-dir src --host 0.0.0.0 --port 8031
+INFO: Started server process [19256]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+INFO: Uvicorn running on http://0.0.0.0:8031 (Press CTRL+C to quit)
+```
+
+:::tip 默认端口
+后端服务默认监听端口为 `8031`，可通过 `.env` 文件中的 `FASTAPI_PORT` 参数修改。
+:::
+
+## 访问 Swagger 文档
+
+后端服务启动后，打开浏览器访问以下地址：
+
+```
+http://127.0.0.1:8031/docs
+```
+
+![](/volume1/1.png)
+
+:::tip 温馨提示
+`Swagger UI` 提供了完整的 API 文档和在线调试功能，可以直观地查看所有接口的请求参数、响应格式和状态码。
+:::
+
+其他可用的文档地址：
+
+| 地址 | 说明 |
+|:----|:----|
+| `http://127.0.0.1:8031/docs` | Swagger UI 交互式文档 |
+| `http://127.0.0.1:8031/redoc` | ReDoc 格式文档 |
+| `http://127.0.0.1:8031/openapi.json` | OpenAPI 规范 JSON |
+
+## 验证后端服务
+
+ 测试接口连通性
+
+使用 `curl` 或浏览器访问健康检查接口：
+
+```bash
+# 测试服务是否正常响应
+curl http://127.0.0.1:8031/api/v1/captcha
+```
+
+返回类似以下 JSON 即表示服务正常运行：
+
+```json
+{
+    "code": 0,
+    "data": {
+        "captcha": "data:image/png;base64,...",
+        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
+    },
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+ 查看日志输出
+
+在终端中观察后端日志输出，确认无异常错误信息。如果出现连接数据库或 `Redis` 失败的错误，请检查 `.env` 配置和相关服务是否正常运行。
+
+## Makefile 常用命令
+
+项目根目录的 `Makefile` 提供了常用命令的快捷方式。
+
+:::tip Windows 用户注意
+`make` 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户有以下选择：
+1. **直接执行对应命令**：表格中"对应命令"列所示的原始命令，如 `python src/main.py`、`python scripts/init_db.py` 等。
+2. **安装 make 工具**：通过 `scoop install make`、`choco install make` 或 `winget install GnuWin32.Make` 安装。
+3. **使用 Git Bash**：安装 Git for Windows 后，自带的 Git Bash 环境支持 `make` 命令。
+:::
+
+| 命令 | 对应命令 | 说明 |
+|:----|:----|:----|
+| `make install` | `pip install -r requirements.txt` | 安装运行时 + 开发依赖 |
+| `make dev` | `python src/main.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/init_db.py` | 初始化数据库 |
+| `make seed-dict` | `python scripts/seed_dict.py` | 初始化业务字典数据 |
+
+## 常见问题
+
+ 端口被占用
+
+如果启动时报错 `Address already in use`，说明端口 `8031` 已被其他程序占用：
+
+```bash
+# Windows 查看端口占用
+netstat -ano | findstr 8031
+
+# Linux / macOS 查看端口占用
+lsof -i :8031
+```
+
+解决方式：终止占用进程，或修改 `.env` 中的 `FASTAPI_PORT` 为其他端口。
+
+ JWT_SALT 未配置
+
+如果启动时报错 `JWT_SALT must be set`，说明未配置 JWT 签名密钥。请在 `.env` 文件中设置：
+
+```bash
+JWT_SALT=your_generated_secret_key_here
+```
+
+ 数据库连接失败
+
+如果启动时报错 `Can't connect to MySQL server`，请检查：
+
+```
+1. MySQL 服务是否已启动
+2. .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
+3. 防火墙是否放行了数据库端口
+```
+
+## 总结
+
+本章节介绍了后端项目的完整启动流程：拉取代码 → 安装依赖 → 配置环境变量 → 初始化数据库 → 启动服务 → 访问 Swagger 文档。通过以上步骤，你已经成功将后端服务运行在本地 `8031` 端口。下一步可以进入 [前端启动](/zh/volume1/frontend) 章节，启动前端项目并登录系统。
@@ -0,0 +1,459 @@
+# 数据库初始化
+
+本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。
+
+项目支持多种数据库，数据库脚本按类型存放在 `document/` 目录下：
+
+```
+document/
+├── mysql/      # MySQL 脚本
+│   └── djangoadmin.fastapi.elevue.sql
+├── postgresql/ # PostgreSQL 脚本
+│   └── djangoadmin.fastapi.elevue.sql
+├── sqlserver/  # SQL Server 脚本
+│   └── djangoadmin.fastapi.elevue.sql
+├── sqlite/     # SQLite 脚本
+│   └── djangoadmin.fastapi.elevue.sql
+└── oracle/     # Oracle 脚本
+    └── djangoadmin.fastapi.elevue.sql
+```
+
+:::tip 温馨提示
+数据库初始化前，请确保已完成以下准备工作：
+1. 目标数据库服务已启动（如 MySQL 8.0+）
+2. `.env` 文件中的 `DB_DRIVER` 和数据库连接信息已正确配置
+3. Python 依赖已安装（`pip install -r requirements.txt`）
+:::
+
+## 方式一：手动初始化（推荐）
+
+手动初始化是最直接、最可控的方式，适合开发环境和生产环境。
+
+### 第一步：创建数据库
+
+根据你使用的数据库类型，手动创建数据库。
+
+**MySQL**：
+
+```sql
+CREATE DATABASE `djangoadmin.fastapi.elevue`
+  DEFAULT CHARACTER SET utf8mb4
+  COLLATE utf8mb4_general_ci;
+```
+
+**PostgreSQL**：
+
+```sql
+CREATE DATABASE "djangoadmin.fastapi.elevue"
+  WITH ENCODING 'UTF8'
+  LC_COLLATE = 'zh_CN.UTF-8'
+  LC_CTYPE = 'zh_CN.UTF-8'
+  TEMPLATE = template0;
+```
+
+**SQL Server**：
+
+```sql
+CREATE DATABASE [djangoadmin.fastapi.elevue]
+  COLLATE Chinese_PRC_CI_AS;
+```
+
+**SQLite**：
+
+无需手动创建，指定文件路径即可（如 `DB_DATABASE=./data/app.db`），首次启动时自动创建文件。
+
+**Oracle**：
+
+Oracle 没有"建库"概念，schema 即连接用户。需由 DBA 预先创建表空间和用户：
+
+```sql
+-- 创建表空间
+CREATE TABLESPACE djangoadmin
+  DATAFILE 'djangoadmin.dbf' SIZE 100M
+  AUTOEXTEND ON NEXT 10M MAXSIZE UNLIMITED;
+
+-- 创建用户并授权
+CREATE USER djangoadmin IDENTIFIED BY your_password
+  DEFAULT TABLESPACE djangoadmin
+  TEMPORARY TABLESPACE temp;
+GRANT CONNECT, RESOURCE, CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE TRIGGER TO djangoadmin;
+```
+
+### 第二步：导入数据库脚本
+
+进入 `document/` 目录，根据你使用的数据库类型选择对应的脚本文件夹，导入其中的 SQL 文件。
+
+**MySQL**：
+
+```bash
+# 使用 mysql 命令行导入
+mysql -uroot -p djangoadmin.fastapi.elevue < document/mysql/djangoadmin.fastapi.elevue.sql
+
+# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/mysql/djangoadmin.fastapi.elevue.sql
+```
+
+**PostgreSQL**：
+
+```bash
+# 使用 psql 命令行导入
+psql -U postgres -d djangoadmin.fastapi.elevue -f document/postgresql/djangoadmin.fastapi.elevue.sql
+
+# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/postgresql/djangoadmin.fastapi.elevue.sql
+```
+
+**SQL Server**：
+
+```bash
+# 使用 sqlcmd 命令行导入
+sqlcmd -S localhost -U sa -P your_password -d djangoadmin.fastapi.elevue -i document/sqlserver/djangoadmin.fastapi.elevue.sql
+
+# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/sqlserver/djangoadmin.fastapi.elevue.sql
+# 或使用 SSMS（SQL Server Management Studio）：打开 SQL 文件 → 执行
+```
+
+**SQLite**：
+
+```bash
+# 使用 sqlite3 命令行导入
+sqlite3 ./data/app.db < document/sqlite/djangoadmin.fastapi.elevue.sql
+
+# 或使用 Navicat 等工具：打开数据库文件 → 运行 SQL 文件 → 选择 document/sqlite/djangoadmin.fastapi.elevue.sql
+```
+
+**Oracle**：
+
+```bash
+# 使用 sqlplus 命令行导入
+sqlplus djangoadmin/your_password@127.0.0.1:1521/XE @document/oracle/djangoadmin.fastapi.elevue.sql
+
+# 或使用 Navicat 等工具：打开连接 → 运行 SQL 文件 → 选择 document/oracle/djangoadmin.fastapi.elevue.sql
+```
+
+:::tip 温馨提示
+Oracle 用户需要有 CREATE TABLE、CREATE SEQUENCE、CREATE TRIGGER 权限。脚本会自动为 Integer 主键补建 sequence + BEFORE INSERT 触发器实现自增。
+:::
+
+### 第三步：配置 .env
+
+确保 `.env` 文件中的数据库驱动和连接信息与你使用的数据库一致：
+
+```bash
+# ============================================================
+# 数据库驱动配置
+# 取消对应数据库的注释即可切换，同一时间仅启用一种数据库
+# ============================================================
+
+# ------------------------------------------------------------
+# MySQL（默认）
+# 说明：开源关系型数据库，适用性广泛，为本项目默认数据库
+# ------------------------------------------------------------
+DB_DRIVER=mysql          # 数据库驱动类型
+DB_HOST=127.0.0.1        # 数据库主机地址
+DB_PORT=3306             # 数据库端口（MySQL 默认 3306）
+DB_DATABASE=djangoadmin.fastapi.elevue   # 数据库名称
+DB_USERNAME=root         # 数据库用户名
+DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
+
+# ------------------------------------------------------------
+# PostgreSQL
+# 说明：功能强大的开源对象关系型数据库，支持高级特性
+# ------------------------------------------------------------
+# DB_DRIVER=postgresql   # 数据库驱动类型
+# DB_HOST=127.0.0.1      # 数据库主机地址
+# DB_PORT=5432           # 数据库端口（PostgreSQL 默认 5432）
+# DB_DATABASE=djangoadmin.fastapi.elevue   # 数据库名称
+# DB_USERNAME=postgres   # 数据库用户名
+# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
+
+# ------------------------------------------------------------
+# SQL Server
+# 说明：微软企业级关系型数据库，适用于 Windows 生态场景
+# ------------------------------------------------------------
+# DB_DRIVER=mssql        # 数据库驱动类型
+# DB_HOST=127.0.0.1      # 数据库主机地址
+# DB_PORT=1433           # 数据库端口（SQL Server 默认 1433）
+# DB_DATABASE=djangoadmin.fastapi.elevue   # 数据库名称
+# DB_USERNAME=sa         # 数据库用户名
+# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
+
+# ------------------------------------------------------------
+# SQLite
+# 说明：轻量级嵌入式文件数据库，适用于本地开发与测试
+# ------------------------------------------------------------
+# DB_DRIVER=sqlite       # 数据库驱动类型
+# DB_DATABASE=./data/app.db  # 数据库文件路径（相对于项目根目录）
+
+# ------------------------------------------------------------
+# Oracle
+# 说明：企业级关系型数据库，适用于大型企业应用场景
+# ------------------------------------------------------------
+# DB_DRIVER=oracle       # 数据库驱动类型
+# DB_HOST=127.0.0.1      # 数据库主机地址
+# DB_PORT=1521           # 数据库端口（Oracle 默认 1521）
+# DB_DATABASE=XE         # 数据库名称（Oracle 实例名，如 XE、ORCL）
+# DB_USERNAME=djangoadmin  # 数据库用户名
+# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
+```
+
+:::tip 配置说明
+1. 默认启用 MySQL，如需切换数据库，请注释掉 MySQL 相关配置，并取消对应数据库配置的注释。
+2. 所有密码占位符请替换为实际数据库密码。
+3. 仅需配置一种数据库即可，多个数据库配置同时启用会导致连接冲突。
+:::
+
+### 第四步：验证
+
+启动后端服务，访问 Swagger 文档验证数据库连接是否正常：
+
+```bash
+python src/main.py
+```
+
+打开浏览器访问 `http://127.0.0.1:8031/docs`，尝试调用登录接口，如能正常返回则说明数据库初始化成功。
+
+![](/volume1/database/1.png)
+
+![](/volume1/database/2.png)
+
+:::tip 温馨提示
+手动初始化的优势：
+1. 可以精确控制导入过程，查看每条 SQL 的执行结果。
+2. 可以根据需要只导入部分表或数据。
+3. 适合生产环境，配合 DBA 的数据库管理流程。
+4. 不依赖 Python 环境，纯 SQL 操作。
+:::
+
+## 方式二：脚本初始化（备选）
+
+项目提供了 `init_db.py` 脚本，可以自动完成数据库初始化。脚本会根据 `.env` 中的 `DB_DRIVER` 配置，自动选择对应的数据库方言执行初始化。
+
+```bash
+# 执行数据库初始化
+python scripts/init_db.py
+```
+
+:::tip 初始化内容
+`scripts/init_db.py` 脚本按 `DB_DRIVER` 分方言执行，自动完成以下操作：
+
+1. **创建数据库**：检测目标数据库是否存在，不存在则自动创建
+   - MySQL：`CREATE DATABASE ... DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`
+   - PostgreSQL：连接 `postgres` 维护库执行 `CREATE DATABASE`
+   - SQL Server：连接 `master` 库执行 `CREATE DATABASE`
+   - SQLite：直接创建数据库文件（`DB_DATABASE` 即文件路径）
+   - Oracle：仅校验连通性（schema 由 DBA 预建）
+2. **导入 SQL 种子数据**：根据 `DB_DRIVER` 查找 `document/{driver}/` 目录下的 SQL 脚本并执行
+3. **补建缺失表**：通过 `Base.metadata.create_all(engine)` 根据 ORM 模型定义补建所有数据表
+4. **Alembic 版本标记**：调用 `alembic stamp head` 将当前数据库状态标记为迁移基线
+
+脚本源码位于 `scripts/init_db.py`，可通过 `--drop-first` 参数先删除已存在库再重建。
+:::
+
+ 初始化输出示例
+
+```
+$ python scripts/init_db.py --drop-first
+[INFO] ============================================================
+[INFO] 数据库初始化开始
+[INFO] ============================================================
+[INFO] 检测数据库驱动: mysql
+[INFO] 连接 MySQL 服务器: 127.0.0.1:3306
+[INFO] 数据库配置: root@127.0.0.1:3306/djangoadmin.fastapi.elevue
+[INFO] 数据表前缀: fastapi_
+[INFO] 删除已有数据库: djangoadmin.fastapi.elevue
+[INFO] 创建数据库: djangoadmin.fastapi.elevue
+[INFO] 查找数据库脚本: document\mysql\djangoadmin.fastapi.elevue.sql
+[INFO] 导入 SQL 脚本...
+[INFO] SQL 脚本导入完成: 784510 条语句
+[INFO] 创建数据表...
+[INFO] 所有数据表均已存在，无需创建
+[INFO] 数据表创建完成: 共 25 张表
+[INFO] 标记 Alembic 版本...
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.schemas
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.tables
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.types
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.constraints
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.defaults
+2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.comments
+INFO  [alembic.runtime.migration] Context impl MySQLImpl.
+INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
+[INFO] Alembic 版本标记完成
+[INFO] ============================================================
+[INFO] 数据库初始化完成！
+[INFO] ============================================================
+```
+
+:::danger 注意事项
+1. **不带 `--drop-first`**（默认）：创建新表和插入种子数据，**不会删除已有数据**，重复执行是安全的（幂等操作）。                                                                                                                                           
+2. **带 `--drop-first`**：会**先删除已有数据库再重建**，所有数据将丢失，仅适用于开发环境或全新部署。                                                                                                                                                       
+3. 请确保 `.env` 中的数据库用户具有 `CREATE DATABASE` 和 `CREATE TABLE` 权限。
+4. 脚本初始化会根据 `DB_DRIVER` 自动查找 `document/{driver}/` 目录下的 SQL 脚本。
+:::
+
+## 多数据库支持
+
+项目通过 `DB_DRIVER` 环境变量切换数据库驱动，无需修改代码。
+
+| 数据库 | DB_DRIVER 值 | 默认端口 | 依赖包 | 脚本目录 |
+|:----|:----|:----|:----|:----|
+| MySQL | `mysql` | 3306 | PyMySQL | `document/mysql/` |
+| PostgreSQL | `postgresql` | 5432 | psycopg[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]`），然后按照上述步骤重新初始化数据库。
+:::
+
+## 种子数据
+
+初始化完成后，数据库中包含以下默认数据：
+
+| 数据 | 说明 |
+|:----|:----|
+| 管理员账号 | `admin` / `123456`（超级管理员，ID=1，跳过权限校验） |
+| 默认角色 | 超级管理员角色 |
+| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
+| 数据字典 | 系统内置字典数据 |
+| 系统配置 | 系统默认配置项 |
+
+如需额外导入业务字典数据，可执行：
+
+```bash
+# 初始化业务字典数据（幂等，按 code 判重，已存在跳过）
+python scripts/seed_dict.py
+```
+
+## 数据库迁移
+
+项目使用 `Alembic` 进行数据库版本迁移管理，确保数据库结构与代码模型保持同步。
+
+ 迁移文件位置
+
+```
+migrations/
+├── env.py               # 迁移环境配置
+└── versions/            # 迁移版本文件
+    └── 0001_baseline.py # 基线版本
+```
+
+ 生成增量迁移
+
+当修改了 ORM 模型（如新增字段、修改表结构）后，需要生成增量迁移文件：
+
+```bash
+# 自动生成迁移脚本（Alembic 会对比当前模型与数据库的差异）
+alembic revision --autogenerate -m "描述本次变更"
+```
+
+ 执行迁移
+
+```bash
+# 应用所有待执行的迁移
+alembic upgrade head
+```
+
+ 版本标记
+
+如果数据库已经手动同步到最新结构，可以标记当前版本：
+
+```bash
+# 标记当前数据库为最新版本
+alembic stamp head
+```
+
+:::tip 迁移工作流
+典型的数据库迁移工作流如下：
+
+```
+1. 修改 ORM 模型（src/modules/**/models.py）
+2. 生成迁移脚本：alembic revision --autogenerate -m "描述本次变更"
+3. 检查生成的迁移文件（migrations/versions/ 目录）
+4. 执行迁移：alembic upgrade head
+5. 验证数据库结构变更
+```
+:::
+
+## Makefile 数据库命令速查
+
+:::tip Windows 用户注意
+`make` 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户可直接执行"对应命令"列所示的原始命令，如 `python scripts/init_db.py`、`alembic revision --autogenerate` 等。如需使用 `make`，可通过 `scoop install make` 或 `choco install make` 安装。
+:::
+
+| 命令 | 对应命令 | 说明 |
+|:----|:----|:----|
+| `make db-init` | `python scripts/init_db.py` | 初始化数据库（建库 + 建表 + 种子数据 + alembic stamp） |
+| `make seed-dict` | `python scripts/seed_dict.py` | 初始化业务字典数据（幂等，按 code 判重） |
+| `make migrate-revision` | `alembic revision --autogenerate` | 生成增量迁移脚本 |
+| `make migrate-upgrade` | `alembic upgrade head` | 应用所有待执行的迁移 |
+| `make migrate-stamp` | `alembic stamp head` | 标记当前数据库为最新版本 |
+| `make db-migrate ARGS="..."` | `python scripts/migrate_db.py ...` | 跨库数据迁移 |
+| `make db-migrate-dry-run ARGS="..."` | `python scripts/migrate_db.py ... --dry-run` | 跨库迁移干跑（只核对计划，不写入目标库） |
+
+## 数据库备份与恢复
+
+ MySQL 备份
+
+```bash
+# 备份数据库
+mysqldump -uroot -p djangoadmin.fastapi.elevue > backup.sql
+
+# 恢复数据库
+mysql -uroot -p djangoadmin.fastapi.elevue < backup.sql
+```
+
+ PostgreSQL 备份
+
+```bash
+# 备份数据库
+pg_dump -U postgres djangoadmin.fastapi.elevue > backup.sql
+
+# 恢复数据库
+psql -U postgres djangoadmin.fastapi.elevue < backup.sql
+```
+
+ SQL Server 备份
+
+```bash
+# 备份数据库
+sqlcmd -S localhost -U sa -P your_password -Q "BACKUP DATABASE [djangoadmin.fastapi.elevue] TO DISK = 'backup.bak'"
+
+# 恢复数据库
+sqlcmd -S localhost -U sa -P your_password -Q "RESTORE DATABASE [djangoadmin.fastapi.elevue] FROM DISK = 'backup.bak'"
+
+# 或使用 Navicat 等工具进行备份恢复
+# 或使用 SSMS（SQL Server Management Studio）：右键数据库 → 任务 → 备份 / 还原
+```
+
+ SQLite 备份
+
+```bash
+# 备份数据库（直接复制文件）
+cp ./data/app.db ./data/app_backup.db
+
+# 恢复数据库（替换文件）
+cp ./data/app_backup.db ./data/app.db
+```
+
+ Oracle 备份
+
+```bash
+# 备份数据库（使用 expdp 数据泵）
+expdp djangoadmin/your_password@127.0.0.1:1521/XE directory=DATA_PUMP_DIR dumpfile=backup.dmp full=y
+
+# 恢复数据库（使用 impdp 数据泵）
+impdp djangoadmin/your_password@127.0.0.1:1521/XE directory=DATA_PUMP_DIR dumpfile=backup.dmp full=y
+
+# 或使用 Navicat 等工具进行备份恢复
+```
+
+## 总结
+
+数据库初始化有两种方式：
+
+```
+推荐方式：手动创建数据库 → 导入 document/{driver}/ 目录下的 SQL 脚本 → 配置 .env → 启动验证
+备选方式：python scripts/init_db.py（自动完成建库、建表、导入种子数据、Alembic 标记）
+```
+
+SQL 脚本按数据库类型分目录存放在 `document/` 下，`init_db.py` 脚本会根据 `.env` 中的 `DB_DRIVER` 自动查找对应目录的脚本文件。后续的模型变更通过 `Alembic` 迁移工具管理，确保数据库结构与代码保持同步。
@@ -0,0 +1,324 @@
+# Docker 一键启动
+
+本章节介绍如何使用 `Docker Compose` 一键启动项目，无需手动安装 Python、Node.js 等运行环境。Docker 方式适合快速体验、测试部署和 CI/CD 场景。
+
+:::tip 温馨提示
+使用 Docker 方式启动前，请确保已安装以下软件：
+1. [Docker Desktop](https://www.docker.com/products/docker-desktop/)（Windows / macOS）或 Docker Engine（Linux）
+2. [Docker Compose](https://docs.docker.com/compose/install/)（Docker Desktop 已内置）
+:::
+
+## 前置准备
+
+ 安装 Docker Desktop
+
+**Windows / macOS**
+
+访问 [Docker Desktop 官网](https://www.docker.com/products/docker-desktop/)，下载并安装适合你操作系统的版本。
+
+安装完成后，在终端中验证：
+
+```bash
+# 查看 Docker 版本
+docker --version
+Docker version 27.3.1, build ce12230
+
+# 查看 Docker Compose 版本
+docker compose version
+Docker Compose version v2.29.7
+```
+
+**Linux（Ubuntu / Debian）**
+
+```bash
+# 安装 Docker
+curl -fsSL https://get.docker.com | sh
+
+# 将当前用户添加到 docker 组
+sudo usermod -aG docker $USER
+
+# 重新登录后验证
+docker --version
+```
+
+ 准备环境变量文件
+
+```bash
+# 复制环境变量示例文件
+cp .env.example .env
+```
+
+编辑 `.env` 文件，修改数据库和 Redis 的连接信息。Docker 模式下，服务间通信使用容器名称作为主机名：
+
+```bash
+# ============================================================
+# 数据库配置（使用 MySQL 容器）
+# 说明：连接 Docker 容器中运行的 MySQL 数据库
+# ============================================================
+DB_HOST=127.0.0.1                # 数据库主机地址（本地容器）
+DB_PORT=3306                     # 数据库端口（MySQL 默认 3306）
+DB_DATABASE=djangoadmin.fastapi.elevue   # 数据库名称
+DB_USERNAME=root                 # 数据库用户名
+DB_PASSWORD=your_password        # 数据库密码（请修改为实际密码）
+
+# ============================================================
+# Redis 配置
+# 说明：用于缓存、Session 存储及消息队列等场景
+# ============================================================
+REDIS_HOST=127.0.0.1             # Redis 主机地址（本地容器）
+REDIS_PORT=6379                  # Redis 端口（默认 6379）
+REDIS_PASSWORD=your_redis_password  # Redis 密码（请修改为实际密码）
+REDIS_AUTH=True                  # 是否启用密码认证（True/False）
+
+# ============================================================
+# JWT 配置（必填）
+# 说明：用于生成和验证用户身份令牌，请务必修改为随机字符串
+# ============================================================
+JWT_SALT=your_generated_secret_key_here   # JWT 加密盐值（建议 32 位以上随机字符串）
+```
+
+:::danger 重要提示
+`JWT_SALT` 必须设置，否则应用无法启动。生成方式：
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+:::
+
+## Docker Compose 配置
+
+项目的 `docker-compose.yml` 文件定义了后端服务的容器编排：
+
+```yaml
+# +======================================================================
+# | 模块: Docker Compose 配置
+# | 说明: FastAPI+EleVue 应用服务容器编排
+# +======================================================================
+version: '3.7'
+# ============================================================
+# 应用服务
+# ============================================================
+services:
+  # ------------------------------------------------------------
+  # 后端服务
+  # ------------------------------------------------------------
+  fastapi_elevue:
+    # 构建镜像名称
+    image: fastapi_elevue
+    # 容器运行时名称
+    container_name: fastapi_elevue
+    # 镜像构建配置
+    build:
+      context: ./              # 构建上下文路径（项目根目录）
+      dockerfile: Dockerfile   # Dockerfile 文件名
+    # 容器重启策略：异常退出时自动重启
+    restart: always
+    # 网络模式：使用宿主机网络栈
+    # 说明：host 模式下容器直接使用宿主机网络，DB_HOST/REDIS_HOST 设为 127.0.0.1
+    #       时可直接连通宿主机上的服务；该模式下 ports 映射配置将被忽略
+    # 注意：若改用 bridge 网络，需将 DB_HOST/REDIS_HOST 改为宿主机可访问地址
+    #       （如 host.docker.internal），并取消下方 ports 的注释
+    network_mode: host
+    # 端口映射（仅在 bridge 网络模式下生效；host 模式下无效）
+    # ports:
+    #   - 8031:8031
+    # 数据卷挂载
+    volumes:
+      - $PWD/uploads:/data/apps/uploads   # 挂载上传文件目录，便于持久化存储
+    # 从宿主机 .env 文件读取环境变量，注入容器进程
+    env_file:
+      - .env
+    # 容器启动执行的命令
+    command: python src/main.py
+    # 日志驱动配置
+    logging:
+      driver: "json-file"              # 使用 JSON 文件日志驱动
+      options:
+        max-size: "500m"               # 单个日志文件最大 500MB
+        max-file: "10"                 # 最多保留 10 个日志文件
+```
+
+:::tip 配置说明
+| 配置项 | 说明 |
+|:----|:----|
+| `restart: always` | 容器异常退出时自动重启 |
+| `network_mode: host` | 使用宿主机网络，DB_HOST/REDIS_HOST 可直接用 127.0.0.1 |
+| `volumes` | 上传文件目录持久化挂载 |
+| `env_file` | 从 `.env` 文件注入环境变量 |
+| `logging` | 日志文件大小限制 500MB，最多保留 10 个文件 |
+:::
+
+## 一键启动
+
+ 构建并启动
+
+```bash
+# 构建镜像并启动容器（首次运行或代码变更后）
+docker compose up --build
+```
+
+ 后台启动
+
+```bash
+# 后台模式启动
+docker compose up --build -d
+```
+
+ 仅启动（镜像已构建）
+
+```bash
+# 直接启动，不重新构建
+docker compose up
+
+# 后台模式
+docker compose up -d
+```
+
+启动成功后，终端输出类似以下信息：
+
+```
+[+] Building 45.2s (12/12) FINISHED
+[+] Running 2/2
+ ✔ Network djangoadmin_default Created
+ ✔ Container fastapi_elevue Started
+```
+
+:::tip 访问服务
+容器启动后，通过以下地址访问：
+
+```
+后端服务：http://127.0.0.1:8031
+Swagger 文档：http://127.0.0.1:8031/docs
+```
+:::
+
+## 常用 Docker 命令
+
+ 查看容器状态
+
+```bash
+# 查看运行中的容器
+docker compose ps
+
+# 查看所有容器（包括已停止的）
+docker compose ps -a
+```
+
+ 查看日志
+
+```bash
+# 查看实时日志
+docker compose logs -f
+
+# 查看最近 100 行日志
+docker compose logs --tail 100
+
+# 查看指定服务日志
+docker compose logs -f fastapi_elevue
+```
+
+ 停止与重启
+
+```bash
+# 停止容器
+docker compose stop
+
+# 停止并删除容器
+docker compose down
+
+# 重启容器
+docker compose restart
+```
+
+ 重新构建
+
+```bash
+# 强制重新构建镜像（不使用缓存）
+docker compose build --no-cache
+
+# 构建并启动
+docker compose up --build
+```
+
+ 进入容器
+
+```bash
+# 进入运行中的容器终端
+docker compose exec fastapi_elevue bash
+
+# 在容器内执行 Python 命令
+docker compose exec fastapi_elevue python -c "print('hello')"
+```
+
+## 环境变量注入
+
+Docker 模式下，环境变量通过 `env_file` 从 `.env` 文件注入到容器中。也可以通过 `docker run` 命令行参数覆盖：
+
+```bash
+# 使用 --env-file 指定环境变量文件
+docker run --env-file .env fastapi_elevue
+
+# 通过 -e 参数覆盖单个变量
+docker run -e FASTAPI_PORT=9090 fastapi_elevue
+```
+
+:::tip 温馨提示
+容器内的环境变量优先级：`docker run -e` > `env_file` > `Dockerfile ENV`。
+:::
+
+## 数据持久化
+
+ 上传文件
+
+`docker-compose.yml` 中配置了上传目录的挂载：
+
+```yaml
+volumes:
+    - $PWD/uploads:/data/apps/uploads
+```
+
+宿主机的 `$PWD/uploads` 目录与容器内的 `/data/apps/uploads` 目录双向同步，确保容器重建后上传文件不丢失。
+
+ 数据库数据
+
+如果使用外部 MySQL 数据库（非 Docker 容器），数据存储在宿主机的 MySQL 数据目录中。如果需要在 Docker 中运行 MySQL，可以添加 MySQL 服务到 `docker-compose.yml`。
+
+## 常见问题
+
+ 构建失败
+
+```bash
+# 清除 Docker 缓存后重新构建
+docker compose build --no-cache
+docker compose up --build
+```
+
+ 端口冲突
+
+如果端口 `8031` 被占用，可修改 `docker-compose.yml` 中的端口映射：
+
+```yaml
+ports:
+    - 9090:8031
+```
+
+ 无法连接数据库
+
+```
+1. 确认 network_mode: host 模式下，DB_HOST 设置为 127.0.0.1
+2. 如果使用 bridge 网络模式，DB_HOST 需要设置为宿主机 IP 或 host.docker.internal
+3. 确认 MySQL 服务允许来自 Docker 网络的连接
+```
+
+ 容器启动后立即退出
+
+```bash
+# 查看容器日志排查原因
+docker compose logs fastapi_elevue
+```
+
+常见原因：`JWT_SALT` 未配置、数据库连接失败、Redis 连接失败。
+
+## 总结
+
+本章节介绍了使用 Docker Compose 一键启动项目的完整流程：安装 Docker → 准备环境变量 → 构建并启动容器 → 常用运维命令。Docker 方式避免了手动安装 Python 和 Node.js 环境的繁琐步骤，适合快速体验和测试部署。生产环境部署时，建议结合 Nginx 反向代理和 HTTPS 证书进行配置。更多环境变量配置项，请参见 [环境变量速查表](/zh/volume1/env-vars)。
@@ -0,0 +1,229 @@
+# 环境变量速查表
+
+本章节汇总了项目 `.env` 文件中所有可配置的环境变量，按功能分类整理。所有变量均可在 `.env.example` 中找到示例。
+
+:::tip 温馨提示
+1. `.env.example` 是环境变量模板文件，已提交到版本控制。真实 `.env` 文件已被 `.gitignore` 忽略。
+2. 首次使用请执行 `cp .env.example .env` 复制模板后修改。
+3. 带有 `必填` 标记的变量必须设置，否则应用无法正常启动。
+:::
+
+## 基础配置
+
+| 变量名 | 默认值 | 说明 |
+|:----|:----|:----|
+| FASTAPI_NAME | FastAPI+EleVue旗舰版 | 应用名称，用于界面显示和系统标识 |
+| FASTAPI_VERSION | v3.0.0 | 应用版本号 |
+| FASTAPI_HOST | 0.0.0.0 | 应用监听地址。`127.0.0.1` 仅本地访问；容器/生产建议 `0.0.0.0` |
+| FASTAPI_PORT | 8031 | 应用监听端口 |
+| FASTAPI_APP | main.py | 应用启动文件名 |
+| FASTAPI_ENV | production | 运行环境：`development` / `production` / `testing` |
+| FASTAPI_DEBUG | False | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
+| FASTAPI_DEMO | False | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status/batchDelete）返回"演示环境，暂无操作权限" |
+| FASTAPI_FILE_URL | http://file.fastapi.elevue | 文件访问域名，用于拼接上传文件的访问 URL。`BaseService._enrich_file_urls()` 会自动为文件字段补此前缀 |
+| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,.gif,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号）。`upload_size_limit_middleware` 按 `Content-Length` 提前拦截超大请求 |
+| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |
+
+:::tip 安全提示
+生产环境务必设置 `FASTAPI_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
+:::
+
+## 数据库配置
+
+| 变量名 | 默认值 | 说明 |
+|:----|:----|:----|
+| DB_DRIVER | mysql | 数据库驱动。可选：`mysql` / `postgresql` / `mssql` / `oracle` / `sqlite` |
+| DB_HOST | 127.0.0.1 | 数据库地址（`sqlite` 时忽略） |
+| DB_PORT | 3306 | 数据库端口（`sqlite` 时忽略） |
+| DB_DATABASE | djangoadmin.fastapi.elevue | 数据库名称。`sqlite` 时作为数据库文件完整路径 |
+| DB_USERNAME | root | 数据库账号（`sqlite` 时忽略） |
+| DB_PASSWORD | CHANGE_ME_DB_PASSWORD | 数据库密码，**必填**（`sqlite` 除外） |
+| DB_PREFIX | fastapi_ | 数据表前缀，所有业务表名自动添加此前缀。模型中通过 `DB_PREFIX + "position"` 拼接表名 |
+| DB_DEBUG | False | 是否开启 SQL 调试日志（对应 SQLAlchemy `echo` 参数）。生产环境务必设为 `False` |
+
+:::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 签名密钥，**必填**。至少 32 字节强随机值，留空应用会拒绝启动 |
+| JWT_EXPIRE_MINUTES | 20 | JWT 令牌过期时间（分钟） |
+| LOGIN_FAIL_MAX | 5 | 登录失败次数上限，超过后锁定账号（防暴力破解） |
+| LOGIN_LOCK_SECONDS | 300 | 登录锁定时间（秒） |
+
+:::danger 重要提示
+`JWT_SALT` 是安全关键配置，必须设置。推荐使用以下命令生成：
+
+```bash
+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 允许的源，多个用逗号分隔 |
+| TRUSTED_PROXY_COUNT | 0 | 可信代理层数。`0` = 不信任 X-Forwarded-For；部署在 Nginx 等反代后设为 `>=1` |
+| TRUSTED_PROXY_IPS | （空） | 可信代理 IP 白名单，逗号分隔 |
+
+:::tip 温馨提示
+本地开发时，`CORS_ALLOWED_ORIGINS` 需包含前端开发服务器地址（默认 `http://localhost:8001`）。如果有多个前端地址，用逗号分隔：
+
+```bash
+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_URL | （空） | 短信服务 API 地址 |
+| SMS_API_KEY | （空） | 短信服务 API 密钥 |
+| SMS_SIGN | （空） | 短信签名 |
+| SMS_TEMPLATE_ID | （空） | 短信模板 ID |
+
+:::tip 温馨提示
+短信功能为预留扩展功能，暂未实现。
+:::
+
+## 请求限流配置
+
+| 变量名 | 默认值 | 说明 |
+|:----|:----|:----|
+| 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 滥用。
+:::
+
+## 环境变量配置示例
+
+以下是一个开发环境的 `.env` 文件示例（基于 `.env.example` 模板修改）：
+
+```bash
+# ============================================================
+# 基础服务配置
+# ============================================================
+FASTAPI_NAME=FastAPI+EleVue旗舰版          # 应用名称
+FASTAPI_VERSION=v3.0.0                    # 应用版本号
+FASTAPI_HOST=127.0.0.1                    # 服务监听地址（127.0.0.1 仅本地访问，0.0.0.0 允许外部访问）
+FASTAPI_PORT=8031                         # 服务监听端口
+FASTAPI_ENV=development                   # 运行环境（development / testing / production）
+FASTAPI_DEBUG=True                        # 调试模式开关（True 开启，生产环境请设为 False）
+FASTAPI_DEMO=False                        # 演示模式开关（True 开启后将限制部分写操作）
+FASTAPI_FILE_URL=http://file.fastapi.elevue # 文件服务地址（用于访问上传的文件）
+
+# ============================================================
+# 数据库配置
+# ============================================================
+DB_DRIVER=mysql                           # 数据库类型（mysql / postgresql / mssql / sqlite / oracle）
+DB_HOST=127.0.0.1                         # 数据库主机地址
+DB_PORT=3306                              # 数据库端口（MySQL 默认 3306）
+DB_DATABASE=djangoadmin.fastapi.elevue    # 数据库名称
+DB_USERNAME=root                          # 数据库用户名
+DB_PASSWORD=your_password                 # 数据库密码（请修改为实际密码）
+DB_PREFIX=fastapi_                        # 数据表前缀（用于区分不同应用的同库表）
+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_32_bytes   # JWT 加密盐值（建议 32 位以上随机字符串，务必修改）
+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 配置来源
+所有配置变量在 `src/core/config/__init__.py` 中通过 `python-dotenv` 从 `.env` 文件加载，然后由各子模块（`app.py`、`database.py`、`redis.py`、`auth.py`、`captcha.py` 等）读取并导出。例如 `DB_DRIVER` 在 `src/core/config/database.py` 中读取并构建 SQLAlchemy 连接 URL。
+:::
+
+:::danger 安全提醒
+1. 真实 `.env` 文件包含敏感信息（数据库密码、JWT 密钥等），已被 `.gitignore` 忽略，请勿提交到版本控制。
+2. 生产环境务必设置 `FASTAPI_DEBUG=False` 和 `DB_DEBUG=False`。
+3. 定期轮换 `JWT_SALT` 密钥，提高系统安全性。
+:::
+
+## 总结
+
+本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、跨域、邮件、短信和限流等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
@@ -0,0 +1,477 @@
+# 环境准备
+
+本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python`  + `FastAPI` 后端、`Vue3` + `ElementPlus` 前端的分离架构，本地开发需准备以下软件。
+
+安装软件：`Python(3.12+)`、`MySQL(8.0+)`、`Redis(3.2+)`、`Node.js(22+)`、`pnpm` 等。
+
+:::tip 温馨提示
+1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。
+2. `Node.js` 安装后还需另外安装 `pnpm` 包管理器，要求 Node.js 22+ 版本以上。
+3. `MySQL 8.0+` 安装启动服务后，可以安装可视化工具 `Navicat` 并连接数据库。
+4. 非 Java/Spring 技术栈，无需安装 JDK 和 Maven。
+:::
+
+## 安装 Python
+
+`Python` 是后端的核心运行环境，`FastAPI` 框架要求 `Python 3.12` 或更高版本。
+
+ 下载 Python
+
+访问 [Python 官方网站](https://www.python.org/downloads/)，选择适合你操作系统的 `Python 3.12+` 版本（推荐最新稳定版）。
+
+![](/volume1/environment/1.png)
+
+![](/volume1/environment/2.png)
+
+点击 `Download` 按钮，下载对应平台的安装包。
+
+ 安装 Python
+
+**Windows 系统**
+
+双击下载的 `.exe` 文件启动安装程序。
+
+:::danger 重要提示
+安装时务必勾选 **`Add Python to PATH`** 选项，将 Python 添加到系统环境变量。否则后续命令无法识别 `python` 和 `pip` 指令。
+:::
+
+选择 `Customize installation`，确认以下选项已勾选：
+
+```
+pip - Python 包管理器
+tcl/tk and IDLE - 图形界面支持（可选）
+py launcher - Python 启动器
+```
+
+点击 `Install` 开始安装，等待安装完成。
+
+**macOS 系统**
+
+双击下载的 `.pkg` 文件，按照安装向导完成安装。macOS 通常自带 Python，但建议安装官方版本以确保版本一致。
+
+**Linux 系统**
+
+大多数 Linux 发行版自带 Python，但版本可能较低，建议通过包管理器安装 `Python 3.12+`。
+
+Ubuntu / Debian：
+
+```bash
+# 更新包索引
+sudo apt update
+
+# 安装 Python 3.12 及 pip
+sudo apt install -y python3.12 python3.12-venv python3-pip
+
+# 设置 python3 指向 3.12（可选，部分系统默认已是）
+sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1
+```
+
+CentOS / RHEL / Fedora：
+
+```bash
+# CentOS / RHEL 8+ / Fedora
+sudo dnf install -y python3.12 python3.12-pip
+
+# CentOS 7（需先启用 EPEL 和 IUS 源）
+sudo yum install -y epel-release
+sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
+sudo yum install -y python312 python312-pip
+```
+
+:::tip 温馨提示
+1. 部分系统需使用 `python3` 和 `pip3` 命令而非 `python` 和 `pip`，可通过 `alias python=python3` 简化。
+2. 推荐使用 `python3 -m venv` 创建虚拟环境隔离项目依赖：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+:::
+
+ 验证安装
+
+打开终端或命令提示符，输入以下命令确认 `Python` 和 `pip` 安装成功：
+
+```bash
+# 查看 Python 版本
+python --version
+Python 3.12.7
+
+# 查看 pip 版本
+pip --version
+pip 24.2 from ... (python 3.12)
+```
+
+:::tip 温馨提示
+如果显示版本号，说明 `Python` 和 `pip` 安装成功。推荐使用 `Python 3.12` 或更高版本。
+:::
+
+ 配置 pip 镜像源（可选）
+
+国内网络环境建议配置 `pip` 镜像源，加速依赖包下载：
+
+```bash
+# 设置阿里云镜像源
+pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
+
+# 设置信任主机
+pip config set global.trusted-host mirrors.aliyun.com
+```
+
+## 安装 MySQL
+
+`MySQL` 是默认的关系型数据库，要求 `8.0` 或更高版本。项目同时支持 `PostgreSQL`、`SQL Server`、`SQLite`、`Oracle` 等数据库驱动。
+
+ 下载软件
+
+访问 [MySQL 官方网站](https://dev.mysql.com/downloads/mysql/)，选择适合你操作系统的 `MySQL 8.0+` 版本（推荐最新稳定版）。
+
+![](/volume1/environment/3.png)
+
+点击 `Download` 按钮，选择合适的安装包下载。
+
+ 安装软件
+
+**Windows 系统**
+
+双击下载的 `.msi` 文件启动安装向导，按照提示完成安装。安装过程中需要设置 `root` 用户密码，请牢记此密码，后续配置 `.env` 文件时需要使用。
+
+**macOS 系统**
+
+推荐使用 `Homebrew` 安装：
+
+```bash
+brew install mysql
+brew services start mysql
+```
+
+**Linux 系统**
+
+Ubuntu / Debian：
+
+```bash
+# 更新包索引
+sudo apt update
+
+# 安装 MySQL 8.0+
+sudo apt install -y mysql-server
+
+# 启动并设置开机自启
+sudo systemctl start mysql
+sudo systemctl enable mysql
+
+# 安全初始化（设置 root 密码、移除匿名用户等）
+sudo mysql_secure_installation
+```
+
+CentOS / RHEL / Fedora：
+
+```bash
+# CentOS / RHEL 8+ / Fedora
+sudo dnf install -y mysql-server
+
+# CentOS 7
+sudo yum install -y mysql-server
+
+# 启动并设置开机自启
+sudo systemctl start mysqld
+sudo systemctl enable mysqld
+```
+
+:::tip 温馨提示
+1. CentOS / RHEL 8+ 默认安装 `mysql-server`（即 MySQL 8.0 社区版）。
+2. CentOS 7 安装后需通过 `grep 'temporary password' /var/log/mysqld.log` 获取临时 root 密码。
+3. 部分发行版可使用 `mariadb-server` 作为 MySQL 兼容替代，但建议使用官方 MySQL 以确保兼容性。
+:::
+
+ 验证安装
+
+打开命令提示符或终端，输入以下命令登录 `MySQL`：
+
+```bash
+# 登录本地 MySQL 服务
+mysql -uroot -p
+
+# 输入密码后显示如下信息
+Enter password: ****
+Welcome to the MySQL monitor. Commands end with ; or \g.
+Your MySQL connection id is 14
+Server version: 8.0.41 MySQL Community Server - GPL
+
+mysql>
+```
+
+:::tip 温馨提示
+输入之前设置的 `root` 密码，成功登录后显示 `MySQL` 提示符即代表安装成功。
+:::
+
+ 创建数据库（可选）
+
+在 `MySQL` 提示符中，可提前创建项目数据库：
+
+```sql
+-- 创建数据库（UTF-8 编码）
+CREATE DATABASE `djangoadmin.fastapi.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
+
+-- 查看数据库
+SHOW DATABASES;
+```
+
+:::tip 温馨提示
+也可以不手动建库，后续执行 `python scripts/init_db.py` 会自动创建数据库并导入初始数据。
+:::
+
+## 安装 Redis
+
+`Redis` 是必需的缓存服务，用于验证码存储、JWT 令牌黑名单、登录限流等功能。要求 `3.2` 或更高版本。
+
+ 下载软件
+
+**Windows 系统**
+
+访问 [Microsoft Archive for Redis](https://github.com/microsoftarchive/redis/tags)，下载适用于 Windows 的安装包（推荐 `Redis-x64-3.2.100.msi`）。
+
+**macOS 系统**
+
+```bash
+brew install redis
+brew services start redis
+```
+
+**Linux 系统**
+
+Ubuntu / Debian：
+
+```bash
+sudo apt update
+sudo apt install -y redis-server
+
+# 启动并设置开机自启
+sudo systemctl start redis-server
+sudo systemctl enable redis-server
+```
+
+CentOS / RHEL / Fedora：
+
+```bash
+# CentOS / RHEL 8+ / Fedora
+sudo dnf install -y redis
+
+# CentOS 7
+sudo yum install -y redis
+
+# 启动并设置开机自启
+sudo systemctl start redis
+sudo systemctl enable redis
+```
+
+ 验证安装
+
+在终端或命令提示符中，执行以下命令启动客户端并测试：
+
+```bash
+# 启动 Redis 客户端
+redis-cli
+
+# 测试连接
+127.0.0.1:6379> ping
+PONG
+
+# 设置键值对
+127.0.0.1:6379> set name django_admin
+OK
+
+# 获取键值
+127.0.0.1:6379> get name
+"django_admin"
+```
+
+:::tip 温馨提示
+输入 `ping` 命令，如果返回 `PONG`，说明 Redis 客户端已成功连接到服务器。
+:::
+
+:::tip 常见问题与解决方法
+1. 服务无法启动：确保 Redis 安装目录正确，并且具有读取权限。检查端口 `6379` 是否被占用。
+2. 连接被拒绝：确保 Redis 服务器正在运行。验证防火墙设置，确保 Redis 端口（默认 `6379`）允许通过。
+:::
+
+## 安装 Node.js
+
+`Node.js` 是前端项目的运行环境，要求 `22` 或更高版本。前端基于 `Vue3` + `ElementPlus` 构建。
+
+ 下载 Node.js
+
+访问 [Node.js 官方网站](https://nodejs.org/zh-cn)，选择 `LTS` 版本（推荐 `v22.x` 或更高），下载适合你操作系统的安装包。
+
+![](/volume1/environment/4.png)
+
+ 安装 Node.js
+
+**Windows 系统**
+
+双击下载的 `.msi` 文件启动安装程序，按照提示完成安装。安装时建议勾选以下选项：
+
+```
+Automatically install the necessary tools - 自动安装所需工具
+Add to PATH - 将 Node.js 添加到系统环境变量
+```
+
+**macOS 系统**
+
+双击下载的 `.pkg` 文件，按照安装向导完成安装。
+
+**Linux 系统**
+
+推荐使用 `nvm`（Node Version Manager）安装，便于管理多版本：
+
+```bash
+# 安装 nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+
+# 重新加载 shell 配置
+source ~/.bashrc
+
+# 安装 Node.js 22+
+nvm install 22
+
+# 设置为默认版本
+nvm alias default 22
+```
+
+或通过 NodeSource 源直接安装：
+
+```bash
+# 添加 NodeSource 源（以 Node.js 22 为例）
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+
+# Ubuntu / Debian
+sudo apt install -y nodejs
+
+# CentOS / RHEL / Fedora
+sudo dnf install -y nodejs
+```
+
+ 验证安装
+
+打开终端或命令提示符，输入以下命令：
+
+```bash
+# 查看 Node.js 版本
+node -v
+v22.14.0
+
+# 查看 npm 版本
+npm -v
+10.9.2
+```
+
+:::tip 温馨提示
+如果显示版本号，说明 `Node.js` 和 `npm` 安装成功。如需同时管理多个 Node 版本，可以使用 `nvm` 工具。
+:::
+
+## 安装 pnpm
+
+`pnpm` 是推荐的前端包管理器，相比 `npm` 和 `yarn` 具有更快的安装速度和更小的磁盘占用。
+
+ 安装 pnpm
+
+通过 `npm` 全局安装 `pnpm`：
+
+```bash
+npm install pnpm -g
+```
+
+ 验证安装
+
+```bash
+# 查看 pnpm 版本
+pnpm -v
+9.15.0
+```
+
+:::tip 温馨提示
+`pnpm` 安装成功后，后续进入前端项目目录即可使用 `pnpm install` 安装依赖。
+:::
+
+ 设置镜像源（可选）
+
+国内网络环境建议配置 `pnpm` 镜像源，加速依赖包下载：
+
+```bash
+# 设置阿里云镜像源
+pnpm config set registry https://registry.npmmirror.com
+
+# 查看当前镜像源
+pnpm config get registry
+```
+
+## 安装 Git
+
+`Git` 是必需的版本控制工具，用于代码的拉取和管理。
+
+ 下载 Git
+
+访问 [Git 官方网站](https://git-scm.com/downloads)，下载适合你操作系统的安装包。
+
+ 安装 Git
+
+**Windows 系统**
+
+双击下载的 `.exe` 文件，按照安装向导完成安装。安装过程中保持默认选项即可。
+
+**macOS 系统**
+
+```bash
+# 使用 Homebrew 安装
+brew install git
+```
+
+**Linux 系统**
+
+```bash
+# Ubuntu / Debian
+sudo apt update
+sudo apt install -y git
+
+# CentOS / RHEL / Fedora
+sudo dnf install -y git
+```
+
+ 验证安装
+
+```bash
+# 查看 Git 版本
+git --version
+git version 2.43.0
+```
+
+## 环境验证清单
+
+完成以上所有软件安装后，打开终端依次执行以下命令，确认所有环境就绪：
+
+```bash
+# 1. Python 环境
+python --version # 期望: Python 3.12+
+pip --version # 期望: pip 对应 Python 版本
+
+# 2. 数据库
+mysql --version # 期望: mysql Ver 8.0+
+
+# 3. 缓存
+redis-cli --version # 期望: redis-cli 8.10+
+
+# 4. 前端运行时
+node -v # 期望: v22+
+pnpm -v # 期望: 11.x+
+
+# 5. 版本控制
+git --version # 期望: git version 2.x+
+```
+
+:::tip 全部就绪
+以上命令均能正确输出版本号，即表示本地开发环境已准备完毕，可以进入下一步：[后端启动](/zh/volume1/backend)。
+:::
+
+## 总结
+
+本章节介绍了本地开发环境所需的全部基础软件及其安装配置步骤。通过以上步骤，你已经完成了 `Python`、`MySQL`、`Redis`、`Node.js`、`pnpm`、`Git` 的安装和验证。这些是运行项目的基础环境，后续章节将基于这些环境进行项目的启动和调试。如果在安装过程中遇到问题，可参考各软件的官方文档或查阅 [常见问题FAQ](/zh/volume1/faq) 章节。
@@ -0,0 +1,424 @@
+# 常见问题FAQ
+
+本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。
+
+:::tip 温馨提示
+遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
+:::
+
+## 1. 端口被占用
+
+**现象**
+
+启动后端服务时报错：
+
+```
+OSError: [Errno 98] Address already in use
+```
+
+或：
+
+```
+ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次
+```
+
+**原因**
+
+端口 `8031`（或配置的其他端口）已被其他程序占用。
+
+**解决方案**
+
+```bash
+# Windows 查看端口占用
+netstat -ano | findstr 8031
+# 找到 PID 后终止进程
+taskkill /PID <进程ID> /F
+
+# Linux / macOS 查看端口占用
+lsof -i :8031
+# 终止进程
+kill -9 <进程ID>
+```
+
+或者修改 `.env` 中的端口号：
+
+```bash
+FASTAPI_PORT=8032
+```
+
+:::tip 温馨提示
+前端开发服务器端口冲突同理，修改 `ui/.env.development` 中的 `VITE_PORT` 即可。
+:::
+
+## 2. 数据库连接失败
+
+**现象**
+
+启动时报错：
+
+```
+pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")
+```
+
+或：
+
+```
+sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1045, "Access denied")
+```
+
+**排查步骤**
+
+```
+1. 检查 MySQL 服务是否已启动
+2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
+3. 检查数据库用户是否有远程连接权限
+4. 检查防火墙是否放行了数据库端口
+```
+
+**解决方案**
+
+```bash
+# 测试数据库连接
+mysql -h127.0.0.1 -P3306 -uroot -p
+
+# 如果是权限问题，授权用户
+mysql -uroot -p
+GRANT ALL PRIVILEGES ON `djangoadmin.fastapi.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
+FLUSH PRIVILEGES;
+```
+
+:::tip 温馨提示
+确认 `.env` 中的 `DB_PASSWORD` 没有多余的空格或引号。密码中的特殊字符可能需要转义。
+:::
+
+## 3. Redis 连接失败
+
+**现象**
+
+启动时报错：
+
+```
+redis.exceptions.ConnectionError: Error connecting to 127.0.0.1:6379
+```
+
+或：
+
+```
+redis.exceptions.AuthenticationError: Authentication required
+```
+
+**排查步骤**
+
+```
+1. 检查 Redis 服务是否已启动
+2. 检查 .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
+3. 检查 REDIS_AUTH 配置是否与 Redis 实际配置一致
+```
+
+**解决方案**
+
+```bash
+# 测试 Redis 连接
+redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
+
+# Windows 启动 Redis 服务
+net start Redis
+
+# Linux 启动 Redis 服务
+sudo systemctl start redis
+
+# macOS 启动 Redis 服务
+brew services start redis
+```
+
+:::tip 温馨提示
+如果 Redis 未设置密码，请将 `.env` 中的 `REDIS_AUTH` 设为 `False`。
+:::
+
+## 4. pip install 安装失败
+
+**现象**
+
+执行 `pip install -r requirements.txt` 时报错：
+
+```
+ERROR: Could not find a version that satisfies the requirement xxx
+```
+
+或：
+
+```
+ERROR: Failed building wheel for xxx
+```
+
+**解决方案**
+
+```bash
+# 方案一：使用国内镜像源
+pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
+
+# 方案二：升级 pip 后重试
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+
+# 方案三：配置全局镜像源
+pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
+pip config set global.trusted-host mirrors.aliyun.com
+```
+
+:::tip 温馨提示
+Windows 用户如果遇到 C 编译错误（如安装 `mysqlclient` 时），可尝试安装 Visual C++ Build Tools，或使用预编译的 wheel 包。
+:::
+
+## 5. JWT_SALT 未配置
+
+**现象**
+
+启动时报错：
+
+```
+ValueError: JWT_SALT must be set
+```
+
+或类似的安全配置错误。
+
+**原因**
+
+`.env` 文件中 `JWT_SALT` 变量为空或未设置。JWT 签名密钥是安全关键配置，应用在 fail-close 模式下会拒绝启动。
+
+**解决方案**
+
+```bash
+# 生成 JWT 密钥
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+
+# 将生成的密钥写入 .env
+JWT_SALT=your_generated_secret_key_here
+```
+
+:::danger 重要提示
+`JWT_SALT` 至少需要 32 字节的强随机值。请勿使用简单字符串（如 `123456` 或 `secret`）作为密钥。
+:::
+
+## 6. pnpm install 安装失败
+
+**现象**
+
+执行 `pnpm install` 时报错：
+
+```
+ERR_PNPM_NO_MATCHING_VERSION
+```
+
+或：
+
+```
+GET https://registry.npmjs.org/xxx error
+```
+
+**解决方案**
+
+```bash
+# 方案一：切换淘宝镜像源
+pnpm config set registry https://registry.npmmirror.com
+pnpm install
+
+# 方案二：清除缓存后重试
+pnpm store prune
+rm -rf node_modules
+pnpm install
+
+# 方案三：使用 --shamefully-hoist 模式
+pnpm install --shamefully-hoist
+```
+
+:::tip 温馨提示
+如果网络环境受限，可以尝试使用 VPN 或配置代理：
+
+```bash
+pnpm config set proxy http://127.0.0.1:7890
+pnpm config set https-proxy http://127.0.0.1:7890
+```
+:::
+
+## 7. API 请求返回 404
+
+**现象**
+
+调用接口时返回：
+
+```json
+{
+    "detail": "Not Found"
+}
+```
+
+**原因**
+
+可能是请求路径不正确，或后端路由未正确注册。
+
+**排查步骤**
+
+```
+1. 检查请求路径是否以 /api/v1/ 开头
+2. 检查 Swagger UI（http://127.0.0.1:8031/docs）中是否存在该接口
+3. 检查前端代理配置中的后端地址是否正确
+```
+
+**解决方案**
+
+```bash
+# 测试后端服务是否正常
+curl http://127.0.0.1:8031/api/v1/captcha
+
+# 检查前端代理配置
+# ui/.env.development
+VITE_PROXY=[["/api","http://127.0.0.1:8031/api"]]
+```
+
+:::tip 温馨提示
+所有业务接口都在 `/api/v1/` 前缀下。登录和验证码接口在 `/api/v1/` 下无需认证，其他接口需要携带 JWT Token。
+:::
+
+## 8. 验证码图片不显示
+
+**现象**
+
+登录页面验证码图片区域空白，或显示加载失败图标。
+
+**排查步骤**
+
+```
+1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
+2. 检查 /api/v1/captcha 接口是否返回正常
+3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）
+```
+
+**解决方案**
+
+```bash
+# 1. 测试验证码接口
+curl http://127.0.0.1:8031/api/v1/captcha
+
+# 2. 测试 Redis 连接
+redis-cli ping
+# 应返回 PONG
+
+# 3. 检查验证码字体文件是否存在
+ls static/fonts/Vera.ttf
+
+# 4. 如果字体文件缺失，检查 .env 中的 CAPTCHA_FONT_PATH 配置
+```
+
+:::tip 温馨提示
+验证码生成依赖 `Pillow` 库和字体文件。如果字体文件缺失，可从项目仓库重新拉取，或修改 `CAPTCHA_FONT_PATH` 指向系统字体。
+:::
+
+## 9. 接口返回 403 权限不足
+
+**现象**
+
+调用接口返回：
+
+```json
+{
+    "code": 1,
+    "data": null,
+    "msg": "权限不足",
+    "ok": false
+}
+```
+
+**原因**
+
+当前登录用户没有该接口的访问权限。项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 `sys:user:list`）。
+
+**解决方案**
+
+```
+1. 使用 admin 账号登录（ID=1 的管理员绕过所有权限检查）
+2. 检查当前用户的角色是否包含该接口的权限
+3. 在系统管理 > 菜单管理中，确认接口对应的权限节点已正确配置
+4. 在系统管理 > 角色管理中，确认角色已分配该权限
+```
+
+:::tip 温馨提示
+`admin` 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 `admin` 账号。
+:::
+
+## 10. 文件上传失败
+
+**现象**
+
+上传文件时返回错误：
+
+```json
+{
+    "code": 1,
+    "data": null,
+    "msg": "文件上传失败",
+    "ok": false
+}
+```
+
+或：
+
+```
+413 Request Entity Too Large
+```
+
+**排查步骤**
+
+```
+1. 检查上传文件扩展名是否在 ALLOWED_EXTS 白名单中
+2. 检查文件大小是否超过 UPLOAD_MAX_SIZE_MB 限制
+3. 检查上传目录是否有写入权限
+4. 检查 .env 中的 FASTAPI_FILE_URL 配置是否正确
+```
+
+**解决方案**
+
+```bash
+# .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
+FASTAPI_FILE_URL=http://file.fastapi.elevue
+```
+
+:::tip 温馨提示
+1. 如需上传更多文件类型，在 `UPLOAD_ALLOWED_EXTS` 中添加对应扩展名（带点号，逗号分隔）。
+2. 如需上传更大文件，增大 `UPLOAD_MAX_SIZE_MB` 值。
+3. 确保项目根目录下的 `uploads/` 目录存在且有写入权限。
+:::
+
+## 快速自检清单
+
+遇到问题时，按以下清单逐项检查：
+
+| 检查项 | 命令 | 期望结果 |
+|:----|:----|:----|
+| Python 版本 | `python --version` | 3.12+ |
+| pip 依赖 | `pip list \| grep fastapi` | fastapi 已安装 |
+| MySQL 服务 | `mysql -uroot -p -e "SELECT 1"` | 返回 1 |
+| Redis 服务 | `redis-cli ping` | PONG |
+| .env 文件 | `cat .env \| grep JWT_SALT` | 非空值 |
+| 后端服务 | `curl http://127.0.0.1:8031/api/v1/captcha` | 返回 JSON |
+| Node.js 版本 | `node -v` | v22+ |
+| pnpm 版本 | `pnpm -v` | 11.x+ |
+| 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 |
+
+:::tip 温馨提示
+如果以上检查项均正常但仍无法运行，建议查看完整错误日志：
+
+```bash
+# 后端日志
+python src/main.py 2>&1 | tee backend.log
+
+# 前端日志
+cd ui && pnpm dev 2>&1 | tee frontend.log
+```
+:::
+
+## 总结
+
+本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。
@@ -0,0 +1,293 @@
+# 第一个接口调试
+
+本章节介绍如何使用 `Swagger UI` 在线文档调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
+
+:::tip 温馨提示
+开始调试前，请确保已完成以下步骤：
+1. 后端服务已启动（参见 [后端启动](/zh/volume1/backend)）
+2. 数据库已初始化（参见 [数据库初始化](/zh/volume1/database)）
+3. Redis 服务已启动
+:::
+
+## 打开 Swagger UI
+
+后端服务启动后，在浏览器中访问以下地址：
+
+```
+http://127.0.0.1:8031/docs
+```
+
+![](/volume1/1.png)
+
+:::tip 温馨提示
+`Swagger UI` 是 FastAPI 自动生成的交互式 API 文档，支持在线发送请求、查看响应和调试接口。所有接口按模块分组展示，可展开查看详情。
+:::
+
+## 第一步：获取验证码
+
+登录前需要先获取图形验证码。在 Swagger UI 中找到验证码接口：
+
+1. 展开 `认证管理` 分组
+2. 点击 `GET /api/v1/captcha` 接口
+3. 点击 `Try it out` 按钮
+4. 点击 `Execute` 执行请求
+
+ 响应示例
+
+```json
+{
+    "code": 0,
+    "data": {
+        "captcha": "data:image/png;base64,iVBORw0KG...",
+        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
+    },
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip 温馨提示
+响应中的 `key` 是验证码的唯一标识，后续登录时需要使用。`captcha` 是 Base64 编码的验证码图片，可以在浏览器中直接查看。
+:::
+
+ 记录关键信息
+
+```
+key: sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ
+验证码图片中的文字: （查看图片获取）
+```
+
+## 第二步：登录获取 Token
+
+使用验证码和账号信息进行登录，获取 JWT 访问令牌。
+
+1. 展开 `认证管理` 分组
+2. 点击 `POST /api/v1/login` 接口
+3. 点击 `Try it out` 按钮
+4. 在请求体中填写以下 JSON：
+
+```json
+{
+    "username": "admin",
+    "password": "123456",
+    "code": "图片中的验证码文字",
+    "key": "第一步获取的key"
+}
+```
+
+5. 点击 `Execute` 执行请求
+
+ 成功响应
+
+```json
+{
+    "code": 0,
+    "data": {
+        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyZWFsbmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsImV4cCI6MTc4ODYxNDk0NiwiaWF0IjoxNzg4NjEzNzQ2fQ.xxxxxxxxxxx"
+    },
+    "msg": "登录成功",
+    "ok": true
+}
+```
+
+ 失败响应示例
+
+```json
+{
+    "code": 1,
+    "data": null,
+    "msg": "验证码错误或已过期",
+    "ok": false
+}
+```
+
+:::danger 常见登录失败原因
+| 错误信息 | 原因 | 解决方式 |
+|:----|:----|:----|
+| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码 |
+| 账号或密码错误 | 用户名或密码不正确 | 使用默认账号 `admin/123456` |
+| 账号已被锁定 | 连续登录失败超过 5 次 | 等待 5 分钟后重试 |
+| 参数校验失败 | 请求体格式错误 | 检查 JSON 格式是否正确 |
+:::
+
+ 记录 Token
+
+```
+token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+:::tip 温馨提示
+Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 `.env` 中的 `JWT_EXPIRE_MINUTES` 修改）。
+:::
+
+## 第三步：配置 Token
+
+在 Swagger UI 中配置 Token，后续请求会自动携带认证信息：
+
+1. 点击 Swagger UI 页面顶部的 `Authorize` 按钮（锁形图标）
+2. 在弹出的对话框中输入：
+
+```
+Bearer <你的token>
+```
+
+例如：
+
+```
+Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+3. 点击 `Authorize` 确认
+4. 点击 `Close` 关闭对话框
+
+:::tip 温馨提示
+配置 Token 后，Swagger UI 会在后续所有请求的 `Authorization` 请求头中自动添加 `Bearer <token>`，无需手动设置。
+:::
+
+## 第四步：调用业务接口
+
+Token 配置完成后，即可调用需要认证的业务接口。
+
+ 调用用户列表接口
+
+1. 展开 `用户管理` 分组
+2. 点击 `GET /api/v1/user/list` 接口
+3. 点击 `Try it out` 按钮
+4. 设置分页参数：
+
+```
+pageNo: 1
+pageSize: 10
+```
+
+5. 点击 `Execute` 执行请求
+
+ 成功响应
+
+```json
+{
+    "code": 0,
+    "data": [
+        {
+            "id": 1,
+            "username": "admin",
+            "realname": "超级管理员",
+            "status": 1,
+            "dept_id": 1,
+            "create_time": "2024-01-01 00:00:00"
+        }
+    ],
+    "count": 1,
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip 温馨提示
+响应中的 `data` 是用户列表数据，`count` 是总记录数。分页参数 `pageNo` 默认为 1，`pageSize` 默认为 10。
+:::
+
+## 接口调用流程图
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ 获取验证码 │────▶│ 用户登录 │────▶│ 配置 Token │────▶│ 调用业务接口 │
+│ GET /captcha │ │ POST /login │ │ Authorize │ │ GET/POST │
+└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
+ │ │ │
+ ▼ ▼ ▼
+ key JWT Token 业务数据响应
+ captcha (20分钟有效)
+```
+
+## 使用 curl 调试
+
+除了 Swagger UI，也可以使用命令行工具 `curl` 进行接口调试：
+
+```bash
+# 1. 获取验证码
+curl -X GET "http://127.0.0.1:8031/api/v1/captcha" | python -m json.tool
+
+# 2. 登录获取 Token
+curl -X POST "http://127.0.0.1:8031/api/v1/login" \
+    -H "Content-Type: application/json" \
+    -d '{
+    "username": "admin",
+    "password": "123456",
+    "captcha_code": "验证码文字",
+    "key": "获取的key"
+    }'
+
+# 3. 使用 Token 调用用户列表
+curl -X GET "http://127.0.0.1:8031/api/v1/user/list?pageNo=1&pageSize=10" \
+    -H "Authorization: Bearer <你的token>"
+```
+
+## API 响应格式说明
+
+所有接口统一返回以下 JSON 格式：
+
+```json
+// 成功响应
+{
+    "code": 0, // 状态码：0=成功，1=失败
+    "data": {}, // 业务数据
+    "msg": "操作成功", // 提示信息
+    "ok": true // 业务状态
+}
+
+// 失败响应
+{
+    "code": 1,
+    "data": null,
+    "msg": "错误信息",
+    "ok": false
+}
+
+// 分页响应
+{
+    "code": 0,
+    "data": [], // 列表数据
+    "count": 100, // 总记录数
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip HTTP 状态码
+无论业务成功或失败，HTTP 状态码始终为 `200`。业务状态通过 `code` 字段区分：`0` 表示成功，`1` 表示失败。
+:::
+
+## 常见问题
+
+ 接口返回 401 Unauthorized
+
+```
+原因：未提供 Token 或 Token 已过期
+解决：重新登录获取 Token，或检查 Swagger UI 中的 Authorize 配置
+```
+
+ 接口返回 403 Forbidden
+
+```
+原因：当前用户无该接口的访问权限
+解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置
+```
+
+ 接口返回 422 Validation Error
+
+```
+原因：请求参数校验失败
+解决：检查请求体 JSON 格式和字段是否符合接口定义
+```
+
+ Token 过期
+
+```
+原因：Token 超过有效期（默认 20 分钟）
+解决：重新登录获取新 Token，或调用 Token 刷新接口
+```
+
+## 总结
+
+本章节通过完整的登录流程演示了如何使用 Swagger UI 调试后端 API 接口：获取验证码 → 登录获取 Token → 配置认证信息 → 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。后续开发中，可以随时通过 `http://127.0.0.1:8031/docs` 查看和调试所有接口。如果遇到问题，请参见 [常见问题FAQ](/zh/volume1/faq) 章节。
@@ -0,0 +1,236 @@
+# 前端启动
+
+本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
+
+:::tip 温馨提示
+启动前端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的 `Node.js` 和 `pnpm` 安装，并已启动后端服务（参见 [后端启动](/zh/volume1/backend)）。
+:::
+
+## 前端目录结构
+
+前端源码位于项目根目录的 `ui/` 文件夹中：
+
+```
+ui/
+├── public/ # 静态资源
+├── src/
+│ ├── api/ # 接口请求封装
+│ ├── assets/ # 资源文件（图片、样式等）
+│ ├── components/ # 公共组件
+│ ├── layout/ # 布局组件
+│ ├── router/ # 路由配置
+│ ├── store/ # 状态管理（Pinia）
+│ ├── utils/ # 工具函数
+│ ├── views/ # 页面视图
+│ ├── App.vue # 根组件
+│ └── main.js # 入口文件
+├── .env.development # 开发环境变量
+├── .env.production # 生产环境变量
+├── vite.config.ts # Vite 构建配置
+├── package.json # 依赖清单
+└── tsconfig.json # TypeScript 配置
+```
+
+## 安装依赖
+
+进入前端项目目录，使用 `pnpm` 安装依赖：
+
+```bash
+# 进入前端目录
+cd ui
+
+# 安装依赖
+pnpm install
+```
+
+安装过程如下：
+
+```
+$ pnpm install
+Lockfile is up to date, resolution step is skipped
+Packages: +1200
++++++++++++++++++++++++++++++++++++++++++++++++++
+Progress: resolved 1200, reused 1200, downloaded 0, added 1200, done
+
+Done in 15.2s
+```
+
+:::tip 温馨提示
+依赖安装完毕后，在 `ui/` 目录下会生成 `node_modules` 文件夹，此文件夹包含了项目全部的前端依赖包。首次安装可能需要较长时间，请耐心等待。
+:::
+
+ 验证依赖安装
+
+```bash
+# 检查 Vue 版本
+npx vue --version
+
+# 检查 Vite 版本
+npx vite --version
+```
+
+:::tip 常见问题
+如果 `pnpm install` 失败，可尝试以下解决方案：
+
+```bash
+# 清除缓存后重新安装
+pnpm store prune
+pnpm install
+
+# 删除 node_modules 后重新安装
+rm -rf node_modules
+pnpm install
+```
+:::
+
+## 配置代理
+
+前端开发服务器通过 `Vite` 代理将 API 请求转发到后端服务。代理配置位于 `vite.config.ts` 文件中。
+
+ 开发环境变量
+
+前端开发环境的变量配置在 `.env.development` 文件中：
+
+```bash
+# 开发服务器端口
+VITE_PORT = 8001
+
+# 网站根目录
+VITE_PUBLIC_PATH = /
+
+# 跨域代理配置（指向后端服务地址）
+VITE_PROXY=[["/api","http://127.0.0.1:8031/api"]]
+
+# 接口前缀
+VITE_GLOB_API_URL_PREFIX = /api
+```
+
+:::tip 代理说明
+`VITE_PROXY` 配置项中，`/api` 是前端请求的路径前缀，`http://127.0.0.1:8031/api` 是后端服务的实际地址。前端所有以 `/api` 开头的请求都会被代理到后端的 `8031` 端口。
+:::
+
+ 修改代理地址
+
+如果后端服务运行在不同的地址或端口，需要修改 `.env.development` 中的代理配置：
+
+```bash
+# 示例：后端运行在 192.168.1.100 的 8031 端口
+VITE_PROXY=[["/api","http://192.168.1.100:8031/api"]]
+```
+
+## 启动开发服务器
+
+确保后端服务已启动后，在 `ui/` 目录下执行以下命令：
+
+```bash
+# 启动前端开发服务器
+pnpm dev
+```
+
+启动成功后，终端将输出类似以下信息：
+
+```
+$ vite
+
+ VITE v3.2.10 ready in 943 ms
+
+ ➜ Local: http://localhost:8001/
+ ➜ Network: http://192.168.1.100:8001/
+```
+
+:::tip 默认端口
+前端开发服务器默认运行在 `http://localhost:8001/`，可通过 `.env.development` 中的 `VITE_PORT` 参数修改端口。
+:::
+
+## 访问系统
+
+在浏览器中打开以下地址：
+
+```
+http://localhost:8001/
+```
+
+![](/demo/1.png)
+
+ 默认登录账号
+
+| 类型 | 账号 | 密码 | 说明 |
+|:----|:----|:----|:----|
+| 管理员 | `admin` | `123456` | 超管账号，默认拥有全部权限 |
+| 普通用户 | `admin2` | `123456` | 普通账号，具有角色权限 |
+
+:::tip 登录验证
+1. 打开登录页面后，应能看到验证码图片正常显示，说明前后端通信正常。
+2. 输入账号 `admin` 和密码 `123456`，点击登录按钮。
+3. 成功登录后将进入系统主界面，表示前后端均已正确启动。
+:::
+
+:::danger 注意事项
+如果验证码图片无法显示，请检查：
+1. 后端服务是否已启动（`http://127.0.0.1:8031`）
+2. 代理配置是否正确（`.env.development` 中的 `VITE_PROXY`）
+3. Redis 服务是否正常运行（验证码存储依赖 Redis）
+:::
+
+## 前端构建与部署
+
+ 开发环境构建
+
+```bash
+# 开发环境打包
+pnpm build:dev
+```
+
+ 生产环境构建
+
+```bash
+# 生产环境打包
+pnpm build
+```
+
+构建完成后，会在 `ui/` 目录下生成 `dist/` 文件夹，包含打包后的静态资源文件。将 `dist/` 目录部署到 `Nginx` 或其他 Web 服务器即可。
+
+ 预览构建结果
+
+```bash
+# 本地预览打包结果
+pnpm preview
+```
+
+## 常见问题
+
+ pnpm install 失败
+
+```bash
+# 清除 pnpm 缓存
+pnpm store prune
+
+# 使用淘宝镜像源
+pnpm config set registry https://registry.npmmirror.com
+pnpm install
+```
+
+ 端口被占用
+
+如果启动时报端口冲突，可修改 `.env.development` 中的 `VITE_PORT`：
+
+```bash
+VITE_PORT = 8002
+```
+
+ API 请求 404
+
+检查后端服务是否启动，以及 `.env.development` 中的 `VITE_PROXY` 代理地址是否与后端实际地址一致。
+
+ 验证码不显示
+
+```
+1. 确认后端服务已启动
+2. 确认 Redis 服务已启动并可连接
+3. 检查浏览器控制台（F12）是否有跨域错误
+4. 检查 .env 中 CORS_ALLOWED_ORIGINS 是否包含前端地址
+```
+
+## 总结
+
+本章节介绍了前端项目的完整启动流程：安装依赖 → 配置代理 → 启动开发服务器 → 访问登录页面。通过以上步骤，你已经成功将前端应用运行在本地 `8001` 端口，并使用默认账号 `admin/123456` 登录系统。下一步可以进入 [第一个接口调试](/zh/volume1/first-api) 章节，学习如何使用 Swagger UI 调试后端 API 接口。