🏗️ 系统架构

Vue Pure Admin + NestJS 全栈架构设计文档

📐 分层架构总览

系统采用 前后端分离 架构，前端 Vue 3 + Vite，后端 NestJS，数据库 MySQL + Redis 缓存。

┌─────────────────────────────────────────────────────────────────────────┐
│                        【客户端层 — Client Layer】                       │
│  ┌─────────────────────┐  ┌───────────────────┐  ┌───────────────────┐ │
│  │  浏览器 (Chrome)   │  │  API 客户端        │  │  Swagger UI       │ │
│  │  localhost:8848       │  │  (Postman / Axios)  │  │  :3001/api-docs   │ │
│  └─────────┬───────────┘  └─────────┬─────────┘  └─────────┬─────────┘ │
└────────────┼────────────────────────┼──────────────────────┼──────────┘
             │                        │                      │
             ▼                        ▼                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                  【网关层 — Gateway Layer  (Plan)                  │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │   Nginx / Caddy — 反向代理 · 负载均衡 · HTTPS · 静态资源      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                  【前端层 — Frontend  Vue 3 + Vite】                       │
│  ┌───────────┐  ┌───────────┐  ┌────────────┐  ┌───────────────────┐ │
│  │ Vue Router │  │  Pinia     │  │ Element Plus │  │ Axios (拦截器)     │ │
│  │ 动态路由    │  │ 状态管理   │  │ 60+ 组件    │  │ JWT 注入 · 刷新    │ │
│  └───────────┘  └───────────┘  └────────────┘  └───────────────────┘ │
│  ┌─────────────────┐  ┌─────────────┐  ┌──────────────────────────┐  │
│  │ Vue I18n        │  │  Echarts     │  │ 权限指令 (v-permission) │  │
│  │ 中/英 国际化    │  │ 数据可视化   │  │ 按钮级权限              │  │
│  └─────────────────┘  └─────────────┘  └──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
             │ HTTP · Bearer JWT · JSON
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                 【后端层 — Backend  NestJS 11】                          │
│                                                                         │
│  ┌──────────────────────────── 请求入口 ────────────────────────────┐  │
│  │ → CORS          → Helmet          → ThrottlerGuard         │  │
│  │   跨域白名单       安全头           全局限流 (60次/60s)              │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                              │                                          │
│  ┌────────────────────────── 中间件 ─────────────────────────────────┐  │
│  │ → Pino Logger   → JwtAuthGuard   → RolesGuard    → ValidationPipe   │  │
│  │   结构化日志        JWT 鉴权         角色权限          DTO 校验        │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                              │                                          │
│  ┌───────────────────────── 业务处理 ────────────────────────────────┐  │
│  │                                                                   │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │  │
│  │  │ Auth      │  │ User      │  │ Role      │  │ Menu      │        │  │
│  │  │ 登录/刷新 │  │ 用户CURD  │  │ 角色CURD  │  │ 菜单CURD  │        │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │  │
│  │  │ Dept      │  │ Log       │  │ Dict      │  │ Mine      │        │  │
│  │  │ 部门管理  │  │ 操作日志  │  │ 字典管理  │  │ 个人信息  │        │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                              │                                          │
│  ┌────────────────────────── 响应出口 ──────────────────────────────┐  │
│  │ → TransformInterceptor    → LoggingInterceptor            │  │
│  │   统一响应 {code,data,msg}     请求耗时 · 参数记录                     │  │
│  │                         → PinoExceptionFilter                    │  │
│  │                           结构化异常 · 错误归类                         │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
┌────────┐ ┌──────┐ ┌──────────┐
│ MySQL 8 │ │Redis 7│ │ 文件存储   │
│ TypeORM│ │ioredis│  │ (待定)    │
│  9 张表 │ │ 缓存  │  │ MinIO/OSS │
└────────┘ └──────┘ └──────────┘

🔄 请求生命周期

一个完整的 API 请求在 NestJS 后端经历的完整链路：

