# Redvadmin-backend

**Repository Path**: ze_1024/redvadmin-backend

## Basic Information

- **Project Name**: Redvadmin-backend
- **Description**: 这是redvadmin项目的后端，欢迎使用
Django + DRF
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-08
- **Last Updated**: 2026-01-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RedvAdmin 后端管理系统

RedvAdmin 是一个基于 Django + DRF 的现代化后台管理系统，提供完善的权限管理、用户管理、部门管理、角色管理等企业级功能。

## ✨ 特性

- 🔐 基于 JWT 的用户认证系统
- 👥 完善的 RBAC 权限管理（角色-菜单-用户）
- 🏢 多层级部门管理
- 📊 详细的操作日志记录
- 📁 文件上传管理
- 📖 Swagger API 文档自动生成
- 🌐 跨域支持（CORS）
- 🛠️ 可复用的基础模型和工具类
- 📝 完整的数据初始化脚本

## 📋 系统要求

- Python 3.9+
- MySQL 5.7+ 或 MySQL 8.0+
- pip（Python 包管理工具）

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/yourusername/redvadmin-backend.git
cd redvadmin-backend
```

### 2. 创建虚拟环境（推荐）

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

**依赖说明：**
- `Django>=4.2.7` - Web框架
- `djangorestframework>=3.14.0` - RESTful API框架
- `djangorestframework-simplejwt>=5.3.0` - JWT认证
- `django-cors-headers>=4.3.0` - 跨域支持
- `drf-yasg>=1.21.7` - Swagger文档生成
- `user-agents==2.2.0` - 用户代理解析
- `django-ipware==5.0.0` - IP地址获取
- `mysqlclient==2.2.7` - MySQL数据库驱动

### 4. 配置数据库

#### 4.1 创建数据库

```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE redvadmin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 退出
exit;
```

#### 4.2 修改数据库配置

编辑 [backend/settings.py](backend/settings.py) 文件中的数据库配置：

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'redvadmin',           # 数据库名
        'USER': 'root',                # 用户名
        'PASSWORD': 'admin123456',     # 密码（修改为你的密码）
        'HOST': 'localhost',           # 数据库地址
        'PORT': '3306',                # 端口
        'OPTIONS': {
            'charset': 'utf8mb4',
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
            'connect_timeout': 28800,
        },
        'CONN_MAX_AGE': 0,
    }
}
```

### 5. 初始化数据库

#### 5.1 执行数据库迁移

**重要：如果你使用的是 MySQL 5.7，请使用专门的迁移命令：**

```bash
# MySQL 5.7 专用迁移命令（推荐）
python manage.py migrate_mysql57
```

**或者使用标准迁移命令（MySQL 8.0+）：**

