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