297 lines
13 KiB
Markdown
297 lines
13 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/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>
|
||
|
|
|
||
|
|
## 目录
|
||
|
|
1. [简介](#简介)
|
||
|
|
2. [项目结构](#项目结构)
|
||
|
|
3. [核心组件](#核心组件)
|
||
|
|
4. [架构总览](#架构总览)
|
||
|
|
5. [详细组件分析](#详细组件分析)
|
||
|
|
6. [依赖关系分析](#依赖关系分析)
|
||
|
|
7. [性能注意事项](#性能注意事项)
|
||
|
|
8. [故障排除指南](#故障排除指南)
|
||
|
|
9. [结论](#结论)
|
||
|
|
10. [附录](#附录)
|
||
|
|
|
||
|
|
## 简介
|
||
|
|
本指南面向首次接触项目的开发者，帮助你在最短时间内完成环境准备、依赖安装、数据库初始化、环境变量配置以及本地或容器化启动。文档同时提供 Docker Compose 的完整部署流程，并给出常见问题的排查建议与基础使用示例，涵盖添加品牌、创建型号、进行 OTA 更新的关键操作路径。
|
||
|
|
|
||
|
|
## 项目结构
|
||
|
|
项目采用前后端分离架构，后端为 Node.js + Express，前端为 Vue 3 + Vite，通过 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"]
|
||
|
|
end
|
||
|
|
FE_PORT --> FRONTEND
|
||
|
|
BE_PORT --> BACKEND
|
||
|
|
DATA_VOL -. 存储OTA升级包 .-> BACKEND
|
||
|
|
FRONTEND --> |"反向代理 /api"| BACKEND
|
||
|
|
BACKEND --> DB
|
||
|
|
BACKEND --> REDIS
|
||
|
|
NET --- BACKEND
|
||
|
|
NET --- FRONTEND
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [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)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [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)
|
||
|
|
|
||
|
|
## 核心组件
|
||
|
|
- 后端入口与启动
|
||
|
|
- 后端通过入口文件启动，内置健康检查与数据库同步逻辑，启动后自动尝试创建表并初始化超级管理员账户。
|
||
|
|
- 环境与配置
|
||
|
|
- 通过统一的环境加载模块从项目根目录加载 .env；支持开发/生产环境切换；数据库、Redis、日志等均通过环境变量配置。
|
||
|
|
- 路由与模型
|
||
|
|
- 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块；模型层定义了品牌、型号、OTA、分享码日志与系统用户等实体。
|
||
|
|
- 日志与监控
|
||
|
|
- 使用 winston 输出到控制台与文件；提供健康检查接口便于外部探活。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [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)
|
||
|
|
|
||
|
|
## 架构总览
|
||
|
|
下图展示了从浏览器到后端 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。
|
||
|
|
- 容器安装
|
||
|
|
- 使用 Docker Compose 一键编排，后端镜像基于 node:22-alpine，前端镜像基于 nginx:alpine，构建完成后自动启动。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
|
||
|
|
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
|
||
|
|
- [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。
|
||
|
|
- 容器化
|
||
|
|
- 使用 docker compose up -d 启动；前端通过 8082 访问，后端通过 8083 访问；健康检查接口 /health 返回健康状态。
|
||
|
|
- 健康检查
|
||
|
|
- 访问 http://localhost:8083/health 验证后端是否正常运行。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [backend/src/app.js:22-38](file://backend/src/app.js#L22-L38)
|
||
|
|
- [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
|
||
|
|
|
||
|
|
### Docker 容器化部署流程
|
||
|
|
- 本地构建前端
|
||
|
|
- 在 frontend 目录执行构建，产物生成于 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 进行健康检查。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [DEPLOY.md:49-119](file://DEPLOY.md#L49-L119)
|
||
|
|
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
|
||
|
|
|
||
|
|
### 基本使用示例
|
||
|
|
- 添加第一个品牌
|
||
|
|
- 通过品牌管理界面或后端接口创建品牌信息。
|
||
|
|
- 创建型号
|
||
|
|
- 在品牌下创建对应型号，填写必要字段并保存。
|
||
|
|
- 进行 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)
|
||
|
|
|
||
|
|
## 依赖关系分析
|
||
|
|
后端应用的依赖关系如下所示：
|
||
|
|
|
||
|
|
```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)
|
||
|
|
|
||
|
|
## 性能注意事项
|
||
|
|
- 日志轮转：服务日志最大大小与保留文件数已在 compose 中配置，避免日志过大影响磁盘。
|
||
|
|
- 端口映射：前端与后端端口映射需与 Nginx 代理配置保持一致，避免代理失败导致性能下降。
|
||
|
|
- 缓存命中：合理设置 Redis 参数与数据库连接池，提升查询性能。
|
||
|
|
- 构建优化：前端构建产物仅需上传，避免重复构建；后端镜像使用 pnpm 与只读依赖锁文件，保证构建一致性。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [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)
|
||
|
|
|
||
|
|
## 故障排除指南
|
||
|
|
- 前端页面空白
|
||
|
|
- 检查 dist 是否上传成功、路径是否正确；查看前端容器日志；确认 Nginx 配置。
|
||
|
|
- API 请求失败
|
||
|
|
- 确认后端容器处于 running 状态；查看后端日志中的数据库、Redis、Meilisearch 连接错误；核对 Nginx 代理目标。
|
||
|
|
- 后端构建失败（pnpm/Node 版本）
|
||
|
|
- 确保上传了 package.json 与 pnpm-lock.yaml；后端镜像基于 node:22-alpine。
|
||
|
|
- 修改 .env 后不生效
|
||
|
|
- 重新创建后端容器以加载新环境变量。
|
||
|
|
- 停止服务
|
||
|
|
- 使用 docker compose down 停止所有服务。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
|
||
|
|
|
||
|
|
## 结论
|
||
|
|
通过本指南，你可以快速完成环境准备、依赖安装、数据库初始化与容器化部署，并掌握常见问题的排查方法。建议在正式环境中完善安全配置（如 JWT 密钥、管理员密码、S3 权限等），并结合日志与健康检查持续监控系统运行状态。
|
||
|
|
|
||
|
|
## 附录
|
||
|
|
- 本地开发命令参考
|
||
|
|
- 后端：在 backend 目录执行启动脚本，默认监听 8083。
|
||
|
|
- 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
|
||
|
|
- 健康检查
|
||
|
|
- 访问 http://localhost:8083/health 获取后端健康状态。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
|
||
|
|
- [backend/src/app.js:31-38](file://backend/src/app.js#L31-L38)
|