WlAdmin 全栈管理系统（中后台）基于 Monorepo + Turbo 架构的现代化全栈管理系统，包含Web前端（

WL-Admin v1.x

全栈管理系统 - Monorepo + Turbo 架构企业级解决方案

项目介绍

一个基于 Monorepo + Turbo 架构的现代化全栈管理系统，包含 Web前端、移动端App、后端服务 和 文档网站 四端应用，支持 Docker 容器化部署。后端提供 JWT 认证、审计日志与在线用户、SSE 实时通知、单点登录、二维码扫码登录；前端提供动态权限路由与增强版 SSE Hook；移动端支持二维码扫码登录、头像上传等功能；文档网站提供完整的项目文档、代码高亮、全文搜索等功能。采用 PNPM 管理依赖，支持并行构建和智能缓存。

在线访问

Web前端：wladmin.cn
后端API：admin.liyq666.top/api/doc/
文档网站：www.wladmin.cn
移动端App：wladmin.cn/app

项目实例

项目特性

🏗️ Monorepo + Turbo 架构

Turbo 2.0.6 - 高性能并行构建系统
PNPM 10.24.0 - 快速、节省磁盘空间的包管理器
智能缓存 - 增量构建和依赖图优化
并行执行 - 多应用同时构建，提升开发效率

🚀 Docker 容器化部署

auto-deploy.sh - 全自动部署脚本，支持版本管理
前端版本管理 - 语义化版本控制，软链接切换
容器分离架构 - Backend、MySQL、Redis 独立容器
数据持久化 - 完整的数据备份和恢复机制

后端能力

JWT 双 Token 认证与权限控制（Access/Refresh）
审计日志与来源采集（Referer、X-Client-Page），列表与详情查询
在线用户接口（基于审计窗口聚合，含来源页面、设备信息、会话信息）
单点登录（SINGLE_LOGIN），登录时保留当前会话并清退其他会话；通过 SSE 发送下线通知
SSE 实时通知（认证连接），心跳与连接统计；支持稳定客户端标识 clientId
二维码扫码登录（App扫描Web端二维码实现快速登录）
统一日志与请求 ID，中间件记录请求信息与敏感脱敏
Token 管理与自动清理
CORS 允许自定义头：X-Client-Id、X-Client-Page、X-Client-Type、X-File-Hash

文档网站能力

Markdown 渲染 - 支持 GitHub Flavored Markdown，自动生成目录（TOC）
代码高亮 - 基于 rehype-pretty-code，支持暗色/亮色主题切换
全文搜索 - 基于 Fuse.js 的模糊搜索，支持分类和文件名显示
响应式设计 - 适配桌面端和移动端，支持侧边栏折叠
主题切换 - 支持暗色/亮色主题，自动跟随系统设置
代码复制 - 一键复制代码块内容
SEO 优化 - 自动生成 sitemap 和 robots.txt
文档分类 - 快速上手、React前端、RN移动端、Node服务端、功能组件、扩展开发

Web前端能力

React 18 + Antd 6 + Webpack 5 + Redux Toolkit + React Router 6
动态权限路由（后端返回菜单动态注册）与按钮级权限
增强版 useSSE Hook：自动认证、自动重连、心跳与事件订阅、稳定 clientId 持久化（localStorage）
基础布局 BasicLayout 集成 SSE 事件（open/welcome/heartbeat/loginout），收到登录异常通知后自动退出
模块化消息管理 - useEventBus + useNotifier 事件总线架构
二维码登录页面（支持App扫码登录）

移动端App能力

React Native 0.81.5 + Expo 54 + TypeScript
二维码扫码登录（扫描Web端二维码实现快速登录）
用户信息管理（头像上传、个人信息展示）
设备信息采集（品牌、型号、操作系统版本等）
EAS Build 构建（支持iOS和Android）
Expo Router 文件路由系统

🎨 全局自动格式化

Prettier 3.3.3 - 统一的代码格式化工具
EditorConfig - 编辑器统一配置（缩进、换行符等）
ESLint 9.39.1 - 代码质量检查与自动修复
Husky + lint-staged - Git 提交前自动格式化
VSCode 集成 - 保存时自动格式化
统一缩进规则 - 默认 2 个空格，JS/TS/JSX/TSX 文件 4 个空格

📁 项目结构

Monorepo + Turbo 架构

