:::warning 特别提醒
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
:::

## 教程概述

本教程将带你从零开始，完成一个完整的后台管理系统的搭建和运行。整个过程分为以下几个步骤：

```
1. 环境准备：安装 Python、MySQL、Redis、Node.js 等基础软件。
2. 获取源码：从官方网站下载授权源码包并解压。
3. 后端启动：安装 Python 依赖、配置环境变量、初始化数据库、启动后端服务。
4. 前端启动：安装前端依赖、启动前端开发服务器。
5. 功能验证：登录系统，验证各功能模块是否正常。
6. 新增模块：以岗位管理为例，演示如何新增一个完整的业务模块。
```

## 第一步：环境准备

确保电脑上已安装以下软件：

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| Python | 3.12+ | 后端运行环境 |
| MySQL | 8.0+ | 数据库 |
| Redis | 3.2+ | 缓存（验证码、JWT黑名单、限流） |
| Node.js | 22+ | 前端构建环境 |
| pnpm | 最新版 | 前端包管理器 |
| Git | 最新版 | 版本控制 |

:::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` 了解版本更新内容。
:::

## 第三步：后端启动

### 3.1 安装 Python 依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 3.2 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env
```

编辑 `.env` 文件，配置数据库和 Redis 连接信息：

```bash
# 数据库配置
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=root
DB_PASSWORD=your_password

# Redis 配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# JWT 密钥（至少32字节）
JWT_SECRET=your_random_secret_key_at_least_32_bytes_long
```

:::danger
`JWT_SECRET` 必须配置，留空时应用会拒绝启动。生成方式：
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
:::

### 3.3 初始化数据库

**方式一：手动导入（推荐）**

```bash
# 1. 登录 MySQL，创建数据库
mysql -uroot -p
CREATE DATABASE `djangoadmin.tornado.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# 2. 导入数据库脚本（脚本位于 document/mysql/ 目录下）
mysql -uroot -p djangoadmin.tornado.elevue < document/mysql/djangoadmin.tornado.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 温馨提示
以上命令是推荐的直接执行方式，适用于所有操作系统。文档中出现的 `make` 命令（如 `make db-init`）是 Linux / macOS 系统的便捷别名，Windows 用户直接使用对应的原始命令即可（如 `python scripts/init_db.py`）。
:::

初始化完成后，数据库中包含以下默认数据：

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

### 3.4 启动后端服务

```bash
python app.py
```

启动成功后会看到：

```
INFO:     Tornado 服务启动成功 on http://127.0.0.1:8041 (Press CTRL+C to quit)
INFO:     Application startup complete.
```

:::tip 温馨提示
打开浏览器访问 `http://127.0.0.1:8041/docs` 可查看 Swagger 交互式 API 文档。
:::

## 第四步：前端启动

### 4.1 安装前端依赖

```bash
# 进入前端目录
cd ui

# 安装依赖
pnpm install
```

:::tip 温馨提示
如果安装速度较慢，可配置国内镜像源：
```bash
pnpm config set registry https://registry.npmmirror.com
```
:::

### 4.2 启动前端开发服务器

```bash
pnpm dev
```

启动成功后会看到：

```
  VITE v3.x.x  ready in xxx ms

  ➜  Local:   http://localhost:8001/
```

### 4.3 访问系统

打开浏览器访问 `http://localhost:8001`，使用默认账号登录：

```
账号：admin
密码：123456
```

:::tip 温馨提示
前端默认运行在 `8001` 端口，后端默认 `8041` 端口。`vite.config.ts` 中配置了代理，前端请求 `/api/*` 路径时自动转发到后端。
:::

## 第五步：功能验证

登录成功后，可以验证以下核心功能：

```
1. 控制台：首页仪表盘，显示系统概况。
2. 用户管理：系统管理 → 用户管理，查看用户列表、新增、编辑、删除。
3. 角色管理：系统管理 → 角色管理，管理角色和权限分配。
4. 菜单管理：系统管理 → 菜单管理，管理菜单和权限节点。
5. 数据字典：数据管理 → 字典管理，管理系统字典数据。
6. 操作日志：系统管理 → 日志管理 → 操作日志，查看操作记录。
```

## 第六步：新增业务模块

以「岗位管理」为例，演示如何新增一个完整的 CRUD 模块。

### 6.1 后端开发

在 `src/modules/position/` 目录下创建以下文件：

**models.py** — 定义数据模型：

```python
# +======================================================================
# | 模块: 岗位数据模型层
# | 说明: 定义岗位表结构，继承 BaseModel 获得通用字段与序列化能力
# +======================================================================
from sqlalchemy import Column, String, Integer, text
from config.database import DB_PREFIX
from core.base_model import BaseModel

class Position(BaseModel):
    """岗位模型"""
    __tablename__ = DB_PREFIX + "position"
    __table_args__ = {"comment": "岗位表"}

    # 岗位名称
    name = Column(String(255), nullable=False, index=True, comment="岗位名称")
    # 岗位状态：0-正常 1-停用
    status = Column(Integer, default=0, server_default=text("0"), comment="岗位状态")
    # 岗位排序
    sort = Column(Integer, default=0, server_default=text("0"), comment="岗位排序")
```

