# 后端启动

本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 `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_AntdVue
```

:::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+AntDesign旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False                    # 默认值为True（演示模式），开发时请设为False

# ============================================================
# 数据库配置（根据实际情况修改）
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.antdvue'
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.antdvue`
  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.antdvue < document/mysql/djangoadmin.django.antdvue.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.antdvue 是否已创建
4. 防火墙是否放行了数据库端口
```

+ Redis 连接失败

Redis 用于存储验证码和 JWT 令牌黑名单，是项目正常运行的必需服务。如果 Redis 连接失败，请检查：

```
1. Redis 服务是否已启动
2. .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
```

## 总结

本章节介绍了后端项目的完整启动流程：获取源码 → 创建虚拟环境 → 安装依赖 → 配置环境变量 → 初始化数据库 → 启动服务。通过以上步骤，你已经成功将后端服务运行在本地 `8000` 端口。下一步可以进入 [前端启动](/zh/volume1/frontend) 章节，启动前端项目并登录系统。