# project-root

**Repository Path**: lyqjob/project-root

## Basic Information

- **Project Name**: project-root
- **Description**: Monorepo + Turbo架构的全栈管理系统；Express + React + Webpck + Antd + Redis + MySQL 实现； 主题切换、JWT认证，双Token无感刷新，错误监控，权限管控，SSE通信（强制登出），自动编码、缓存管理（Redis + 内存）自动降级、日志管理、智谱（AI 对话）、版本管理（支持回滚）、通知公告、App扫码登录等
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://wladmin.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 29
- **Forks**: 4
- **Created**: 2025-10-24
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Nodejs, React, JavaScript, React-native, TypeScript

## README

<p align="center" >
	<img alt="logo" src="https://admin.liyq666.top/uploads/logo.png">
</p>
<h1 align="center" style="margin: 10px 0 30px; font-weight: bold;">WL-Admin v1.0.4</h1>
<h4 align="center">全栈管理系统 - Monorepo + Turbo 架构企业级解决方案</h4>
<p align="center">
	<a href="https://gitee.com/lyqjob/project-root"><img src="https://gitee.com/lyqjob/project-root/badge/star.svg?theme=gvp"></a>
	<a href="https://gitee.com/lyqjob/project-root"><img src="https://img.shields.io/badge/WL Admin-v1.0.4-brightgreen.svg"></a>
	<a href="https://gitee.com/lyqjob/project-root/blob/master/LICENSE"><img src="https://img.shields.io/github/license/mashape/apistatus.svg"></a>
</p>

## 项目介绍

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

## 在线访问

