Files

T

2026-06-30 14:46:52 +08:00

15 KiB

Raw Blame History

开发指南

**本文引用的文件** - [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)

简介

本开发指南面向参与“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：部署与运维指南，涵盖首次部署、更新部署、常见问题与本地开发。

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

图表来源

章节来源

核心组件

后端入口与生命周期
- 应用入口负责加载环境、初始化日志、同步数据库表、引导超级管理员，并启动 HTTP 服务。
- 关键点：健康检查接口、根路径响应、统一 CORS 配置、请求体大小限制中间件。
路由聚合
- 路由按功能模块拆分并在入口集中注册，便于扩展与维护。
认证中间件
- 基于 Bearer Token 的鉴权，支持超级管理员权限校验。
环境加载
- 统一从项目根目录加载 .env，支持本地开发与 Docker 环境差异。
前端应用与路由
- 基于 Vue 3 + Element Plus，内置路由守卫实现登录态与权限控制。
- Vite 开发服务器配置了 /api 代理到后端端口。

章节来源

架构总览

系统采用前后端分离与容器化部署：

前端：Nginx 静态托管，通过 /api 代理转发至后端。
后端：Node.js + Express，提供 REST API，连接数据库、缓存与对象存储。
编排：Docker Compose 统一管理服务生命周期与网络。
部署：提供本地构建 + 上传脚本与一键部署流程。

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 搜索引擎"]

图表来源

详细组件分析

后端应用与启动流程

加载环境变量：优先读取根目录 .env，确保开发与生产一致性。
初始化日志、数据库与超级管理员引导。
启动 HTTP 服务器，提供根路径与健康检查接口。

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 : "返回运行状态"

图表来源

章节来源

认证与权限控制

鉴权中间件：解析 Authorization 头，校验 Bearer Token 有效性与过期时间。
超级管理员校验：对特定路由进行权限拦截。
前端路由守卫：根据登录态与角色重定向或拒绝访问。

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

图表来源

章节来源

前端应用与开发体验

应用入口：注册 Element Plus、路由、主题样式，完成首屏渲染控制。
开发服务器：Vite 提供热更新与 /api 代理，便于联调后端。
路由设计：菜单驱动的权限路由，支持超级管理员专属页面。

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 : "渲染页面"

图表来源

章节来源

部署与上传脚本

支持按模块选择性上传：前端、后端、编排文件。
支持虚拟执行预览同步结果，避免误操作。
默认上传到服务器指定根目录，支持自定义 SSH 密钥与远端路径。

flowchart TD
CLI["命令行参数"] --> Resolve["解析预设/路径"]
Resolve --> BuildList["生成待同步列表"]
BuildList --> DryRun{"是否预览模式"}
DryRun --> |是| Preview["打印预览信息"]
DryRun --> |否| Sync["rsync 同步"]
Preview --> Done["完成"]
Sync --> Done

图表来源

scripts/upload.sh:1-191

章节来源

scripts/upload.sh:1-191

依赖分析

后端依赖
- 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 提供静态资源与代理。

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

图表来源

章节来源

性能考虑

服务端
- 合理设置数据库连接池与查询索引，避免慢查询。
- 使用缓存层（Redis）降低热点数据读取压力。
- 控制日志级别与输出频率，避免 I/O 抖动。
客户端
- 按需加载组件与路由，减少首屏体积。
- 图片与静态资源启用压缩与缓存策略。
编排与部署
- 使用只读挂载静态资源，避免不必要的写入。
- 合理设置容器日志轮转，控制磁盘占用。

故障排查指南

前端页面空白
- 检查前端构建产物是否上传成功、Nginx 配置是否正确。
- 查看前端容器日志定位问题。
API 请求失败
- 确认后端服务状态、数据库/缓存/搜索引擎连接情况。
- 核对 Nginx 代理目标与端口映射。
后端构建失败（pnpm/Node 版本）
- 确认上传了 package.json 与 pnpm-lock.yaml。
- 检查后端镜像基础版本与 Node 版本匹配。
修改 .env 后不生效
- 强制重建后端容器以重新注入环境变量。
停止与重启
- 使用 Compose 停止或重启相关服务。

章节来源

DEPLOY.md:226-256

结论

本指南提供了从开发到部署的全链路实践建议。建议团队在日常工作中遵循统一的代码规范、版本与分支策略，并结合自动化测试与日志监控提升交付质量与稳定性。

附录

开发环境配置

本地开发
- 后端：根目录配置 .env，安装依赖后启动服务。
- 前端：安装依赖后启动开发服务器，自动代理 /api 到后端端口。
Docker 开发
- 使用 Compose 启动服务，注意端口映射与容器内端口一致性。

章节来源

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 构建与启动。
仅更新前端或后端时，可选择性上传并重启对应服务。

章节来源

团队协作与文档维护

代码审查
- 至少一名合作者审查并通过 CI 检查后方可合并。
文档
- 重要变更同步更新 README、DEPLOY.md 与内部 Wiki。
沟通
- 使用问题跟踪与每日站会保持进度透明。

15 KiB Raw Blame History Unescape Escape

开发指南

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端应用与启动流程

认证与权限控制

前端应用与开发体验

部署与上传脚本

依赖分析

性能考虑

故障排查指南

结论

附录

开发环境配置

Git 工作流与分支策略

代码规范与命名约定

测试策略

依赖管理与版本控制

发布流程

团队协作与文档维护

15 KiB

Raw Blame History