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

19 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) - [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)

更新摘要

变更内容

  • 新增 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 端口并通过宿主端口映射对外提供服务。

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

图表来源

章节来源

核心组件

  • 后端入口与启动
    • 后端通过入口文件启动，内置健康检查与数据库同步逻辑，启动后自动尝试创建表并初始化超级管理员账户。
  • 环境与配置
    • 通过统一的环境加载模块从项目根目录加载 .env；支持开发/生产环境切换；数据库、Redis、日志等均通过环境变量配置。
  • 路由与模型
    • 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块；模型层定义了品牌、型号、OTA、分享码日志与系统用户等实体。
  • 日志与监控
    • 使用 winston 输出到控制台与文件；提供健康检查接口便于外部探活。
  • 新增 frontend_v2 现代化前端架构
    • 基于 pnpm workspaces 的多包管理，支持 TypeScript 类型安全，UnoCSS 原子化样式，Vite 极速构建。

章节来源

架构总览

下图展示了从浏览器到后端 API 的典型请求链路，以及后端与数据库、缓存之间的交互。

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 : "返回响应"

图表来源

详细组件分析

环境与依赖安装

  • 环境要求
    • 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 采用现代化的多包架构，支持更好的代码复用和类型安全。

章节来源

环境变量配置

  • 配置位置
    • 根目录 .env（与 docker-compose.yml 同级），本地开发与 Docker 部署均从此处读取。
  • 关键变量类别
    • 数据库：数据库主机、端口、名称、用户名、密码。
    • 应用：应用名、环境（development/production）。
    • 认证：JWT 密钥、后台管理员用户名与密码。
    • 搜索：Meilisearch 地址、密钥、索引。
    • S3：区域、OTA 与测量桶名称。
    • OTA：X8/X9 基础地址、上传目录。
    • Redis EQ：主机、端口、密码、数据库编号。
  • 加载机制
    • 后端启动前统一从根目录加载 .env；Docker 部署时由 compose env_file 注入，容器内不再读取本地 .env 文件。

章节来源

数据库初始化

  • 初始化流程
    • 启动时后端尝试同步数据库表结构；若失败则记录告警但不影响服务继续运行。
    • 同时会初始化超级管理员账户，确保首次可用。
  • 连接参数
    • 默认连接 localhost:3306，数据库名与凭据可通过环境变量覆盖。

章节来源

缓存与日志

  • Redis
    • 提供 EQ 缓存客户端工厂方法，支持密码、数据库选择与错误监听。
  • 日志
    • 控制台与文件双通道输出，日志目录位于后端 src 下 logs。

章节来源

路由与模型

  • 路由
    • 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块。
  • 模型
    • 品牌、型号、OTA、分享码日志、系统用户等实体定义。

章节来源

启动命令与健康检查

  • 本地开发
    • 后端：在 backend 目录执行启动脚本，默认监听 8083。
    • 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
    • 新增 frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
  • 容器化
    • 使用 docker compose up -d 启动；前端通过 8082 访问，后端通过 8083 访问；健康检查接口 /health 返回健康状态。
  • 健康检查

更新 frontend_v2 提供更强大的开发体验，包括 TypeScript 类型检查、UnoCSS 原子化样式和更快的构建速度。

章节来源

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 支持更灵活的构建策略，可以单独构建特定包或全量构建。

章节来源

基本使用示例

  • 添加第一个品牌
    • 通过品牌管理界面或后端接口创建品牌信息。
  • 创建型号
    • 在品牌下创建对应型号，填写必要字段并保存。
  • 进行 OTA 更新
    • 上传升级包至指定目录（由环境变量配置），在 OTA 页面关联型号并发布更新。
  • 注意事项
    • OTA 升级包存储目录需与后端容器挂载一致；S3 配置按需调整。

章节来源

frontend_v2 现代化前端架构

  • 项目结构
    • 采用 pnpm workspaces 管理多个子包，每个包可独立开发和测试。
    • 支持 TypeScript 类型安全，提供更好的开发体验和代码质量保障。
    • 集成 UnoCSS 原子化样式框架，提升样式开发效率。
  • 包管理
    • packages 目录下包含多个功能包：alova（API 客户端）、axios（HTTP 客户端）、color（颜色处理）、hooks（自定义钩子）、materials（UI 组件）、scripts（构建脚本）、uno-preset（样式预设）、utils（工具函数）。
  • 开发工作流
    • 支持增量构建和热重载，开发体验更佳。
    • 类型检查和 ESLint 规则确保代码质量。
    • 支持按需加载和代码分割，优化打包体积。

新增 frontend_v2 提供了更现代化、类型安全的开发体验，适合大型项目和团队协作。

章节来源

依赖关系分析

后端应用的依赖关系如下所示：

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"]

图表来源

新增 frontend_v2 的依赖关系更加模块化，支持更好的代码复用和维护。

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

图表来源

性能注意事项

  • 日志轮转：服务日志最大大小与保留文件数已在 compose 中配置，避免日志过大影响磁盘。
  • 端口映射：前端与后端端口映射需与 Nginx 代理配置保持一致，避免代理失败导致性能下降。
  • 缓存命中：合理设置 Redis 参数与数据库连接池，提升查询性能。
  • 构建优化：前端构建产物仅需上传，避免重复构建；后端镜像使用 pnpm 与只读依赖锁文件，保证构建一致性。
  • 新增 frontend_v2 性能优化：支持增量构建、代码分割和按需加载，显著提升开发体验和构建速度。

章节来源

故障排除指南

  • 前端页面空白
    • 检查 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 后重新安装依赖。
    • 开发服务器无法启动：检查端口占用和配置文件语法。

章节来源

结论

通过本指南，你可以快速完成环境准备、依赖安装、数据库初始化与容器化部署，并掌握常见问题的排查方法。建议在正式环境中完善安全配置（如 JWT 密钥、管理员密码、S3 权限等），并结合日志与健康检查持续监控系统运行状态。

更新 frontend_v2 的引入为项目带来了更现代化的开发体验，包括类型安全、更好的包管理和更快的构建速度，适合长期维护和团队协作。

附录

  • 本地开发命令参考
    • 后端：在 backend 目录执行启动脚本，默认监听 8083。
    • 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
    • 新增 frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
  • 健康检查
  • 新增 frontend_v2 常用命令
    • 安装依赖：pnpm install
    • 开发模式：pnpm dev
    • 构建生产版本：pnpm build
    • 类型检查：pnpm type-check
    • 代码格式化：pnpm format

章节来源

Reference in New Issue View Git Blame Copy Permalink