1
客户端发起请求 浏览器 / Postman 发送 HTTP 请求，Header 携带 Authorization: Bearer <JWT>
2
CORS + Helmet 安全过滤 校验请求来源是否在 CORS 白名单内；Helmet 添加安全响应头（防 XSS/CSRF）
3
ThrottlerGuard 限流检查 全局限流：同一 IP 每 60 秒最多 60 次请求，超出返回 429 Too Many Requests
4
Pino Logger 请求日志 记录请求方法、URL、参数、来源 IP，生成唯一 traceId
5
JwtAuthGuard 鉴权 解析 JWT Token → 验证签名/有效期 → 注入 req.user（userId + username）
6
RolesGuard 权限校验 读取 @Roles() 装饰器声明的角色 → 对比 req.user.roles → 无权限返回 403
7
ValidationPipe 参数校验 对 DTO 使用 class-validator 装饰器校验 → 自动 trim/转换类型 → 不合法返回 400
8
Controller → Service → Repository Controller 解析路由参数 → Service 处理业务逻辑 → TypeORM Repository 执行 SQL
9
Interceptors 响应包装 TransformInterceptor 统一封装为 { success, data, message } 格式
10
Pino 响应日志 + 异常捕获 记录响应耗时、状态码；异常时 PinoExceptionFilter 结构化记录错误上下文

🔐 RBAC 数据模型

基于 用户 — 角色 — 菜单 三级模型的权限控制体系：

┌─────────────────────── RBAC 权限模型 ───────────────────────┐
│                                                             │
│    ┌──────────┐     N:M      ┌──────────┐     N:M      ┌──────────┐
│    │  User    │◄──────────►│  Role    │◄──────────►│  Menu    │
│    │──────────│  user_role │──────────│  role_menu │──────────│
│    │ id       │             │ id       │             │ id       │
│    │ username │             │ name     │             │ name     │
│    │ password │             │ code     │             │ path     │
│    │ nickname │             │ status   │             │ icon     │
│    │ status   │             │ remark   │             │ type     │
│    └──────────┘             └──────────┘             │ parentId │
│         │                                            │ sort     │
│         │ 1:N                                        │ visible  │
│         ▼                                            │ keepAlive│
│    ┌──────────┐                                      └──────────┘
│    │  Dept    │                                            │
│    │──────────│                                      ┌──────────┐
│    │ id       │                                      │  Log     │
│    │ name     │                                      │──────────│
│    │ parentId │                                      │ 操作日志 │
│    │ sort     │                                      └──────────┘
│    └──────────┘
│                                     ┌──────────┐  ┌──────────┐
│    ┌──────────┐  ┌──────────┐         │ DictType │  │ DictData │
│    │ UserRole │  │ RoleMenu │         │──────────│  │──────────│
│    │userId   │  │roleId   │         │ 字典类型 │  │ 字典数据 │
│    │roleId   │  │menuId   │         └──────────┘  └──────────┘
│    └──────────┘  └──────────┘
│                                                             │
└─────────────────────────────────────────────────────────────┘

📦 后端模块图谱

AppModule根模块，组装所有子模块
ConfigModule全局配置中心 (.env + YAML)
TypeOrmModuleMySQL / SQLite ORM 连接
DatabaseModule注册 9 个实体 Repository
AuthModule登录 / 刷新 Token / JWT 策略
UserModule用户 CRUD · 分配角色
RoleModule角色 CRUD · 分配菜单
MenuModule菜单树 · 按钮权限
DeptModule部门树管理
DictModule字典类型 + 字典数据
LogModule操作日志记录 / 清空
MineModule个人信息修改 / 密码重置
MapModule地图服务 (预留)
RedisModuleioredis · 全局缓存服务
LoggerModulePino · 结构化日志
ThrottlerModule全局限流 (60次/60s)

🐳 Docker 环境拓扑

项目提供 开发 和 生产 两套 Docker 编排方案，新成员 docker compose up -d 即可一键启动完整环境。

