djangoadmin-wiki/DjangoAdmin_Django_AntdVue/zh/volume1/backend.md

后端启动

本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 Python + Django 6.0 框架，采用分层架构设计（View 层 → Service 层 → Model 层），配合 MySQL 数据库和 Redis 缓存。

:::tip 温馨提示 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 :::

获取源码

前往 官方网站 购买授权后，按以下步骤获取源码：

1. 登录官方网站，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。

# 进入项目根目录（以实际解压路径为准
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 虚拟环境隔离项目依赖，避免与其他项目冲突：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（Windows）
venv\Scripts\activate

# 激活虚拟环境（Linux / macOS）
source venv/bin/activate

:::tip 温馨提示 激活虚拟环境后，终端提示符前会显示 (venv) 前缀，表示当前处于虚拟环境中。后续所有 pip 命令都应在虚拟环境下执行。 :::

安装依赖

进入项目根目录，使用 pip 安装后端依赖包：

# 安装运行时依赖
pip install -r requirements.txt

:::danger 重要提示 requirements.txt 文件为 UTF-16LE 编码，在某些平台（如 Linux/macOS）上 pip install -r requirements.txt 可能会报错。如果遇到此问题，请先将文件转换为 UTF-8 编码：

# 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 镜像源（参见 环境准备），或使用国内镜像临时安装：

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

:::

• 验证依赖安装

# 检查 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 文件管理所有配置参数。首次使用需要根据实际情况修改：

# 使用文本编辑器打开 .env 文件
# Windows
notepad .env

# Linux / macOS
vim .env

• 编辑 .env 文件

使用文本编辑器打开 .env 文件，修改以下关键配置：

# ============================================================
# 基础配置
# ============================================================
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 文件中的值会覆盖默认值。完整的环境变量列表请参见 环境变量速查表。

初始化数据库

首次启动前，需要初始化数据库结构。项目使用 Django 的 makemigrations 和 migrate 命令管理数据库迁移。

第一步：创建数据库

在 MySQL 提示符中创建项目数据库：

-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.antdvue`
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

第二步：执行数据库迁移

# 为所有应用生成迁移文件
python manage.py makemigrations

# 执行所有迁移，创建数据表
python manage.py migrate

:::tip 温馨提示 makemigrations 会根据 models.py 中的模型定义自动生成迁移文件，migrate 会执行迁移文件创建或修改数据表结构。更多数据库相关内容请参见 数据库初始化 章节。 :::

第三步：导入初始数据

数据库初始数据（管理员账号、默认角色、菜单权限等）通过 SQL 脚本导入。脚本位于项目对应目录中：

# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.django.antdvue < document/mysql/djangoadmin.django.antdvue.sql

:::tip 种子数据说明 初始化完成后，数据库中包含以下默认数据：

数据	说明
管理员账号	admin / 123456（超级管理员，ID=1，跳过权限校验）
默认角色	超级管理员角色
默认菜单	系统管理、内容管理、监控管理等菜单及权限节点
数据字典	系统内置字典数据
系统配置	系统默认配置项
:::

启动后端服务

一切准备就绪后，执行以下命令启动后端服务：

# 启动 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 或浏览器访问验证码接口：

# 测试服务是否正常响应
curl http://127.0.0.1:8000/login/captcha

返回类似以下 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 已被其他程序占用：

# 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 端口。下一步可以进入 前端启动 章节，启动前端项目并登录系统。