- **Web前端**：[https://wladmin.cn](https://wladmin.cn)
- **后端API**：[https://admin.liyq666.top/api/doc/](https://admin.liyq666.top/api/doc/)
- **文档网站**：[https://www.wladmin.cn](https://www.wladmin.cn)
- **移动端App**：[https://wladmin.cn/app](https://expo.dev/accounts/liyq/projects/app-rn-ts/builds/baa8d23c-208e-4af9-8bff-6123d872cf63)

## 项目实例

![alt text](readme-images/image0.png)
![alt text](readme-images/image1.png)
![alt text](readme-images/image2.png)
![alt text](readme-images/image3.png)
![alt text](readme-images/image4.png)
![alt text](readme-images/image5.png)
![alt text](readme-images/image6.png)
![alt text](readme-images/image7.png)
![alt text](readme-images/image8.png)
![alt text](readme-images/image9.png)
![alt text](readme-images/image10.png)
![alt text](readme-images/image11.png)
![alt text](readme-images/image12.png)
![alt text](readme-images/image13.png)
![alt text](readme-images/image14.png)

## 项目特性

### 🏗️ 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` 记录命中率与耗时；日志模块输出结构化信息方便排查。

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

```javascript
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 - [下载地址](https://nodejs.org/)
- **PNPM** >= 10.24.0 - 安装命令：`npm install -g pnpm`
- **MySQL** >= 8.0 - [下载地址](https://dev.mysql.com/downloads/mysql/)
- **Git** - 用于克隆项目

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

- **Docker** >= 20.10 - [下载地址](https://www.docker.com/)
- **Docker Compose** - 通常随Docker一起安装
- **Redis** >= 6.0 - 用于生产环境缓存（可选，后端支持内存缓存降级）

⚠️ **重要提示**：

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

### 📖 相关文档

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

- 📘 [Monorepo + Turbo架构使用指南](./docs/Monorepo%20+%20Turbo架构使用指南.md) - 了解项目架构和依赖管理
- 📘 [部署文件清单](./docs/部署文件清单.md) - 了解部署所需文件和配置
- 📘 [自动化部署指南](./docs/自动化部署指南.md) - 了解自动化部署流程

---

## 第一步：克隆项目

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

# 进入项目目录
cd project-root
```

---

## 第二步：安装依赖

### 2.1 安装PNPM（如果未安装）

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

# 验证安装
pnpm --version
```

### 2.2 安装项目依赖

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

**说明**：

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

---

## 第三步：配置数据库

### 3.1 创建数据库

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

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

# 退出MySQL
exit;
```

### 3.2 初始化数据库表和数据

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

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

```bash
# 进入数据库初始化脚本目录
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/sqlinit/README.md) 了解完整的初始化脚本说明。

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

```bash
# 进入后端目录
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 后端环境变量配置

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

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

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

**必需配置项**：

```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`，如需修改：

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

### 4.3 移动端API配置（可选）

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

---

## 第五步：启动开发服务

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

```bash
# 在项目根目录执行
pnpm dev
```

该命令会：

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

### 5.2 方式二：分别启动服务

```bash
# 仅启动Web前端
pnpm dev:frontend

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

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

```bash
# 启动后端服务
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脚本）初始化数据库，需要手动创建管理员账号：

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

```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前端访问

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

### 7.2 移动端App开发

#### 安装Expo CLI（如果未安装）

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

#### 启动移动端开发服务

```bash
cd apps/app-rn-ts
pnpm start
```

#### 运行到设备

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

**详细说明**：请参考 [移动端构建与调试指南](./apps/app-rn-ts/docs/构建与调试指南.md)

---

## 第八步：生产环境部署

### 8.1 本地构建生产版本

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

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

**构建产物说明**：

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

### 8.2 服务器部署

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

```bash
# 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
```

#### 方式二：手动部署

详细步骤请参考：

- 📘 [部署指南](https://www.wladmin.cn/docs/started/部署指南) - 完整的部署配置说明和手动部署步骤

### 8.3 Nginx配置

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

#### 完整Nginx配置示例

```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压缩**：减少传输数据量，提升加载速度

#### 配置步骤

1. **编辑Nginx配置文件**：

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

2. **测试配置**：

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

3. **重载Nginx配置**：

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

4. **查看Nginx状态**：

```bash
# 查看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)     # 缓存服务（可选）
```

**详细说明**：

- 📘 [部署指南](https://www.wladmin.cn/docs/started/部署指南) - 自动化部署完整流程和Docker容器化部署说明

---

## 常见问题排查

### 问题1：PNPM安装失败

**解决方案**：

```bash
# 清除PNPM缓存
pnpm store prune

# 删除node_modules和锁文件后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### 问题2：端口被占用

**解决方案**：

```bash
# 查看端口占用
lsof -i :8080  # Web前端端口
lsof -i :8888  # 后端端口

# 停止占用端口的进程
pnpm kill:ports  # 使用项目提供的脚本
# 或手动kill
kill -9 <PID>
```

### 问题3：数据库连接失败

**检查项**：

1. MySQL服务是否启动：`mysql -u root -p`
2. 数据库是否创建：`SHOW DATABASES;`
3. 环境变量配置是否正确：检查 `apps/node-express-mysql/.env`
4. 用户权限是否正确：`GRANT ALL PRIVILEGES ON database_name.* TO 'user'@'localhost';`

### 问题4：前端无法连接后端

**检查项**：

1. 后端服务是否启动：访问 http://localhost:8888/health
2. CORS配置是否正确：检查后端 `config/base/cors.js`
3. API地址配置：检查前端 `src/config/api.config.ts`

### 问题5：移动端构建失败

**解决方案**：

- 📘 参考 [移动端构建与调试指南](./apps/app-rn-ts/docs/构建与调试指南.md)
- 📘 iOS构建参考 [iOS构建与分发指南](./apps/app-rn-ts/docs/iOS构建与分发指南.md)

---

## 📚 更多文档资源

### 架构文档

- 📘 [Monorepo + Turbo架构使用指南](https://www.wladmin.cn/docs/extended/Monorepo架构指南) - 项目架构详解
- 📘 [后端目录结构规范](./apps/node-express-mysql/docs/1.目录文件结构规范.md) - 后端代码组织规范
- 📘 [移动端项目架构指南](./apps/app-rn-ts/docs/项目架构指南.md) - 移动端架构说明

### 功能文档

- 📘 [二维码扫码登录功能文档](./apps/react-antd-webpack/docs/App扫码登录Web端功能文档.md) - 二维码登录完整说明
- 📘 [发布订阅消息管理](./apps/react-antd-webpack/docs/发布订阅消息管理.md) - 消息系统架构
- 📘 [Keep-Alive缓存管理](./apps/react-antd-webpack/docs/Keep-Alive缓存管理.md) - 页面缓存机制

### 后端文档

- 📘 [安全防护文档](https://www.wladmin.cn/docs/backend/安全防护) - 完整的安全防护措施
- 📘 [缓存模块文档](https://www.wladmin.cn/docs/backend/缓存模块) - 缓存系统详细说明
- 📘 [日志模块文档](https://www.wladmin.cn/docs/backend/日志模块) - 日志系统详细说明
- 📘 [定时任务文档](https://www.wladmin.cn/docs/backend/定时任务) - 定时任务调度系统
- 📘 [统一响应文档](https://www.wladmin.cn/docs/backend/统一响应) - 统一响应格式规范
- 📘 [SSE通信文档](https://www.wladmin.cn/docs/function/SSE通信) - SSE实时通信流程
- 📘 [扫码登录文档](https://www.wladmin.cn/docs/function/扫码登录) - 二维码登录流程

### 部署文档

- 📘 [部署指南](https://www.wladmin.cn/docs/started/部署指南) - 完整的部署配置说明和部署流程
- 📘 [Bash Shell脚本编写指南](https://www.wladmin.cn/docs/extended/BashShell脚本指南) - 脚本开发最佳实践
- 📘 [Gitee Webhook自动部署指南](https://www.wladmin.cn/docs/extended/GiteeWebHook) - Webhook自动部署
- 📘 [Docker操作指南](https://www.wladmin.cn/docs/extended/Docker操作指南) - Docker容器化部署说明
- 📘 [Nginx配置指南](https://www.wladmin.cn/docs/extended/Nginx配置指南) - Nginx反向代理配置

### 移动端文档

- 📘 [移动端构建与调试指南](./apps/app-rn-ts/docs/构建与调试指南.md) - 应用打包和真机调试
- 📘 [iOS构建与分发指南](./apps/app-rn-ts/docs/iOS构建与分发指南.md) - iOS应用构建和分发
- 📘 [路由系统指南](./apps/app-rn-ts/docs/路由系统指南.md) - Expo Router路由系统

### 开发规范

- 📘 [前端开发规范](./apps/react-antd-webpack/document/前端开发规范/README.md) - 前端代码规范
- 📘 [代码规范](https://www.wladmin.cn/docs/started/代码规范) - 代码规范和使用指南

## 🛠️ 开发命令

### Turbo 构建命令

```bash
# 构建所有应用
pnpm build

# 构建Web前端
pnpm build:frontend

# 构建文档网站
pnpm build:doc

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

# 清理构建缓存
pnpm clean

# 代码检查
pnpm lint
```

### 移动端构建命令

```bash
# 进入移动端目录
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
```

**详细说明**：

- 📘 [移动端构建与调试指南](./apps/app-rn-ts/docs/构建与调试指南.md) - Android构建详细步骤
- 📘 [iOS构建与分发指南](./apps/app-rn-ts/docs/iOS构建与分发指南.md) - iOS构建和分发方法

### 代码格式化命令

```bash
# 格式化所有文件
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 等

**详细说明**：请参考 [代码规范](https://www.wladmin.cn/docs/started/代码规范)

### 清理命令

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

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

**清理脚本功能**：

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

**使用场景**：

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

### 其他命令

```bash
# 运行测试
pnpm test

# 停止所有服务
pnpm stop

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

## 📚 API 接口文档

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

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

Swagger 文档包含：

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

**相关功能文档**：

- 📘 [二维码扫码登录功能文档](./apps/react-antd-webpack/docs/App扫码登录Web端功能文档.md) - 二维码登录完整说明
- 📘 [SSE管理文档](./apps/node-express-mysql/docs/6.SSE管理.md) - SSE实时通信说明

## 前端特性

### 动态权限路由

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

### 状态管理

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

### 错误处理

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

### 性能优化

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

## 安全特性

### 认证安全

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

### 输入验证

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

### 验证码保护

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

## 响应格式

### 成功响应

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

### 错误响应

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

## 开发调试

### 后端调试

```bash
# 查看验证码状态
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. 本地构建

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

#### 2. 上传到服务器

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

#### 3. 自动部署

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

### 部署功能特性

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

### 部署命令

```bash
# 部署指定版本
./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
```

### 详细部署文档

- 📖 [部署指南](https://www.wladmin.cn/docs/started/部署指南) - 完整的部署配置说明和部署步骤
- 📖 [Bash Shell脚本编写指南](https://www.wladmin.cn/docs/extended/BashShell脚本指南) - 脚本开发最佳实践
- 📖 [Docker操作指南](https://www.wladmin.cn/docs/extended/Docker操作指南) - Docker容器化部署说明

### Docker 服务架构

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

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

### 端口分配

| 服务                 | 端口 | 说明             |
| -------------------- | ---- | ---------------- |
| Frontend (系统Nginx) | 80   | 前端静态文件服务 |
| Backend (Node.js)    | 8888 | 后端API服务      |
| MySQL                | 3306 | 数据库服务       |
| Redis                | 6379 | 缓存服务         |

## 📈 性能优化

### 后端优化

- **数据库索引** - 为查询字段添加适当索引
- **连接池** - 使用数据库连接池
- **缓存策略** - Redis缓存热点数据
- **压缩中间件** - 启用gzip压缩

### 前端优化

- **代码分割** - 路由级别的代码分割
- **懒加载** - 组件和路由懒加载
- **资源压缩** - 图片和静态资源压缩
- **CDN加速** - 静态资源CDN部署

## 🤝 贡献指南

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

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 👨‍💻 作者

- **lyq** - _项目创建者和维护者_ - [lyqjob@yeah.net](mailto:lyqjob@yeah.net)

## 🙏 致谢

⭐ 如果这个项目对你有帮助，请给它一个星标！