project-root/                              # 项目根目录
├── apps/                                 # 应用程序
│   ├── react-antd-webpack/             # React Web前端应用
│   │   ├── build/                      # Webpack 构建配置
│   │   ├── public/                     # 静态资源
│   │   ├── src/                        # 源代码
│   │   │   ├── components/             # 通用组件
│   │   │   ├── hooks/                  # 自定义 Hooks
│   │   │   ├── layouts/                # 布局组件
│   │   │   ├── pages/                  # 页面模块
│   │   │   │   ├── architecture/       # 系统架构页面
│   │   │   │   ├── home/               # 首页
│   │   │   │   ├── login/              # 登录页面（含二维码登录）
│   │   │   │   └── setting/            # 系统设置
│   │   │   ├── router/                 # 路由配置
│   │   │   ├── services/               # API 服务
│   │   │   ├── store/                  # 状态管理
│   │   │   └── utils/                  # 工具函数
│   │   ├── docs/                       # 前端文档
│   │   └── package.json               # 前端依赖配置
│   ├── app-rn-ts/                      # React Native 移动端应用
│   │   ├── app/                        # Expo Router 路由目录
│   │   │   ├── (tabs)/                 # Tab导航页面
│   │   │   ├── login.tsx              # 登录页面
│   │   │   └── scan.tsx                # 二维码扫描页面
│   │   ├── src/                        # 源代码
│   │   │   ├── components/            # 组件
│   │   │   ├── services/              # API服务
│   │   │   ├── utils/                 # 工具函数
│   │   │   └── config/                # 配置文件
│   │   ├── assets/                     # 静态资源
│   │   ├── docs/                       # 移动端文档
│   │   ├── eas.json                    # EAS Build配置
│   │   └── package.json               # 移动端依赖配置
│   ├── node-express-mysql/             # Node.js 后端应用
│   │   ├── config/                    # 配置管理
│   │   ├── docs/                      # 后端文档
│   │   ├── public/                    # 静态资源
│   │   ├── sql/                       # 数据库脚本
│   │   ├── src/                        # 源代码
│   │   │   ├── cache/                 # 缓存服务
│   │   │   ├── controllers/           # 控制器
│   │   │   ├── infra/                 # 基础设施
│   │   │   ├── logger/                # 日志模块
│   │   │   ├── middlewares/           # 中间件
│   │   │   ├── models/                # 数据模型
│   │   │   ├── routes/                # 路由
│   │   │   ├── services/              # 业务服务
│   │   │   └── utils/                 # 工具函数
│   │   └── package.json               # 后端依赖配置
│   └── doc-next-ts/                    # Next.js 文档网站应用
│       ├── src/                        # 源代码
│       │   ├── app/                   # Next.js App Router
│       │   ├── components/            # 公共组件
│       │   ├── content/               # Markdown 文档内容
│       │   │   └── docs/              # 文档分类目录
│       │   │       ├── started/       # 快速上手
│       │   │       ├── frontend/      # React前端
│       │   │       ├── app/           # RN移动端
│       │   │       ├── backend/       # Node服务端
│       │   │       ├── function/      # 功能组件
│       │   │       └── extended/      # 扩展开发
│       │   ├── lib/                   # 工具函数库
│       │   ├── hooks/                 # 自定义 Hooks
│       │   └── styles/                # 全局样式
│       ├── public/                     # 静态资源
│       └── package.json               # 文档站依赖配置
├── docker_project/                      # Docker 部署配置
│   ├── docker-compose.yml             # 应用服务配置
│   ├── docker-compose/                # 基础设施服务
│   │   ├── docker-compose.yml        # MySQL + Redis
│   │   └── db-data/                  # 数据库数据目录
│   │       └── sqlinit/              # 数据库初始化脚本
│   │           ├── README.md         # 初始化脚本说明
│   │           ├── 建表.sql          # 创建所有核心数据表
│   │           ├── 监控数据相关表.sql # 监控功能数据表
│   │           ├── 省市区数据.sql    # 全国省市区地理数据
│   │           └── 预制数据.sql      # 系统初始化数据（用户、角色、菜单等）
│   ├── scripts/                       # 部署脚本
│   │   ├── auto-deploy.sh            # 主部署脚本
│   │   └── backup.sh                 # 备份脚本
│   └── .env.example                   # 环境变量模板
├── docs/                                # 项目文档目录（仅包含README）
│   └── README.md                       # 文档说明
├── sql/                                 # SQL 脚本目录
│   └── sqlinit/                        # 数据库初始化脚本
│       ├── README.md                   # 初始化脚本说明
│       ├── 建表.sql                    # 创建所有核心数据表
│       ├── 监控数据相关表.sql          # 监控功能数据表
│       ├── 省市区数据.sql              # 全国省市区地理数据
│       └── 预制数据.sql                # 系统初始化数据（用户、角色、菜单等）
├── packages/                            # 共享包（预留）
├── scripts/                             # 构建脚本
│   ├── build-for-deploy.sh            # 构建部署脚本
│   └── auto-deploy.sh                 # 自动部署脚本
├── turbo.json                          # Turbo 构建配置
├── package.json                        # 根项目配置
└── README.md                           # 项目说明

缓存功能