┌────────────────────── Docker 开发环境 (docker-compose.yml) ──────────────────────┐
│                                                                                   │
│   localhost:3001         localhost:3306         localhost:6379
│        │                       │                       │
│        ▼                       ▼                       ▼
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  │ vpa-server      │    │ vpa-mysql       │    │ vpa-redis       │
│  │ NestJS 11       │    │ MySQL 8.0       │    │ Redis 7          │
│  │ Dockerfile       │    │ utf8mb4          │    │ AOF 持久化       │
│  │ 端口 3001         │    │ 端口 3306         │    │ 端口 6379         │
│  │ healthcheck ✓    │    │ healthcheck ✓    │    │ healthcheck ✓    │
│  └───────────────┘    └───────────────┘    └───────────────┘
│        │                       │                       │
│  ┌─────┴─────────────┐  ┌──────┴────────┐  ┌───────┴───────┐
│  │ app-uploads 卷     │  │ mysql-data 卷  │  │ redis-data 卷 │
│  └───────────────────┘  └───────────────┘  └───────────────┘
│                   ──── vpa-network (bridge) ────
│
└───────────────────────────────────────────────────────────────────────────────────┘

┌────────────────────── Docker 生产环境 (docker-compose.prod.yml) ──────────────────┐
│                                                                                   │
│   https://your-domain.com
│        │
│        ▼
│  ┌──────────────────────────────────────────────────────────────┐
│  │ vpa-nginx-prod  (Nginx Alpine)                             │
│  │ :80 → 301 → :443   SSL 终止   Gzip   限流   反向代理         │
│  └──────────────────────────────────────────────────────────────┘
│        │ proxy_pass http://vpa-server-prod:3001
│        ▼
│  ┌────────────────────────┐    ┌────────────────────────┐
│  │ vpa-server-prod        │    │ vpa-redis-prod         │
│  │ Dockerfile.prod        │    │ Redis 7 · AOF · 密码   │
│  │ 多阶段构建              │    │ maxmemory 512mb        │
│  │ 非 root 用户            │    │ LRU 淘汰策略           │
│  │ 资源限制 CPU/Mem        │    └────────────────────────┘
│  └────────────────────────┘
│        │
│        │ 外部 MySQL（不在 compose 内）
│        ▼
│  ┌────────────────────────┐
│  │ 生产 MySQL 实例          │
│  │ 独立部署 / RDS 云数据库   │
│  └────────────────────────┘
│
└───────────────────────────────────────────────────────────────────────────────────┘

🤝 协同开发规范

多人协作时的代码风格与工具链约定：

配置项文件作用
编辑器统一 .editorconfig 缩进 2 空格、UTF-8、LF 换行 — 跨 IDE 统一
代码格式化 .prettierrc.js 单引号、尾逗号、100 字符换行 — pnpm run format
ESLint eslint.config.mjs TypeScript 规范 — pnpm run lint
Docker 开发 docker-compose.yml 新成员无需安装 MySQL/Redis，一行命令启动
环境变量 .env / .env.production.example 开发与生产分离，敏感配置不入库
包管理器 pnpm-lock.yaml 锁定依赖版本，统一用 pnpm

📥 新成员 5 分钟上手

# 1. 克隆项目 git clone <repo-url> vue-pure-admin-server cd vue-pure-admin-server # 2. 安装 pnpm（如未安装） npm install -g pnpm # 3. 安装依赖 pnpm install # 4. 复制环境变量（开发用） cp .env .env.development # 或直接使用已有的 .env # 5. 启动 Docker 基础设施（MySQL + Redis） docker compose up -d mysql redis # 6. 启动后端开发服务器 pnpm run start:dev # → http://localhost:3001 (首页) # → http://localhost:3001/api-docs (Swagger) # 7. 执行种子数据（首次） node scripts/seed.js

🚀 上线前准备清单

按类别列出的生产环境部署检查项，勾选即确认。

📝 代码质量

  • ESLint 零错误 (pnpm run lint)
  • TypeScript 严格模式编译通过 (nest build)
  • 无 console.log 残留（使用 Pino 日志）
  • 单元测试通过 (pnpm run test) 覆盖率 ≥ 60%
  • 代码已合并到主分支，无未解决的 MR/PR

