小蚂蚁云

特别提醒

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

教程概述

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

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	最新版	版本控制

温馨提示

详细的安装步骤请参考环境准备章节。

第二步：获取源码

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

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

bash

# 进入项目目录（以实际解压路径为准）
cd djangoadmin

温馨提示

源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
解压后请先阅读根目录下的 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.fastapi.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_SALT=your_random_secret_key_at_least_32_bytes_long

DANGER

JWT_SALT 必须配置，留空时应用会拒绝启动。生成方式：

bash

python -c "import secrets; print(secrets.token_urlsafe(48))"

3.3 初始化数据库

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

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

温馨提示

项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等数据库，对应的 SQL 脚本分别存放在 document/ 目录下的对应文件夹中（mysql/、postgresql/、sqlserver/、sqlite/、oracle/）。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考数据库初始化章节。

方式二：脚本初始化（备选）

bash

# 自动完成建库、建表、导入种子数据
python scripts/init_db.py

温馨提示

以上命令是推荐的直接执行方式，适用于所有操作系统。文档中出现的 make 命令（如 make db-init）是 Linux / macOS 系统的便捷别名，Windows 用户直接使用对应的原始命令即可（如 python scripts/init_db.py）。

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

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

3.4 启动后端服务

bash

python src/main.py

启动成功后会看到：

INFO:     Uvicorn running on http://127.0.0.1:8031 (Press CTRL+C to quit)
INFO:     Application startup complete.

温馨提示

打开浏览器访问 http://127.0.0.1:8031/docs 可查看 Swagger 交互式 API 文档。

第四步：前端启动

4.1 安装前端依赖

bash

# 进入前端目录
cd ui

# 安装依赖
pnpm install

温馨提示

如果安装速度较慢，可配置国内镜像源：

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

温馨提示

前端默认运行在 8001 端口，后端默认 8031 端口。vite.config.ts 中配置了代理，前端请求 /api/* 路径时自动转发到后端。

第五步：功能验证

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

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

第六步：新增业务模块

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

6.1 后端开发

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

models.py — 定义数据模型：

python

from sqlalchemy import Column, String, Integer, text
from core.base_db import base_db
from core.base_model import base_model
from core.config import DB_PREFIX

class Position(base_model, base_db):
    """岗位模型类"""
    __tablename__ = DB_PREFIX + "position"
    __table_comment__ = "岗位表"

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

schemas.py — 定义表单校验：

python

from pydantic import BaseModel, Field
from core.base_schemas import BaseForm

class PositionForm(BaseForm):
    """岗位创建/编辑表单"""
    name: str = Field(..., min_length=1, max_length=150, description="岗位名称")
    status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
    sort: int = Field(..., ge=0, le=99999, description="岗位排序")

class PositionStatusForm(BaseModel):
    """岗位状态更新表单"""
    id: int = Field(..., gt=0, description="岗位ID")
    status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")

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

python

from modules.system.position.models import Position
from core.base_repository import BaseRepository

class PositionRepository(BaseRepository[Position]):
    """岗位数据仓库，继承基础仓库获得通用 CRUD 能力"""
    pass

position_repo = PositionRepository(Position)

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

python

from typing import Optional
from core.base_service import BaseService
from modules.system.position.models import Position
from modules.system.position.repository import position_repo
from modules.system.user.models import User
from modules.system.user.repository import user_repo
from utils.request import parse_id_list

class PositionService(BaseService[Position]):
    """岗位业务服务类，继承基础服务获得通用 CRUD 能力"""
    # 数据访问与模型
    repo = position_repo
    model = Position
    # 分页差异点
    page_like_fields = ('name',)
    page_eq_fields = ('status',)
    page_order_by = (('sort', 'asc'),)
    # 唯一性校验
    unique_fields = {'name': '岗位名称不能重复'}

    # 删除前校验：存在用户引用该岗位时禁止删除
    def _before_delete(self, ids) -> Optional[str]:
        id_list = parse_id_list(str(ids))
        if id_list and user_repo.filter(User.position_id.in_(id_list), User.is_delete == 0).first():
            return "存在用户引用该岗位，请先调整用户岗位"
        return None

position_service = PositionService()

6.2 注册路由

在 src/api/v1/endpoints/position.py 中创建 Endpoint，然后在 src/api/v1/router.py 中注册：

python

# src/api/v1/router.py
from api.v1.endpoints import position
v1.include_router(position.router, prefix="/position", tags=["岗位管理"])

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. 在角色管理中为角色分配"岗位管理"菜单权限

温馨提示

详细的端到端教程请参考模块开发实战章节。

常见问题

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

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

温馨提示

更多问题请参考常见问题FAQ 章节。

总结

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

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

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

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

📁 文件处理

🔧 核心工具

🧩 辅助工具

教程概述

第一步：环境准备

第二步：获取源码

第三步：后端启动

3.1 安装 Python 依赖

3.2 配置环境变量

3.3 初始化数据库

3.4 启动后端服务

第四步：前端启动

4.1 安装前端依赖

4.2 启动前端开发服务器

4.3 访问系统

第五步：功能验证

第六步：新增业务模块

6.1 后端开发

6.2 注册路由

6.3 前端开发

6.4 配置菜单权限

常见问题

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

教程概述 ​

第一步：环境准备 ​

第二步：获取源码 ​

第三步：后端启动 ​

3.1 安装 Python 依赖 ​

3.2 配置环境变量 ​

3.3 初始化数据库 ​

3.4 启动后端服务 ​

第四步：前端启动 ​

4.1 安装前端依赖 ​

4.2 启动前端开发服务器 ​

4.3 访问系统 ​

第五步：功能验证 ​

第六步：新增业务模块 ​

6.1 后端开发 ​

6.2 注册路由 ​

6.3 前端开发 ​

6.4 配置菜单权限 ​

常见问题 ​

总结 ​

教程概述

第一步：环境准备

第二步：获取源码

第三步：后端启动

3.1 安装 Python 依赖

3.2 配置环境变量

3.3 初始化数据库

3.4 启动后端服务

第四步：前端启动

4.1 安装前端依赖

4.2 启动前端开发服务器

4.3 访问系统

第五步：功能验证

第六步：新增业务模块

6.1 后端开发

6.2 注册路由

6.3 前端开发

6.4 配置菜单权限

常见问题

总结