# 系统架构

<cite>
**本文引用的文件**
- [backend/src/app.js](file://backend/src/app.js)
- [backend/src/routes/index.js](file://backend/src/routes/index.js)
- [backend/src/middleware/auth.js](file://backend/src/middleware/auth.js)
- [backend/src/utils/jwt.js](file://backend/src/utils/jwt.js)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/src/models/index.js](file://backend/src/models/index.js)
- [backend/src/services/userBootstrap.js](file://backend/src/services/userBootstrap.js)
- [backend/Dockerfile](file://backend/Dockerfile)
- [backend/package.json](file://backend/package.json)
- [frontend/src/main.js](file://frontend/src/main.js)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/App.vue](file://frontend/src/App.vue)
- [frontend/package.json](file://frontend/package.json)
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本系统是一个前后端分离的耳机品牌与型号管理平台，采用 Vue 3 + Express 的技术栈，通过 Nginx 作为静态资源与反向代理服务，配合 Docker Compose 实现快速部署与运维。系统遵循分层架构与 MVC 设计模式，后端以路由-控制器-模型（R-C-M）为核心组织业务逻辑，前端以组件化与路由守卫保障安全与导航体验。

## 项目结构
- 后端（Node.js + Express）：集中于 backend 目录，包含配置、中间件、路由、模型、服务与工具模块，并通过 Dockerfile 与 docker-compose.yml 提供容器化运行支持。
- 前端（Vue 3 + Element Plus）：集中于 frontend 目录，包含入口、路由、布局、视图与通用工具，构建产物由 Nginx 提供静态托管。
- 部署与运维：通过 docker-compose.yml 统一编排前端 Nginx 与后端 Node 服务，共享网络与卷，便于升级与日志管理。

```mermaid
graph TB
subgraph "前端Nginx 静态"
FE_Main["frontend/src/main.js"]
FE_Router["frontend/src/router/index.js"]
FE_App["frontend/src/App.vue"]
end
subgraph "后端Node.js + Express"
BE_App["backend/src/app.js"]
BE_Routes["backend/src/routes/index.js"]
BE_MW_Auth["backend/src/middleware/auth.js"]
BE_Utils_JWT["backend/src/utils/jwt.js"]
BE_Config_Env["backend/src/config/env.js"]
BE_Config_DB["backend/src/config/database.js"]
BE_Config_Logger["backend/src/config/logger.js"]
BE_Config_Redis["backend/src/config/redis.js"]
BE_Models_Index["backend/src/models/index.js"]
BE_Services_Bootstrap["backend/src/services/userBootstrap.js"]
end
subgraph "基础设施"
DC["docker-compose.yml"]
DF["backend/Dockerfile"]
end
FE_Main --> FE_Router
FE_Router --> FE_App
FE_Router --> BE_App
BE_App --> BE_Routes
BE_App --> BE_MW_Auth
BE_App --> BE_Config_DB
BE_App --> BE_Config_Logger
BE_App --> BE_Config_Redis
BE_App --> BE_Config_Env
BE_Routes --> BE_MW_Auth
BE_Routes --> BE_Models_Index
BE_App --> BE_Services_Bootstrap
DC --> DF
```

图表来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)

章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)

## 核心组件
- 后端入口与中间件
  - 入口文件负责加载环境、初始化日志、同步数据库表、挂载路由与启动服务。
  - 中间件包括 CORS、JSON 解析、请求体大小限制等。
- 路由与控制器
  - 路由汇总文件统一导出路由集合，各业务路由按模块划分，控制器职责清晰。
- 认证与授权
  - 基于 JWT 的认证中间件，支持超级管理员权限校验。
- 配置与环境
  - 环境变量统一管理，支持开发/生产环境切换；数据库、日志、Redis 等配置模块化。
- 模型与数据层
  - ORM 层通过 Sequelize 管理实体，模型导出统一入口。
- 服务与工具
  - 用户引导服务用于首次部署创建超级管理员；JWT 工具封装签发与解析；密码工具用于安全存储。
- 前端入口与路由
  - Vue 应用在入口文件中注册路由与 UI 组件库；路由守卫处理鉴权与权限跳转。

章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)

## 架构总览
系统采用前后端分离架构，前端通过 Nginx 提供静态资源与 API 代理，后端以 Express 提供 RESTful 服务。核心交互流程如下：

```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Nginx as "Nginx 前端服务"
participant Backend as "Express 后端"
participant DB as "数据库"
participant Redis as "Redis 缓存"
Browser->>Nginx : "GET /"
Nginx-->>Browser : "返回前端静态页面"
Browser->>Nginx : "POST /api/login"
Nginx->>Backend : "代理转发 /api/login"
Backend->>DB : "查询用户信息"
DB-->>Backend : "返回用户数据"
Backend-->>Nginx : "返回 JWT Token"
Nginx-->>Browser : "设置 Cookie/LocalStorage 并返回响应"
Browser->>Nginx : "GET /api/dashboard/stats"
Nginx->>Backend : "代理转发 /api/dashboard/stats"
Backend->>Redis : "读取缓存"
Redis-->>Backend : "返回缓存数据"
Backend-->>Nginx : "返回统计结果"
Nginx-->>Browser : "返回响应"
```

图表来源
- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
- [backend/src/utils/jwt.js:7-21](file://backend/src/utils/jwt.js#L7-L21)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)

## 详细组件分析

### 后端入口与启动流程
- 加载环境变量与日志配置
- 初始化数据库连接并尝试同步表结构
- 启动 HTTP 服务并打印健康检查与文档地址

```mermaid
flowchart TD
Start(["启动入口"]) --> LoadEnv["加载环境变量"]
LoadEnv --> InitLogger["初始化日志"]
InitLogger --> SyncDB["同步数据库表结构"]
SyncDB --> BootstrapAdmin["引导超级管理员"]
BootstrapAdmin --> Listen["启动 HTTP 服务"]
Listen --> Health["健康检查接口 /health"]
Health --> Docs["文档接口 /docs, /redoc"]
```

图表来源
- [backend/src/app.js:42-57](file://backend/src/app.js#L42-L57)
- [backend/src/services/userBootstrap.js:5-25](file://backend/src/services/userBootstrap.js#L5-L25)

章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)

### 路由与控制器（MVC）
- 路由汇总：统一导出各业务路由模块，便于集中挂载。
- 控制器职责：处理请求参数、调用服务层、返回标准化响应。
- 中间件：认证与权限校验在路由层前置，确保受保护接口的安全性。

```mermaid
graph LR
RoutesIndex["路由汇总<br/>backend/src/routes/index.js"] --> AuthRouter["认证路由"]
RoutesIndex --> BrandsRouter["品牌路由"]
RoutesIndex --> ModelsRouter["型号路由"]
RoutesIndex --> OtaRouter["OTA 路由"]
RoutesIndex --> UsersRouter["用户路由"]
RoutesIndex --> DashboardRouter["仪表盘路由"]
AuthMW["认证中间件<br/>backend/src/middleware/auth.js"] --> AuthRouter
AuthMW --> BrandsRouter
AuthMW --> ModelsRouter
AuthMW --> OtaRouter
AuthMW --> UsersRouter
AuthMW --> DashboardRouter
```

图表来源
- [backend/src/routes/index.js:4-12](file://backend/src/routes/index.js#L4-L12)
- [backend/src/middleware/auth.js:3-33](file://backend/src/middleware/auth.js#L3-L33)

章节来源
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)

### 认证与授权（JWT）
- 登录成功后签发带过期时间的访问令牌，前端持久化存储并在后续请求头携带。
- 中间件从 Authorization 头解析 Bearer Token，验证失败返回 401。
- 超级管理员权限在路由守卫中进行二次校验。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Front as "前端路由"
participant AuthMW as "认证中间件"
participant JWTU as "JWT 工具"
participant DB as "数据库"
Client->>Front : "访问受保护路由"
Front->>AuthMW : "携带 Authorization : Bearer <token>"
AuthMW->>JWTU : "解码并验证 token"
JWTU-->>AuthMW : "返回用户信息"
AuthMW->>DB : "可选：刷新用户状态"
DB-->>AuthMW : "返回最新状态"
AuthMW-->>Front : "放行并注入 req.user"
```

图表来源
- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
- [backend/src/utils/jwt.js:19-21](file://backend/src/utils/jwt.js#L19-L21)

章节来源
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)

### 数据模型与分层
- 表层（Models）：定义实体与字段，统一导出便于上层引用。
- 服务层（Services）：封装业务逻辑与外部集成（如 S3、Redis、Meilisearch）。
- 控制器层（Routes）：接收请求、参数校验、调用服务、返回响应。
- 配置层（Config）：数据库、日志、Redis、环境变量等配置模块化。

```mermaid
graph TB
Controllers["控制器Routes"]
Services["服务Services"]
Models["模型Models"]
Config["配置Config"]
Utils["工具Utils"]
Controllers --> Services
Services --> Models
Services --> Config
Controllers --> Utils
Controllers --> Config
```

图表来源
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)

章节来源
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)

### 前端路由与导航
- 路由守卫：根据 meta 字段决定是否需要登录与超级管理员权限；对已登录但无权限的用户进行重定向。
- 导航组件：基于 Element Plus 与 Vue Router 组合，提供侧边栏与标签页导航。

```mermaid
flowchart TD
Enter["进入路由"] --> NeedAuth{"是否需要登录？"}
NeedAuth --> |否| Next["直接放行"]
NeedAuth --> |是| CheckToken["检查 Token 是否存在且未过期"]
CheckToken --> |否| RedirectLogin["重定向至登录页"]
CheckToken --> |是| CheckRole{"是否需要超级管理员？"}
CheckRole --> |否| Next
CheckRole --> |是| IsAdmin{"是否为超级管理员？"}
IsAdmin --> |否| Home["重定向至首页"]
IsAdmin --> |是| Next
```

图表来源
- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)

章节来源
- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)

## 依赖分析
- 技术栈与版本
  - 后端：Node.js 22、Express、Sequelize、MySQL2、jsonwebtoken、axios、winston、ioredis、@aws-sdk/client-s3、zod 等。
  - 前端：Vue 3、Element Plus、Vue Router、Vite、axios 等。
  - 容器与编排：Docker、Docker Compose。
- 第三方集成
  - 数据库：MySQL（通过 Sequelize）。
  - 缓存：Redis（ioredis）。
  - 对象存储：AWS S3（@aws-sdk/client-s3）。
  - 日志：Winston。
  - 校验：Zod。
- 版本兼容性
  - 后端固定使用 pnpm 11.5.2 与 Node 22；前端使用 Vite 6.x 与 Vue 3.x 生态。

```mermaid
graph TB
subgraph "后端依赖"
Node["Node.js 22"]
Express["Express"]
Sequelize["Sequelize + MySQL2"]
JWT["jsonwebtoken"]
Axios["axios"]
Winston["winston"]
Redis["ioredis"]
S3["@aws-sdk/client-s3"]
Zod["zod"]
end
subgraph "前端依赖"
Vue["Vue 3"]
EP["Element Plus"]
VR["Vue Router"]
Vite["Vite"]
end
Node --> Express
Express --> Sequelize
Express --> JWT
Express --> Axios
Express --> Winston
Express --> Redis
Express --> S3
Express --> Zod
Vue --> EP
Vue --> VR
Vite --> Vue
```

图表来源
- [backend/package.json:11-27](file://backend/package.json#L11-L27)
- [frontend/package.json:10-22](file://frontend/package.json#L10-L22)

章节来源
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)

## 性能考虑
- 前端静态资源与缓存
  - Nginx 提供静态资源托管与缓存策略，减少后端压力。
- 后端缓存与数据库
  - Redis 用于热点数据缓存，降低数据库读取压力；ORM 查询应结合索引与分页。
- API 限流与请求体大小限制
  - 通过中间件限制请求体大小，避免异常流量导致内存压力。
- 部署与伸缩
  - Docker Compose 支持水平扩展与滚动更新；建议引入负载均衡与多副本部署。

## 故障排查指南
- 健康检查
  - 访问后端 /health 接口确认服务可用。
- 日志定位
  - 查看后端容器日志与 Nginx 访问/错误日志，定位连接失败与权限问题。
- 环境变量
  - 修改 .env 后需重启后端容器使新配置生效。
- 常见问题
  - 前端白屏：确认 dist 目录上传与 Nginx 配置正确。
  - API 失败：检查数据库、Redis、Meilisearch 连接与权限。
  - 构建失败：确认上传了 package.json 与 pnpm-lock.yaml，且 Node 版本匹配。

章节来源
- [DEPLOY.md:104-113](file://DEPLOY.md#L104-L113)
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)

## 结论
该系统通过前后端分离与分层架构实现了清晰的职责划分与良好的可维护性。后端以 Express + Sequelize 为核心，结合 JWT、Redis、S3 等组件满足业务与扩展需求；前端以 Vue 3 为基础，配合路由守卫与 UI 组件库提供良好的用户体验。Docker Compose 提供了稳定的部署与运维能力，适合在生产环境中持续演进。

## 附录

### 系统上下文图
```mermaid
graph TB
Browser["浏览器"]
Nginx["Nginx前端静态 + 代理"]
Backend["Node.js 后端Express"]
MySQL["MySQL"]
Redis["Redis"]
S3["AWS S3"]
Browser --> Nginx
Nginx --> Backend
Backend --> MySQL
Backend --> Redis
Backend --> S3
```

图表来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/package.json:21](file://backend/package.json#L21)

### 组件分解图（后端）
```mermaid
graph TB
App["入口 app.js"]
Routers["路由汇总 routes/index.js"]
AuthMW["认证中间件 middleware/auth.js"]
JWTU["JWT 工具 utils/jwt.js"]
Env["环境配置 config/env.js"]
DB["数据库配置 config/database.js"]
Logger["日志配置 config/logger.js"]
RedisCfg["Redis 配置 config/redis.js"]
Models["模型导出 models/index.js"]
Bootstrap["引导服务 services/userBootstrap.js"]
App --> Routers
App --> AuthMW
App --> DB
App --> Logger
App --> RedisCfg
App --> Env
Routers --> AuthMW
Routers --> Models
App --> Bootstrap
AuthMW --> JWTU
```

图表来源
- [backend/src/app.js:14-37](file://backend/src/app.js#L14-L37)
- [backend/src/routes/index.js:4-12](file://backend/src/routes/index.js#L4-L12)
- [backend/src/middleware/auth.js:3-33](file://backend/src/middleware/auth.js#L3-L33)
- [backend/src/utils/jwt.js:7-25](file://backend/src/utils/jwt.js#L7-L25)
- [backend/src/config/env.js:7-12](file://backend/src/config/env.js#L7-L12)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [backend/src/services/userBootstrap.js:5-25](file://backend/src/services/userBootstrap.js#L5-L25)

### 部署拓扑与端口映射
- 前端（Nginx）：宿主端口 8082 -> 容器端口 80，静态资源来自 dist，代理 /api 到后端。
- 后端（Node.js）：宿主端口 8083 -> 容器端口 8000，容器内固定 PORT=8000 以匹配 Nginx 代理。
- 网络：两服务加入同一桥接网络，便于内部通信。
- 卷：OTA 升级包本地存储卷挂载至后端容器，便于 X9 设备离线升级。

章节来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [DEPLOY.md:7-11](file://DEPLOY.md#L7-L11)
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)

### 安全性、监控与灾备
- 安全性
  - JWT 过期时间控制、中间件统一鉴权、超级管理员权限校验。
  - 生产环境必须修改 JWT_SECRET 与默认管理员密码。
- 监控
  - Winston 输出日志，Docker 日志轮转配置，建议接入集中式日志系统。
- 灾难恢复
  - 数据库与 Redis 建议启用备份与异地复制；对象存储 S3 建议开启版本控制与跨区域复制。

章节来源
- [backend/src/utils/jwt.js:3-5](file://backend/src/utils/jwt.js#L3-L5)
- [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)

### 架构演进路线图与未来规划
- 短期
  - 引入统一的 OpenAPI/Swagger 文档与校验（Zod 已具备基础校验能力）。
  - 增强日志与指标采集，完善告警机制。
- 中期
  - 引入消息队列（如 Redis Streams/RabbitMQ）处理异步任务（如 OTA 文件处理、通知发送）。
  - 前端组件库与路由按功能域进一步拆分，提升可维护性。
- 长期
  - 服务网格与 API 网关（如 Kong/Envoy）增强可观测性与治理能力。
  - 多环境（Dev/Staging/Prod）与蓝绿/金丝雀发布策略。