342 lines
11 KiB
Markdown
342 lines
11 KiB
Markdown
# 后端启动
|
||
|
||
本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 `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
|
||
```
|
||
|
||
|
||
|
||
:::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) 章节，启动前端项目并登录系统。
|