audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修改 wiki

Browse Source
This commit is contained in:
eafonyang
2026-07-09 11:16:59 +08:00
parent b4926ba148
commit 6fab4a86d4
42 changed files with 625 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/knowledge/zh/Docker Compose 编排与 rsync 增量部署/build_system.md → .qoder/repowiki/knowledge/zh/Docker Compose 编排与 rsync 增量部署/Docker Compose 编排与 rsync 增量部署.md
+17
View File
@@ -1,3 +1,20 @@
---
kind: build_system
name: Docker Compose 编排与 rsync 增量部署
category: build_system
scope:
- '**'
source_files:
- docker-compose.yml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/nginx.conf
- scripts/upload.sh
- DEPLOY.md
- backend/package.json
- frontend/package.json
---
## 1. 构建系统与工具链
项目采用 **Docker Compose** 作为核心编排工具，结合 **pnpm** 进行依赖管理。整体架构分为前端（Vue 3 + Vite）和后端（Node.js + Express）两个独立服务。
.qoder/repowiki/knowledge/zh/Docker Compose 编排与 rsync 增量部署/_module.yaml
-15
View File
@@ -1,15 +0,0 @@
schema_version: 1
module_path: build_system
title: Docker Compose 编排与 rsync 增量部署
scope: []
source_files:
- docker-compose.yml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/nginx.conf
- scripts/upload.sh
- DEPLOY.md
- backend/package.json
- frontend/package.json
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/_index.yaml
+5 -90
View File
@@ -3,11 +3,11 @@ schema_version: 1
locale: zh-CN
branch: main
nodes_managed: true
exported_at: "2026-07-01T09:22:46Z"
exported_at: "2026-07-09T02:41:34Z"
modules:
"":
dir_name: 音频设备管理全栈平台
title: 音频设备管理全栈平台
dir_name: 耳机品牌与 OTA 升级管理平台（前后端编排）
title: 耳机品牌与 OTA 升级管理平台（前后端编排）
scope:
- .gitignore
- README.md
@@ -23,8 +23,8 @@ modules:
depends_on: []
related_to: []
backend:
dir_name: 音频设备管理后端 API
title: 音频设备管理后端 API
dir_name: 耳机品牌与型号管理后端 API
title: 耳机品牌与型号管理后端 API
scope:
- backend/
source_files: []
@@ -32,66 +32,6 @@ modules:
depends_on: []
related_to:
- path: frontend
build_system:
dir_name: Docker Compose 编排与 rsync 增量部署
title: Docker Compose 编排与 rsync 增量部署
scope: []
source_files:
- docker-compose.yml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/nginx.conf
- scripts/upload.sh
- DEPLOY.md
- backend/package.json
- frontend/package.json
children: []
depends_on: []
related_to: []
configuration_system:
dir_name: 基于环境变量与 Docker Compose 的分层配置体系
title: 基于环境变量与 Docker Compose 的分层配置体系
scope: []
source_files:
- .env.example
- backend/src/config/loadEnv.js
- backend/src/config/env.js
- backend/src/config/database.js
- backend/src/config/redis.js
- docker-compose.yml
- frontend/vite.config.js
children: []
depends_on: []
related_to: []
dependency_management:
dir_name: 基于 pnpm 与 Docker 的前后端依赖管理
title: 基于 pnpm 与 Docker 的前后端依赖管理
scope: []
source_files:
- backend/package.json
- frontend/package.json
- backend/pnpm-lock.yaml
- frontend/pnpm-lock.yaml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/pnpm-workspace.yaml
children: []
depends_on: []
related_to: []
error_handling:
dir_name: 全栈错误处理与响应规范
title: 全栈错误处理与响应规范
scope: []
source_files:
- backend/src/utils/response.js
- backend/src/app.js
- backend/src/middleware/auth.js
- backend/src/routes/models.js
- backend/src/routes/auth.js
- frontend/src/utils/request.js
children: []
depends_on: []
related_to: []
frontend:
dir_name: 耳机品牌与 OTA 升级管理前端
title: 耳机品牌与 OTA 升级管理前端
@@ -102,28 +42,3 @@ modules:
depends_on: []
related_to:
- path: backend
frontend_style:
dir_name: 深色玻璃拟态主题系统 (Lux Theme)
title: 深色玻璃拟态主题系统 (Lux Theme)
scope: []
source_files:
- frontend/src/styles/lux-theme.css
- frontend/src/layout/index.vue
- frontend/src/main.js
- frontend/src/App.vue
- frontend/package.json
children: []
depends_on: []
related_to: []
logging_system:
dir_name: 后端日志系统 (Winston)
title: 后端日志系统 (Winston)
scope: []
source_files:
- backend/src/config/logger.js
- backend/src/app.js
- backend/src/routes/auth.js
- backend/src/config/database.js
children: []
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/全栈错误处理与响应规范/_module.yaml
-13
View File
@@ -1,13 +0,0 @@
schema_version: 1
module_path: error_handling
title: 全栈错误处理与响应规范
scope: []
source_files:
- backend/src/utils/response.js
- backend/src/app.js
- backend/src/middleware/auth.js
- backend/src/routes/models.js
- backend/src/routes/auth.js
- frontend/src/utils/request.js
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/全栈错误处理与响应规范/error_handling.md → .qoder/repowiki/knowledge/zh/全栈错误处理与响应规范/全栈错误处理与响应规范.md
+15
View File
@@ -1,3 +1,18 @@
---
kind: error_handling
name: 全栈错误处理与响应规范
category: error_handling
scope:
- '**'
source_files:
- backend/src/utils/response.js
- backend/src/app.js
- backend/src/middleware/auth.js
- backend/src/routes/models.js
- backend/src/routes/auth.js
- frontend/src/utils/request.js
---
### 1. 核心策略：统一响应结构与业务码
该仓库采用**基于 HTTP 200 的业务状态码**模式，而非依赖 HTTP 协议层的状态码来区分业务逻辑的成功与失败。
.qoder/repowiki/knowledge/zh/后端日志系统 (Winston)/_module.yaml
-11
View File
@@ -1,11 +0,0 @@
schema_version: 1
module_path: logging_system
title: 后端日志系统 (Winston)
scope: []
source_files:
- backend/src/config/logger.js
- backend/src/app.js
- backend/src/routes/auth.js
- backend/src/config/database.js
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/后端日志系统 (Winston)/logging_system.md → .qoder/repowiki/knowledge/zh/后端日志系统 (Winston)/后端日志系统 (Winston).md
+13
View File
@@ -1,3 +1,16 @@
---
kind: logging_system
name: 后端日志系统 (Winston)
category: logging_system
scope:
- '**'
source_files:
- backend/src/config/logger.js
- backend/src/app.js
- backend/src/routes/auth.js
- backend/src/config/database.js
---
## 1. 核心框架与配置
- **框架**: 使用 `winston` 作为后端 Node.js 应用的统一日志框架。
- **配置文件**: `backend/src/config/logger.js` 负责初始化 logger 实例。
.qoder/repowiki/knowledge/zh/基于 pnpm 与 Docker 的前后端依赖管理/_module.yaml
-14
View File
@@ -1,14 +0,0 @@
schema_version: 1
module_path: dependency_management
title: 基于 pnpm 与 Docker 的前后端依赖管理
scope: []
source_files:
- backend/package.json
- frontend/package.json
- backend/pnpm-lock.yaml
- frontend/pnpm-lock.yaml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/pnpm-workspace.yaml
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/基于 pnpm 与 Docker 的前后端依赖管理/dependency_management.md → .qoder/repowiki/knowledge/zh/基于 pnpm 与 Docker 的前后端依赖管理/基于 pnpm 与 Docker 的前后端依赖管理.md
+16
View File
@@ -1,3 +1,19 @@
---
kind: dependency_management
name: 基于 pnpm 与 Docker 的前后端依赖管理
category: dependency_management
scope:
- '**'
source_files:
- backend/package.json
- frontend/package.json
- backend/pnpm-lock.yaml
- frontend/pnpm-lock.yaml
- backend/Dockerfile
- frontend/Dockerfile
- frontend/pnpm-workspace.yaml
---
## 1. 核心系统与工具
该项目采用 **pnpm** 作为前后端统一的 JavaScript/TypeScript 包管理器，并通过 **Docker Compose** 进行容器化编排。项目明确指定了 `packageManager` 字段（`pnpm@11.5.2`），利用 Corepack 机制确保开发环境与生产环境使用完全一致的包管理版本。
.qoder/repowiki/knowledge/zh/基于环境变量与 Docker Compose 的分层配置体系/_module.yaml
-14
View File
@@ -1,14 +0,0 @@
schema_version: 1
module_path: configuration_system
title: 基于环境变量与 Docker Compose 的分层配置体系
scope: []
source_files:
- .env.example
- backend/src/config/loadEnv.js
- backend/src/config/env.js
- backend/src/config/database.js
- backend/src/config/redis.js
- docker-compose.yml
- frontend/vite.config.js
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/基于环境变量与 Docker Compose 的分层配置体系/configuration_system.md → .qoder/repowiki/knowledge/zh/基于环境变量与 Docker Compose 的分层配置体系/基于环境变量与 Docker Compose 的分层配置体系.md
+16
View File
@@ -1,3 +1,19 @@
---
kind: configuration_system
name: 基于环境变量与 Docker Compose 的分层配置体系
category: configuration_system
scope:
- '**'
source_files:
- .env.example
- backend/src/config/loadEnv.js
- backend/src/config/env.js
- backend/src/config/database.js
- backend/src/config/redis.js
- docker-compose.yml
- frontend/vite.config.js
---
## 1. 核心系统与工具
该项目采用 **环境变量（Environment Variables）** 作为唯一的配置来源，结合 **`dotenv`** 库进行本地开发时的文件加载，并通过 **Docker Compose** 在部署时注入环境变量。这种模式遵循了 [12-Factor App](https://12factor.net/zh-cn/config) 的配置原则，实现了配置与代码的分离。
.qoder/repowiki/knowledge/zh/按功能边界拆分 model_index.vue 为子组件与 composable/按功能边界拆分 model_index.vue 为子组件与 composable.md
+30
View File
@@ -0,0 +1,30 @@
---
kind: design
name: 按功能边界拆分 model/index.vue 为子组件与 composable
source: session
category: adr
---
# 按功能边界拆分 model/index.vue 为子组件与 composable
_来源：e2577ff → b4926ba 提交周期内记录的编码计划——内容为规划时意图，实现可能滞后或有出入。_
**状态：** accepted
## 背景
frontend/src/views/model/index.vue 文件膨胀至 1824 行，同时承载搜索列表、5 个对话框、大量状态管理与样式，导致可读性与可维护性下降。
## 决策驱动
- 单文件过大难以维护
- 各对话框逻辑耦合在页面中
- 列表/搜索/分页等通用逻辑需要复用
## 备选方案
- **保持 monolithic index.vue** _（已否决）_ — 优点：改动最小；缺点：文件持续膨胀，新需求只能继续往里堆代码
- **拆分为 components + composables 目录结构** — 优点：每个对话框独立成组件；useModelList.js 抽取列表/搜索/分页/排序/复制等共享逻辑；index.vue 仅保留编排职责（~250 行）；缺点：引入更多文件，需维护 props/emits 契约
## 决策
将 model/index.vue 按功能边界拆分为：components/ModelFormDialog.vue、EqCacheDialog.vue、PushProgressDialog.vue、CsvViewerDialog.vue、PushViewDialog.vue 五个对话框组件，以及 composables/useModelList.js 提取列表核心逻辑；index.vue 仅保留搜索表单+表格+分页模板与操作按钮的编排逻辑。
## 影响
每个对话框可独立演进与测试，useModelList.js 可在其他页面复用列表能力；代价是新增跨组件通信需通过 props/emits/ref，且目录层级加深。
.qoder/repowiki/knowledge/zh/深色玻璃拟态主题系统 (Lux Theme)/_module.yaml
-12
View File
@@ -1,12 +0,0 @@
schema_version: 1
module_path: frontend_style
title: 深色玻璃拟态主题系统 (Lux Theme)
scope: []
source_files:
- frontend/src/styles/lux-theme.css
- frontend/src/layout/index.vue
- frontend/src/main.js
- frontend/src/App.vue
- frontend/package.json
depends_on: []
related_to: []
.qoder/repowiki/knowledge/zh/深色玻璃拟态主题系统 (Lux Theme)/frontend_style.md → .qoder/repowiki/knowledge/zh/深色玻璃拟态主题系统 (Lux Theme)/深色玻璃拟态主题系统 (Lux Theme).md
+14
View File
@@ -1,3 +1,17 @@
---
kind: frontend_style
name: 深色玻璃拟态主题系统 (Lux Theme)
category: frontend_style
scope:
- '**'
source_files:
- frontend/src/styles/lux-theme.css
- frontend/src/layout/index.vue
- frontend/src/main.js
- frontend/src/App.vue
- frontend/package.json
---
## 1. 核心系统与工具
- **UI 框架**: Vue 3 + Element Plus。
- **样式方案**: 原生 CSS + CSS Variables (CSS Custom Properties)。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/_module.yaml → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/_module.yaml
+1 -1
View File
@@ -1,6 +1,6 @@
schema_version: 1
module_path: ""
title: 音频设备管理全栈平台
title: 耳机品牌与 OTA 升级管理平台（前后端编排）
scope:
- .gitignore
- README.md
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/架构设计.md
+4
View File
@@ -0,0 +1,4 @@
- **服务编排**：`docker-compose.yml` 定义 `backend`（Node.js + Sequelize）和 `frontend`（Nginx 静态托管）两个服务，共用 `audio-network` 桥接网络，前端通过 Nginx 反向代理 `/api` 至后端。
- **配置边界**：根目录 `.env` 为唯一环境变量源，Compose 注入后端容器；`.env.example` 提供模板，禁止子模块各自维护环境文件。
- **存储契约**：宿主机 `/data/projects/source` 挂载至后端容器，作为 OTA 升级包的持久化共享卷，前后端以此路径为约定进行文件交互。
- **部署流水线**：`scripts/upload.sh` 基于 rsync/ssh 将前端构建产物、后端源码与编排文件增量推送至服务器，配合 `DEPLOY.md` 形成本地→远端的标准化运维路径。
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/概述.md
+1
View File
@@ -0,0 +1 @@
通过 Docker Compose 统一编排 Vue 3 前端与 Express 后端，并以标准化脚本驱动从本地到远程服务器的增量同步与容器化部署。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/耳机品牌与 OTA 升级管理前端/_module.yaml → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与 OTA 升级管理前端/_module.yaml
View File
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/耳机品牌与 OTA 升级管理前端/技术栈.md → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与 OTA 升级管理前端/技术栈.md
View File
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/耳机品牌与 OTA 升级管理前端/架构设计.md → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与 OTA 升级管理前端/架构设计.md
View File
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/耳机品牌与 OTA 升级管理前端/概述.md → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与 OTA 升级管理前端/概述.md
View File
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/耳机品牌与 OTA 升级管理前端/编码规范.md → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与 OTA 升级管理前端/编码规范.md
View File
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/_module.yaml → .qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/_module.yaml
+1 -1
View File
@@ -1,6 +1,6 @@
schema_version: 1
module_path: backend
title: 音频设备管理后端 API
title: 耳机品牌与型号管理后端 API
scope:
- backend/
source_files: []
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/技术栈.md
+1
View File
@@ -0,0 +1 @@
Node.js 22 (Alpine) + Express v4；Sequelize v6 + mysql2 访问 MySQL；ioredis 连接 Redis 缓存 EQ；@aws-sdk/client-s3 上传 OTA 包与测量文件；axios 调用 Meilisearch 搜索索引；jsonwebtoken 签发/验证 JWT；zod 做参数校验；winston 输出到 `logs/app.log`。
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/架构设计.md
+4
View File
@@ -0,0 +1,4 @@
- 入口 `src/app.js` 加载 `.env`（`config/loadEnv.js` 从仓库根目录读取）、注册 CORS/JSON/bodyLimit 中间件、挂载路由数组并调用 `sequelize.sync()` 建表后执行 `ensureBootstrapSuperAdmin` 引导超级管理员。
- 分层组织：`routes/` 按业务域拆分（auth, brands, models, ota, blacklist, otaTargetDevice, shareCodeLogs, users, dashboard），由 `routes/index.js` 汇总导出供 app 遍历挂载；`models/` 使用 Sequelize 定义实体并通过 `index.js` 统一导出；`services/` 封装外部依赖（S3、Redis、Meilisearch、曲线服务）；`middleware/` 提供认证与请求体大小限制；`utils/` 暴露 JWT、密码哈希、统一响应格式；`validators/` 以 zod schema 校验入参。
- 认证边界：`middleware/auth.js` 解析 Bearer token 注入 `req.user`，受保护路由在各自文件中通过 `router.use(authMiddleware)` 全局启用，仅 `/health`、根路径等公开接口例外；`requireSuperAdmin` 用于超管专用端点。
- 启动流程：`start.sh` → `node src/app.js` → `loadEnv` → `sequelize.sync()` → `userBootstrap.ensureBootstrapSuperAdmin()` → `app.listen(8083)`，异常时降级继续运行。
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/概述.md
+1
View File
@@ -0,0 +1 @@
基于 Express + Sequelize 的 RESTful 服务，提供耳机品牌、型号、OTA 升级、用户与黑名单管理的后端接口。
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/特殊配置与命令.md
+1
View File
@@ -0,0 +1 @@
包管理器锁定为 `pnpm@11.5.2`，安装需 `pnpm install --frozen-lockfile`；本地开发可用 `pnpm dev`（nodemon 热重载），生产通过 `start.sh`/`stop.sh`/`restart.sh` 或 Docker 镜像启动；首次启动若 `dashboard_user` 为空则根据 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 环境变量创建初始超级管理员。
.qoder/repowiki/knowledge/zh/耳机品牌与 OTA 升级管理平台（前后端编排）/耳机品牌与型号管理后端 API/编码规范.md
+5
View File
@@ -0,0 +1,5 @@
- 所有 API 返回统一 JSON 结构，包含 `code`（1:成功 / 0:错误 / 2:无数据）、`msg` 和 `data` 字段，由 `utils/response.js` 的 `ApiResponse` 生成。
- 受保护路由在各自文件顶部通过 `router.use(authMiddleware)` 全局启用 JWT 校验，仅健康检查等公开接口例外。
- 更新操作显式判断请求体字段是否为 `undefined` 或 `'null'` 字符串，区分“未提供”与“设为空”，避免覆盖现有值。
- 关键业务动作（登录、CRUD、权限拒绝）通过 `logger.info/warn/error` 记录到 `logs/app.log`，错误堆栈附带上下文信息。
- 环境变量集中通过 `config/loadEnv.js` 从仓库根目录 `.env` 加载，Docker 场景下由 compose env_file 注入而不覆盖已有变量。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/架构设计.md
-4
View File
@@ -1,4 +0,0 @@
- **服务编排**：使用 `docker-compose.yml` 定义 `backend` (Node.js) 和 `frontend` (Nginx) 服务，通过 `audio-network` 桥接网络实现内部通信。
- **配置管理**：根目录 `.env` 作为唯一环境变量源，由 Compose 注入后端容器，前端通过 Nginx 反向代理 `/api` 至后端。
- **部署流水线**：`scripts/upload.sh` 脚本基于 rsync/ssh 实现增量代码同步，配合 `DEPLOY.md` 规范了从本地构建到服务器重启的标准化运维路径。
- **存储映射**：宿主机目录 `/data/projects/source` 挂载至后端容器，用于持久化存储 OTA 升级包。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/概述.md
-1
View File
@@ -1 +0,0 @@
通过 Docker Compose 统一编排前后端服务，结合标准化部署脚本实现从本地开发到远程服务器的自动化同步与容器化运维。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/特殊配置与命令.md
-2
View File
@@ -1,2 +0,0 @@
- **一键同步**：执行 `./scripts/upload.sh all` 将前端产物、后端源码及编排文件同步至远程服务器。
- **服务启动**：在服务器端执行 `docker compose build --no-cache backend && docker compose up -d` 完成全量更新与启动。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/编码规范.md
-2
View File
@@ -1,2 +0,0 @@
- 所有服务共享根目录 `.env` 进行环境配置，禁止在各子模块中维护独立的环境变量文件。
- 前端静态资源通过 Nginx 托管并代理 API 请求，后端统一暴露于 8000 端口（容器内）并通过 Compose 映射至宿主机 8083。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/技术栈.md
-5
View File
@@ -1,5 +0,0 @@
- **运行时与框架**：Node.js 22 (Alpine), Express.js v4。
- **数据持久化**：MySQL (via `mysql2` and `sequelize` ORM)。
- **缓存与搜索**：Redis (via `ioredis` for EQ cache), Meilisearch (via `axios` for model search)。
- **文件存储**：AWS S3 (via `@aws-sdk/client-s3` for OTA packages and measurement files)。
- **工具库**：`jsonwebtoken` (JWT), `zod` (Schema 验证), `multer` (文件上传), `winston` (日志)。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/架构设计.md
-5
View File
@@ -1,5 +0,0 @@
- **分层架构**：采用经典的 MVC 模式，`routes/` 处理 HTTP 请求与响应，`models/` (Sequelize) 定义数据模型，`services/` 封装外部存储（S3, Redis）和业务逻辑。
- **入口与初始化**：`src/app.js` 为应用入口，负责加载环境变量、同步数据库表结构 (`sequelize.sync()`) 并引导创建超级管理员 (`userBootstrap`)。
- **路由组织**：`src/routes/index.js` 汇总所有业务路由（auth, brands, models, ota 等），通过 Express 中间件机制挂载。
- **认证机制**：`middleware/auth.js` 实现基于 JWT 的身份验证，支持普通用户登录与超级管理员权限校验 (`requireSuperAdmin`)。
- **外部集成**：通过 `services/` 目录下的模块与 AWS S3 (文件存储)、Redis (EQ 缓存)、Meilisearch (搜索索引) 及远程曲线服务进行交互。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/概述.md
-1
View File
@@ -1 +0,0 @@
提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/特殊配置与命令.md
-3
View File
@@ -1,3 +0,0 @@
- **依赖管理**：使用 `pnpm` 作为包管理器 (`packageManager: pnpm@11.5.2`)，安装命令为 `pnpm install --frozen-lockfile`。
- **启动脚本**：提供 `start.sh`, `stop.sh`, `restart.sh` 用于进程管理；Docker 镜像基于 `node:22-alpine` 构建。
- **环境引导**：首次启动时会自动执行 `ensureBootstrapSuperAdmin`，若数据库无用户则根据环境变量 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 创建初始超级管理员。
.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/编码规范.md
-4
View File
@@ -1,4 +0,0 @@
- 统一响应格式：所有 API 均通过 `utils/response.js` 中的 `ApiResponse` 对象返回标准化 JSON，包含 `code` (1:成功, 0:错误, 2:无数据), `msg` 和 `data` 字段。
- 集中式日志记录：使用 `winston` 配置的 `logger` 记录关键业务操作（如登录、创建/更新/删除资源）及错误信息，日志输出至 `logs/app.log`。
- 路由级认证保护：受保护的路由组（如 brands, models, ota）在路由文件顶部通过 `router.use(authMiddleware)` 全局启用 JWT 验证，仅公开接口（如 `/health`, `/api/ota/latest/check`）例外。
- 参数空值处理：在更新操作中，显式检查请求体字段是否为 `undefined` 或 `'null'` 字符串，以区分“未提供”与“设为空”，避免意外覆盖现有数据。
.qoder/repowiki/zh/content/开发指南.md → .qoder/repowiki/zh/content/开发指南/开发指南.md
View File
.qoder/repowiki/zh/content/开发指南/设计系统.md
+325
View File
@@ -0,0 +1,325 @@
# 设计系统
<cite>
**本文引用的文件**
- [backend/src/app.js](file://backend/src/app.js)
- [backend/src/routes/index.js](file://backend/src/routes/index.js)
- [backend/src/routes/auth.js](file://backend/src/routes/auth.js)
- [backend/src/models/index.js](file://backend/src/models/index.js)
- [backend/src/models/Brand.js](file://backend/src/models/Brand.js)
- [backend/src/models/Model.js](file://backend/src/models/Model.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/package.json](file://backend/package.json)
- [frontend/src/main.js](file://frontend/src/main.js)
- [frontend/src/App.vue](file://frontend/src/App.vue)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
- [frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
- [frontend/package.json](file://frontend/package.json)
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可扩展性](#性能与可扩展性)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本项目是一个面向耳机品牌与型号管理的后台管理系统，包含前后端分离的完整实现：前端基于 Vue 3 + Element Plus，后端基于 Express + Sequelize（MySQL），通过 Docker Compose 进行容器化部署。系统提供品牌管理、型号管理、OTA 升级包管理、黑名单管理、定向升级、分享码日志以及用户认证等能力。
## 项目结构
仓库采用前后端分层组织方式：
- backend：Express 应用入口、路由、模型、配置、中间件、服务与工具模块
- frontend：Vue 3 应用入口、路由、布局、视图、API 封装、样式与工具
- docker-compose.yml：编排前端 Nginx 与后端 Node 服务
- DEPLOY.md：部署与环境说明
```mermaid
graph TB
subgraph "前端"
FE_main["frontend/src/main.js"]
FE_app["frontend/src/App.vue"]
FE_router["frontend/src/router/index.js"]
FE_layout["frontend/src/layout/index.vue"]
FE_home["frontend/src/views/home/index.vue"]
end
subgraph "后端"
BE_app["backend/src/app.js"]
BE_routes["backend/src/routes/index.js"]
BE_auth["backend/src/routes/auth.js"]
BE_models["backend/src/models/index.js"]
BE_brand["backend/src/models/Brand.js"]
BE_model["backend/src/models/Model.js"]
BE_db["backend/src/config/database.js"]
end
FE_main --> FE_app
FE_app --> FE_router
FE_router --> FE_layout
FE_layout --> FE_home
FE_main --> |"HTTP 请求 /api/*"| BE_app
BE_app --> BE_routes
BE_routes --> BE_auth
BE_auth --> BE_models
BE_models --> BE_brand
BE_models --> BE_model
BE_app --> BE_db
```
**图表来源**
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
- [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
- [frontend/src/layout/index.vue:1-348](file://frontend/src/layout/index.vue#L1-L348)
- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-15](file://backend/src/routes/index.js#L1-L15)
- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
- [backend/src/models/index.js:1-10](file://backend/src/models/index.js#L1-L10)
- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
**章节来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
## 核心组件
- 应用入口
- 后端：Express 应用初始化、全局中间件、健康检查、路由挂载、数据库同步与启动监听
- 前端：Vue 应用创建、Element Plus 注册、路由挂载、加载遮罩处理
- 路由层
- 后端：按功能域拆分路由并统一汇总挂载
- 前端：基于 vue-router 的页面路由与导航守卫（鉴权、超级管理员控制）
- 数据模型
- 使用 Sequelize 定义实体（如 Brand、Model），集中导出供路由与服务使用
- 配置与基础设施
- 数据库连接、环境变量加载、日志、Redis 等（部分在配置目录中）
**章节来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-15](file://backend/src/routes/index.js#L1-L15)
- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
- [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
- [backend/src/models/index.js:1-10](file://backend/src/models/index.js#L1-L10)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
## 架构总览
系统采用经典的前后端分离架构，前端静态资源由 Nginx 托管并通过反向代理将 /api 转发到后端；后端以 Express 提供服务，使用 Sequelize 访问 MySQL。
```mermaid
graph TB
Client["浏览器客户端"]
Nginx["Nginx(前端容器)"]
API["Express(后端容器)"]
DB["MySQL"]
Redis["Redis(可选)"]
Client --> Nginx
Nginx --> |"/api/*" 代理| API
API --> DB
API --> Redis
```
**图表来源**
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
## 详细组件分析
### 认证流程（登录与鉴权）
该流程涵盖前端导航守卫、后端登录接口、JWT 签发与受保护接口的鉴权中间件。
```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端路由守卫"
participant API as "后端认证路由"
participant DB as "数据库"
participant JWT as "JWT工具"
U->>FE : 访问受保护页面
FE->>FE : 检查本地令牌是否过期
alt 无令牌或已过期
FE-->>U : 重定向至登录页
else 有有效令牌
FE->>API : GET /api/auth/me
API->>DB : 查询当前用户
DB-->>API : 返回用户信息
API-->>FE : 返回用户信息
FE-->>U : 放行并渲染页面
end
U->>API : POST /api/auth/login
API->>DB : 校验用户名/状态
DB-->>API : 返回用户记录
API->>API : 校验密码哈希
API->>JWT : 生成访问令牌
JWT-->>API : 返回令牌
API-->>U : 返回令牌与用户信息
```
**图表来源**
- [frontend/src/router/index.js:76-100](file://frontend/src/router/index.js#L76-L100)
- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
- [backend/src/routes/auth.js:66-77](file://backend/src/routes/auth.js#L66-L77)
**章节来源**
- [frontend/src/router/index.js:76-100](file://frontend/src/router/index.js#L76-L100)
- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
- [backend/src/routes/auth.js:66-77](file://backend/src/routes/auth.js#L66-L77)
### 首页“今日新增”数据流
首页展示当日新增的型号与 OTA 记录，调用仪表盘统计接口获取数据。
```mermaid
sequenceDiagram
participant V as "Home 视图"
participant API as "Dashboard API"
participant S as "后端路由/服务"
participant DB as "数据库"
V->>API : 请求今日统计数据
API->>S : 进入业务逻辑
S->>DB : 聚合当日新增型号/OTA
DB-->>S : 返回统计结果
S-->>API : 组装响应
API-->>V : 返回 models/otas 列表
V->>V : 渲染卡片与列表
```
**图表来源**
- [frontend/src/views/home/index.vue:127-148](file://frontend/src/views/home/index.vue#L127-L148)
**章节来源**
- [frontend/src/views/home/index.vue:127-148](file://frontend/src/views/home/index.vue#L127-L148)
### 数据模型与关系（简化）
以下模型用于品牌与型号管理，字段注释清晰，便于理解数据结构。
```mermaid
erDiagram
BRAND {
int id PK
string name UK
}
MODEL {
int id PK
string brand_name
string name
string form
string rig
string source
string eq_key
datetime create_at
}
BRAND ||--o{ MODEL : "brand_name 关联"
```
**图表来源**
- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-53)
**章节来源**
- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-53)
### 布局与导航
侧边栏支持折叠/展开、面包屑与用户菜单，结合路由元信息进行权限控制与高亮。
```mermaid
flowchart TD
Start(["进入 Layout"]) --> ResolveMenu["根据当前路径计算展开菜单"]
ResolveMenu --> Breadcrumb["解析面包屑标题与分组"]
Breadcrumb --> UserMenu{"用户菜单操作"}
UserMenu --> |退出| Logout["清除本地认证并重定向登录"]
UserMenu --> |账号管理| ToUsers["跳转系统用户管理"]
UserMenu --> |修改密码| OpenDialog["打开修改密码弹窗"]
Logout --> End(["结束"])
ToUsers --> End
OpenDialog --> End
```
**图表来源**
- [frontend/src/layout/index.vue:174-231](file://frontend/src/layout/index.vue#L174-L231)
**章节来源**
- [frontend/src/layout/index.vue:174-231](file://frontend/src/layout/index.vue#L174-L231)
## 依赖关系分析
- 后端依赖
- Express、Sequelize、MySQL、JSON Web Token、Multer、Axios、Zod、Winston、ioredis、AWS SDK（S3）等
- 前端依赖
- Vue 3、Element Plus、Vue Router、Axios、JSON Pretty 等
- 运行时编排
- Docker Compose 编排前端 Nginx 与后端 Node 服务，端口映射与网络互通
```mermaid
graph LR
FE_pkg["frontend/package.json"]
BE_pkg["backend/package.json"]
Compose["docker-compose.yml"]
FE_pkg --> |"构建产物 dist"| Compose
BE_pkg --> |"镜像构建/运行"| Compose
Compose --> |"Nginx 8082 -> 80"| FE_static["前端静态资源"]
Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]
```
**图表来源**
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
**章节来源**
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
## 性能与可扩展性
- 数据库连接
- 使用 Sequelize 连接 MySQL，建议在生产环境启用连接池与慢查询日志，合理设置超时与重试策略
- 静态资源
- 前端通过 Nginx 缓存静态资源，开启 Gzip/Brotli 压缩可提升首屏加载速度
- 鉴权与限流
- 建议在网关层增加速率限制与请求体大小限制（后端已有 bodyLimit 中间件）
- 扩展点
- 可按功能域继续拆分路由与服务，引入缓存层（Redis）与消息队列以提升吞吐
[本节为通用指导，不直接分析具体文件]
## 故障排查指南
- 前端空白
- 确认 dist 已上传且 Nginx 配置正确，查看浏览器控制台是否有 404 或跨域错误
- API 请求失败
- 检查后端容器状态与健康检查接口，查看后端日志定位数据库/Redis 连接问题
- 后端构建失败
- 确认镜像基础版本与 pnpm 版本一致，确保上传了 package.json 与锁文件
- 环境变量未生效
- 重新创建容器使 .env 生效
**章节来源**
- [DEPLOY.md:226-269](file://DEPLOY.md#L226-L269)
## 结论
本设计系统以清晰的模块化与容器化部署为基础，提供了完整的品牌与型号管理能力，并在认证、路由、模型与部署方面形成了稳定的工程实践。后续可在缓存、监控与可观测性方面进一步增强，以满足更大规模的生产需求。
[本节为总结性内容，不直接分析具体文件]
## 附录
- 关键入口与脚本
- 后端入口：[backend/src/app.js](file://backend/src/app.js)
- 前端入口：[frontend/src/main.js](file://frontend/src/main.js)
- 路由汇总：[backend/src/routes/index.js](file://backend/src/routes/index.js)
- 认证路由：[backend/src/routes/auth.js](file://backend/src/routes/auth.js)
- 模型索引：[backend/src/models/index.js](file://backend/src/models/index.js)
- 数据库配置：[backend/src/config/database.js](file://backend/src/config/database.js)
- 前端路由：[frontend/src/router/index.js](file://frontend/src/router/index.js)
- 布局组件：[frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
- 首页视图：[frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
- 部署文档：[DEPLOY.md](file://DEPLOY.md)
- 编排文件：[docker-compose.yml](file://docker-compose.yml)
.qoder/repowiki/zh/content/系统架构/后端架构.md
+80 -2
View File
@@ -22,6 +22,13 @@
- [backend/src/services/measurementStorage.js](file://backend/src/services/measurementStorage.js)
</cite>
## 更新摘要
**变更内容**
- 增强了curveClient服务的错误处理和日志记录机制
- 提升了音频曲线API集成的可靠性和可观测性
- 优化了外部API调用的超时配置和异常处理
- 完善了响应数据的详细日志输出用于调试
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
@@ -392,6 +399,8 @@ I --> |是| K["放行"]
- 外部服务错误
- S3/曲线服务捕获异常并记录日志，抛出统一错误
**更新** curveClient服务增强了错误处理和日志记录机制，提升了音频曲线API集成的可靠性
章节来源
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [backend/src/routes/auth.js:60-64](file://backend/src/routes/auth.js#L60-L64)
@@ -485,6 +494,62 @@ App->>App : "listen(PORT)"
- [backend/src/app.js:22-34](file://backend/src/app.js#L22-L34)
- [backend/src/app.js:42-59](file://backend/src/app.js#L42-L59)
### 音频曲线API集成增强
**新增** curveClient服务经过重大增强，显著提升了音频曲线API集成的可靠性和可观测性：
#### 增强的错误处理机制
- **网络请求异常处理**：axios请求失败时记录详细的警告日志，包含完整的URL和错误信息
- **HTTP状态码验证**：对非200状态码进行专门处理，返回明确的错误信息
- **响应数据验证**：多层嵌套的响应数据结构解析，支持多种格式
- **Base64解码容错**：自定义字符映射和标准Base64转换的错误处理
- **JSON解析异常**：解码后JSON格式的验证和错误捕获
#### 完善的日志记录系统
- **请求追踪日志**：记录完整的请求参数（品牌、型号、佩戴方式、目标类型、完整URL）
- **响应调试日志**：详细记录响应状态码、数据类型和部分响应内容（限制长度避免日志过大）
- **错误诊断日志**：关键错误点记录原始数据片段，便于问题定位
- **结构化日志格式**：统一的timestamp-level-message格式，支持元数据扩展
#### 可靠的超时配置
- **请求超时控制**：默认20秒超时，防止长时间阻塞
- **连接超时保护**：Redis客户端配置10秒连接超时
- **重试机制**：Redis操作最多重试2次
```mermaid
sequenceDiagram
participant Client as "调用方"
participant Curve as "curveClient.js"
participant Axios as "Axios HTTP客户端"
participant Logger as "日志系统"
participant External as "外部曲线API"
Client->>Curve : fetchAndValidateCurve()
Curve->>Logger : 记录请求参数日志
Curve->>Axios : GET 请求(带超时配置)
Axios->>External : 发送HTTP请求
External-->>Axios : 返回响应
Axios-->>Curve : 响应数据
Curve->>Logger : 记录响应状态和数据类型
Curve->>Curve : 解析响应数据
alt 解析成功
Curve->>Curve : Base64解码
Curve->>Curve : JSON解析
Curve->>Curve : 验证parametric_eq结构
Curve-->>Client : 返回验证结果
else 解析失败
Curve->>Logger : 记录详细错误信息
Curve-->>Client : 返回错误信息
end
```
图表来源
- [backend/src/services/curveClient.js:81-138](file://backend/src/services/curveClient.js#L81-L138)
- [backend/src/config/logger.js:10-26](file://backend/src/config/logger.js#L10-L26)
章节来源
- [backend/src/services/curveClient.js:1-147](file://backend/src/services/curveClient.js#L1-147)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
## 依赖关系分析
- 包管理与运行
- 依赖 express、sequelize、mysql2、jsonwebtoken、winston、ioredis 等
@@ -531,6 +596,10 @@ SVC --> LOG["logger.js"]
- 设置超时与错误处理，避免阻塞请求
- 日志
- 控制台与文件双通道，避免 info 级日志过多
- 音频曲线API
- 合理的超时配置（20秒）防止长时间等待
- 响应数据截断日志避免日志过大
- 错误处理快速失败，不阻塞主流程
## 故障排查指南
- 认证失败
@@ -545,15 +614,22 @@ SVC --> LOG["logger.js"]
- S3 读取/上传失败
- 检查凭证或 IAM 角色配置
- 关注 NoSuchKey 等特定异常
- **音频曲线API问题**
- 检查 CURVE_API_BASE_URL 环境变量配置
- 查看详细的请求和响应日志，特别是响应数据类型和内容
- 确认网络连接和防火墙设置
- 检查Base64编码格式是否正确
- 验证parametric_eq数据结构是否符合要求
章节来源
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/app.js:48-51](file://backend/src/app.js#L48-L51)
- [backend/src/config/redis.js:24-26](file://backend/src/config/redis.js#L24-L26)
- [backend/src/services/measurementStorage.js:102-107](file://backend/src/services/measurementStorage.js#L102-L107)
- [backend/src/services/curveClient.js:92-116](file://backend/src/services/curveClient.js#L92-L116)
## 结论
本后端以 Express 为核心，采用清晰的分层与模块化设计，结合 Sequelize、Redis 与 Winston 实现了稳定的数据访问、缓存与日志能力。认证授权、请求限制与统一响应提升了安全性与一致性。建议后续引入 API 版本前缀、完善错误分类与指标上报，持续优化数据库与缓存策略以提升整体性能与可观测性。
本后端以 Express 为核心，采用清晰的分层与模块化设计，结合 Sequelize、Redis 与 Winston 实现了稳定的数据访问、缓存与日志能力。认证授权、请求限制与统一响应提升了安全性与一致性。**最新的curveClient服务增强显著提升了音频曲线API集成的可靠性和可观测性，通过完善的错误处理机制、详细的日志记录和合理的超时配置，确保了外部服务调用的稳定性。** 建议后续引入 API 版本前缀、完善错误分类与指标上报，持续优化数据库与缓存策略以提升整体性能与可观测性。
## 附录
- 环境变量
@@ -563,6 +639,7 @@ SVC --> LOG["logger.js"]
- JWT_SECRET：令牌签名密钥
- DASHBOARD_ADMIN_*：超级管理员初始化用户名与密码
- AWS_*：S3 区域、凭证与桶名
- **CURVE_API_BASE_URL：音频曲线API基础地址**
- 路由示例
- GET / → 根路径
- GET /health → 健康检查
@@ -578,4 +655,5 @@ SVC --> LOG["logger.js"]
- [backend/src/services/userBootstrap.js:9-10](file://backend/src/services/userBootstrap.js#L9-L10)
- [backend/src/services/measurementStorage.js:9-12](file://backend/src/services/measurementStorage.js#L9-L12)
- [backend/src/app.js:22-34](file://backend/src/app.js#L22-L34)
- [backend/src/routes/auth.js:24-77](file://backend/src/routes/auth.js#L24-L77)
- [backend/src/routes/auth.js:24-77](file://backend/src/routes/auth.js#L24-L77)
- [backend/src/services/curveClient.js:8](file://backend/src/services/curveClient.js#L8)
.qoder/repowiki/zh/content/部署与运维/部署指南.md
+74 -33
View File
@@ -20,6 +20,13 @@
- [frontend/vite.config.js](file://frontend/vite.config.js)
</cite>
## 更新摘要
**变更内容**
- 更新了Docker Compose配置说明，突出网络和卷挂载优化
- 增强了前后端服务连接稳定性的配置细节
- 添加了网络隔离和容器间通信的配置说明
- 完善了卷挂载的安全性和性能考虑
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
@@ -41,10 +48,11 @@
- 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
- 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
- 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
- **新增**：使用自定义桥接网络 `audio-network` 确保容器间通信的稳定性和安全性。
```mermaid
graph TB
subgraph "服务器"
subgraph "Docker 网络 audio-network"
FE["Nginx 前端<br/>端口 80 映射 8082"]
BE["Node.js 后端<br/>端口 8000 映射 8083"]
VOL1["/data/project/dashboard/frontend/dist"]
@@ -55,12 +63,12 @@ FE --- VOL1
BE --- VOL2
```
图表来源
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
章节来源
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
**章节来源**
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
- [DEPLOY.md:1-16](file://DEPLOY.md#L1-L16)
## 核心组件
@@ -68,10 +76,12 @@ BE --- VOL2
- 基于 Node.js 22 Alpine，使用 pnpm 作为包管理器，生产依赖安装在容器内完成。
- 通过环境变量 PORT=8000 固定容器内端口，与 Nginx 代理保持一致。
- 日志目录在容器内创建，便于持久化与查看。
- **新增**：加入 `extra_hosts` 配置支持 `host.docker.internal` 访问宿主机。
- 前端服务（Nginx）
- 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 与 nginx.conf。
- Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
- 支持静态资源缓存与上传大小限制。
- **新增**：卷挂载使用只读模式 (`:ro`) 提升安全性。
- 上传脚本（upload.sh）
- 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
- 提供虚拟执行（-n）预览能力，便于确认同步范围。
@@ -80,12 +90,12 @@ BE --- VOL2
- 后端支持通过 APP_ENV 切换开发/生产环境行为。
- JWT 密钥、管理员密码等敏感信息需在生产环境强制替换。
章节来源
**章节来源**
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [backend/src/config/env.js:1-12](file://backend/src/config/env.js#L1-L12)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/loadEnv.js:1-14](file://backend/src/config/loadEnv.js#L1-L14)
- [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)
@@ -94,21 +104,26 @@ BE --- VOL2
- 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
- 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
- Docker Compose 控制服务生命周期与网络隔离。
- **新增**：所有服务加入自定义桥接网络 `audio-network`，确保容器间通信的稳定性和安全性。
```mermaid
graph TB
U["用户浏览器"] --> P["宿主机端口 8082/Nginx"]
P --> |"/api 代理"| B["后端容器 8000"]
P --> |静态资源"| D["/data/project/dashboard/frontend/dist"]
P --> |静态资源| D["/data/project/dashboard/frontend/dist"]
B --> S["OTA 存储卷 /data/projects/source"]
subgraph "Docker 网络 audio-network"
B
P
end
```
图表来源
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
章节来源
- [DEPLOY.md:5-16](file://DEPLY.md#L5-L16)
**章节来源**
- [DEPLOY.md:5-16](file://DEPLOY.md#L5-L16)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
## 详细组件分析
@@ -122,9 +137,9 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 关键点：PORT=8000（容器内固定）、JWT_SECRET、DASHBOARD_ADMIN_PASSWORD、数据库、搜索、S3、Redis、OTA 等参数
- .env 不会被上传脚本自动上传，需在服务器单独维护
- 上传代码并启动
- 参考“本地构建 + 上传”章节
- 参考"本地构建 + 上传"章节
章节来源
**章节来源**
- [DEPLOY.md:18-46](file://DEPLOY.md#L18-L46)
### 本地构建 + 上传（推荐）
@@ -146,7 +161,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 后端 API：http://服务器 IP:8083/api/...
- 健康检查：http://服务器 IP:8083/health
章节来源
**章节来源**
- [DEPLOY.md:49-120](file://DEPLOY.md#L49-L120)
- [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
@@ -159,7 +174,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 一键流程
- 本地构建前端并上传，服务器执行后端镜像构建与启动
章节来源
**章节来源**
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
### docker-compose.yml 说明
@@ -168,17 +183,21 @@ B --> S["OTA 存储卷 /data/projects/source"]
- environment: 设置 PORT=8000，覆盖容器内端口
- ports: 8083:8000（宿主:容器）
- volumes: 挂载 OTA 存储目录
- **新增**：networks: audio-network 加入自定义网络
- **新增**：extra_hosts: host.docker.internal:host-gateway 支持宿主机访问
- frontend
- image: nginx:alpine
- ports: 8082:80
- volumes: 挂载 dist 与 nginx.conf
- volumes: 挂载 dist 与 nginx.conf（只读模式 :ro）
- depends_on: 依赖后端容器
- **新增**：networks: audio-network 加入自定义网络
- 日志轮转
- 每个服务启用 json-file，单文件最大 10MB，最多 5 份
- 网络
- 使用自定义桥接网络 audio-network，便于容器间通信
- **新增**：使用自定义桥接网络 audio-network，便于容器间通信
- **新增**：网络驱动为 bridge，提供容器间隔离和通信
章节来源
**章节来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
@@ -186,7 +205,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 后端镜像构建所需文件
- Dockerfile、package.json、pnpm-lock.yaml、src/
章节来源
**章节来源**
- [DEPLOY.md:174-187](file://DEPLOY.md#L174-L187)
### 环境变量参考
@@ -198,7 +217,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- OTA：OTA_X8_PUBLIC_BASE、OTA_X9_URL_BASE、OTA_UPLOAD_DIR
- Redis EQ：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_EQ_DB
章节来源
**章节来源**
- [DEPLOY.md:190-203](file://DEPLOY.md#L190-L203)
### 目录结构（服务器）
@@ -215,7 +234,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- nginx.conf
- /data/projects/source/（OTA 升级包存储）
章节来源
**章节来源**
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
### 上传脚本使用方法
@@ -229,7 +248,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 默认不同步 nginx.conf 与 Dockerfile，需要时需显式指定
- 路径不在项目内会被跳过
章节来源
**章节来源**
- [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
@@ -243,7 +262,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- Compose
- scp docker-compose.yml 至服务器根目录
章节来源
**章节来源**
- [DEPLOY.md:77-91](file://DEPLOY.md#L77-L91)
### 构建与启动命令
@@ -255,7 +274,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 停止服务
- docker compose down
章节来源
**章节来源**
- [DEPLOY.md:92-103](file://DEPLOY.md#L92-L103)
- [DEPLOY.md:251-256](file://DEPLOY.md#L251-L256)
@@ -269,7 +288,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 前端：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083/api/...
章节来源
**章节来源**
- [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
### 后端本地脚本（非 Docker）
@@ -277,7 +296,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- restart.sh：停止占用 8083 端口的进程并重启服务
- stop.sh：查找并终止占用 8083 端口的进程
章节来源
**章节来源**
- [backend/start.sh:1-5](file://backend/start.sh#L1-L5)
- [backend/restart.sh:1-43](file://backend/restart.sh#L1-L43)
- [backend/stop.sh:1-14](file://backend/stop.sh#L1-L14)
@@ -289,7 +308,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 监听 80，将 /api 代理到后端容器 8000
- 支持静态资源缓存与上传大小限制
章节来源
**章节来源**
- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
@@ -303,6 +322,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
- 外部依赖与集成点
- Docker Compose 管理服务生命周期与网络
- Nginx 作为反向代理与静态资源服务
- **新增**：自定义网络 audio-network 提供容器间通信
```mermaid
graph LR
@@ -312,13 +332,17 @@ BE --> DB["数据库"]
BE --> MEILI["Meilisearch"]
BE --> S3["S3 对象存储"]
BE --> REDIS["Redis"]
subgraph "Docker 网络 audio-network"
NGINX
BE
end
```
图表来源
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
章节来源
**章节来源**
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
@@ -329,10 +353,16 @@ BE --> REDIS["Redis"]
- Nginx 对静态资源进行缓存与压缩，提升前端加载速度
- 端口与网络
- 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
- **新增**：卷挂载优化
- 前端卷挂载使用只读模式 (:ro)，提升安全性和性能
- 后端 OTA 存储卷直接映射宿主机目录，避免额外开销
- **新增**：网络优化
- 自定义桥接网络减少网络延迟
- 容器间通信通过内部网络，不经过宿主机网络栈
章节来源
**章节来源**
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-L32)
- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-32)
## 故障排查指南
- 前端页面空白
@@ -343,19 +373,26 @@ BE --> REDIS["Redis"]
- 确认后端容器处于 running 状态
- 查看后端日志，定位数据库、Redis、Meilisearch 连接问题
- 确认 Nginx 代理目标为 http://backend:8000
- **新增**：检查容器是否在同一个网络中：`docker network inspect audio-network`
- 后端构建失败（pnpm / Node 版本）
- 后端镜像基于 node:22-alpine，确保上传了 package.json 与 pnpm-lock.yaml
- 修改 .env 后不生效
- 通过 docker compose up -d --force-recreate 使新环境变量生效
- 网络相关问题
- **新增**：检查网络连通性：`docker exec dashboard-frontend ping backend`
- **新增**：查看网络配置：`docker network ls`
- **新增**：检查容器网络：`docker inspect dashboard-backend | grep NetworkMode`
- 停止服务
- docker compose down
章节来源
**章节来源**
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
## 结论
本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。
**新增**：通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面得到了显著提升。
## 附录
### 环境变量与安全配置建议
@@ -366,12 +403,16 @@ BE --> REDIS["Redis"]
- S3 通常通过云服务 IAM 角色访问，避免在 .env 中硬编码密钥
- 网络与端口
- 仅开放必要端口，防火墙策略最小化
- **新增**：利用 Docker 网络隔离，避免不必要的端口暴露
- 日志与监控
- 结合日志轮转与容器日志采集，定期巡检
- 配置加载
- 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
- **新增**：卷挂载安全
- 前端静态资源使用只读挂载 (:ro)，防止运行时修改
- 后端数据卷根据业务需求选择合适的挂载模式
章节来源
**章节来源**
- [DEPLOY.md:36-42](file://DEPLOY.md#L36-L42)
- [backend/src/config/env.js:1-12](file://backend/src/config/env.js#L1-L12)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)
.qoder/repowiki/zh/meta/repowiki-metadata.json
+1 -1
View File
File diff suppressed because one or more lines are too long