签入版本

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) 章节，启动前端项目并登录系统。