# 快速开始

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