```bash
# 生成迁移文件（首次安装通常已包含）
python manage.py makemigrations

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

**说明：**
- MySQL 5.7 不支持 `RENAME COLUMN` 语法，`migrate_mysql57` 命令会自动处理这个兼容性问题
- 使用 `migrate_mysql57` 可以避免 token_blacklist 迁移报错
- 该命令会自动检测并修复列重命名问题

#### 5.2 初始化系统数据

**重要：使用 `init_all_data` 命令一键初始化所有数据**

```bash
python manage.py init_all_data
```

此命令会自动创建：
- ✅ 3个部门（RedvAdmin、运营部、技术部）
- ✅ 5个岗位（总经理、副总经理、部门经理、主管、员工）
- ✅ 3个角色（超级管理员、管理员、普通用户）
- ✅ 完整的菜单树结构（系统管理相关菜单）
- ✅ 1个超级管理员账号
- ✅ 角色-菜单权限关联

**默认管理员账号：**
- 用户名：`superadmin`
- 密码：`admin123456`

**其他初始化命令（可选）：**
```bash
# 单独初始化各模块数据
python manage.py init_departments  # 初始化部门
python manage.py init_positions    # 初始化岗位
python manage.py init_roles        # 初始化角色
python manage.py init_menus        # 初始化菜单
```

### 6. 启动开发服务器

```bash
python manage.py runserver
```

服务启动后，访问：
- 后端API：http://localhost:8000
- Swagger文档：http://localhost:8000/swagger/
- ReDoc文档：http://localhost:8000/redoc/

## 📁 项目结构

```
redvadmin-backend/
├── backend/                    # 项目配置目录
│   ├── settings.py            # 项目设置（数据库、中间件、日志等）
│   ├── urls.py                # 主URL配置
│   └── wsgi.py                # WSGI配置
├── redvadmin/                 # 主应用目录
│   ├── models/                # 数据模型
│   │   ├── user.py           # 用户模型
│   │   ├── role.py           # 角色模型
│   │   ├── menu.py           # 菜单模型
│   │   ├── department.py     # 部门模型
│   │   ├── position.py       # 岗位模型
│   │   └── operation_log.py  # 操作日志模型
│   ├── views/                 # 视图层
│   │   ├── login.py          # 登录/登出视图
│   │   ├── user.py           # 用户管理视图
│   │   ├── role.py           # 角色管理视图
│   │   ├── menu.py           # 菜单管理视图
│   │   ├── department.py     # 部门管理视图
│   │   └── file.py           # 文件上传视图
│   ├── serializers/           # 序列化器
│   ├── utils/                 # 工具类
│   │   ├── response.py       # 统一响应格式
│   │   ├── permissions.py    # 权限控制
│   │   ├── pagination.py     # 分页工具
│   │   ├── filters.py        # 过滤器
│   │   └── swagger.py        # Swagger配置
│   ├── middleware/            # 中间件
│   │   └── operation_log.py  # 操作日志中间件
│   ├── management/            # Django管理命令
│   │   └── commands/         # 自定义命令
│   │       ├── init_all_data.py      # 初始化所有数据
│   │       ├── init_departments.py   # 初始化部门
│   │       ├── init_positions.py     # 初始化岗位
│   │       ├── init_roles.py         # 初始化角色
│   │       └── init_menus.py         # 初始化菜单
│   └── migrations/            # 数据库迁移文件
├── logs/                      # 日志目录（自动创建）
│   ├── server.log            # 服务日志
│   └── error.log             # 错误日志
├── media/                     # 媒体文件目录（自动创建）
├── requirements.txt           # 项目依赖
├── manage.py                  # Django管理脚本
└── README.md                  # 项目说明文档
```

## 🔌 API 接口说明

### 认证接口

| 接口 | 方法 | 说明 | 是否需要认证 |
|------|------|------|-------------|
| `/api/login/` | POST | 用户登录 | ❌ |
| `/api/logout/` | POST | 用户登出 | ✅ |
| `/api/token/refresh/` | POST | 刷新Token | ✅ |

### 用户管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/user/` | GET | 获取用户列表 | `system:user:query` |
| `/api/sys/user/` | POST | 创建用户 | `system:user:add` |
| `/api/sys/user/{id}/` | PUT | 更新用户 | `system:user:edit` |
| `/api/sys/user/{id}/` | DELETE | 删除用户 | `system:user:remove` |
| `/api/sys/user/{id}/reset_password/` | POST | 重置密码 | `system:user:resetPwd` |

### 角色管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/role/` | GET | 获取角色列表 | `system:role:query` |
| `/api/sys/role/` | POST | 创建角色 | `system:role:add` |
| `/api/sys/role/{id}/` | PUT | 更新角色 | `system:role:edit` |
| `/api/sys/role/{id}/` | DELETE | 删除角色 | `system:role:remove` |

### 菜单管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/menu/` | GET | 获取菜单列表 | `system:menu:query` |
| `/api/sys/menu/get_menu_tree/` | GET | 获取菜单树 | `system:menu:query` |
| `/api/sys/menu/` | POST | 创建菜单 | `system:menu:add` |
| `/api/sys/menu/{id}/` | PUT | 更新菜单 | `system:menu:edit` |
| `/api/sys/menu/{id}/` | DELETE | 删除菜单 | `system:menu:remove` |

### 部门管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/dept/` | GET | 获取部门列表 | `system:dept:query` |
| `/api/sys/dept/get_dept_tree/` | GET | 获取部门树 | `system:dept:query` |
| `/api/sys/dept/` | POST | 创建部门 | `system:dept:add` |
| `/api/sys/dept/{id}/` | PUT | 更新部门 | `system:dept:edit` |
| `/api/sys/dept/{id}/` | DELETE | 删除部门 | `system:dept:remove` |

### 岗位管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/position/` | GET | 获取岗位列表 | `system:position:query` |
| `/api/sys/position/` | POST | 创建岗位 | `system:position:add` |
| `/api/sys/position/{id}/` | PUT | 更新岗位 | `system:position:edit` |
| `/api/sys/position/{id}/` | DELETE | 删除岗位 | `system:position:remove` |

### 操作日志

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/sys/operation-log/` | GET | 获取日志列表 | `system:operlog:list` |
| `/api/sys/operation-log/{id}/` | GET | 获取日志详情 | `system:operlog:query` |

### 文件管理

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/system/upload/` | POST | 上传文件 | 需认证 |
| `/system/files/` | GET | 获取文件列表 | 需认证 |
| `/system/files/{id}/delete/` | DELETE | 删除文件 | 需认证 |

## 🔒 认证说明

### 登录获取Token

```bash
POST /api/login/
Content-Type: application/json

{
  "username": "superadmin",
  "password": "admin123456"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
  }
}
```

### 使用Token访问接口

在请求头中添加 Authorization：

```bash
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```

### 刷新Token

