# admin-system

**Repository Path**: yyq_9086/admin-system

## Basic Information

- **Project Name**: admin-system
- **Description**: 后端管理系统：nodejs+express
- **Primary Language**: NodeJS
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Admin System

一个基于 Node.js + Express + MongoDB 的企业级后台管理系统，提供完整的用户管理、角色权限控制（RBAC）和系统管理功能。

## 功能特性

### 核心功能
- 🔐 **用户认证**：注册、登录、JWT 双令牌认证、账户锁定机制
- 👥 **用户管理**：完整的 CRUD 操作、个人资料管理、密码修改
- 🎭 **角色管理**：角色 CRUD、权限分配、角色等级
- 🔑 **权限管理**：权限 CRUD、资源操作控制、模块分组
- 📊 **仪表盘统计**：用户增长、角色分布、权限使用统计
- 🛡️ **安全特性**：Helmet 安全头、CORS 跨域保护、密码加密

### 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Express | ^5.2.1 | Web 框架 |
| Mongoose | ^9.1.5 | MongoDB ODM |
| bcryptjs | ^3.0.3 | 密码加密 |
| jsonwebtoken | ^9.0.3 | JWT 令牌认证 |
| helmet | ^8.1.0 | HTTP 安全头 |
| cors | ^2.8.5 | 跨域资源共享 |
| express-validator | ^7.3.1 | 请求验证 |

## 项目结构

```
admin-system/
├── src/
│   ├── config/
│   │   ├── database.js        # 数据库连接配置
│   │   ├── initDatabase.js    # 数据库初始化脚本
│   │   └── permission.config.js # 路由权限配置
│   ├── controllers/
│   │   ├── authController.js  # 认证控制器
│   │   ├── userController.js  # 用户控制器
│   │   ├── roleController.js  # 角色控制器
│   │   ├── permissionController.js # 权限控制器
│   │   └── adminController.js # 管理后台控制器
│   ├── middleware/
│   │   ├── authMiddleware.js  # JWT 认证中间件
│   │   ├── roleMiddleware.js  # 角色权限中间件
│   │   └── permissionGuard.js # 通用权限守卫中间件
│   ├── models/
│   │   ├── User.js            # 用户模型
│   │   ├── Role.js            # 角色模型
│   │   └── Permission.js      # 权限模型
│   ├── repositories/
│   │   ├── UserRepository.js  # 用户数据访问层
│   │   ├── RoleRepository.js  # 角色数据访问层
│   │   └── PermissionRepository.js # 权限数据访问层
│   ├── routes/
│   │   ├── authRoutes.js      # 认证路由
│   │   ├── userRoutes.js      # 用户路由
│   │   ├── roleRoutes.js      # 角色路由
│   │   ├── permissionRoutes.js # 权限路由
│   │   └── adminRoutes.js     # 管理后台路由
│   ├── services/
│   │   ├── AuthService.js     # 认证业务逻辑
│   │   ├── UserService.js     # 用户管理业务逻辑
│   │   ├── RoleService.js     # 角色管理业务逻辑
│   │   ├── PermissionService.js # 权限管理业务逻辑
│   │   └── AdminService.js    # 管理后台业务逻辑
│   ├── utils/
│   │   ├── response.js        # 统一响应工具
│   │   ├── errors.js          # 错误处理类
│   │   ├── asyncHandler.js    # 异步处理包装器
│   │   ├── queryBuilder.js    # 查询构建工具
│   │   ├── validators.js      # 验证工具
│   │   └── jwt.js             # JWT 工具
│   └── app.js                 # Express 应用配置
├── .env.example               # 环境变量示例
├── server.js                  # 服务入口
└── package.json               # 项目依赖
```

## 快速开始

### 环境要求
- Node.js >= 16.0.0
- MongoDB >= 4.4

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-username/admin-system.git
cd admin-system
```

2. **安装依赖**
```bash
npm install
```

3. **配置环境变量**
```bash
cp .env.example .env
```

编辑 `.env` 文件，配置数据库连接和 JWT 密钥：
```env
PORT=3000
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/admin-system
JWT_SECRET=your-super-secret-jwt-key
JWT_REFRESH_SECRET=your-super-secret-refresh-key
```

4. **启动服务**
```bash
npm start
```

服务将在 `http://localhost:3000` 启动。

### 默认账户

首次启动会自动创建默认超级管理员账户：
- 用户名：`admin`
- 邮箱：`admin@example.com`
- 密码：`admin123456`

⚠️ **请在生产环境中立即修改默认密码！**

## API 文档

### 认证模块 `/api/auth`

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| POST | `/register` | 用户注册 | ❌ |
| POST | `/login` | 用户登录 | ❌ |
| POST | `/refresh-token` | 刷新令牌 | ❌ |
| POST | `/logout` | 退出登录 | ✅ |
| GET | `/me` | 获取当前用户信息 | ✅ |