架构：支持内存与 Redis 双实现，依据 config/cache.js 的 type 与 config/redis 自动选择；Redis 使用 SCAN MATCH 批量清理，避免阻塞。
键规范：统一通过 generateCacheKey(module, resourceType, identifier, operation?) 生成，例如：
- 列表：app:v1:permission:list:<filtersJson>
- 单项：app:v1:user:item:<id>、app:v1:role:item:<id>
- 用户角色：app:v1:user:roles:<userId>
- 权限码：app:v1:permission:codes:user:<userId>
模式清理：使用 getCacheKeyPattern(module, resourceType) 生成模式，示例：
- 清理权限列表：clearByPattern(getCacheKeyPattern('permission','list'))
- 清理角色列表：clearByPattern(getCacheKeyPattern('role','list'))
- 清理用户统计：clearByPattern(getCacheKeyPattern('user','stats'))
读缓存位置：模型/服务层统一设置读缓存（如 withCache 装饰器、cacheService.get/set），控制器层主要进行失效与聚合响应缓存。
失效策略：写操作完成后在控制器集中清理相关键（精确 del + 按模块模式 clearByPattern），确保响应与后端数据一致。
监控与日志：缓存操作由 cacheMonitor 记录命中率与耗时；日志模块输出结构化信息方便排查。

示例代码（列表缓存与清理）：

const {
  generateCacheKey,
  getCacheKeyPattern,
} = require("./node-express-mysql/src/cache/utils/cacheKeyGenerator");
const cacheService = require("./node-express-mysql/src/cache/cacheService");

// 读取（命中则直接返回）
const cacheKey = generateCacheKey("role", "list", JSON.stringify({ page, limit, filters }));
const cached = await cacheService.get(cacheKey);

// 写入（查询后写入）
await cacheService.set(cacheKey, { data, pagination }, null, "role.list");

// 清理（写操作后）
await cacheService.clearByPattern(getCacheKeyPattern("role", "list"));

更多规范见后端文档：node-express-mysql/docs/3.缓存管理.md、node-express-mysql/docs/2.缓存键命名规范.md。

技术栈

🏗️ 构建工具

Turbo 2.0.6 - 高性能并行构建系统
PNPM 10.24.0 - 快速、节省磁盘空间的包管理器

🚀 部署工具

Docker - 容器化部署
Docker Compose - 容器编排
auto-deploy.sh - 自动部署脚本

🐳 后端技术栈

Node.js >= 20.10.0 - JavaScript运行时
Express.js 5.1.0 - Web应用框架
MySQL >= 8.0 - 关系型数据库
Redis - 缓存和会话存储
JWT - JSON Web Token认证
bcryptjs 3.0.2 - 密码加密
ioredis 5.8.2 - Redis客户端
svg-captcha - 图形验证码
multer 2.0.2 - 文件上传
node-schedule 2.1.1 - 定时任务
Swagger - API文档

⚛️ Web前端技术栈

React 18.2.0 - UI框架
Ant Design 6.0.0 - UI组件库
Webpack 5.99.9 - 模块打包器
Babel 7.27.4 - JavaScript编译器
Redux Toolkit 2.8.2 - 状态管理
React Router 6.30.0 - 路由管理
Axios 1.10.0 - HTTP客户端
Less 4.3.0 - CSS预处理器
Day.js 1.11.19 - 时间处理
ESLint 9.39.1 - 代码规范
SparkMD5 3.0.2 - 文件哈希计算

📱 移动端技术栈

React Native 0.81.5 - 跨平台移动应用框架
Expo 54.0.29 - React Native开发工具链
Expo Router 6.0.19 - 文件路由系统
React Native Paper 5.14.5 - Material Design组件库
TypeScript - 类型安全
Expo Camera - 相机扫描
Expo Image Picker - 图片选择
Expo Crypto - 文件哈希
Expo File System - 文件系统
Expo Device - 设备信息
EAS Build - 云端/本地构建服务

📚 文档网站技术栈

Next.js 16.1.0 - React 全栈框架
TypeScript - 类型安全
Tailwind CSS 3.4.19 - 原子化 CSS 框架
rehype-pretty-code - 代码高亮（支持暗色/亮色主题）
remark + rehype - Markdown 处理
Fuse.js 7.1.0 - 全文搜索
@tailwindcss/typography - 排版插件

📚 开发工具

Prettier 3.3.3 - 代码格式化工具
ESLint 9.39.1 - 代码质量检查工具
EditorConfig - 编辑器统一配置
Husky 9.1.7 - Git hooks 管理
lint-staged 15.2.10 - Git 提交前格式化
ShellCheck - Bash 脚本静态分析
shfmt - Shell 代码格式化
Bats - Bash 自动化测试

🔐 权限设计

该项目的权限架构采用 RBAC0 + 权限层级 + 数据域 来设计，相比传统的5张数据库表，多了两张数据库表，分别是权限表和角色权限关联表，以角色为核心，通过角色与菜单/权限点/数据域的关联，实现细粒度的权限控制。

