audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1da6d7254452cedd2f952f329cff270f405f15f4
dashboard/.qoder/repowiki/zh/content/快速开始.md
T
eafonyang 1da6d72544 全新的 ui，soybean admin
2026-07-17 09:35:32 +08:00

410 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 快速开始
<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)
- [frontend_v2/package.json](file://frontend_v2/package.json)
- [frontend_v2/pnpm-workspace.yaml](file://frontend_v2/pnpm-workspace.yaml)
- [frontend_v2/tsconfig.json](file://frontend_v2/tsconfig.json)
- [frontend_v2/vite.config.ts](file://frontend_v2/vite.config.ts)
- [frontend_v2/uno.config.ts](file://frontend_v2/uno.config.ts)
- [backend/src/app.js](file://backend/src/app.js)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/src/routes/index.js](file://backend/src/routes/index.js)
- [backend/src/models/index.js](file://backend/src/models/index.js)
</cite>
## 更新摘要
**变更内容**
- 新增 frontend_v2 前端架构支持，采用 pnpm workspaces 和 TypeScript 配置
- 更新开发工作流以适配新的包结构和工具链
- 增强前端构建系统和类型安全支持
- 优化多包管理和依赖共享机制
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能注意事项](#性能注意事项)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向首次接触项目的开发者，帮助你在最短时间内完成环境准备、依赖安装、数据库初始化、环境变量配置以及本地或容器化启动。文档同时提供 Docker Compose 的完整部署流程，并给出常见问题的排查建议与基础使用示例，涵盖添加品牌、创建型号、进行 OTA 更新的关键操作路径。
**更新** 新增了 frontend_v2 现代化前端架构的支持，采用 pnpm workspaces 管理多包项目，TypeScript 提供类型安全，UnoCSS 实现原子化样式，Vite 提供极速开发体验。
## 项目结构
项目采用前后端分离架构，后端为 Node.js + Express，前端支持两种架构：传统 Vue 3 + Vite (frontend) 和现代化多包架构 (frontend_v2)，通过 Nginx 提供静态资源与反向代理。整体通过 Docker Compose 编排，后端容器暴露 8000 端口，前端容器暴露 80 端口并通过宿主端口映射对外提供服务。
```mermaid
graph TB
subgraph "宿主机"
FE_PORT["前端端口 8082 -> 80"]
BE_PORT["后端端口 8083 -> 8000"]
DATA_VOL["卷: /data/projects/source"]
end
subgraph "容器网络"
NET["bridge: audio-network"]
end
subgraph "后端服务"
BACKEND["dashboard-backend<br/>Node.js 22 Alpine"]
DB["MySQL"]
REDIS["Redis"]
end
subgraph "前端服务"
FRONTEND["Nginx Alpine"]
FRONTEND_V2["frontend_v2<br/>pnpm workspaces + TypeScript"]
end
FE_PORT --> FRONTEND
FE_PORT --> FRONTEND_V2
BE_PORT --> BACKEND
DATA_VOL -. 存储OTA升级包 .-> BACKEND
FRONTEND --> |"反向代理 /api"| BACKEND
FRONTEND_V2 --> |"反向代理 /api"| BACKEND
BACKEND --> DB
BACKEND --> REDIS
NET --- BACKEND
NET --- FRONTEND
NET --- FRONTEND_V2
```
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
**章节来源**
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
## 核心组件
- 后端入口与启动
- 后端通过入口文件启动，内置健康检查与数据库同步逻辑，启动后自动尝试创建表并初始化超级管理员账户。
- 环境与配置
- 通过统一的环境加载模块从项目根目录加载 .env；支持开发/生产环境切换；数据库、Redis、日志等均通过环境变量配置。
- 路由与模型
- 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块；模型层定义了品牌、型号、OTA、分享码日志与系统用户等实体。
- 日志与监控
- 使用 winston 输出到控制台与文件；提供健康检查接口便于外部探活。
- **新增** frontend_v2 现代化前端架构
- 基于 pnpm workspaces 的多包管理，支持 TypeScript 类型安全，UnoCSS 原子化样式，Vite 极速构建。
**章节来源**
- [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/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
## 架构总览
下图展示了从浏览器到后端 API 的典型请求链路，以及后端与数据库、缓存之间的交互。
```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant F as "Nginx 前端"
participant B as "Node.js 后端"
participant D as "MySQL"
participant R as "Redis"
U->>F : "访问前端页面"
F-->>U : "返回静态页面"
U->>F : "发起 /api 请求"
F->>B : "反向代理到 http : //backend : 8000"
B->>D : "查询/写入数据"
B->>R : "读取/写入缓存"
B-->>F : "返回 JSON 响应"
F-->>U : "返回响应"
```
**图表来源**
- [docker-compose.yml:13-38](file://docker-compose.yml#L13-L38)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
## 详细组件分析
### 环境与依赖安装
- 环境要求
- Node.js：后端使用 Node.js 22（容器镜像已内置），前端使用 Node.js 18（构建阶段）。
- 包管理器：项目使用 pnpm，版本在 package.json 中固定。
- 数据库：MySQL（默认端口 3306），用于存储业务数据。
- 缓存：Redis（默认端口 6379），用于 EQ 缓存等场景。
- 本地安装（非容器）
- 后端：在 backend 目录安装依赖并启动。
- 前端：在 frontend 目录安装依赖并启动，开发服务器默认端口为 3000，/api 代理至后端 8083。
- **新增** frontend_v2：在项目根目录使用 pnpm install 安装所有包，支持多包开发和独立构建。
- 容器安装
- 使用 Docker Compose 一键编排，后端镜像基于 node:22-alpine，前端镜像基于 nginx:alpine，构建完成后自动启动。
**更新** frontend_v2 采用现代化的多包架构，支持更好的代码复用和类型安全。
**章节来源**
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
### 环境变量配置
- 配置位置
- 根目录 .env（与 docker-compose.yml 同级），本地开发与 Docker 部署均从此处读取。
- 关键变量类别
- 数据库：数据库主机、端口、名称、用户名、密码。
- 应用：应用名、环境（development/production）。
- 认证：JWT 密钥、后台管理员用户名与密码。
- 搜索：Meilisearch 地址、密钥、索引。
- S3：区域、OTA 与测量桶名称。
- OTA：X8/X9 基础地址、上传目录。
- Redis EQ：主机、端口、密码、数据库编号。
- 加载机制
- 后端启动前统一从根目录加载 .env；Docker 部署时由 compose env_file 注入，容器内不再读取本地 .env 文件。
**章节来源**
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)
- [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)
### 数据库初始化
- 初始化流程
- 启动时后端尝试同步数据库表结构；若失败则记录告警但不影响服务继续运行。
- 同时会初始化超级管理员账户，确保首次可用。
- 连接参数
- 默认连接 localhost:3306，数据库名与凭据可通过环境变量覆盖。
**章节来源**
- [backend/src/app.js:42-57](file://backend/src/app.js#L42-L57)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
### 缓存与日志
- Redis
- 提供 EQ 缓存客户端工厂方法，支持密码、数据库选择与错误监听。
- 日志
- 控制台与文件双通道输出，日志目录位于后端 src 下 logs。
**章节来源**
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
### 路由与模型
- 路由
- 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块。
- 模型
- 品牌、型号、OTA、分享码日志、系统用户等实体定义。
**章节来源**
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
### 启动命令与健康检查
- 本地开发
- 后端：在 backend 目录执行启动脚本，默认监听 8083。
- 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
- **新增** frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
- 容器化
- 使用 docker compose up -d 启动；前端通过 8082 访问，后端通过 8083 访问；健康检查接口 /health 返回健康状态。
- 健康检查
- 访问 http://localhost:8083/health 验证后端是否正常运行。
**更新** frontend_v2 提供更强大的开发体验，包括 TypeScript 类型检查、UnoCSS 原子化样式和更快的构建速度。
**章节来源**
- [backend/src/app.js:22-38](file://backend/src/app.js#L22-L38)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)
- [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
### Docker 容器化部署流程
- 本地构建前端
- 在 frontend 目录执行构建，产物生成于 dist。
- **新增** frontend_v2：在项目根目录执行 pnpm build 构建所有包，产物生成于各包的 dist 目录。
- 上传到服务器
- 使用上传脚本或手动 rsync 上传前端 dist、nginx.conf、后端源码与 docker-compose.yml。
- 服务器构建与启动
- 在服务器执行 docker compose build --no-cache backend 与 docker compose up -d。
- 验证
- 使用 docker compose ps 与 docker compose logs -f backend 检查状态与日志；使用 curl http://localhost:8083/health 进行健康检查。
**更新** frontend_v2 支持更灵活的构建策略，可以单独构建特定包或全量构建。
**章节来源**
- [DEPLOY.md:49-119](file://DEPLOY.md#L49-L119)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
### 基本使用示例
- 添加第一个品牌
- 通过品牌管理界面或后端接口创建品牌信息。
- 创建型号
- 在品牌下创建对应型号，填写必要字段并保存。
- 进行 OTA 更新
- 上传升级包至指定目录（由环境变量配置），在 OTA 页面关联型号并发布更新。
- 注意事项
- OTA 升级包存储目录需与后端容器挂载一致；S3 配置按需调整。
**章节来源**
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
### frontend_v2 现代化前端架构
- 项目结构
- 采用 pnpm workspaces 管理多个子包，每个包可独立开发和测试。
- 支持 TypeScript 类型安全，提供更好的开发体验和代码质量保障。
- 集成 UnoCSS 原子化样式框架，提升样式开发效率。
- 包管理
- packages 目录下包含多个功能包：alova（API 客户端）、axios（HTTP 客户端）、color（颜色处理）、hooks（自定义钩子）、materials（UI 组件）、scripts（构建脚本）、uno-preset（样式预设）、utils（工具函数）。
- 开发工作流
- 支持增量构建和热重载，开发体验更佳。
- 类型检查和 ESLint 规则确保代码质量。
- 支持按需加载和代码分割，优化打包体积。
**新增** frontend_v2 提供了更现代化、类型安全的开发体验，适合大型项目和团队协作。
**章节来源**
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
- [frontend_v2/uno.config.ts:1-50](file://frontend_v2/uno.config.ts#L1-L50)
## 依赖关系分析
后端应用的依赖关系如下所示：
```mermaid
graph LR
APP["backend/src/app.js"] --> CFG_ENV["backend/src/config/env.js"]
APP --> CFG_DB["backend/src/config/database.js"]
APP --> CFG_REDIS["backend/src/config/redis.js"]
APP --> CFG_LOGGER["backend/src/config/logger.js"]
APP --> ROUTES["backend/src/routes/index.js"]
APP --> MODELS["backend/src/models/index.js"]
APP --> LOADENV["backend/src/config/loadEnv.js"]
```
**图表来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
**新增** frontend_v2 的依赖关系更加模块化，支持更好的代码复用和维护。
```mermaid
graph TB
subgraph "frontend_v2 主包"
MAIN["package.json"] --> WORKSPACE["pnpm-workspace.yaml"]
MAIN --> TS_CONFIG["tsconfig.json"]
MAIN --> VITE_CONFIG["vite.config.ts"]
MAIN --> UNO_CONFIG["uno.config.ts"]
end
subgraph "子包"
ALOVA["packages/alova"]
AXIOS["packages/axios"]
COLOR["packages/color"]
HOOKS["packages/hooks"]
MATERIALS["packages/materials"]
SCRIPTS["packages/scripts"]
UNOPRESET["packages/uno-preset"]
UTILS["packages/utils"]
end
WORKSPACE --> ALOVA
WORKSPACE --> AXIOS
WORKSPACE --> COLOR
WORKSPACE --> HOOKS
WORKSPACE --> MATERIALS
WORKSPACE --> SCRIPTS
WORKSPACE --> UNOPRESET
WORKSPACE --> UTILS
```
**图表来源**
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)
- [frontend_v2/uno.config.ts:1-50](file://frontend_v2/uno.config.ts#L1-L50)
## 性能注意事项
- 日志轮转：服务日志最大大小与保留文件数已在 compose 中配置，避免日志过大影响磁盘。
- 端口映射：前端与后端端口映射需与 Nginx 代理配置保持一致，避免代理失败导致性能下降。
- 缓存命中：合理设置 Redis 参数与数据库连接池，提升查询性能。
- 构建优化：前端构建产物仅需上传，避免重复构建；后端镜像使用 pnpm 与只读依赖锁文件，保证构建一致性。
- **新增** frontend_v2 性能优化：支持增量构建、代码分割和按需加载，显著提升开发体验和构建速度。
**章节来源**
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)
## 故障排除指南
- 前端页面空白
- 检查 dist 是否上传成功、路径是否正确；查看前端容器日志；确认 Nginx 配置。
- API 请求失败
- 确认后端容器处于 running 状态；查看后端日志中的数据库、Redis、Meilisearch 连接错误；核对 Nginx 代理目标。
- 后端构建失败（pnpm/Node 版本）
- 确保上传了 package.json 与 pnpm-lock.yaml；后端镜像基于 node:22-alpine。
- 修改 .env 后不生效
- 重新创建后端容器以加载新环境变量。
- 停止服务
- 使用 docker compose down 停止所有服务。
- **新增** frontend_v2 常见问题
- pnpm 版本过低：确保使用 pnpm v8+ 以支持 workspaces。
- TypeScript 类型错误：检查 tsconfig.json 配置和类型定义。
- 构建失败：清理 node_modules 后重新安装依赖。
- 开发服务器无法启动：检查端口占用和配置文件语法。
**章节来源**
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
## 结论
通过本指南，你可以快速完成环境准备、依赖安装、数据库初始化与容器化部署，并掌握常见问题的排查方法。建议在正式环境中完善安全配置（如 JWT 密钥、管理员密码、S3 权限等），并结合日志与健康检查持续监控系统运行状态。
**更新** frontend_v2 的引入为项目带来了更现代化的开发体验，包括类型安全、更好的包管理和更快的构建速度，适合长期维护和团队协作。
## 附录
- 本地开发命令参考
- 后端：在 backend 目录执行启动脚本，默认监听 8083。
- 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
- **新增** frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
- 健康检查
- 访问 http://localhost:8083/health 获取后端健康状态。
- **新增** frontend_v2 常用命令
- 安装依赖：pnpm install
- 开发模式：pnpm dev
- 构建生产版本：pnpm build
- 类型检查：pnpm type-check
- 代码格式化：pnpm format
**章节来源**
- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
- [backend/src/app.js:31-38](file://backend/src/app.js#L31-L38)
- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
Reference in New Issue View Git Blame Copy Permalink