快速开始

当你第一次拉取项目、或准备把它跑起来与前端联调时，从这里开始。

本指南帮助你在 5 分钟内 完成后端服务 youlai-django（Python/Django）的启动与验证，你将完成：

• 导入数据库初始化脚本
• 配置本地 MySQL / Redis
• 启动服务并访问 Swagger
• 使用默认账号完成一次登录验证

前置条件

必需环境：

环境	版本要求	下载地址
Python	3.12+	Python官网
MySQL	5.7+ / 8.x	安装教程
Redis	7.x	安装教程

开发工具（可选）：

• PyCharm（推荐）
• Visual Studio Code + Python 插件

项目结构

youlai-django/
├── apps/                     # 业务模块
│   ├── auth/                 # 认证模块
│   ├── system/               # 系统模块（用户/角色/菜单/部门/字典/通知/日志）
│   ├── codegen/              # 代码生成模块
│   ├── file/                 # 文件上传模块
│   ├── message/              # SSE 实时通信
│   └── utils/                # 跨应用工具集
├── config/                   # 项目配置
│   ├── settings/             # 环境配置
│   │   ├── base.py           # 通用配置
│   │   ├── dev.py            # 开发配置
│   │   └── prod.py           # 生产配置
│   └── urls.py               # 全局路由
├── core/                     # 公共基础能力（异常、权限、分页、中间件等）
├── sql/                      # 数据库脚本
│   └── mysql/
│       └── youlai_admin_django.sql  # 初始化脚本
├── requirements.txt          # Python 依赖
├── docker-compose.yml         # Docker 编排
└── manage.py                 # Django 入口

安装步骤

数据库初始化

执行数据库脚本：

mysql -u root -p < sql/mysql/youlai_admin_django.sql

或通过数据库管理工具导入 sql/mysql/youlai_admin_django.sql。

配置修改

开发环境默认读取项目根目录 .env。你需要至少配置数据库与 Redis：

数据库配置：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=youlai_admin_django
DB_USER=root
DB_PASSWORD=your_password

Redis配置：

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

会话模式（可选）：

# jwt / redis-token
SESSION_TYPE=jwt

安装依赖并启动

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows
pip install -r requirements.txt
python manage.py runserver 0.0.0.0:8000

启动成功标志：

Starting development server at http://0.0.0.0:8000/

快速验证

接口文档

访问 Swagger 文档：

http://localhost:8000/api/docs/swagger/

如需 ReDoc：

http://localhost:8000/api/docs/redoc/

登录测试

使用 Swagger 或 curl 测试登录接口：

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

成功响应：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "access": "eyJhbGc...",
    "refresh": "eyJhbGc...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

前端联调

克隆前端项目

git clone https://gitee.com/youlaiorg/vue3-element-admin.git
cd vue3-element-admin

配置后端地址

修改 .env.development：

VITE_APP_API_URL=http://localhost:8000

启动前端

pnpm install
pnpm run dev

访问 http://localhost:5173，使用以下账号登录：

• 用户名：admin
• 密码：123456

迁移状态对齐（可选）

如果用 SQL 脚本初始化数据库后，后续需要修改 Django 模型，需执行：

python manage.py migrate --fake-initial

注意：需要数据库用户有 CREATE 权限，用于创建 django_migrations 表记录迁移历史。 如果数据库用户权限不足，可手动创建该表或联系管理员授权。

常见问题

端口冲突

解决方案：修改启动命令中的端口：python manage.py runserver 0.0.0.0:8001

数据库连接失败

排查步骤：

1. 确认 MySQL 服务已启动
2. 检查数据库连接配置
3. 确认数据库 youlai_admin 已创建

Redis 连接失败

排查步骤：

1. 确认 Redis 服务已启动：redis-cli ping
2. 检查 Redis 连接配置

下一步

• 部署运维 - 生产环境部署指南
• 配置说明 - 详细配置参数
• 登录认证 - 登录认证与会话管理
• 数据权限 - 数据权限配置