eafonyang
399 lines
15 KiB
Markdown
399 lines
15 KiB
Markdown
# 开发指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [README.md](file://README.md)
|
||
- [DEPLOY.md](file://DEPLOY.md)
|
||
- [docker-compose.yml](file://docker-compose.yml)
|
||
- [backend/package.json](file://backend/package.json)
|
||
- [frontend/package.json](file://frontend/package.json)
|
||
- [backend/src/app.js](file://backend/src/app.js)
|
||
- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
|
||
- [backend/src/config/env.js](file://backend/src/config/env.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/services/userBootstrap.js](file://backend/src/services/userBootstrap.js)
|
||
- [frontend/vite.config.js](file://frontend/vite.config.js)
|
||
- [frontend/src/main.js](file://frontend/src/main.js)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
|
||
- [scripts/upload.sh](file://scripts/upload.sh)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本开发指南面向参与“Audio Dashboard”项目的开发者，提供从环境搭建、代码规范、开发流程、测试策略到部署与运维的全流程指导。项目采用前后端分离架构：前端基于 Vue 3 + Vite，后端基于 Node.js + Express，通过 Docker Compose 进行编排，Nginx 提供静态资源与反向代理。
|
||
|
||
## 项目结构
|
||
项目采用多模块组织方式，根目录包含后端、前端、脚本与部署编排文件。关键目录与职责如下：
|
||
- backend：后端 Node.js 应用，包含配置、中间件、模型、路由、服务、工具与验证器等。
|
||
- frontend：前端 Vue 3 应用，包含 API 封装、组件、布局、路由、样式与视图。
|
||
- scripts：部署与同步脚本，支持一键上传与预览模式。
|
||
- docker-compose.yml：服务编排定义，包含后端 API 与前端 Nginx 服务。
|
||
- DEPLOY.md：部署与运维指南，涵盖首次部署、更新部署、常见问题与本地开发。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "根目录"
|
||
DC["docker-compose.yml"]
|
||
DEP["DEPLOY.md"]
|
||
SCR["scripts/upload.sh"]
|
||
end
|
||
subgraph "后端 backend"
|
||
BPJ["backend/package.json"]
|
||
APP["backend/src/app.js"]
|
||
CFG["backend/src/config/"]
|
||
MID["backend/src/middleware/"]
|
||
MOD["backend/src/models/"]
|
||
RT["backend/src/routes/"]
|
||
SVC["backend/src/services/"]
|
||
UTL["backend/src/utils/"]
|
||
VAL["backend/src/validators/"]
|
||
end
|
||
subgraph "前端 frontend"
|
||
FPJ["frontend/package.json"]
|
||
VCFG["frontend/vite.config.js"]
|
||
MAIN["frontend/src/main.js"]
|
||
ROUTER["frontend/src/router/index.js"]
|
||
API["frontend/src/api/"]
|
||
CMP["frontend/src/components/"]
|
||
LYT["frontend/src/layout/"]
|
||
VIEWS["frontend/src/views/"]
|
||
STY["frontend/src/styles/"]
|
||
end
|
||
DC --> APP
|
||
DC --> VCFG
|
||
APP --> RT
|
||
APP --> CFG
|
||
APP --> MID
|
||
APP --> SVC
|
||
RT --> MID
|
||
RT --> MOD
|
||
RT --> SVC
|
||
RT --> VAL
|
||
MAIN --> ROUTER
|
||
MAIN --> API
|
||
MAIN --> CMP
|
||
MAIN --> LYT
|
||
MAIN --> VIEWS
|
||
MAIN --> STY
|
||
```
|
||
|
||
图表来源
|
||
- [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/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
|
||
- [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)
|
||
|
||
章节来源
|
||
- [README.md:1-94](file://README.md#L1-L94)
|
||
- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
|
||
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
|
||
|
||
## 核心组件
|
||
- 后端入口与生命周期
|
||
- 应用入口负责加载环境、初始化日志、同步数据库表、引导超级管理员，并启动 HTTP 服务。
|
||
- 关键点：健康检查接口、根路径响应、统一 CORS 配置、请求体大小限制中间件。
|
||
- 路由聚合
|
||
- 路由按功能模块拆分并在入口集中注册，便于扩展与维护。
|
||
- 认证中间件
|
||
- 基于 Bearer Token 的鉴权，支持超级管理员权限校验。
|
||
- 环境加载
|
||
- 统一从项目根目录加载 .env，支持本地开发与 Docker 环境差异。
|
||
- 前端应用与路由
|
||
- 基于 Vue 3 + Element Plus，内置路由守卫实现登录态与权限控制。
|
||
- Vite 开发服务器配置了 /api 代理到后端端口。
|
||
|
||
章节来源
|
||
- [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/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
|
||
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
|
||
- [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)
|
||
- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
|
||
|
||
## 架构总览
|
||
系统采用前后端分离与容器化部署：
|
||
- 前端：Nginx 静态托管，通过 /api 代理转发至后端。
|
||
- 后端：Node.js + Express，提供 REST API，连接数据库、缓存与对象存储。
|
||
- 编排：Docker Compose 统一管理服务生命周期与网络。
|
||
- 部署：提供本地构建 + 上传脚本与一键部署流程。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Browser["浏览器"] --> Nginx["Nginx 前端服务<br/>端口 8082 → 80"]
|
||
Nginx --> API["后端 API 服务<br/>端口 8083 → 8000"]
|
||
subgraph "容器网络"
|
||
Nginx
|
||
API
|
||
end
|
||
API --> DB["MySQL 数据库"]
|
||
API --> REDIS["Redis 缓存"]
|
||
API --> S3["AWS S3 存储"]
|
||
API --> MEILI["Meilisearch 搜索引擎"]
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
|
||
- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
|
||
|
||
## 详细组件分析
|
||
|
||
### 后端应用与启动流程
|
||
- 加载环境变量：优先读取根目录 .env，确保开发与生产一致性。
|
||
- 初始化日志、数据库与超级管理员引导。
|
||
- 启动 HTTP 服务器，提供根路径与健康检查接口。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Entrypoint as "入口(app.js)"
|
||
participant Env as "环境加载(loadEnv.js)"
|
||
participant DB as "数据库(sequelize)"
|
||
participant Boot as "引导(userBootstrap.js)"
|
||
participant Server as "HTTP 服务器"
|
||
Entrypoint->>Env : "加载根目录 .env"
|
||
Entrypoint->>DB : "同步数据库表"
|
||
Entrypoint->>Boot : "创建超级管理员"
|
||
Entrypoint->>Server : "监听端口并启动"
|
||
Server-->>Entrypoint : "返回运行状态"
|
||
```
|
||
|
||
图表来源
|
||
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
|
||
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
|
||
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
|
||
|
||
章节来源
|
||
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
|
||
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
|
||
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
|
||
|
||
### 认证与权限控制
|
||
- 鉴权中间件：解析 Authorization 头，校验 Bearer Token 有效性与过期时间。
|
||
- 超级管理员校验：对特定路由进行权限拦截。
|
||
- 前端路由守卫：根据登录态与角色重定向或拒绝访问。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["进入受保护路由"]) --> CheckAuth["检查是否需要登录"]
|
||
CheckAuth --> |否| Allow["放行"]
|
||
CheckAuth --> |是| HasToken{"是否存在有效 Token"}
|
||
HasToken --> |否| RedirectLogin["重定向到登录页"]
|
||
HasToken --> |是| NeedSA{"是否需要超级管理员"}
|
||
NeedSA --> |否| Allow
|
||
NeedSA --> |是| IsSA{"是否为超级管理员"}
|
||
IsSA --> |否| ToHome["重定向到首页"]
|
||
IsSA --> |是| Allow
|
||
Allow --> End(["继续导航"])
|
||
RedirectLogin --> End
|
||
ToHome --> End
|
||
```
|
||
|
||
图表来源
|
||
- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
|
||
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
|
||
|
||
章节来源
|
||
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
|
||
- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
|
||
|
||
### 前端应用与开发体验
|
||
- 应用入口：注册 Element Plus、路由、主题样式，完成首屏渲染控制。
|
||
- 开发服务器：Vite 提供热更新与 /api 代理，便于联调后端。
|
||
- 路由设计：菜单驱动的权限路由，支持超级管理员专属页面。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Browser as "浏览器"
|
||
participant Vite as "Vite 开发服务器"
|
||
participant Proxy as "代理(/api)"
|
||
participant Backend as "后端 API"
|
||
Browser->>Vite : "访问 /"
|
||
Vite-->>Browser : "返回首页"
|
||
Browser->>Vite : "访问 /api/*"
|
||
Vite->>Proxy : "转发到 http : //localhost : 8083"
|
||
Proxy->>Backend : "请求后端接口"
|
||
Backend-->>Proxy : "返回数据"
|
||
Proxy-->>Vite : "透传响应"
|
||
Vite-->>Browser : "渲染页面"
|
||
```
|
||
|
||
图表来源
|
||
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
|
||
- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
|
||
|
||
章节来源
|
||
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
|
||
- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
|
||
|
||
### 部署与上传脚本
|
||
- 支持按模块选择性上传：前端、后端、编排文件。
|
||
- 支持虚拟执行预览同步结果，避免误操作。
|
||
- 默认上传到服务器指定根目录，支持自定义 SSH 密钥与远端路径。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
CLI["命令行参数"] --> Resolve["解析预设/路径"]
|
||
Resolve --> BuildList["生成待同步列表"]
|
||
BuildList --> DryRun{"是否预览模式"}
|
||
DryRun --> |是| Preview["打印预览信息"]
|
||
DryRun --> |否| Sync["rsync 同步"]
|
||
Preview --> Done["完成"]
|
||
Sync --> Done
|
||
```
|
||
|
||
图表来源
|
||
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
|
||
|
||
章节来源
|
||
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
|
||
|
||
## 依赖分析
|
||
- 后端依赖
|
||
- Web 框架与工具：Express、CORS、Sequelize、MySQL2、Axios、Dotenv、Zod、Winston、IORedis。
|
||
- 包管理：pnpm，锁定版本以保证一致性。
|
||
- 前端依赖
|
||
- 框架与 UI：Vue 3、Element Plus、Vue Router。
|
||
- 构建与开发：Vite、@vitejs/plugin-vue。
|
||
- 运行时与编排
|
||
- Docker Compose 管理服务、网络与卷，Nginx 提供静态资源与代理。
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "后端"
|
||
BE_PKG["backend/package.json"]
|
||
BE_EXP["Express"]
|
||
BE_DB["Sequelize/MySQL2"]
|
||
BE_LOG["Winston 日志"]
|
||
BE_CACHE["IORedis"]
|
||
BE_S3["@aws-sdk/client-s3"]
|
||
end
|
||
subgraph "前端"
|
||
FE_PKG["frontend/package.json"]
|
||
FE_VUE["Vue 3"]
|
||
FE_ROUTER["Vue Router"]
|
||
FE_ELE["Element Plus"]
|
||
FE_VITE["Vite"]
|
||
end
|
||
BE_PKG --> BE_EXP
|
||
BE_PKG --> BE_DB
|
||
BE_PKG --> BE_LOG
|
||
BE_PKG --> BE_CACHE
|
||
BE_PKG --> BE_S3
|
||
FE_PKG --> FE_VUE
|
||
FE_PKG --> FE_ROUTER
|
||
FE_PKG --> FE_ELE
|
||
FE_PKG --> FE_VITE
|
||
```
|
||
|
||
图表来源
|
||
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
|
||
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
|
||
|
||
章节来源
|
||
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
|
||
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
|
||
|
||
## 性能考虑
|
||
- 服务端
|
||
- 合理设置数据库连接池与查询索引，避免慢查询。
|
||
- 使用缓存层（Redis）降低热点数据读取压力。
|
||
- 控制日志级别与输出频率，避免 I/O 抖动。
|
||
- 客户端
|
||
- 按需加载组件与路由，减少首屏体积。
|
||
- 图片与静态资源启用压缩与缓存策略。
|
||
- 编排与部署
|
||
- 使用只读挂载静态资源，避免不必要的写入。
|
||
- 合理设置容器日志轮转，控制磁盘占用。
|
||
|
||
## 故障排查指南
|
||
- 前端页面空白
|
||
- 检查前端构建产物是否上传成功、Nginx 配置是否正确。
|
||
- 查看前端容器日志定位问题。
|
||
- API 请求失败
|
||
- 确认后端服务状态、数据库/缓存/搜索引擎连接情况。
|
||
- 核对 Nginx 代理目标与端口映射。
|
||
- 后端构建失败（pnpm/Node 版本）
|
||
- 确认上传了 package.json 与 pnpm-lock.yaml。
|
||
- 检查后端镜像基础版本与 Node 版本匹配。
|
||
- 修改 .env 后不生效
|
||
- 强制重建后端容器以重新注入环境变量。
|
||
- 停止与重启
|
||
- 使用 Compose 停止或重启相关服务。
|
||
|
||
章节来源
|
||
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
|
||
|
||
## 结论
|
||
本指南提供了从开发到部署的全链路实践建议。建议团队在日常工作中遵循统一的代码规范、版本与分支策略，并结合自动化测试与日志监控提升交付质量与稳定性。
|
||
|
||
## 附录
|
||
|
||
### 开发环境配置
|
||
- 本地开发
|
||
- 后端：根目录配置 .env，安装依赖后启动服务。
|
||
- 前端：安装依赖后启动开发服务器，自动代理 /api 到后端端口。
|
||
- Docker 开发
|
||
- 使用 Compose 启动服务，注意端口映射与容器内端口一致性。
|
||
|
||
章节来源
|
||
- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
|
||
- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
|
||
- [backend/src/app.js:40-56](file://backend/src/app.js#L40-L56)
|
||
|
||
### Git 工作流与分支策略
|
||
- 建议采用 Git Flow 或 GitHub Flow，主分支受保护，特性分支从 develop 拉取并合并回 develop，发布前打标签并合并到 main。
|
||
- 合并请求（MR）必须通过代码审查与 CI 检查。
|
||
|
||
### 代码规范与命名约定
|
||
- 文件与目录
|
||
- 后端按功能分层（config/middleware/models/routes/services/utils/validators），统一小写与下划线。
|
||
- 前端按功能域组织（api/components/layout/router/utils/views/styles），组件与页面使用 PascalCase。
|
||
- 命名
|
||
- 变量与函数使用驼峰命名；常量使用大写下划线；类与构造函数使用帕斯卡命名。
|
||
- 文档
|
||
- README 保持简洁，贡献者指南与变更日志独立维护。
|
||
|
||
### 测试策略
|
||
- 单元测试
|
||
- 后端：针对工具函数、验证器与服务层进行单元测试。
|
||
- 前端：针对工具函数与组件逻辑进行单元测试。
|
||
- 集成测试
|
||
- 后端：集成数据库、缓存与外部服务的端到端接口测试。
|
||
- 端到端测试
|
||
- 使用自动化测试框架（如 Playwright/Cypress）覆盖关键用户路径。
|
||
|
||
### 依赖管理与版本控制
|
||
- 包管理
|
||
- 使用 pnpm 并锁定版本，确保团队一致性。
|
||
- 版本发布
|
||
- 语义化版本管理，变更记录与发布说明同步更新。
|
||
|
||
### 发布流程
|
||
- 本地构建前端产物，使用上传脚本同步到服务器，随后在服务器执行 Compose 构建与启动。
|
||
- 仅更新前端或后端时，可选择性上传并重启对应服务。
|
||
|
||
章节来源
|
||
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
|
||
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
|
||
|
||
### 团队协作与文档维护
|
||
- 代码审查
|
||
- 至少一名合作者审查并通过 CI 检查后方可合并。
|
||
- 文档
|
||
- 重要变更同步更新 README、DEPLOY.md 与内部 Wiki。
|
||
- 沟通
|
||
- 使用问题跟踪与每日站会保持进度透明。 |