核心特性：

✅ 四层权限模型（系统管理层、功能模块层、操作权限层、数据权限层）
✅ 7张权限关联表（用户、角色、菜单、权限点、关联表）
✅ 超级管理员统一判断机制
✅ 前端动态权限路由 + 按钮级权限控制
✅ 后端接口权限校验 + 数据权限过滤

四层模型

系统管理层（角色与层级）、功能模块层（菜单/模块）、操作权限层（权限点/接口/按钮）、数据权限层（部门/数据域）。

目标：更精细、更灵活的权限控制，满足复杂业务场景；兼容当前实现并可渐进增强。
用户层：user，账号主体，绑定所属部门与基础信息。
角色层：role，权限载体，聚合菜单/权限点/数据权限。
菜单/资源层：menu，页面/目录/按钮（node_type）与路由/组件，含权限编码 code 与访问类型 access_type（0-公共，1-私有）。
权限点/数据权限层：permission 作为操作点（接口/按钮）集合，department 作为数据域；通过关联表构成角色的操作与数据范围。

数据库（7 张权限关联表）

user：用户表，含 department_id 等基础字段。
role：角色表，含系统预置与保护标识（is_system/is_protected）。
menu：菜单表，目录/菜单/按钮（node_type=1/2/3），权限编码 code 与路由/组件信息。
permission：权限点表，定义接口/操作编码集合。
user_role：用户与角色关联表（多对多）。
role_menu：角色与菜单关联表（多对多），决定角色可见页面/按钮。
role_permission：角色与权限点关联表（多对多），决定角色可用接口/操作。
扩展：department 与 role_data_permission（角色数据权限关联表）用于数据域授权，限定角色的数据访问范围。

关联关系

用户→角色：user_role；一个用户可绑定多个角色。
角色→菜单：role_menu；决定该角色在前端可见的目录/页面/按钮集合。
角色→权限点：role_permission；决定该角色在后端可用的接口/操作集合。
角色→数据域：role_data_permission；定义角色在不同部门/数据范围内的可访问性。

判定流程

后端接口权限：
- 认证中间件校验 Token 并设置 req.user。
- 路由层使用权限校验中间件（如 checkPermission('code') 与等级 checkPermissionLevel(40)）核验权限码与安全等级。
- 权限码来源：菜单/权限表的 code，通过用户的角色聚合得到可用集合（menuModel.getUserPermissionCodes）。
前端页面权限：
- 路由与菜单：后端返回的菜单按 access_type 与 role_menu 过滤；非超级管理员补齐父级目录，保证导航完整。
- 按钮权限：AuthButton 基于权限码 code 控制显隐（与后端同源编码）。

超级管理员

统一判断：utils.isSuperAdminById(userId)，依据角色 code='SUPER_ADMIN' 或系统预置且受保护（is_system=1 && is_protected=1）。
超级管理员跳过菜单与权限过滤，拥有全部资源与操作能力。

模型层

PermissionModel：获取权限列表/详情、按角色/用户获取权限码；分配角色权限（事务）、缓存 permissions:role:*、permission_codes:user:*。
DataPermissionModel：按角色/用户获取数据权限（部门ID集合），校验用户是否可访问某部门；生成数据权限 SQL 过滤条件。
MenuModel：按用户返回菜单支持 access_type 过滤；非超级管理员补齐父级目录，保证导航完整；支持最小字段集与完整字段集。

中间件

checkPermission(requiredPermissions, { checkDataPermission, dataPermissionType })
checkRole(requiredRoles)
checkPermissionLevel(minLevel)
checkDataPermission(permissionType)

路由

权限管理：GET /permissions、GET /permissions/:id、GET /roles/:roleId/permissions、PUT /roles/:roleId/permissions、GET /user/permissions
角色管理：GET /roles、GET /roles/:id、POST /roles（层级≥20）、PUT /roles/:id、DELETE /roles/:id、GET/PUT /roles/:roleId/data-permissions

权限码规范（示例）

模块层：module:{模块名}:{操作}（如 module:user:view、module:role:edit）
操作层：{模块名}:{实体}:{操作}（如 system:user:create、system:role:delete、content:article:publish）

🚀 从零开始 - 完整部署指南

本指南将带你从克隆项目到成功运行和部署整个系统。

📋 前置要求

在开始之前，请确保你的开发环境满足以下要求：

必需环境

Node.js >= 20.10.0 - 下载地址
PNPM >= 10.24.0 - 安装命令：npm install -g pnpm
MySQL >= 8.0 - 下载地址
Git - 用于克隆项目

可选环境（用于生产部署）

Docker >= 20.10 - 下载地址
Docker Compose - 通常随Docker一起安装
Redis >= 6.0 - 用于生产环境缓存（可选，后端支持内存缓存降级）

