340 lines
11 KiB
Markdown
340 lines
11 KiB
Markdown
# 后端启动
|
||
|
||
本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 `Python` + `Django 6.0` 框架，采用分层架构设计（View 层 → Service 层 → Model 层），配合 `MySQL` 数据库和 `Redis` 缓存。
|
||
|
||
:::tip 温馨提示
|
||
启动后端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的所有软件安装。
|
||
:::
|
||
|
||
## 获取源码
|
||
|
||
前往 [官方网站](https://www.djangoadmin.cn) 购买授权后，按以下步骤获取源码：
|
||
|
||
```
|
||
1. 登录官方网站，进入「个人中心」→「我的订单」页面。
|
||
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
|
||
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
|
||
4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。
|
||
```
|
||
|
||
```bash
|
||
# 进入项目根目录（以实际解压路径为准
|
||
cd DjangoAdmin_Django_NaiveVue
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
|
||
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
|
||
3. 解压后请先阅读根目录下的 `README.md` 了解项目基本信息。
|
||
4. 如需使用 Git 管理代码，可在解压后自行初始化仓库：`git init && git add . && git commit -m "init"`。
|
||
:::
|
||
|
||
项目目录结构如下：
|
||
|
||
```
|
||
├── application/ # Django 应用目录
|
||
│ ├── settings.py # 项目配置文件
|
||
│ ├── urls.py # 主路由配置
|
||
│ ├── wsgi.py # WSGI 入口
|
||
│ ├── login/ # 登录模块
|
||
│ ├── user/ # 用户管理模块
|
||
│ ├── role/ # 角色管理模块
|
||
│ ├── menu/ # 菜单管理模块
|
||
│ ├── example/ # 案例模块（示例）
|
||
│ └── ... # 其他业务模块
|
||
├── config/ # 配置模块
|
||
│ └── env.py # 环境变量读取
|
||
├── middleware/ # 中间件（登录校验、权限校验等）
|
||
├── utils/ # 工具函数（JWT、响应封装等）
|
||
├── public/ # 静态资源和上传文件目录
|
||
├── templates/ # Django 模板文件
|
||
├── ui/ # 前端源码
|
||
├── manage.py # Django 管理命令入口
|
||
├── generator.py # 代码生成器 CLI
|
||
├── .env # 环境变量配置文件
|
||
└── requirements.txt # Python 依赖清单
|
||
```
|
||
|
||
## 创建虚拟环境
|
||
|
||
建议使用 Python 虚拟环境隔离项目依赖，避免与其他项目冲突：
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境（Windows）
|
||
venv\Scripts\activate
|
||
|
||
# 激活虚拟环境（Linux / macOS）
|
||
source venv/bin/activate
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
激活虚拟环境后，终端提示符前会显示 `(venv)` 前缀，表示当前处于虚拟环境中。后续所有 `pip` 命令都应在虚拟环境下执行。
|
||
:::
|
||
|
||
## 安装依赖
|
||
|
||
进入项目根目录，使用 `pip` 安装后端依赖包：
|
||
|
||
```bash
|
||
# 安装运行时依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
:::danger 重要提示
|
||
`requirements.txt` 文件为 `UTF-16LE` 编码，在某些平台（如 Linux/macOS）上 `pip install -r requirements.txt` 可能会报错。如果遇到此问题，请先将文件转换为 `UTF-8` 编码：
|
||
|
||
```bash
|
||
# Windows (PowerShell)
|
||
Get-Content requirements.txt -Encoding Unicode | Set-Content -Encoding UTF8 requirements_utf8.txt
|
||
pip install -r requirements_utf8.txt
|
||
|
||
# Linux / macOS
|
||
iconv -f UTF-16LE -t UTF-8 requirements.txt > requirements_utf8.txt
|
||
pip install -r requirements_utf8.txt
|
||
```
|
||
:::
|
||
|
||
:::tip 温馨提示
|
||
如果网络较慢，可先配置 pip 镜像源（参见 [环境准备](/zh/volume1/environment)），或使用国内镜像临时安装：
|
||
|
||
```bash
|
||
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
|
||
```
|
||
:::
|
||
|
||
+ 验证依赖安装
|
||
|
||
```bash
|
||
# 检查 Django 是否安装成功
|
||
python -c "import django; print(django.get_version())"
|
||
6.0.3
|
||
|
||
# 检查 Django REST Framework 是否安装成功
|
||
python -c "import rest_framework; print(rest_framework.VERSION)"
|
||
3.17.1
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
依赖安装完成后，如果上述命令输出版本号，说明核心依赖已正确安装。
|
||
:::
|
||
|
||
## 配置环境变量
|
||
|
||
项目通过 `.env` 文件管理所有配置参数。首次使用需要根据实际情况修改：
|
||
|
||
```bash
|
||
# 使用文本编辑器打开 .env 文件
|
||
# Windows
|
||
notepad .env
|
||
|
||
# Linux / macOS
|
||
vim .env
|
||
```
|
||
|
||
+ 编辑 `.env` 文件
|
||
|
||
使用文本编辑器打开 `.env` 文件，修改以下关键配置：
|
||
|
||
```bash
|
||
# ============================================================
|
||
# 基础配置
|
||
# ============================================================
|
||
DJANGO_NAME=Django+NaiveUI旗舰版
|
||
DJANGO_VERSION=v3.0.0
|
||
DJANGO_DEBUG=True
|
||
DJANGO_DEMO=False # 默认值为True（演示模式），开发时请设为False
|
||
|
||
# ============================================================
|
||
# 数据库配置（根据实际情况修改）
|
||
# ============================================================
|
||
DATABASE_ENGINE="django.db.backends.mysql"
|
||
DATABASE_NAME='djangoadmin.django.naivevue'
|
||
DATABASE_HOST="127.0.0.1"
|
||
DATABASE_PORT=3306
|
||
DATABASE_USER="root"
|
||
DATABASE_PASSWORD="root" # 修改为真实密码
|
||
DATABASE_PREFIX="django_"
|
||
|
||
# ============================================================
|
||
# Redis 缓存配置（根据实际情况修改）
|
||
# ============================================================
|
||
REDIS_HOST="127.0.0.1"
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD="123456" # 修改为真实密码
|
||
REDIS_DB=0
|
||
```
|
||
|
||
:::danger 重要提示
|
||
1. `DATABASE_PASSWORD` 和 `REDIS_PASSWORD` 请填写真实的服务密码。
|
||
2. 生产环境务必设置 `DJANGO_DEBUG=False`，避免泄漏内部错误信息。
|
||
3. `DJANGO_DEMO` 代码默认值为 `True`（演示模式开启），**开发调试时必须设为 `False`**，否则所有写操作（add/update/delete/status）将返回"演示环境，暂无操作权限"。生产环境按需设置。
|
||
:::
|
||
|
||
环境变量通过 `config/env.py` 文件读取，该文件定义了所有配置项的默认值。`.env` 文件中的值会覆盖默认值。完整的环境变量列表请参见 [环境变量速查表](/zh/volume1/env-vars)。
|
||
|
||
## 初始化数据库
|
||
|
||
首次启动前，需要初始化数据库结构。项目使用 Django 的 `makemigrations` 和 `migrate` 命令管理数据库迁移。
|
||
|
||
### 第一步：创建数据库
|
||
|
||
在 `MySQL` 提示符中创建项目数据库：
|
||
|
||
```sql
|
||
-- 创建数据库（UTF-8 编码）
|
||
CREATE DATABASE `djangoadmin.django.naivevue`
|
||
DEFAULT CHARACTER SET utf8mb4
|
||
COLLATE utf8mb4_general_ci;
|
||
```
|
||
|
||
### 第二步：执行数据库迁移
|
||
|
||
```bash
|
||
# 为所有应用生成迁移文件
|
||
python manage.py makemigrations
|
||
|
||
# 执行所有迁移，创建数据表
|
||
python manage.py migrate
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`makemigrations` 会根据 `models.py` 中的模型定义自动生成迁移文件，`migrate` 会执行迁移文件创建或修改数据表结构。更多数据库相关内容请参见 [数据库初始化](/zh/volume1/database) 章节。
|
||
:::
|
||
|
||
### 第三步：导入初始数据
|
||
|
||
数据库初始数据（管理员账号、默认角色、菜单权限等）通过 SQL 脚本导入。脚本位于项目对应目录中：
|
||
|
||
```bash
|
||
# 使用 mysql 命令行导入
|
||
mysql -uroot -p djangoadmin.django.naivevue < document/mysql/djangoadmin.django.naivevue.sql
|
||
```
|
||
|
||
:::tip 种子数据说明
|
||
初始化完成后，数据库中包含以下默认数据：
|
||
|
||
| 数据 | 说明 |
|
||
|:----|:----|
|
||
| 管理员账号 | `admin` / `123456`（超级管理员，ID=1，跳过权限校验） |
|
||
| 默认角色 | 超级管理员角色 |
|
||
| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
|
||
| 数据字典 | 系统内置字典数据 |
|
||
| 系统配置 | 系统默认配置项 |
|
||
:::
|
||
|
||
## 启动后端服务
|
||
|
||
一切准备就绪后，执行以下命令启动后端服务：
|
||
|
||
```bash
|
||
# 启动 Django 开发服务器（默认 8000 端口）
|
||
python manage.py runserver
|
||
|
||
# 指定端口启动
|
||
python manage.py runserver 8080
|
||
|
||
# 指定 IP 和端口启动（允许外部访问）
|
||
python manage.py runserver 0.0.0.0:8000
|
||
```
|
||
|
||
启动成功后，终端将输出类似以下信息：
|
||
|
||
```
|
||
Watching for file changes with StatReloader
|
||
Performing system checks...
|
||
|
||
System check identified no issues (0 silenced).
|
||
September 08, 2026 - 10:00:00
|
||
Django version 6.0.3, using settings 'application.settings'
|
||
Starting development server at http://127.0.0.1:8000/
|
||
Quit the server with CTRL-BREAK.
|
||
```
|
||
|
||
:::tip 默认端口
|
||
后端服务默认监听端口为 `8000`。如需修改端口，可在启动命令中指定，如 `python manage.py runserver 8080`。
|
||
:::
|
||
|
||
## 验证后端服务
|
||
|
||
+ 测试接口连通性
|
||
|
||
使用 `curl` 或浏览器访问验证码接口：
|
||
|
||
```bash
|
||
# 测试服务是否正常响应
|
||
curl http://127.0.0.1:8000/login/captcha
|
||
```
|
||
|
||
返回类似以下 JSON 即表示服务正常运行：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"captcha": "data:image/png;base64,...",
|
||
"key": 1
|
||
},
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
+ 查看 Django Admin 后台
|
||
|
||
后端服务启动后，可以访问 Django 自带的管理后台：
|
||
|
||
```
|
||
http://127.0.0.1:8000/admin/
|
||
```
|
||
|
||
+ 查看日志输出
|
||
|
||
在终端中观察后端日志输出，确认无异常错误信息。如果出现连接数据库或 `Redis` 失败的错误，请检查 `.env` 配置和相关服务是否正常运行。
|
||
|
||
## 常见问题
|
||
|
||
+ 端口被占用
|
||
|
||
如果启动时报错 `Address already in use`，说明端口 `8000` 已被其他程序占用：
|
||
|
||
```bash
|
||
# Windows 查看端口占用
|
||
netstat -ano | findstr 8000
|
||
|
||
# Linux / macOS 查看端口占用
|
||
lsof -i :8000
|
||
```
|
||
|
||
解决方式：终止占用进程，或指定其他端口启动：`python manage.py runserver 8080`。
|
||
|
||
+ requirements.txt 安装失败
|
||
|
||
`requirements.txt` 文件为 `UTF-16LE` 编码，部分系统可能无法正确解析。参见上方"安装依赖"章节的解决方案。
|
||
|
||
+ 数据库连接失败
|
||
|
||
如果启动时报错 `Can't connect to MySQL server`，请检查：
|
||
|
||
```
|
||
1. MySQL 服务是否已启动
|
||
2. .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
|
||
3. 数据库 djangoadmin.django.naivevue 是否已创建
|
||
4. 防火墙是否放行了数据库端口
|
||
```
|
||
|
||
+ Redis 连接失败
|
||
|
||
Redis 用于存储验证码和 JWT 令牌黑名单，是项目正常运行的必需服务。如果 Redis 连接失败，请检查：
|
||
|
||
```
|
||
1. Redis 服务是否已启动
|
||
2. .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
|
||
```
|
||
|
||
## 总结
|
||
|
||
本章节介绍了后端项目的完整启动流程：获取源码 → 创建虚拟环境 → 安装依赖 → 配置环境变量 → 初始化数据库 → 启动服务。通过以上步骤，你已经成功将后端服务运行在本地 `8000` 端口。下一步可以进入 [前端启动](/zh/volume1/frontend) 章节，启动前端项目并登录系统。
|