```bash
POST /api/token/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

## 🛠️ 开发指南

### 新增模块开发流程

1. **创建模型** - 在 `redvadmin/models/` 目录下创建模型文件
2. **创建序列化器** - 在 `redvadmin/serializers/` 目录下创建序列化器
3. **创建视图** - 在 `redvadmin/views/` 目录下创建视图
4. **注册路由** - 在 `redvadmin/urls.py` 中注册路由
5. **执行迁移** - 运行 `python manage.py makemigrations` 和 `python manage.py migrate`

### 权限控制示例

```python
from rest_framework.permissions import IsAuthenticated
from redvadmin.utils.permissions import CustomPermission

class YourViewSet(ModelViewSet):
    permission_classes = [IsAuthenticated, CustomPermission]
    perms_map = {
        'list': ['system:yourmodule:query'],
        'create': ['system:yourmodule:add'],
        'update': ['system:yourmodule:edit'],
        'destroy': ['system:yourmodule:remove'],
    }
```

### 自定义响应格式

```python
from redvadmin.utils.response import success, error

def your_view(request):
    # 成功响应
    return success(data={'key': 'value'}, message='操作成功')

    # 错误响应
    return error(message='操作失败', code=400)
```

## 📦 生产部署

### 1. 修改配置

编辑 [backend/settings.py](backend/settings.py)：

```python
# 关闭调试模式
DEBUG = False

# 设置允许的主机
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']

# 修改SECRET_KEY（生成新的密钥）
SECRET_KEY = 'your-production-secret-key'
```

### 2. 收集静态文件

```bash
python manage.py collectstatic
```

### 3. 使用 Gunicorn + Nginx

#### 安装 Gunicorn

```bash
pip install gunicorn
```

#### 启动 Gunicorn

```bash
gunicorn backend.wsgi:application --bind 0.0.0.0:8000 --workers 4
```

#### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /media/ {
        alias /path/to/your/media/;
    }

    location /static/ {
        alias /path/to/your/static/;
    }
}
```

## 🐛 常见问题

### 1. MySQL 5.7 迁移语法错误

**问题描述：**
```
django.db.utils.ProgrammingError: (1064, "You have an error in your SQL syntax... near 'RENAME COLUMN `jti_hex` TO `jti`'")
```

**解决方案：**

使用专门的 MySQL 5.7 迁移命令：
```bash
python manage.py migrate_mysql57
```

这个命令会自动：
- 检测 MySQL 5.7 兼容性问题
- 使用 `CHANGE COLUMN` 代替 `RENAME COLUMN`
- 自动修复 token_blacklist 迁移问题
- 标记问题迁移为已应用

**或者手动修复（如果已经遇到错误）：**
```bash
# 运行修复脚本
python fix_migration.py

# 然后标记迁移为已应用
python manage.py migrate --fake token_blacklist 0006_auto_20171017_2113
```

详细说明请参考：
- [MYSQL57_FIX_README.md](MYSQL57_FIX_README.md) - MySQL 5.7 修复详细说明
- [DEPLOY_MYSQL57.md](DEPLOY_MYSQL57.md) - MySQL 5.7 专用部署指南

### 2. mysqlclient 安装失败

**Windows：**
- 下载预编译的 wheel 文件：https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient
- 安装：`pip install mysqlclient-xxx.whl`

**Linux：**
```bash
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
pip install mysqlclient
```

### 3. 数据库连接错误

检查以下几点：
- MySQL 服务是否启动
- 数据库名、用户名、密码是否正确
- MySQL 是否允许远程连接（如果不是 localhost）
- 防火墙是否开放 3306 端口

### 4. 权限相关问题

- 确保已执行 `python manage.py init_all_data` 初始化数据
- 检查用户是否关联了角色
- 检查角色是否关联了菜单权限

### 5. Token 过期

默认配置：
- Access Token 有效期：60分钟
- Refresh Token 有效期：1天

可在 [backend/settings.py](backend/settings.py) 中修改：

```python
SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}
```

## 📝 更新日志

### v1.1.0 (2025-10-12)
- ✨ 添加完整的 README 文档
- ✨ 优化初始化数据脚本
- ✨ 添加详细的 API 接口说明
- 🐛 修复部分已知问题

### v1.0.0 (2024-02-28)
- 🎉 初始版本发布
- ✅ 完成基础功能开发
- 📖 添加 Swagger 文档

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建新分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -am 'Add some feature'`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 📮 联系方式

- 作者：Redv
- 邮箱：redv@redvadmin.com
- Gitee：https://gitee.com/redv678

## 🙏 致谢

感谢以下开源项目：
- [Django](https://www.djangoproject.com/)
- [Django REST Framework](https://www.django-rest-framework.org/)
- [drf-yasg](https://drf-yasg.readthedocs.io/)
- [SimpleJWT](https://django-rest-framework-simplejwt.readthedocs.io/)

---

如有问题，欢迎提 Issue 或 Pull Request！