# mi-management

**Repository Path**: isycr/mi-management

## Basic Information

- **Project Name**: mi-management
- **Description**: 技术栈：nodejs+express
描述：实现小功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-16
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级 Node.js + Express + MySQL 服务器

![Node.js](https://img.shields.io/badge/node.js-v16+-green.svg)
![Express](https://img.shields.io/badge/express-v4.x-blue.svg)
![MySQL](https://img.shields.io/badge/mysql-v8.0+-orange.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

这是一个基于 Node.js、Express 和 MySQL 构建的企业级服务器应用，具备高可用性、可扩展性和安全性，适用于企业级应用的后端服务需求。

## 目录

- [项目概述](#项目概述)
- [技术栈](#技术栈)
- [架构设计](#架构设计)
- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [安装部署](#安装部署)
- [配置说明](#配置说明)
- [API 文档](#api-文档)
- [数据库设计](#数据库设计)
- [安全措施](#安全措施)
- [性能优化](#性能优化)
- [监控与日志](#监控与日志)
- [CI/CD 流程](#cicd-流程)
- [贡献指南](#贡献指南)
- [问题处理](#问题处理)
- [许可证](#许可证)

## 项目概述

本项目是一个企业级后端服务器解决方案，采用现代化的 Node.js 技术栈，提供稳定、高效、安全的 API 服务。服务器设计遵循 RESTful 架构风格，支持水平扩展，可满足从小型应用到大型企业系统的各种需求。

主要应用场景：
- 企业级 SaaS 平台后端
- 移动应用和前端应用的 API 服务
- 数据处理和业务逻辑服务
- 第三方系统集成服务

## 技术栈

- **运行环境**: Node.js (v16+)
- **Web 框架**: Express.js (v4.x)
- **数据库**: MySQL (v8.0+)
- **ORM 工具**: Sequelize
- **API 文档**: Swagger
- **身份认证**: JWT (JSON Web Tokens)
- **日志管理**: Winston, Morgan
- **测试框架**: Jest, Supertest
- **代码质量**: ESLint, Prettier
- **部署工具**: Docker, Docker Compose
- **CI/CD**: GitHub Actions

## 架构设计

本系统采用分层架构设计，确保代码的可维护性和可扩展性：

1. **路由层 (Routes)**: 处理 HTTP 请求路由
2. **控制器层 (Controllers)**: 处理请求逻辑
3. **服务层 (Services)**: 实现业务逻辑
4. **数据访问层 (Models)**: 处理数据操作
5. **中间件 (Middleware)**: 处理跨切面关注点（认证、日志等）
6. **工具层 (Utils)**: 提供通用功能和工具函数

系统架构图:
```
客户端 → 负载均衡 → API 网关 → 认证服务 → 业务服务 → 数据访问层 → 数据库
                                      ↓
                                  缓存服务
                                      ↓
                                  消息队列
```

## 功能特性

- **用户认证与授权**: 基于 JWT 的身份验证，支持角色权限管理
- **RESTful API**: 规范的 API 设计，支持版本控制
- **数据验证**: 请求数据自动验证和清洗,
- **错误处理**: 统一的错误处理机制和错误响应格式
- **数据库迁移**: 支持数据库结构版本管理
- **缓存机制**: 集成 Redis 缓存，提升性能
- **请求限流**: 防止恶意请求和 DoS 攻击
- **日志记录**: 详细的访问日志和错误日志
- **健康检查**: 系统状态监控端点
- **国际化**: 多语言支持
- **批量操作**: 支持数据批量处理
- **事务管理**: 数据库事务支持，确保数据一致性

## 环境要求

- Node.js v16.0.0 或更高版本
- npm v7.0.0 或更高版本
- MySQL v8.0.0 或更高版本
- Redis v6.0.0 或更高版本（可选，用于缓存）
- 至少 2GB RAM
- 10GB 可用磁盘空间

## 安装部署

### 本地开发环境

1. 克隆代码仓库
   ```bash
   git clone https://gitee.com/isycr/mi-management.git
   ```

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

3. 配置环境变量
   ```bash
   cp .env.example .env
   # 编辑 .env 文件，配置数据库连接等信息
   ```

4. 初始化数据库
   ```bash
   npm run db:init
   # 初始化数据库（运行迁移和种子）
   ```

5. 启动开发服务器
   ```bash
   npm run dev
   ```

6. 访问 API
   ```bash
   服务器默认运行在 http://localhost:3000
   ```

### 生产环境部署

#### Docker 部署（推荐）

1. 构建 Docker 镜像
   ```bash
   docker build -t enterprise-server:latest .
   ```

2. 使用 Docker Compose 启动服务
   ```bash
   docker-compose up -d
   ```

#### 传统部署

1. 安装 PM2 进程管理器
   ```bash
   npm install -g pm2
   ```

2. 构建项目
   ```bash
   npm run build
   ```

3. 启动服务
   ```bash
   pm2 start ecosystem.config.js --env production
   ```

4. 设置开机自启动
   ```bash
   pm2 startup
   pm2 save
   ```

## 配置说明

系统配置通过环境变量文件和配置文件管理，支持多环境配置。

### 环境变量文件

项目使用不同的环境变量文件来区分开发和生产环境：
- `.env.development` - 开发环境配置文件
- `.env.production` - 生产环境配置文件
- `.env.example` - 环境变量配置示例文件

环境变量文件需要手动创建，你可以从 `.env.example` 复制并根据需要修改：

```bash
# 开发环境
cp .env.example .env.development

# 生产环境
cp .env.example .env.production
```

开发环境环境变量示例 (`.env.development`):

```
NODE_ENV=development

# 服务器配置
PORT=3000
API_PREFIX=/api/v1
API_BASE_URL=https://api.example.com

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=mimouse_db
DB_USER=mimouse_app
DB_PASSWORD=mimouse123
DB_POOL_SIZE=10

# JWT 配置
JWT_SECRET=your_jwt_secret_key_should_be_long_and_random
JWT_EXPIRES_IN=7d
JWT_REFRESH_SECRET=your_jwt_refresh_secret_key
JWT_REFRESH_EXPIRES_IN=30d

# 日志配置
LOG_LEVEL=debug
LOG_FILE=./logs/app.log

# 缓存配置
REDIS_ENABLED=false
REDIS_HOST=localhost
REDIS_PORT=6379

# HTTPS配置
USE_HTTPS=false

# 速率限制
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100
```

### 配置文件结构

配置文件位于 `src/config/index.js`，负责从环境变量文件中读取配置并应用默认值。主要配置项包括：

- 应用环境和服务器端口
- API 前缀
- 数据库连接信息
- JWT 认证配置
- 速率限制配置
- 日志级别配置

配置模块会根据 `NODE_ENV` 自动加载对应的环境变量文件：
- 当 `NODE_ENV=development` 时，加载 `.env.development`
- 其他情况（如生产环境）加载 `.env.production`

在生产环境中，系统会自动验证关键配置（如 JWT 密钥）是否存在。

## API 文档

API 文档使用 Swagger 自动生成，访问以下地址查看完整文档：

```
http://localhost:3000/api-docs
```

主要 API 端点概览：

- `GET /api/v1/health` - 健康检查
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/register` - 用户注册
- `GET /api/v1/users` - 获取用户列表
- `GET /api/v1/users/:id` - 获取用户详情
- `PUT /api/v1/users/:id` - 更新用户信息
- `DELETE /api/v1/users/:id` - 删除用户

## 数据库设计

数据库采用 MySQL，使用 Sequelize ORM 进行管理。主要数据模型包括：

- Product (产品)
- ...

数据库迁移文件位于 `src/db/migrations/` 目录，种子文件位于 `src/db/seeders/` 目录。


常用数据库操作命令：

```bash
# 仅运行迁移脚本
npm run db:migrate

# 回滚迁移
npm run db:rollback

# 仅运行种子脚本
npm run db:seed

# 清空种子数据
npm run db:undo-seed

# 初始化数据库（运行迁移和种子）
npm run db:init

# 启动服务器并初始化数据库
npm run start:init-db
```

## 安全措施

本系统实施了多层次的安全防护措施：

1. **数据传输安全**
   - 强制使用 HTTPS
   - 敏感数据传输加密

2. **身份认证与授权**
   - 基于 JWT 的无状态认证
   - 细粒度的 RBAC 权限控制
   - 密码哈希存储 (bcrypt)

3. **API 安全**
   - 请求速率限制
   - CSRF 防护
   - 输入验证和 sanitization
   - HTTP 安全头配置

4. **数据库安全**
   - 参数化查询防止 SQL 注入
   - 最小权限原则的数据库用户
   - 敏感数据加密存储

5. **服务器安全**
   - 依赖包定期安全审计
   - 安全相关 HTTP 头配置
   - 防止常见攻击 (XSS, CSRF 等)

## 性能优化

系统采用多种性能优化策略：

1. **数据库优化**
   - 合理的索引设计
   - 查询优化
   - 数据库连接池

2. **缓存策略**
   - Redis 缓存热门数据
   - 响应缓存
   - 数据库查询缓存

3. **代码层面优化**
   - 异步非阻塞处理
   - 批量操作减少数据库交互
   - 避免不必要的计算和IO操作

4. **服务器优化**
   - 集群模式充分利用多核CPU
   - 压缩响应数据
   - 静态资源缓存

## 监控与日志

### 监控

- 系统健康检查端点: `/api/v1/health`
- 性能指标监控: 集成 Prometheus 和 Grafana
- 错误告警: 配置邮件和 Slack 通知

### 日志

- 访问日志: 使用 Morgan 记录所有 HTTP 请求
- 应用日志: 使用 Winston 记录不同级别的日志
- 日志分级: error, warn, info, verbose, debug, silly
- 日志轮转: 按大小和时间自动轮转日志文件
- 日志位置: `logs/` 目录

## CI/CD 流程

项目使用 GitHub Actions 实现持续集成和持续部署：

1. **持续集成**
   - 代码提交时自动运行 lint 检查
   - 运行单元测试和集成测试
   - 构建项目确保没有编译错误

2. **持续部署**
   - 合并到 develop 分支自动部署到测试环境
   - 合并到 main 分支自动部署到生产环境
   - 部署前自动运行安全扫描

CI/CD 配置文件位于 `.github/workflows/` 目录。

## 贡献指南

我们欢迎社区贡献，如果你想为项目贡献代码，请遵循以下流程：

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交你的修改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request

请确保你的代码符合项目的代码规范，并通过所有测试。

## 问题处理

### 常见问题

1. **数据库连接失败**
   - 检查数据库服务是否运行
   - 验证数据库连接配置
   - 检查数据库用户权限

2. **服务启动失败**
   - 检查端口是否被占用
   - 检查依赖是否安装完整
   - 查看日志文件获取详细错误信息

3. **API 响应缓慢**
   - 检查数据库查询性能
   - 查看缓存是否正常工作
   - 检查服务器资源使用情况

### 提交 Issue

如果遇到无法解决的问题，请在 GitHub 上提交 Issue，提供以下信息：

- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 错误日志
- 环境信息

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

© 2023 Your Company. 保留所有权利。