⚠️ 重要提示：

本项目使用 PNPM 作为包管理器，请勿使用 npm 或 yarn
不要运行 npm install 或 yarn install
只运行 pnpm install 安装依赖

📖 相关文档

在开始之前，建议先阅读以下文档了解项目架构：

📘 Monorepo + Turbo架构使用指南 - 了解项目架构和依赖管理
📘 部署文件清单 - 了解部署所需文件和配置
📘 自动化部署指南 - 了解自动化部署流程

第一步：克隆项目

# 克隆项目到本地
git clone <repository-url>

# 进入项目目录
cd project-root

第二步：安装依赖

2.1 安装PNPM（如果未安装）

# 使用npm全局安装pnpm
npm install -g pnpm

# 验证安装
pnpm --version

2.2 安装项目依赖

# 在项目根目录执行，安装所有应用的依赖
pnpm install

说明：

该命令会安装根目录、apps/react-antd-webpack、apps/node-express-mysql、apps/app-rn-ts 的所有依赖
PNPM 使用 workspace 机制，会智能处理依赖共享，避免重复安装
安装过程可能需要几分钟，请耐心等待

第三步：配置数据库

3.1 创建数据库

# 登录MySQL
mysql -u root -p

# 创建数据库（请根据实际情况修改数据库名）
CREATE DATABASE your_database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 退出MySQL
exit;

3.2 初始化数据库表和数据

项目提供了完整的数据库初始化脚本，位于 sql/sqlinit/ 目录。

方式一：使用项目提供的初始化脚本（推荐）

# 进入数据库初始化脚本目录
cd sql/sqlinit

# 按顺序执行初始化脚本（重要：必须按顺序执行）
# 1. 创建所有核心数据表
mysql -u root -p your_database_name < 建表.sql

# 2. 创建监控数据相关表（可选，根据业务需求）
mysql -u root -p your_database_name < 监控数据相关表.sql

# 3. 导入省市区地理数据（可选，根据业务需求）
mysql -u root -p your_database_name < 省市区数据.sql

# 4. 导入系统预制数据（包含超级管理员账号、角色、菜单、权限等）
mysql -u root -p your_database_name < 预制数据.sql

初始化脚本说明：

脚本文件	说明	是否必需
`建表.sql`	创建所有系统核心数据表结构（用户、角色、菜单、权限、审计日志等）	✅ 必需
`监控数据相关表.sql`	创建系统监控功能的数据表、视图和存储过程	⚠️ 可选
`省市区数据.sql`	导入全国省市区地理数据（约678KB）	⚠️ 可选
`预制数据.sql`	导入系统初始化数据（组织、用户、角色、菜单、权限等）	✅ 必需

预制数据包含：

✅ 超级管理员账号（用户名：superadmin，密码：123456）
✅ 6种系统角色（超级管理员、系统管理员、业务管理员、部门管理员、普通用户、访客）
✅ 完整的系统菜单结构（工作台、系统管理、系统监控、个人中心、系统设置等）
✅ 系统各模块的操作权限定义
✅ 用户角色绑定关系

详细说明：请参考数据库初始化脚本说明了解完整的初始化脚本说明。

方式二：使用后端目录的SQL脚本

# 进入后端目录
cd apps/node-express-mysql

# 查看SQL脚本文件
ls sql/

# 按顺序执行SQL脚本（根据实际需要）
# 1. 用户表
mysql -u root -p your_database_name < sql/用户表.sql

# 2. 角色表
mysql -u root -p your_database_name < sql/角色表.sql

# 3. 菜单表
mysql -u root -p your_database_name < sql/菜单表.sql

# 4. 权限表
mysql -u root -p your_database_name < sql/权限表.sql

# 5. 其他关联表...
# 继续执行其他SQL文件