🔒 安全加固

  • JWT_SECRET 更换为 ≥ 32 位随机强密码
  • CORS origin 白名单限定为生产域名
  • Helmet 安全头已启用（防 XSS / Clickjacking / MIME sniffing）
  • ThrottlerGuard 限流参数针对生产调优（建议 30次/60s）
  • 密码 bcrypt saltRounds ≥ 10
  • .env 文件已加入 .gitignore，不提交到仓库
  • 敏感接口（登录/注册）增加额外限流保护

🗄️ 数据库

  • 生产数据库 synchronize: false（已在代码中固定）
  • SQL 迁移脚本已就绪（scripts/ 目录下的 *.sql）
  • 数据库连接池参数已优化（默认 10 连接，按需调整）
  • 数据库定时备份脚本已配置（建议每日凌晨全量备份）
  • 生产数据库密码不同于开发环境

⚡ Redis

  • requirepass 已设置强密码
  • 持久化策略已配置：RDB + AOF（appendonly yes）
  • maxmemory-policy allkeys-lru 内存淘汰策略
  • 生产 Redis 绑定内网 IP，未暴露公网

📦 构建 & 部署

  • pnpm run build 生产构建成功，产物在 dist/
  • Node.js 版本已锁定（22.x LTS），生产环境一致
  • 已有 Dockerfile + Dockerfile.prod 多阶段构建
  • 已有 docker-compose.yml（开发）和 docker-compose.prod.yml（生产）
  • 已有 ecosystem.config.js PM2 集群模式配置
  • 已有 deploy.sh 一键部署脚本（Docker / PM2 / 回滚）
  • 已有 nginx/ 反向代理配置（HTTPS + 负载均衡 + Gzip）
  • 生产 .env.production 中 [CHANGE_ME] 已替换为真实值
  • 健康检查端点 GET /api/health 可访问（需实现）

📊 日志 & 监控

  • Pino 日志级别设为 info（生产不输出 debug）
  • 日志输出到文件 / 集中收集平台（ELK / Loki）
  • 异常告警已配置（钉钉 / 飞书 / 邮件）
  • 接口响应时间监控（> 3s 告警）
  • 进程内存 / CPU 监控已配置

⚙️ 环境变量

  • 已有 .env.production 模板文件
  • 生产环境 NODE_ENV=production
  • 数据库连接、Redis、JWT 均使用环境变量注入
  • 敏感配置使用密钥管理服务（Vault / K8s Secret）

📋 文档 & 上线验证

  • Swagger API 文档更新至最新版本
  • 上线 checklist 填入实际日期和执行人
  • 回滚方案已准备（数据库快照 / 上一版本 Docker 镜像）
  • 灰度发布策略已确定（按比例 / 按用户）

⚡ 快速上线命令参考

# ========== 方式一：Docker 一键部署（推荐） ========== # 1. 准备生产配置（首次） cp .env.production.example .env.production # 编辑 .env.production，替换所有 [CHANGE_ME] 项 # 2. 一键部署 docker compose -f docker-compose.prod.yml up -d --build # 3. 查看状态 docker compose -f docker-compose.prod.yml ps docker compose -f docker-compose.prod.yml logs -f # ========== 方式二：deploy.sh 部署脚本 ========== chmod +x deploy.sh ./deploy.sh docker # Docker 部署 ./deploy.sh pm2 # PM2 部署 ./deploy.sh rollback # 回滚 # ========== 方式三：PM2 手动部署 ========== pnpm install --frozen-lockfile pnpm run build pm2 start ecosystem.config.js --env production pm2 save pm2 startup # ========== 方式四：本地 Docker 开发环境 ========== docker compose up -d # 一键启动 MySQL + Redis + NestJS docker compose down # 停止 docker compose logs -f app # 查看后端日志 # ========== 验证服务 ========== curl http://localhost:3001/ curl http://localhost:3001/api-docs # Swagger 文档
← 返回首页