### 用户模块 `/api/users`

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| GET | `/list` | 获取用户列表（分页） | ✅ |
| GET | `/profile` | 获取个人资料 | ✅ |
| PUT | `/profile` | 更新个人资料 | ✅ |
| PUT | `/profile/password` | 修改个人密码 | ✅ |
| GET | `/:id` | 获取用户详情 | ✅ |
| POST | `/` | 创建用户 | ✅ |
| PUT | `/:id` | 更新用户 | ✅ |
| DELETE | `/:id` | 删除用户 | ✅ |
| POST | `/batch-delete` | 批量删除用户 | ✅ |
| PUT | `/:id/status` | 更新用户状态 | ✅ |
| PUT | `/:id/reset-password` | 重置用户密码 | ✅ |
| PUT | `/:id/unlock` | 解锁用户 | ✅ |

### 角色模块 `/api/roles`

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| GET | `/list` | 获取角色列表 | ✅ |
| GET | `/active` | 获取活跃角色 | ✅ |
| GET | `/:id` | 获取角色详情 | ✅ |
| GET | `/:id/users` | 获取角色下的用户 | ✅ |
| POST | `/` | 创建角色 | ✅ |
| PUT | `/:id` | 更新角色 | ✅ |
| DELETE | `/:id` | 删除角色 | ✅ |
| PUT | `/:id/status` | 更新角色状态 | ✅ |
| PUT | `/:id/permissions` | 分配权限 | ✅ |
| POST | `/:id/permissions` | 添加单个权限 | ✅ |
| DELETE | `/:id/permissions/:permissionId` | 移除单个权限 | ✅ |

### 权限模块 `/api/permissions`

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| GET | `/list` | 获取权限列表 | ✅ |
| GET | `/active` | 获取活跃权限 | ✅ |
| GET | `/by-module` | 按模块分组获取 | ✅ |
| GET | `/by-resource` | 按资源分组获取 | ✅ |
| GET | `/:id` | 获取权限详情 | ✅ |
| GET | `/:id/roles` | 获取权限关联的角色 | ✅ |
| POST | `/` | 创建权限 | ✅ |
| POST | `/batch` | 批量创建权限 | ✅ |
| PUT | `/:id` | 更新权限 | ✅ |
| DELETE | `/:id` | 删除权限 | ✅ |
| PUT | `/:id/status` | 更新权限状态 | ✅ |

### 管理后台模块 `/api/admin`

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| GET | `/dashboard` | 仪表盘统计数据 | ✅ |
| GET | `/stats/user-growth` | 用户增长统计 | ✅ |
| GET | `/stats/role-distribution` | 角色分布统计 | ✅ |
| GET | `/stats/permission-usage` | 权限使用统计 | ✅ |
| GET | `/health` | 系统健康状态 | ✅ |

## 查询参数

### 分页参数
- `page`: 页码（默认 1）
- `limit`: 每页数量（默认 10，最大 100）

### 搜索参数
- `search`: 搜索关键词（支持模糊搜索）

### 排序参数
- `sortBy`: 排序字段
- `sortOrder`: 排序方向（asc/desc）

### 筛选参数
- `status`: 状态筛选
- `role`: 角色筛选

### 示例
```
GET /api/users/list?page=1&limit=20&search=john&status=active&sortBy=createdAt&sortOrder=desc
```

## 权限系统

### RBAC 模型
```
User ──┐
       │ belongs to
       ▼
     Role ──┐
             │ has many
             ▼
        Permission
```

### 权限中间件使用

```javascript
const { checkPermission, checkRole, isAdmin } = require('./middleware/roleMiddleware');

// 检查特定权限
router.post('/', authMiddleware, checkPermission('user', 'create'), userController.createUser);

// 检查角色
router.delete('/:id', authMiddleware, checkRole('ADMIN', 'SUPER_ADMIN'), userController.deleteUser);

// 检查是否为管理员
router.get('/dashboard', authMiddleware, isAdmin(), adminController.getDashboardStats);
```

## 响应格式

### 成功响应
```json
{
  "success": true,
  "message": "操作成功",
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### 分页响应
```json
{
  "success": true,
  "message": "获取成功",
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### 错误响应
```json
{
  "success": false,
  "message": "错误信息",
  "code": "ERROR_CODE",
  "errors": [ ... ]
}
```

## 开发指南

### 开发模式
```bash
npm run dev
```

### 代码规范
- 使用 ESLint 进行代码检查
- 遵循 Airbnb JavaScript 风格指南

## 部署

### Docker 部署
```bash
docker build -t admin-system .
docker run -p 3000:3000 admin-system
```

### PM2 部署
```bash
pm2 start server.js --name admin-system
```

## 安全建议

1. **生产环境必须修改默认密码**
2. **使用强密码作为 JWT 密钥**
3. **启用 HTTPS**
4. **配置防火墙规则**
5. **定期备份数据库**
6. **启用日志审计**

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！