**schemas.py** — 定义表单校验：

```python
# +======================================================================
# | 模块: 岗位请求校验模型层
# | 说明: 定义岗位创建/编辑与状态更新的 Pydantic 校验模型
# +======================================================================
from pydantic import Field
from core.base_schema import BaseSchema, BaseStatusSchema

class PositionSchema(BaseSchema):
    """岗位创建/编辑表单"""
    name: str = Field(..., min_length=1, max_length=150, description="岗位名称")
    status: int = Field(default=0, ge=0, le=1, description="岗位状态")
    sort: int = Field(default=0, ge=0, le=99999, description="岗位排序")

class PositionStatusSchema(BaseStatusSchema):
    """岗位状态更新表单"""
    pass
```

**repository.py** — 定义数据访问层：

```python
# +======================================================================
# | 模块: 岗位数据访问层
# | 说明: 定义岗位仓储，继承 BaseRepository 获得通用 CRUD 与软删除能力
# +======================================================================
from core.base_repository import BaseRepository
from modules.position.models import Position

class PositionRepository(BaseRepository):
    """岗位数据仓库"""
    model = Position
```

**service.py** — 定义业务逻辑层：

```python
# +======================================================================
# | 模块: 岗位业务逻辑层
# | 说明: 定义岗位服务，声明差异点，最后导出服务单例
# +======================================================================
from core.base_service import BaseService
from modules.position.models import Position
from modules.position.repository import PositionRepository
from modules.position.schemas import PositionSchema, PositionStatusSchema

class PositionService(BaseService):
    """岗位服务"""
    # 基础声明
    model = Position
    repo_cls = PositionRepository
    create_schema = PositionSchema
    update_schema = PositionSchema
    status_schema = PositionStatusSchema
    # 分页查询字段与排序
    page_like_fields = ("name",)
    page_eq_fields = ("status",)
    page_order_by = (("sort", "asc"),)
    # 唯一性校验
    unique_fields = {"name": "岗位名称不能重复"}

# 服务单例
position_service = PositionService()
```

### 6.2 注册路由

在 `src/api/v1/position.py` 中定义路由，然后在 `src/api/v1/router.py` 中注册：

```python
# src/api/v1/position.py
from modules.position.handlers import (
    PositionPageHandler, PositionDetailHandler, PositionAddHandler,
    PositionUpdateHandler, PositionDeleteHandler, PositionStatusHandler,
    PositionBatchDeleteHandler,
)

routes = [
    (r"/position/page", PositionPageHandler),
    (r"/position/detail/(\d+)", PositionDetailHandler),
    (r"/position/add", PositionAddHandler),
    (r"/position/update", PositionUpdateHandler),
    (r"/position/delete/(\d+)", PositionDeleteHandler),
    (r"/position/status", PositionStatusHandler),
    (r"/position/batchDelete", PositionBatchDeleteHandler),
]
```

```python
# src/api/v1/router.py — 在 _RESOURCE_MODULES 列表中追加
from api.v1 import position
_RESOURCE_MODULES = [
    # ... 已有模块 ...
    position,
]
```

### 6.3 前端开发

在 `ui/src/api/system/position.ts` 中定义接口，在 `ui/src/views/system/position/` 中创建页面文件（index.vue、edit.vue、columns.ts、querySchemas.ts）。

### 6.4 配置菜单权限

在系统管理 → 菜单管理中：

```
1. 新增菜单：岗位管理（路径：/system/position，组件：system/position/index）
2. 新增按钮：查看（sys:position:page）、新增（sys:position:add）、编辑（sys:position:update）、删除（sys:position:delete）
3. 在角色管理中为角色分配"岗位管理"菜单权限
```

:::tip 温馨提示
详细的端到端教程请参考 [模块开发实战](/zh/volume2/overview) 章节。
:::

## 常见问题

在部署和使用过程中，可能会遇到以下常见问题：

```
1. 端口被占用：修改 .env 中的 TORNADO_PORT 或终止占用端口的进程。
2. 数据库连接失败：检查 .env 中的数据库配置，确认 MySQL 服务已启动。
3. Redis 连接失败：检查 Redis 服务状态和密码配置。
4. JWT_SECRET 未配置：使用 python -c "import secrets; print(secrets.token_urlsafe(48))" 生成。
5. pnpm install 失败：配置国内镜像 pnpm config set registry https://registry.npmmirror.com。
```

:::tip 温馨提示
更多问题请参考 [常见问题FAQ](/zh/volume1/faq) 章节。
:::

## 总结

通过以上步骤，你已经完成了从零搭建一个完整的后台管理系统的全过程：

```
1. 环境准备：Python + MySQL + Redis + Node.js + pnpm
2. 后端启动：pip install → 配置 .env → 初始化数据库 → python app.py
3. 前端启动：pnpm install → pnpm dev
4. 功能验证：登录系统，验证各模块功能
5. 新增模块：models → schemas → repository → service → endpoint → 前端页面 → 菜单权限
```

整个搭建过程约 30 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。