# 或者一次性执行所有SQL文件（如果MySQL支持）
for file in sql/*.sql; do
    mysql -u root -p your_database_name < "$file"
done

⚠️ 注意：使用方式二时，需要手动创建管理员账号和初始化数据。建议使用方式一（项目提供的初始化脚本），可以快速获得完整的系统环境。

第四步：配置环境变量

4.1 后端环境变量配置

# 进入后端目录
cd apps/node-express-mysql

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量文件（根据实际情况修改）
vim .env
# 或使用其他编辑器
# code .env
# nano .env

必需配置项：

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=your_database_name

# JWT密钥（请使用强密码，至少32位随机字符串）
JWT_SECRET=your-jwt-secret-key-32-chars-minimum
REFRESH_SECRET=your-refresh-secret-key-32-chars-minimum

# 服务端口
PORT=8888
NODE_ENV=development

# 日志级别
LOG_LEVEL=debug

# 单点登录开关（on/off）
SINGLE_LOGIN=on

# Redis配置（可选，不配置则使用内存缓存）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 文件上传配置
UPLOAD_DIR=./data/uploads
BASE_URL=http://localhost:8888

安全提示：

⚠️ 生产环境请使用强密码（至少12位，包含大小写字母、数字和特殊字符）
⚠️ JWT密钥建议使用32位以上随机字符串
⚠️ 不要将 .env 文件提交到Git仓库

4.2 前端API配置（可选）

前端默认连接 http://localhost:8888，如需修改：

# 编辑前端API配置文件
cd apps/react-antd-webpack
vim src/utils/api/request.js
# 或
vim src/config/api.config.ts

4.3 移动端API配置（可选）

# 编辑移动端API配置文件
cd apps/app-rn-ts
vim src/config/api.config.ts

第五步：启动开发服务

5.1 方式一：并行启动所有服务（推荐）

# 在项目根目录执行
pnpm dev

该命令会：

✅ 并行启动 Web 前端（端口 8080）
✅ 并行启动后端服务（端口 8888）
✅ 并行启动文档网站（端口 8081）
✅ 使用 Turbo 并行构建，提升启动速度

5.2 方式二：分别启动服务

# 仅启动Web前端
pnpm dev:frontend

# 仅启动后端服务
pnpm dev:backend

5.3 方式三：进入子目录单独启动

# 启动后端服务
cd apps/node-express-mysql
pnpm dev

# 启动Web前端（新开终端）
cd apps/react-antd-webpack
pnpm dev

# 启动文档网站（新开终端）
cd apps/doc-next-ts
pnpm dev

# 启动移动端开发服务（新开终端，需要Expo CLI）
cd apps/app-rn-ts
pnpm start

5.4 验证服务启动

启动成功后，访问以下地址验证：

✅ Web前端：http://localhost:8080
✅ 后端API：http://localhost:8888
✅ 文档网站：http://localhost:8081
✅ API文档：http://localhost:8888/api/docs/
✅ 健康检查：http://localhost:8888/health

第六步：验证数据库初始化

6.1 如果使用了预制数据脚本

如果按照第三步的方式一执行了 预制数据.sql 脚本，系统已经自动创建了超级管理员账号，可以直接使用以下信息登录：

默认登录信息（⚠️ 生产环境请立即修改）：

用户名：superadmin
密码：123456
管理员邮箱：lyqjob@yeah.net
管理员手机：15290612103

预制数据包含：

✅ 超级管理员账号（已绑定超级管理员角色）
✅ 6种系统角色（超级管理员、系统管理员、业务管理员、部门管理员、普通用户、访客）
✅ 完整的系统菜单结构
✅ 系统各模块的操作权限定义

6.2 如果未使用预制数据脚本

如果使用方式二（后端目录的SQL脚本）初始化数据库，需要手动创建管理员账号：

方式一：通过数据库直接创建

-- 登录MySQL
mysql -u root -p your_database_name

-- 插入管理员用户（密码需要先加密）
-- 默认密码：admin123（请在生产环境修改）
INSERT INTO user (username, password, name, email, is_delete)
VALUES ('admin', '$2a$10$加密后的密码', '管理员', 'admin@example.com', 0);

-- 创建超级管理员角色并关联用户
-- （具体SQL请参考项目中的初始化脚本）

⚠️ 安全提示：

系统初始化后，请立即修改超级管理员密码
生产环境中，请删除或修改默认的测试数据
建议使用强密码（至少12位，包含大小写字母、数字和特殊字符）

第七步：访问系统

7.1 Web前端访问

打开浏览器访问：http://localhost:8080
使用管理员账号登录
登录成功后会自动跳转到首页

7.2 移动端App开发

安装Expo CLI（如果未安装）

npm install -g expo-cli
# 或使用npx（推荐）
npx expo-cli --version

启动移动端开发服务

cd apps/app-rn-ts
pnpm start

运行到设备

iOS模拟器：按 i 键或运行 pnpm ios
Android模拟器：按 a 键或运行 pnpm android
真机调试：使用 Expo Go App 扫描终端显示的二维码

详细说明：请参考移动端构建与调试指南

第八步：生产环境部署

8.1 本地构建生产版本

# 在项目根目录执行构建脚本
./scripts/build-for-deploy.sh v1.0.0

# 构建产物会生成在 build-history/日期/时间/ 目录

构建产物说明：

backend/ - 后端Docker镜像文件
frontend/ - 前端静态文件
version-info.txt - 版本信息

8.2 服务器部署

方式一：自动化部署（推荐）

# 1. 上传构建产物到服务器
scp -r build-history/20251218/191137/* root@server:/opt/docker_project/backup/

# 2. 上传部署脚本和配置
scp docker_project/docker-compose.yml root@server:/opt/docker_project/
scp docker_project/nginx.conf root@server:/opt/docker_project/
scp -r docker_project/scripts root@server:/opt/docker_project/

# 3. 登录服务器执行自动部署
ssh root@server
cd /opt/docker_project
./scripts/auto-deploy.sh deploy v1.0.0

方式二：手动部署

详细步骤请参考：

📘 部署指南 - 完整的部署配置说明和手动部署步骤

8.3 Nginx配置

生产环境部署时，需要在服务器上配置Nginx作为反向代理服务器。Nginx配置文件位于 docker_project/nginx.conf。

完整Nginx配置示例

server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    # 前端静态文件服务
    root /opt/docker_project/frontend/current;
    index index.html;

    # 代理 API 请求到后端（必须在 / 之前，确保优先匹配）
    location /api/ {
        # 代理到后端服务
        proxy_pass http://127.0.0.1:8888/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 转发自定义请求头（重要：用于客户端类型识别和单点登录）
        proxy_set_header X-Client-Type $http_x_client_type;
        proxy_set_header X-Client-Page $http_x_client_page;
        proxy_set_header X-Client-Id $http_x_client_id;
        proxy_set_header X-File-Hash $http_x_file_hash;

        # WebSocket支持（如果需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 前端路由支持（SPA应用，必须在最后）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 代理必应（用于某些功能）
    location /bing/ {
        proxy_pass https://www.bing.com/;
        proxy_set_header Host www.bing.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_ssl_server_name on;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }

    # 静态资源缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Gzip压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml+rss;
}

配置说明

必需配置：

✅ 前端静态文件服务：root 指向前端构建产物目录（通常使用软链接 current）
✅ API代理：location /api/ 将API请求代理到后端服务（http://127.0.0.1:8888/）
✅ SPA路由支持：try_files 确保前端路由正常工作
✅ 请求头转发：proxy_set_header 确保后端能获取真实客户端信息

可选配置：

⚠️ 必应代理：location /bing/ 用于某些需要访问必应的功能（可选）
⚠️ 静态资源缓存：提升静态资源加载速度
⚠️ Gzip压缩：减少传输数据量，提升加载速度

配置步骤

编辑Nginx配置文件：

# 在服务器上编辑nginx.conf
vim /opt/docker_project/nginx.conf
# 或
nano /opt/docker_project/nginx.conf

测试配置：

# 测试Nginx配置是否正确
nginx -t

重载Nginx配置：

# 重载配置（不中断服务）
nginx -s reload
# 或
systemctl reload nginx

查看Nginx状态：

# 查看Nginx运行状态
systemctl status nginx
# 或
ps aux | grep nginx

注意事项

⚠️ 域名配置：将 your-domain.com 替换为实际域名
⚠️ 前端路径：确保 root 路径指向正确的前端构建产物目录
⚠️ 后端地址：确保后端服务运行在 127.0.0.1:8888
⚠️ 防火墙：确保80端口（HTTP）和443端口（HTTPS，如果使用SSL）已开放
⚠️ SSL证书：生产环境建议配置HTTPS，添加SSL证书配置

8.4 Docker部署架构

生产服务器
├── Nginx (端口80)          # 前端静态文件服务 + API反向代理
├── Backend容器 (端口8888)   # Node.js后端服务
├── MySQL容器 (端口3306)     # 数据库服务
└── Redis容器 (端口6379)     # 缓存服务（可选）

详细说明：

📘 部署指南 - 自动化部署完整流程和Docker容器化部署说明

🛠️ 开发命令

Turbo 构建命令

# 构建所有应用
pnpm build

# 构建Web前端
pnpm build:frontend

# 构建文档网站
pnpm build:doc

# 构建后端（如果需要）
pnpm build:backend

# 清理构建缓存
pnpm clean

# 代码检查
pnpm lint

移动端构建命令

# 进入移动端目录
cd apps/app-rn-ts

# Android APK构建（预览版）
pnpm build:android:apk

# Android APK构建（开发版）
pnpm build:android:dev

# Android AAB构建（生产版，用于Google Play）
pnpm build:android:prod

# iOS构建（开发版）
pnpm build:ios:dev

# iOS构建（预览版）
pnpm build:ios:preview

# iOS构建（生产版）
pnpm build:ios:prod

# 本地构建（需要Docker）
pnpm build:android:apk:local
pnpm build:ios:dev:local

代码格式化命令

# 格式化所有文件
pnpm format

# 格式化 apps 目录下的所有文件
pnpm format:apps

# 检查格式（不修改文件）
pnpm format:check

格式化说明：

✅ 保存时自动格式化 - VSCode 保存文件时自动格式化（需安装 Prettier 扩展）
✅ Git 提交前自动格式化 - 使用 Husky + lint-staged 在提交前自动格式化
✅ 统一缩进规则 - 默认 2 个空格，JS/TS/JSX/TSX 文件 4 个空格
✅ 支持文件类型 - JS/TS/JSON/CSS/Less/SCSS/MD/YAML 等

清理命令

# 彻底清理所有依赖和缓存（模拟从零克隆场景）
./scripts/clean-all-dependencies.sh

# 清理后重新安装依赖
pnpm install

清理脚本功能：

✅ 删除所有 node_modules 目录
✅ 删除 .turbo 缓存目录
✅ 删除构建产物（dist、build、.next、out 等）
✅ 删除 TypeScript 构建信息文件（*.tsbuildinfo）
✅ 清理 PNPM 全局缓存
✅ 删除项目级缓存文件

使用场景：

🔄 模拟从零克隆项目的场景
🐛 排查依赖包相关问题
🧹 清理磁盘空间
🔍 验证依赖安装是否正常

其他命令

# 运行测试
pnpm test

# 停止所有服务
pnpm stop

# 强制结束端口占用
pnpm kill:ports

📚 API 接口文档

本项目提供完整的 Swagger API 文档，启动后端服务后可通过以下地址访问：

Swagger API 文档：http://localhost:8888/api/docs/

Swagger 文档包含：

✅ 所有接口的详细说明
✅ 请求参数和响应格式
✅ 在线测试功能
✅ 接口权限说明
✅ 认证方式说明

前端特性

动态权限路由

动态路由注册 - 根据后端返回的菜单数据动态注册路由
权限控制 - 基于RBAC模型的页面级权限控制
按钮权限 - 支持按钮级别的权限控制
路由守卫 - 自动处理未授权访问和登录失效

状态管理

Redux Toolkit - 现代化的状态管理方案
持久化存储 - 用户信息和菜单数据本地缓存
无感刷新 - 自动处理Token过期和刷新

错误处理

全局错误捕获 - ErrorBoundary + 全局错误监听
错误去重 - 防止重复错误上报
友好降级 - 错误页面自动跳转到有效页面

性能优化

代码分割 - 路由级别的懒加载
资源优化 - 图片压缩和CDN支持
缓存策略 - 合理的缓存机制

安全特性

认证安全

JWT双Token - Access Token + Refresh Token机制
Token过期 - 访问令牌1小时过期，刷新令牌7天过期
自动清理 - 定时清理过期和已撤销的token
强制登出 - 支持强制登出用户所有设备

输入验证

参数验证 - 所有接口都有完整的参数验证
格式检查 - 验证ID、邮箱、手机号等格式
重复性检查 - 防止创建重复的用户名、角色编码等
SQL注入防护 - 使用参数化查询防止SQL注入

验证码保护

图形验证码 - 使用svg-captcha生成验证码
内存存储 - 验证码存储在服务器端内存中
过期机制 - 验证码5分钟自动过期
一次性使用 - 验证码使用后自动清除

响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "username": "admin",
    "name": "管理员"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

错误响应

{
  "success": false,
  "code": 400,
  "message": "请求参数错误",
  "data": null,
  "timestamp": "2024-01-01T12:00:00.000Z"
}

开发调试

后端调试

# 查看验证码状态
curl -H "Authorization: Bearer <token>" \
     http://localhost:8888/captcha/status

# 手动清理过期token
curl -X POST -H "Authorization: Bearer <token>" \
     http://localhost:8888/cleanup-tokens

# 获取token统计信息
curl -H "Authorization: Bearer <token>" \
     http://localhost:8888/token-stats

前端调试

Redux DevTools - 状态管理调试
React DevTools - 组件调试
Network面板 - API请求调试
Console日志 - 错误信息查看

🐳 Docker 部署

本项目支持完整的 Docker 容器化部署，提供自动化部署脚本和版本管理。

快速部署（推荐）

1. 本地构建

# 构建生产版本
./scripts/build-for-deploy.sh v1.0.0

2. 上传到服务器

# 上传构建产物到服务器
scp -r build-history/20251208/153826/* root@server:/opt/docker_project/backup/

3. 自动部署

# 登录服务器并执行部署
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.0"

部署功能特性

✅ 自动加载 Docker 镜像
✅ 前端版本管理（语义化版本）
✅ Protect 目录同步（SSL 证书等）
✅ 备份和回滚机制
✅ 环境变量自动更新
✅ 软链接管理

部署命令

# 部署指定版本
./scripts/auto-deploy.sh deploy v1.0.0

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

# 查看部署状态
./scripts/auto-deploy.sh status

# 清理旧版本
./scripts/auto-deploy.sh cleanup

Docker 服务架构

本项目采用容器分离架构，各服务独立部署：

# 容器分离架构
├── Backend (Node.js后端)
│   ├── 依赖 → MySQL (数据存储)
│   └── 依赖 → Redis (缓存)
│
├── Frontend (系统级Nginx)
│   ├── 提供 → 静态文件服务（版本管理）
│   └── 代理 → Backend API请求
│
└── Infrastructure (基础设施)
    ├── MySQL (数据库)
    └── Redis (缓存)