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

新增项目文档

Browse Source
This commit is contained in:
eafonyang
2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/zh/content/部署与运维/故障排除.md
+507
View File
@@ -0,0 +1,507 @@
# 故障排除
<cite>
**本文引用的文件**
- [DEPLOY.md](file://DEPLOY.md)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/src/app.js](file://backend/src/app.js)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/utils/response.js](file://backend/src/utils/response.js)
- [frontend/nginx.conf](file://frontend/nginx.conf)
- [frontend/src/utils/request.js](file://frontend/src/utils/request.js)
- [scripts/upload.sh](file://scripts/upload.sh)
- [backend/package.json](file://backend/package.json)
- [frontend/package.json](file://frontend/package.json)
- [backend/start.sh](file://backend/start.sh)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向运维与开发人员，提供 Audio Dashboard 在 Docker 环境下的系统性故障排除与常见问题解答（FAQ）。覆盖前端页面空白、API 请求失败、后端构建失败、Docker 相关问题、网络连接问题、数据库连接问题、日志分析方法、错误代码含义、调试技巧、性能诊断、内存泄漏检测与系统瓶颈分析，以及紧急情况下的快速恢复与回滚策略。
## 项目结构
- 前端采用 Vite 构建，Nginx 提供静态托管与 /api 代理。
- 后端采用 Express + Sequelize，通过 Docker Compose 编排，前端反向代理到后端容器。
- 环境变量集中于根目录 .env，Compose 读取并注入到容器。
```mermaid
graph TB
subgraph "宿主机"
FE["前端静态资源<br/>frontend/dist"]
NGINX["Nginx 配置<br/>frontend/nginx.conf"]
DC["Docker Compose<br/>docker-compose.yml"]
ENV[".env 环境变量"]
end
subgraph "容器"
F["frontend(Nginx)"]
B["backend(Node.js)"]
DB["MySQL"]
REDIS["Redis"]
S3["S3 存储"]
end
FE --> F
NGINX --> F
ENV --> B
DC --> F
DC --> B
F --> |"HTTP 80"| B
B --> DB
B --> REDIS
B --> S3
```
图表来源
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
章节来源
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
## 核心组件
- 前端请求封装与拦截器：统一设置 /api 基础路径、Token 注入、401/403 处理与错误提示。
- 后端入口与健康检查：Express 应用、CORS、Body 解析、/health 健康检查、表初始化与启动日志。
- 日志系统：Winston 控制台与文件输出，按时间戳格式化。
- 数据库连接：Sequelize 初始化，开发/生产日志开关。
- 环境变量：APP_ENV 切换开发/生产，PORT 控制监听端口。
- Nginx 代理：/api 代理到 backend:8000，静态缓存与上传大小限制。
- 上传脚本：rsync 同步前端 dist、后端 src/package/pnpm-lock、compose 文件。
章节来源
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
## 架构总览
- 前端通过 Nginx 将 /api 请求转发至 backend:8000。
- 后端监听容器内 8000 端口，宿主机映射 8083。
- 健康检查端点 /health 用于快速验证后端状态。
- 环境变量 .env 通过 env_file 注入，确保数据库、Redis、S3 等配置一致。
```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant N as "Nginx(Frontend)"
participant E as "Express(API)"
participant DB as "MySQL"
participant R as "Redis"
U->>N : "GET /api/xxx"
N->>E : "proxy_pass http : //backend : 8000"
E->>DB : "查询/写入"
E->>R : "缓存/计数"
E-->>N : "JSON 响应"
N-->>U : "HTML/JS + JSON"
```
图表来源
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [docker-compose.yml:19-20](file://docker-compose.yml#L19-L20)
## 详细组件分析
### 前端请求与错误处理
- 基础路径：/api，超时 10 秒。
- Token 注入：除登录接口外自动附加 Authorization。
- 401：清理本地认证并重定向到登录页。
- 403：提示无权限。
- 通用错误：控制台记录并全局消息提示。
```mermaid
flowchart TD
Start(["发起请求"]) --> Inject["注入 Token非登录"]
Inject --> Send["发送到 /api"]
Send --> Resp{"响应 code"}
Resp --> |code==0| Err["抛出错误并显示消息"]
Resp --> |401| AuthErr["清理认证并跳转登录"]
Resp --> |403| PermErr["提示无权限"]
Resp --> |其他| Ok["返回数据"]
Err --> End(["结束"])
AuthErr --> End
PermErr --> End
Ok --> End
```
图表来源
- [frontend/src/utils/request.js:11-69](file://frontend/src/utils/request.js#L11-L69)
章节来源
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
### 后端启动与健康检查
- CORS 开放，支持 JSON/URL 编码请求体。
- /health 返回健康状态。
- 启动时尝试同步数据库表并引导超级管理员账户。
- 日志输出包含时间戳与元信息。
```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "Express(app)"
participant S as "Sequelize"
participant L as "Logger"
A->>L : "info : Creating database tables..."
A->>S : "sync()"
S-->>A : "成功/失败"
A->>L : "info/error 日志"
A->>A : "listen(PORT)"
C->>A : "GET /health"
A-->>C : "{ status : 'healthy' }"
```
图表来源
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)
- [backend/src/config/logger.js:10-26](file://backend/src/config/logger.js#L10-L26)
章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
### 数据库连接与环境变量
- 通过 DATABASE_* 环境变量配置主机、端口、库名、账号、密码。
- 生产环境关闭 Sequelize 日志，开发环境开启。
- 定义冻结表名与禁用时间戳，减少迁移成本。
```mermaid
flowchart TD
Env["读取 .env DATABASE_*"] --> NewDB["创建 Sequelize 实例"]
NewDB --> Dev{"APP_ENV 是否 development"}
Dev --> |是| LogOn["开启 Sequelize 日志"]
Dev --> |否| LogOff["关闭 Sequelize 日志"]
LogOn --> Sync["启动时 sync()"]
LogOff --> Sync
Sync --> Ready["应用可用"]
```
图表来源
- [backend/src/config/database.js:4-21](file://backend/src/config/database.js#L4-L21)
- [backend/src/config/env.js:7-10](file://backend/src/config/env.js#L7-L10)
章节来源
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
### Nginx 代理与静态资源
- /api 代理到 http://backend:8000。
- 支持 Vue Router 历史模式回退到 index.html。
- 静态资源缓存一年，Gzip 压缩常用类型。
- 上传文件最大 8MB。
```mermaid
flowchart TD
Req["浏览器请求"] --> Path{"路径匹配"}
Path --> |/api*| Proxy["代理到 backend:8000"]
Path --> |/| HTML["返回 index.html"]
Path --> |静态资源| Cache["缓存一年 + Gzip"]
Proxy --> Resp["返回后端响应"]
HTML --> Resp
Cache --> Resp
```
图表来源
- [frontend/nginx.conf:11-26](file://frontend/nginx.conf#L11-L26)
- [frontend/nginx.conf:28-32](file://frontend/nginx.conf#L28-L32)
章节来源
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
### 上传与部署脚本
- 支持同步前端 dist、后端 src/package/pnpm-lock、compose 文件。
- 默认目标服务器与密钥可配置。
- 支持虚拟执行预览同步内容。
```mermaid
flowchart TD
Run["执行 upload.sh"] --> Resolve["解析预设/自定义路径"]
Resolve --> Sync["rsync 同步到远端"]
Sync --> Done["完成"]
```
图表来源
- [scripts/upload.sh:77-151](file://scripts/upload.sh#L77-L151)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
章节来源
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
## 依赖关系分析
- 前端依赖 axios、Vue、Element Plus 等，构建后由 Nginx 提供。
- 后端依赖 Express、Sequelize、MySQL2、Winston、ioredis、@aws-sdk 等。
- Compose 将 .env 注入后端容器，前端挂载 dist 与 nginx.conf。
```mermaid
graph LR
FE_PKG["frontend/package.json"] --> FE_DEPS["运行时依赖"]
BE_PKG["backend/package.json"] --> BE_DEPS["运行时依赖"]
DC["docker-compose.yml"] --> ENV[".env 注入"]
FE_DEPS --> FE_APP["Nginx 静态服务"]
BE_DEPS --> BE_APP["Express 应用"]
ENV --> BE_APP
FE_APP --> |"HTTP"| BE_APP
```
图表来源
- [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:13-14](file://docker-compose.yml#L13-L14)
章节来源
- [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-46](file://docker-compose.yml#L1-L46)
## 性能考虑
- 日志轮转：单文件最大 10MB，最多 5 个文件，避免磁盘占用过大。
- Nginx 缓存：静态资源一年缓存，降低带宽与后端压力。
- Gzip 压缩：对文本与 JS/CSS/JSON 启用压缩。
- 上传大小限制：8MB，避免大体积请求导致内存压力。
- 健康检查：/health 快速定位后端存活状态。
章节来源
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
- [frontend/nginx.conf:28-32](file://frontend/nginx.conf#L28-L32)
- [frontend/nginx.conf:19](file://frontend/nginx.conf#L19)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
## 故障排除指南
### 一、前端页面空白
- 检查点
- 前端构建产物是否上传至 /data/project/dashboard/frontend/dist。
- Nginx 是否加载正确的 default.conf。
- 浏览器控制台是否存在 404 或跨域错误。
- 健康检查 /health 是否可达。
- 排查步骤
- 登录服务器，确认 dist 目录存在且内容完整。
- 查看 Nginx 日志与容器日志。
- 确认 /api 代理指向 backend:8000。
- 快速修复
- 重新构建并上传前端，或重启 frontend 容器。
章节来源
- [DEPLOY.md:226-233](file://DEPLOY.md#L226-L233)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
- [docker-compose.yml:33-35](file://docker-compose.yml#L33-L35)
### 二、API 请求失败
- 检查点
- backend 容器状态是否 running。
- /health 是否返回 healthy。
- 数据库、Redis、Meilisearch 连接是否正常。
- Nginx 代理是否正确指向 backend:8000。
- 排查步骤
- docker compose ps 查看服务状态。
- docker compose logs -f backend 查看错误堆栈。
- curl http://localhost:8083/health 验证健康检查。
- 检查 .env 中 DATABASE_*、REDIS_*、AWS_* 等配置。
- 快速修复
- 修正 .env 后，强制重建并重启 backend 容器。
章节来源
- [DEPLOY.md:234-249](file://DEPLOY.md#L234-L249)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [docker-compose.yml:19-20](file://docker-compose.yml#L19-L20)
### 三、后端构建失败（pnpm / Node 版本）
- 检查点
- 后端镜像基于 node:22-alpine。
- package.json 与 pnpm-lock.yaml 是否随后端一起上传。
- 排查步骤
- 确认上传脚本包含 backend 相关文件。
- 在服务器执行 docker compose build --no-cache backend。
- 快速修复
- 重新上传后端文件并重新构建。
章节来源
- [DEPLOY.md:240-244](file://DEPLOY.md#L240-L244)
- [scripts/upload.sh:14-18](file://scripts/upload.sh#L14-L18)
- [backend/package.json:5](file://backend/package.json#L5)
### 四、修改 .env 后不生效
- 现象
- 更改环境变量后，容器未感知。
- 排查步骤
- docker compose up -d --force-recreate backend。
- 快速修复
- 强制重建后端容器以加载新 .env。
章节来源
- [DEPLOY.md:245-249](file://DEPLOY.md#L245-L249)
### 五、停止与重启服务
- 停止
- docker compose down。
- 仅重启前端
- docker compose restart frontend。
- 仅更新后端
- 上传后端文件，build 并 up -d backend。
章节来源
- [DEPLOY.md:251-255](file://DEPLOY.md#L251-L255)
- [DEPLOY.md:135-144](file://DEPLOY.md#L135-L144)
### 六、Docker 相关问题
- 端口冲突
- 检查宿主机 8082/8083 是否被占用。
- 权限问题
- 确认 dist 与 nginx.conf 挂载权限。
- 日志过大
- 使用日志轮转配置，必要时清理历史日志。
章节来源
- [docker-compose.yml:19-20](file://docker-compose.yml#L19-L20)
- [docker-compose.yml:33-35](file://docker-compose.yml#L33-L35)
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
### 七、网络连接问题
- 前端无法访问 /api
- 检查 Nginx 代理配置与 backend 容器连通性。
- 确认容器网络 audio-network 是否创建成功。
- 后端无法访问外部服务
- 检查 DNS、防火墙、安全组规则。
- 确认 AWS 凭证或 IAM 角色配置。
章节来源
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
- [docker-compose.yml:23-24](file://docker-compose.yml#L23-L24)
- [DEPLOY.md:190-203](file://DEPLOY.md#L190-L203)
### 八、数据库连接问题
- 检查点
- DATABASE_HOST/PORT/NAME/USER/PASSWORD 是否正确。
- MySQL 服务可达，账号具备权限。
- 容器内网络与端口映射是否正确。
- 排查步骤
- 在 backend 容器内测试连接（nslookup/mysql 命令）。
- 查看后端启动日志中的数据库连接错误。
- 快速修复
- 修正 .env 中数据库配置并重建后端容器。
章节来源
- [backend/src/config/database.js:4-21](file://backend/src/config/database.js#L4-L21)
- [backend/src/app.js:42-51](file://backend/src/app.js#L42-L51)
### 九、日志分析方法
- 后端日志
- 控制台与文件同时输出，查看启动阶段的表同步与错误信息。
- 前端日志
- 浏览器开发者工具 Network/Console。
- Nginx 日志
- 容器标准输出，关注 4xx/5xx 与代理错误。
- 建议
- 结合时间戳定位问题发生时段，优先查看 ERROR/异常堆栈。
章节来源
- [backend/src/config/logger.js:10-26](file://backend/src/config/logger.js#L10-L26)
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)
- [docker-compose.yml:21-22](file://docker-compose.yml#L21-L22)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
### 十、错误代码含义与调试技巧
- 响应结构
- code=1：成功；code=0：业务错误；code=2：无数据。
- 前端拦截器
- code=0：统一错误提示与拒绝 Promise。
- 401：清除本地认证并跳转登录。
- 403：提示无权限。
- 调试技巧
- 打开浏览器 Network 面板，观察请求头与响应体。
- 在后端添加最小复现接口，逐步缩小范围。
- 使用 curl 直连 /health 与关键业务接口验证后端状态。
章节来源
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [frontend/src/utils/request.js:27-69](file://frontend/src/utils/request.js#L27-L69)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
### 十一、性能问题诊断
- CPU/内存飙升
- 检查后端日志中慢查询与异常堆栈。
- 关注 Nginx 代理错误与后端队列积压。
- 静态资源加载慢
- 确认缓存头与 Gzip 是否生效。
- 检查 dist 是否最新版本。
- 数据库慢
- 查看数据库连接数与锁等待。
- 优化查询与索引。
章节来源
- [frontend/nginx.conf:28-32](file://frontend/nginx.conf#L28-L32)
- [backend/src/config/database.js:15](file://backend/src/config/database.js#L15)
### 十二、内存泄漏检测与系统瓶颈分析
- 方法
- 使用 Node.js 内置分析工具生成 Heap/Profile 快照。
- 持续监控容器资源使用率与错误日志。
- 逐步禁用功能模块定位可疑代码段。
- 建议
- 限制并发与批量操作，增加重试与熔断机制。
[本节为通用指导，无需特定文件引用]
### 十三、紧急恢复与回滚策略
- 快速恢复
- 重启 frontend 与 backend 容器。
- 回滚到上一个稳定版本的 dist 与后端镜像。
- 回滚步骤
- 前端：恢复上一版 dist。
- 后端：切换镜像标签或重新 build 上一版。
- 预案
- 保留最近一次构建产物与镜像快照。
- 使用只读挂载与备份卷保障数据安全。
章节来源
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
## 结论
通过统一的日志输出、清晰的 Nginx 代理、严格的环境变量注入与完善的健康检查，Audio Dashboard 在 Docker 环境下具备良好的可观测性与可维护性。遇到问题时，建议按照“前端空白 → API 失败 → 构建失败 → 网络/数据库 → 日志分析 → 性能诊断 → 回滚恢复”的顺序逐层排查，结合本文提供的图示与步骤，可高效定位并解决问题。
## 附录
### A. 常用命令速查
- 启动/更新
- docker compose build --no-cache backend
- docker compose up -d
- 停止/重启
- docker compose down
- docker compose restart frontend
- 日志
- docker compose logs -f backend
- docker compose logs frontend
- 健康检查
- curl http://localhost:8083/health
章节来源
- [DEPLOY.md:92-118](file://DEPLOY.md#L92-L118)
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
### B. 环境变量参考
- 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD
- 应用：APP_NAME、APP_ENV
- 认证：JWT_SECRET、DASHBOARD_ADMIN_USERNAME、DASHBOARD_ADMIN_PASSWORD
- 搜索：MEILISEARCH_URL、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- S3：AWS_REGION、AWS_S3_OTA_BUCKET、AWS_S3_MEASUREMENT_BUCKET
- 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)
.qoder/repowiki/zh/content/部署与运维/环境配置.md
+351
View File
@@ -0,0 +1,351 @@
# 环境配置
<cite>
**本文引用的文件**
- [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/utils/jwt.js](file://backend/src/utils/jwt.js)
- [backend/src/services/otaStorage.js](file://backend/src/services/otaStorage.js)
- [backend/src/services/eqCacheStorage.js](file://backend/src/services/eqCacheStorage.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/app.js](file://backend/src/app.js)
- [backend/package.json](file://backend/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. [附录](#附录)
## 简介
本文件系统性梳理后端服务的环境配置，覆盖数据库连接、JWT 认证、Redis 缓存、S3 存储等关键模块，并给出开发、测试、生产三类环境的配置差异建议、安全存储与版本控制策略、配置验证方法、常见错误与修复方案，以及配置模板与示例文件说明。
## 项目结构
后端通过入口文件统一加载环境变量与初始化各子系统；配置层按功能拆分，便于独立维护与替换。
```mermaid
graph TB
A["入口应用<br/>backend/src/app.js"] --> B["加载环境变量<br/>backend/src/config/loadEnv.js"]
A --> C["数据库配置<br/>backend/src/config/database.js"]
A --> D["JWT 工具<br/>backend/src/utils/jwt.js"]
A --> E["Redis 客户端<br/>backend/src/config/redis.js"]
A --> F["OTA 存储S3/本地<br/>backend/src/services/otaStorage.js"]
A --> G["EQ 缓存读写<br/>backend/src/services/eqCacheStorage.js"]
A --> H["日志配置<br/>backend/src/config/logger.js"]
A --> I["环境判断<br/>backend/src/config/env.js"]
J["Docker Compose<br/>docker-compose.yml"] --> A
K["部署文档<br/>DEPLOY.md"] --> A
```
图示来源
- [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/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)
章节来源
- [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)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)
## 核心组件
- 环境变量加载：统一从项目根目录加载 .env，支持本地与 Docker 两种模式。
- 环境判断：通过 APP_ENV 判断 development/production，影响日志与部分行为。
- 数据库：基于 Sequelize 的 MySQL 连接，支持日志输出与表定义选项。
- JWT：基于 HS256 的签名与校验，支持自定义密钥与过期时间。
- Redis：EQ 缓存专用客户端，支持密码、超时与错误日志。
- S3：OTA 包上传，支持显式凭证与 IAM 角色两种方式。
- 日志：Winston 控制台与文件双通道输出。
章节来源
- [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/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
## 架构总览
下图展示环境变量在系统中的流向与依赖关系。
```mermaid
graph TB
subgraph "运行时"
ENV["环境变量<br/>.env 加载"]
APP["应用入口<br/>src/app.js"]
DB["数据库<br/>Sequelize"]
JWT["JWT 工具"]
RDS["Redis 客户端"]
S3["S3 客户端"]
LOG["日志"]
end
ENV --> APP
APP --> DB
APP --> JWT
APP --> RDS
APP --> S3
APP --> LOG
```
图示来源
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
## 详细组件分析
### 数据库连接配置（MySQL/Sequelize）
- 关键变量
- DATABASE_HOST：数据库主机，默认 localhost
- DATABASE_PORT：数据库端口，默认 3306
- DATABASE_NAME：数据库名，默认 audio
- DATABASE_USER：用户名，默认 root
- DATABASE_PASSWORD：密码，默认 root123
- 行为特征
- 开发环境启用 SQL 日志打印
- 冻结表名、禁用时间戳
- 配置验证
- 启动时尝试同步模型，失败会记录警告但继续运行
- 常见错误
- 凭据错误：核对 DATABASE_USER/PASSWORD
- 端口/主机不可达：确认网络连通与防火墙
- 字符集问题：确保 utf8mb4 支持
章节来源
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)
### JWT 认证配置
- 关键变量
- JWT_SECRET：签名密钥（必须在生产环境强制设置）
- 算法：HS256
- 过期时间：12 小时
- 安全建议
- 生产环境务必设置强随机密钥，避免硬编码
- 密钥长度至少 256 位
- 常见错误
- 密钥缺失：默认值仅用于开发，生产会失效
- 过期频繁：检查客户端刷新逻辑与服务端时钟
章节来源
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [DEPLOY.md:39](file://DEPLOY.md#L39)
### Redis 缓存配置（EQ 缓存）
- 关键变量
- REDIS_HOST：默认 127.0.0.1
- REDIS_PORT：默认 6379
- REDIS_PASSWORD：可选
- REDIS_EQ_DB：默认 1
- 行为特征
- 单例客户端，带最大重试与连接超时
- 连接错误通过日志上报
- 常见错误
- 密码错误：确认 REDIS_PASSWORD 与 ACL 设置
- DB 选择错误：核对 REDIS_EQ_DB
- 连接超时：检查网络与 Redis 性能
章节来源
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)
### S3 存储配置（OTA 升级包）
- 关键变量
- AWS_REGION：默认 eu-central-1
- AWS_ACCESS_KEY_ID：可选（本地开发）
- AWS_SECRET_ACCESS_KEY：可选（本地开发）
- AWS_S3_OTA_BUCKET：默认 luxsin-app-bucket
- OTA_UPLOAD_DIR：X9 本地存储目录（开发默认临时目录，生产默认 /data/projects/source）
- OTA_X8_PUBLIC_BASE：X8 下载地址前缀
- OTA_X9_URL_BASE：X9 下载地址前缀
- 行为特征
- X8：上传至 S3，支持显式凭证或 IAM 角色
- X9：保存到宿主机卷（/data/projects/source）
- 常见错误
- S3 权限不足：检查 IAM 角色或凭证
- 本地目录权限：确认写入权限与磁盘空间
- 地址拼接异常：核对 OTA_X8_PUBLIC_BASE/OTA_X9_URL_BASE 结尾斜杠处理
章节来源
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [docker-compose.yml:26](file://docker-compose.yml#L26)
### 环境变量加载与环境判断
- 加载策略
- 本地开发：读取项目根目录 .env
- Docker：通过 compose env_file 注入，容器内不覆盖已有变量
- 环境常量
- APP_ENV：development/production
- isDevelopment/isProduction：用于分支逻辑（如数据库日志）
章节来源
- [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)
- [docker-compose.yml:13-18](file://docker-compose.yml#L13-L18)
### Meilisearch 搜索引擎配置
- 文档中明确列出变量类别与变量名，但未在后端代码中直接实现对应客户端。
- 建议在实际集成时新增配置模块，遵循现有命名风格与加载方式。
章节来源
- [DEPLOY.md:199](file://DEPLOY.md#L199)
## 依赖关系分析
- 入口应用依赖配置模块与服务模块
- 配置模块之间低耦合，通过 process.env 解耦
- Docker Compose 提供环境变量注入与端口映射
```mermaid
graph LR
APP["app.js"] --> LOADENV["loadEnv.js"]
APP --> DB["database.js"]
APP --> JWTU["jwt.js"]
APP --> REDIS["redis.js"]
APP --> OTAS["otaStorage.js"]
APP --> EQCS["eqCacheStorage.js"]
APP --> LOGF["logger.js"]
DC["docker-compose.yml"] --> APP
```
图示来源
- [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/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
## 性能考虑
- 数据库
- 开发环境开启 SQL 日志便于调试，生产关闭以降低开销
- 合理设置连接池参数（如需扩展）
- Redis
- 控制最大重试次数与连接超时，避免阻塞请求
- 使用独立 DB 隔离 EQ 缓存，减少键冲突
- S3
- 上传前计算 MD5，避免重复上传
- 生产环境优先使用 IAM 角色，减少凭证泄露风险
## 故障排查指南
- 环境变量不生效
- Docker：修改 .env 后需重建容器或强制重启
- 本地：确认根目录 .env 是否存在且格式正确
- 数据库连接失败
- 核对主机、端口、凭据与字符集
- 检查防火墙与网络策略
- Redis 连接失败
- 核对主机、端口、密码与 DB 选择
- 检查 Redis 服务状态与资源限制
- S3 上传失败
- 核对区域、桶名与凭证或 IAM 角色
- 检查网络与对象权限
- 健康检查
- 访问 /health 确认服务可用
- 查看容器日志定位具体错误
章节来源
- [DEPLOY.md:245-255](file://DEPLOY.md#L245-L255)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
## 结论
本项目采用集中式环境变量加载与模块化配置设计，结合 Docker Compose 实现多环境一致性。建议在生产环境严格管理敏感变量，采用 IAM 角色与最小权限原则，并完善配置验证与监控告警机制。
## 附录
### 不同环境配置差异建议
- 开发环境
- APP_ENV=development
- 数据库日志开启
- JWT_SECRET 可使用默认值（仅开发）
- OTA_UPLOAD_DIR 指向本地临时目录
- 测试环境
- APP_ENV=production
- 数据库日志关闭
- JWT_SECRET 强随机值
- S3 使用测试账号或角色
- 生产环境
- APP_ENV=production
- 所有敏感变量通过环境注入
- S3 优先 IAM 角色
- 日志与健康检查完善
章节来源
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js:15](file://backend/src/config/database.js#L15)
- [DEPLOY.md:39](file://DEPLOY.md#L39)
- [docker-compose.yml:18](file://docker-compose.yml#L18)
### 敏感信息的安全存储与版本控制策略
- .env 不纳入版本控制，服务器单独维护
- 使用 IAM 角色替代明文凭证（S3）
- 密钥轮换流程：生成新密钥 → 更新 .env → 重启服务 → 废弃旧密钥
- 最小权限原则：仅为需要的功能授予最小权限
章节来源
- [DEPLOY.md:40-41](file://DEPLOY.md#L40-L41)
- [DEPLOY.md:39](file://DEPLOY.md#L39)
### 配置验证方法
- 启动日志：观察数据库同步与服务启动信息
- 健康检查：访问 /health
- 功能测试：登录、查询、上传等关键路径
- 日志审计：关注错误日志与异常堆栈
章节来源
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
### 常见配置错误与解决办法
- JWT_SECRET 未设置：在生产环境设置强随机密钥
- S3 凭证或权限问题：检查凭证或 IAM 角色策略
- Redis 密码或 DB 错误：核对密码与 DB 编号
- 端口映射冲突：调整宿主机端口或容器端口
- 环境变量未生效：在 Docker 中强制重建容器
章节来源
- [backend/src/utils/jwt.js:3](file://backend/src/utils/jwt.js#L3)
- [backend/src/services/otaStorage.js:77-83](file://backend/src/services/otaStorage.js#L77-L83)
- [backend/src/config/redis.js:20-22](file://backend/src/config/redis.js#L20-L22)
- [DEPLOY.md:245-249](file://DEPLOY.md#L245-L249)
### 配置模板与示例文件说明
- 示例文件位置：项目根目录提供 .env.example（后端 README 中提及）
- 变量分类参考：数据库、应用、认证、搜索、S3、OTA、Redis EQ 等
- 服务器维护：.env 仅在服务器维护，不提交到版本库
章节来源
- [DEPLOY.md:29-34](file://DEPLOY.md#L29-L34)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)
.qoder/repowiki/zh/content/部署与运维/监控运维.md
+348
View File
@@ -0,0 +1,348 @@
# 监控运维
<cite>
**本文引用的文件**
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/Dockerfile](file://backend/Dockerfile)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/start.sh](file://backend/start.sh)
- [backend/restart.sh](file://backend/restart.sh)
- [backend/stop.sh](file://backend/stop.sh)
- [backend/package.json](file://backend/package.json)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [frontend/nginx.conf](file://frontend/nginx.conf)
- [DEPLOY.md](file://DEPLOY.md)
- [backend/src/routes/index.js](file://backend/src/routes/index.js)
- [backend/src/routes/dashboard.js](file://backend/src/routes/dashboard.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向生产环境的监控与运维，围绕系统监控指标、日志管理、性能调优、容器与服务健康检查、日志轮转与分析、异常告警、服务重启/停止/重新部署流程、备份与灾难恢复以及自动化运维脚本进行系统化说明。文档以仓库现有实现为基础，结合 Docker Compose 部署与 Nginx 代理链路，给出可操作的运维实践。
## 项目结构
- 后端采用 Node.js + Express，使用 winston 输出日志，Dockerfile 在容器内创建日志目录并暴露 8000 端口。
- 前端通过 Nginx 提供静态资源与反向代理，将 /api 前缀转发至后端容器的 8000 端口。
- docker-compose.yml 定义了 backend 与 frontend 两个服务，启用 json-file 日志轮转（单文件 10m，最多 5 个），并挂载 OTA 升级包存储卷。
- 运维脚本提供本地启动、重启与停止能力；部署指南提供完整的构建、上传与验证流程。
```mermaid
graph TB
subgraph "宿主机"
HOST["8082:80<br/>8083:8000"]
end
subgraph "容器网络"
NET["bridge 网络"]
end
subgraph "容器: 前端"
NGINX["Nginx<br/>监听 80<br/>反代 /api -> backend:8000"]
end
subgraph "容器: 后端"
NODE["Node.js 应用<br/>监听 8000"]
LOGS["/app/logs<br/>应用日志"]
end
HOST --> NGINX
NGINX --> |"HTTP"| NODE
NET --> NGINX
NET --> NODE
NODE --> LOGS
```
图表来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
章节来源
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
## 核心组件
- 日志系统：后端使用 winston 输出到控制台与文件，日志目录在容器内创建；前端通过 Nginx 提供静态资源与 API 代理。
- 容器编排：Docker Compose 定义服务、端口映射、日志轮转、网络与卷挂载。
- 运维脚本：start.sh、restart.sh、stop.sh 提供本地启动、重启与停止能力。
- 健康检查：部署指南中提供 /health 健康检查验证方法。
- 环境与配置：APP_ENV 控制开发/生产行为；数据库与 Redis 连接通过环境变量注入。
章节来源
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [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)
- [DEPLOY.md:104-118](file://DEPLOY.md#L104-L118)
- [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)
## 架构总览
下图展示从浏览器到后端 API 的完整链路，包括 Nginx 代理、后端服务与日志输出位置。
```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant F as "Nginx(前端)"
participant B as "Node.js(后端)"
participant L as "日志文件"
U->>F : "请求 /api/*"
F->>B : "反向代理到 backend : 8000"
B->>L : "写入应用日志(app.log)"
B-->>F : "返回响应(JSON)"
F-->>U : "返回页面/接口数据"
```
图表来源
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
- [backend/src/config/logger.js:19-26](file://backend/src/config/logger.js#L19-L26)
- [backend/Dockerfile:5-6](file://backend/Dockerfile#L5-L6)
章节来源
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
## 详细组件分析
### 日志管理与轮转
- 日志输出：后端使用 winston，同时输出到控制台与文件；日志目录在容器内创建。
- 日志轮转：Compose 使用 json-file 驱动，单文件大小限制为 10m，最多保留 5 个文件。
- 日志分析建议：生产环境建议将容器日志接入集中式日志系统（如 ELK/Fluentd/Loki），以便聚合、检索与告警。
```mermaid
flowchart TD
Start(["应用启动"]) --> Init["初始化 winston 日志器"]
Init --> DirCheck{"日志目录存在？"}
DirCheck --> |否| Mk["创建 /app/logs"]
DirCheck --> |是| Ready["准备就绪"]
Mk --> Ready
Ready --> Write["写入控制台与文件(app.log)"]
Write --> End(["运行中"])
```
图表来源
- [backend/src/config/logger.js:5-26](file://backend/src/config/logger.js#L5-L26)
- [backend/Dockerfile:5-6](file://backend/Dockerfile#L5-L6)
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
章节来源
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [docker-compose.yml:1-6](file://docker-compose.yml#L1-L6)
### Docker 容器监控
- 端口与网络：后端容器固定监听 8000，前端容器监听 80；通过宿主端口 8082/8083 对外提供服务。
- 卷挂载：OTA 升级包存储挂载到宿主机目录，便于持久化与备份。
- 重启策略：unless-stopped，提升稳定性。
- 日志轮转：json-file 驱动，max-size/max-file 控制磁盘占用。
章节来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [backend/Dockerfile:15-16](file://backend/Dockerfile#L15-L16)
### 服务健康检查
- 健康检查端点：部署指南提供 curl 命令验证 /health。
- 建议：在生产中可将 /health 设计为返回 200/500 并携带简要状态信息，便于监控系统自动探测。
章节来源
- [DEPLOY.md:104-118](file://DEPLOY.md#L104-L118)
### 性能监控指标定义
- 后端指标（建议采集）：
- QPS/吞吐：每秒请求数、成功/失败率
- 响应时间：P50/P95/P99 延迟
- 错误率：4xx/5xx 比例
- 资源使用：CPU、内存、线程数
- 数据库连接：活跃连接数、等待队列长度
- Redis 连接：可用性、命令耗时
- IO：磁盘读写、日志文件大小增长
- 前端指标（建议采集）：
- 静态资源命中率、缓存命中
- Nginx 连接数、请求速率、错误码分布
章节来源
- [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)
### 资源使用跟踪与异常告警
- 建议使用 Prometheus + Grafana 或云监控（如 CloudWatch/Azure Monitor）采集容器与主机指标，并设置阈值告警。
- 关键告警场景：
- CPU/内存持续高位
- 响应时间 P95 超过阈值
- 数据库/Redis 连接池耗尽
- 日志文件增长过快（接近 max-size）
章节来源
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
- [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 下执行启动脚本
- 重启：使用重启脚本，内部查找并终止占用宿主 8083 端口的进程，随后启动应用
- 停止：使用停止脚本，查找并终止占用 8083 的进程
- 生产部署：
- 仅更新前端：本地构建后上传前端产物，服务器执行 frontend 重启
- 仅更新后端：上传后端代码，服务器执行后端镜像重建与 up
- 一键流程：前端构建 + 上传 + 后端重建 + 部署
- 停止服务：docker compose down
```mermaid
flowchart TD
A["开始"] --> B{"选择操作类型"}
B --> |本地启动| S["执行 start.sh"]
B --> |本地重启| R["执行 restart.sh<br/>终止旧进程并启动新进程"]
B --> |本地停止| T["执行 stop.sh<br/>终止占用 8083 的进程"]
B --> |生产更新前端| U1["本地构建 -> 上传前端 -> 服务器 restart frontend"]
B --> |生产更新后端| U2["上传后端 -> 服务器 build --no-cache backend -> up -d backend"]
B --> |停止服务| D["docker compose down"]
S --> E["完成"]
R --> E
T --> E
U1 --> E
U2 --> E
D --> E
```
图表来源
- [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)
- [DEPLOY.md:122-153](file://DEPLOY.md#L122-L153)
章节来源
- [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)
- [DEPLOY.md:104-153](file://DEPLOY.md#L104-L153)
### 备份策略、数据恢复与灾难恢复
- 数据库备份：
- MySQL：定期执行逻辑备份（mysqldump）或物理备份（Percona XtraBackup），并校验归档与异地存放
- 缓存数据：
- Redis：导出 RDB 快照或开启 AOF，确保快照与增量日志定期归档
- 文件与升级包：
- OTA 升级包：/data/projects/source 目录作为挂载卷，纳入常规文件备份策略
- 日志：
- 容器日志：json-file 轮转，建议将日志目录也纳入备份范围
- 恢复演练：
- 定期进行备份恢复演练，验证备份完整性与恢复时间目标（RTO/RPO）
章节来源
- [docker-compose.yml:25-26](file://docker-compose.yml#L25-L26)
- [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)
### 自动化运维工具与脚本
- 上传脚本：scripts/upload.sh 支持上传 frontend、backend、compose 等子任务，便于一键部署
- Compose 命令：build、up、down、logs、ps 等用于构建、启动、停止与日志查看
- 建议扩展：
- CI/CD：在流水线中集成前端构建、上传与后端镜像构建
- 健康检查钩子：在部署前后执行 /health 校验
- 告警联动：当部署失败或健康检查失败时自动回滚
章节来源
- [DEPLOY.md:63-90](file://DEPLOY.md#L63-L90)
- [DEPLOY.md:100-102](file://DEPLOY.md#L100-L102)
- [DEPLOY.md:148-153](file://DEPLOY.md#L148-L153)
## 依赖关系分析
- 后端应用依赖：
- Express 提供 Web 服务与路由
- Winston 提供日志记录
- Sequelize/MySQL 提供数据持久化
- ioredis 提供 Redis 连接
- dotenv 加载环境变量
- 前端依赖：
- Nginx 提供静态资源与反向代理
- 运维依赖：
- Docker Compose 管理多容器编排
- Shell 脚本提供本地启动/停止/重启
```mermaid
graph LR
APP["后端应用"] --> W["winston"]
APP --> S["sequelize/mysql"]
APP --> R["ioredis"]
APP --> E["express"]
APP --> D["dotenv"]
FE["前端(Nginx)"] --> APP
OPS["运维"] --> DC["docker-compose"]
OPS --> SH["shell 脚本"]
```
图表来源
- [backend/package.json:11-27](file://backend/package.json#L11-L27)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [backend/start.sh:1-5](file://backend/start.sh#L1-L5)
章节来源
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [backend/start.sh:1-5](file://backend/start.sh#L1-L5)
## 性能考虑
- Nginx 层优化：
- 启用 gzip 压缩静态资源
- 合理设置 client_max_body_size 与缓存头
- 后端层优化：
- 数据库连接池与查询优化
- Redis 命令超时与重试策略
- 日志级别与格式开销控制
- 容器层优化：
- 合理设置 restart 策略与资源限制
- 使用只读卷与最小权限原则
章节来源
- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-L32)
- [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:10-26](file://backend/src/config/logger.js#L10-L26)
- [docker-compose.yml:21-22](file://docker-compose.yml#L21-L22)
## 故障排查指南
- 前端页面空白：
- 检查 dist 是否上传、路径是否正确
- 查看前端容器日志
- API 请求失败：
- 确认后端容器处于 running 状态
- 查看后端容器日志，关注数据库、Redis、搜索引擎连接错误
- 核对 Nginx 代理目标为 backend:8000
- 后端构建失败：
- 确认已上传 package.json 与 pnpm-lock.yaml
- 使用指定 Node 版本与包管理器版本
- 修改 .env 不生效：
- 强制重建后端容器使其加载新环境变量
- 停止服务：
- 使用 docker compose down
章节来源
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
## 结论
本运维文档基于现有代码与部署配置，给出了日志管理、容器监控、健康检查、性能指标、异常告警、服务运维流程、备份与灾难恢复以及自动化脚本的实践建议。建议在生产环境中补充集中式日志、指标采集与告警体系，并完善备份与恢复演练，以保障系统稳定与可追溯性。
## 附录
- 健康检查端点：/health（参考部署指南中的 curl 示例）
- 环境变量参考：数据库、应用、认证、搜索、S3、OTA、Redis EQ 等（参考部署指南中的表格）
章节来源
- [DEPLOY.md:104-118](file://DEPLOY.md#L104-L118)
- [DEPLOY.md:190-203](file://DEPLOY.md#L190-L203)
.qoder/repowiki/zh/content/部署与运维/部署与运维.md
+349
View File
@@ -0,0 +1,349 @@
# 部署与运维
<cite>
**本文引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [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)
- [scripts/upload.sh](file://scripts/upload.sh)
- [backend/package.json](file://backend/package.json)
- [frontend/package.json](file://frontend/package.json)
- [backend/start.sh](file://backend/start.sh)
- [backend/restart.sh](file://backend/restart.sh)
- [backend/stop.sh](file://backend/stop.sh)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向部署与运维工程师，系统性说明项目的容器化部署、环境配置、生产部署流程、容器编排、服务依赖与网络设置、部署脚本使用、自动化流程、环境变量与数据库/缓存配置、监控与日志、性能调优、故障排除、备份恢复与灾难恢复、CI/CD 与版本发布/回滚策略，以及安全配置与访问控制。
## 项目结构
- 前端采用 Nginx 静态托管，后端为 Node.js API，二者通过 Docker Compose 在同一自定义桥接网络中通信。
- 前端不构建镜像，直接挂载服务器上的构建产物与 Nginx 配置；后端以独立镜像运行。
- 日志轮转策略在 Compose 层统一配置，便于生产环境管理。
- OTA 升级包本地存储通过宿主机卷挂载到后端容器，确保升级资源可用性。
```mermaid
graph TB
subgraph "宿主机"
V1["/data/projects/source<br/>OTA 存储卷"]
FDist["/data/project/dashboard/frontend/dist<br/>前端静态资源"]
NConf["/data/project/dashboard/frontend/nginx.conf<br/>Nginx 配置"]
end
subgraph "Docker 网络 audio-network"
FE["容器 dashboard-frontend<br/>Nginx:80"]
BE["容器 dashboard-backend<br/>Node.js:8000"]
end
V1 --> BE
FDist --> FE
NConf --> FE
FE --> |"反向代理 /api → http://backend:8000"| BE
```
图表来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
章节来源
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [DEPLOY.md:1-120](file://DEPLOY.md#L1-L120)
## 核心组件
- 后端服务（Node.js）
- 基于 Node.js 22 Alpine 镜像，使用 pnpm 生产依赖安装，工作目录包含日志目录，暴露 8000 端口。
- 通过环境变量驱动数据库、Redis、搜索、S3、OTA 等配置。
- 前端服务（Nginx）
- 使用 Nginx Alpine 镜像，挂载静态资源与 Nginx 配置，不构建镜像，减少部署复杂度。
- 容器编排与网络
- Compose 定义自定义桥接网络，前后端在同一网络内通信；前端通过 Nginx 将 /api 代理到后端容器的 8000 端口。
- 部署脚本
- 提供一键上传前端、后端、Compose 的 rsync 脚本，支持虚拟执行与多目标组合。
章节来源
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
## 架构总览
- 端口映射
- 前端 Nginx 暴露 80，映射到宿主机 8082。
- 后端 Node.js 暴露 8000，映射到宿主机 8083。
- 服务依赖
- 前端依赖后端 API；Compose 通过 depends_on 实现启动顺序。
- 网络
- 两容器加入同一自定义桥接网络，实现容器间通过服务名访问。
- 日志
- 每个服务启用 JSON 文件日志轮转，单文件最大 10MB，最多 5 个文件。
```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant FE as "dashboard-frontend(Nginx)"
participant BE as "dashboard-backend(Node.js)"
U->>FE : "访问 http : //<host> : 8082/"
FE->>FE : "解析路由与静态资源"
U->>FE : "请求 /api/*"
FE->>BE : "反向代理到 http : //backend : 8000"
BE-->>FE : "返回 API 响应"
FE-->>U : "返回 HTML/JS/CSS 与 API 数据"
```
图表来源
- [docker-compose.yml:28-41](file://docker-compose.yml#L28-L41)
- [DEPLOY.md:114-118](file://DEPLOY.md#L114-L118)
章节来源
- [DEPLOY.md:5-118](file://DEPLOY.md#L5-L118)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
## 详细组件分析
### 后端容器与应用配置
- 环境变量加载
- 容器内通过根目录 .env 注入；本地开发与 Docker 部署共享同一 .env 加载逻辑，但 Docker 下容器内无 .env 文件，由 Compose 注入。
- 环境类型
- 通过 APP_ENV 判断开发/生产环境，影响日志输出等行为。
- 数据库连接
- 使用 Sequelize 连接 MySQL，支持主机、端口、用户名、密码、字符集、日志开关等配置项。
- Redis 缓存
- 提供 EQ 缓存客户端工厂方法，支持主机、端口、密码、数据库编号、超时与重试配置，并记录错误日志。
- 日志
- 使用 Winston 输出到控制台与文件，日志目录位于应用内部 logs 子目录。
```mermaid
flowchart TD
Start(["启动后端"]) --> LoadEnv["加载根目录 .envCompose 注入"]
LoadEnv --> EnvCheck{"APP_ENV 是否为 production"}
EnvCheck --> |是| Prod["生产模式：关闭 ORM 日志"]
EnvCheck --> |否| Dev["开发模式：开启 ORM 日志"]
Prod --> DB["初始化数据库连接Sequelize"]
Dev --> DB
DB --> RedisInit["初始化 Redis 客户端"]
RedisInit --> Logger["初始化日志记录器"]
Logger --> Ready(["服务就绪"])
```
图表来源
- [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/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)
### 前端容器与 Nginx 配置
- 镜像与构建
- 使用 Nginx Alpine 镜像，挂载静态资源与 Nginx 配置文件，不构建前端镜像。
- 代理规则
- 前端通过 Nginx 将 /api 代理到后端容器的 8000 端口，确保 SPA 与 API 请求分离。
- 卷挂载
- 前端 dist 与 nginx.conf 通过宿主机卷挂载，便于快速更新与热替换。
章节来源
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [docker-compose.yml:28-41](file://docker-compose.yml#L28-L41)
### 容器编排与网络
- 自定义桥接网络
- 两容器加入同一网络，实现通过服务名访问后端 API。
- 端口映射
- 前端 80:8082，后端 8000:8083，避免端口冲突。
- 日志轮转
- 每个服务启用 JSON 文件日志轮转，单文件 10MB，最多 5 份。
章节来源
- [docker-compose.yml:43-46](file://docker-compose.yml#L43-L46)
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
### 部署脚本与自动化
- 功能特性
- 支持同步前端、后端、Compose 三类目标，也支持指定路径与虚拟执行。
- 默认目标包含前端 dist、后端 src 与依赖锁文件、Compose 文件。
- SSH 密钥与远程路径可配置，便于跨环境复用。
- 使用场景
- 本地构建前端后，一键上传前端与 Compose 并在服务器执行 docker compose up -d。
- 后端代码变更后，上传后端文件并在服务器重建后端镜像并启动。
```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Script as "upload.sh"
participant Server as "服务器"
Dev->>Script : "执行 ./scripts/upload.sh frontend"
Script->>Server : "rsync 前端 dist 到 /data/project/dashboard/frontend/dist"
Dev->>Script : "执行 ./scripts/upload.sh compose"
Script->>Server : "rsync docker-compose.yml"
Dev->>Server : "在服务器执行 docker compose up -d"
Server-->>Dev : "验证服务状态与日志"
```
图表来源
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
- [DEPLOY.md:49-113](file://DEPLOY.md#L49-L113)
章节来源
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
- [DEPLOY.md:49-113](file://DEPLOY.md#L49-L113)
### 本地开发与非容器部署
- 本地开发
- 后端在 8083 端口启动，前端在 3000 端口启动并通过代理转发 /api 到后端。
- 非容器部署
- 通过 start.sh/stop.sh/restart.sh 管理本地进程，便于调试与快速迭代。
章节来源
- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
- [backend/start.sh:1-5](file://backend/start.sh#L1-L5)
- [backend/stop.sh:1-14](file://backend/stop.sh#L1-L14)
- [backend/restart.sh:1-43](file://backend/restart.sh#L1-L43)
## 依赖分析
- 后端依赖
- Web 框架、ORM、MySQL 驱动、JWT、S3 SDK、Redis 客户端、日志、校验等。
- 前端依赖
- Vue 3、Element Plus、路由、HTTP 客户端等。
- 版本锁定
- 后端与前端均使用 pnpm 并固定版本，保证构建一致性。
```mermaid
graph LR
BE["后端 Node.js"] --> PkgBE["package.json 依赖"]
FE["前端 Vue 应用"] --> PkgFE["package.json 依赖"]
PkgBE --> Express["express"]
PkgBE --> Sequelize["sequelize + mysql2"]
PkgBE --> JWT["jsonwebtoken"]
PkgBE --> S3["@aws-sdk/client-s3"]
PkgBE --> Redis["ioredis"]
PkgBE --> Winston["winston"]
PkgBE --> Dotenv["dotenv"]
PkgFE --> Vue["vue"]
PkgFE --> EP["element-plus"]
PkgFE --> Axios["axios"]
PkgFE --> Router["vue-router"]
```
图表来源
- [backend/package.json:11-27](file://backend/package.json#L11-L27)
- [frontend/package.json:10-22](file://frontend/package.json#L10-L22)
章节来源
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
## 性能考虑
- 日志轮转
- Compose 层启用日志轮转，避免磁盘膨胀；建议结合系统日志聚合与保留策略。
- 静态资源优化
- 前端构建产物通过 Nginx 提供，建议配合缓存头与压缩策略提升首屏性能。
- 数据库与缓存
- 生产环境建议使用专用数据库与 Redis 实例，合理设置连接池与超时参数。
- 容器资源
- 建议在生产环境中为容器设置 CPU/内存限制与健康检查，增强稳定性。
- CDN 与反代
- 对静态资源与 API 可引入反向代理与 CDN，降低后端压力。
## 故障排除指南
- 前端页面空白
- 检查 dist 是否上传成功、Nginx 代理是否指向后端 8000 端口、浏览器控制台是否存在 404。
- API 请求失败
- 确认后端容器处于 running 状态、查看后端日志定位数据库/Redis/Meilisearch 连接问题。
- 后端构建失败（pnpm/Node 版本）
- 确保上传了 package.json 与 pnpm-lock.yaml，后端镜像基于 node:22-alpine。
- .env 修改不生效
- 通过重新创建容器使新环境变量生效。
- 停止/重启服务
- 使用 docker compose down 或在服务器执行 restart.sh/stop.sh/stop.sh 管理本地进程。
章节来源
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
- [backend/restart.sh:1-43](file://backend/restart.sh#L1-L43)
- [backend/stop.sh:1-14](file://backend/stop.sh#L1-L14)
## 结论
本项目采用轻量化的容器化方案：前端 Nginx 静态托管、后端 Node.js API，通过 Compose 统一编排与网络隔离，辅以集中式 .env 管理与 rsync 自动化脚本，形成可重复、可审计的生产部署流程。建议在生产中进一步完善资源限制、健康检查、日志聚合与监控告警体系，以满足高可用与可观测性要求。
## 附录
### 环境变量与配置清单
- 数据库
- DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD
- 应用
- APP_NAME、APP_ENV
- 认证
- JWT_SECRET、DASHBOARD_ADMIN_USERNAME、DASHBOARD_ADMIN_PASSWORD
- 搜索
- MEILISEARCH_URL、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- S3
- AWS_REGION、AWS_S3_OTA_BUCKET、AWS_S3_MEASUREMENT_BUCKET
- 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)
### 目录结构（服务器）
- /data/project/dashboard/
- .env、docker-compose.yml、backend/（含 Dockerfile、package.json、pnpm-lock.yaml、src/）、frontend/（dist、nginx.conf）
- /data/projects/source/（OTA 升级包存储）
章节来源
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
### 监控指标与日志管理
- 指标
- 建议采集容器 CPU/内存/IO、API 响应时间与错误率、数据库连接数、Redis 命中率等。
- 日志
- 后端日志写入容器内 logs 文件，结合 Compose 日志轮转；建议接入集中式日志系统进行检索与告警。
章节来源
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
### 备份与灾难恢复
- 数据库
- 定期导出 MySQL 数据，保存至安全位置或对象存储。
- 配置与代码
- .env 与源码版本化管理，确保可追溯与快速回滚。
- OTA 存储
- /data/projects/source 作为本地存储，建议异地复制或对象存储归档。
- 灾难恢复
- 准备最小化恢复步骤：拉起 Compose、恢复 .env、恢复数据库快照、恢复静态资源与 Nginx 配置。
### CI/CD 流程、版本发布与回滚
- 流程建议
- 代码合并触发流水线：前端构建、后端构建、上传脚本执行、Compose 启动。
- 发布与回滚
- 以标签/分支为版本依据；回滚时使用相同镜像版本或恢复 .env 快照，必要时回退数据库迁移。
### 安全配置、防火墙与访问控制
- 端口与防火墙
- 仅开放 8082（前端）、8083（后端）与必要的系统端口；限制来源 IP。
- 认证与密钥
- 生产环境务必更换 JWT_SECRET、管理员密码；S3 优先使用 IAM 角色而非明文凭据。
- 网络隔离
- 将数据库与缓存置于隔离网络，仅允许后端容器访问；必要时启用网络策略。
.qoder/repowiki/zh/content/部署与运维/部署指南.md
+377
View File
@@ -0,0 +1,377 @@
# 部署指南
<cite>
**本文引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [scripts/upload.sh](file://scripts/upload.sh)
- [frontend/nginx.conf](file://frontend/nginx.conf)
- [backend/start.sh](file://backend/start.sh)
- [backend/restart.sh](file://backend/restart.sh)
- [backend/stop.sh](file://backend/stop.sh)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
- [backend/src/utils/jwt.js](file://backend/src/utils/jwt.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/package.json](file://backend/package.json)
- [frontend/package.json](file://frontend/package.json)
- [frontend/vite.config.js](file://frontend/vite.config.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向首次部署、本地构建上传以及后续更新部署的全流程操作，覆盖服务器准备工作、目录结构创建、环境变量配置、Docker Compose 配置说明、服务端口映射与网络设置、上传脚本使用方法、手动 rsync 方式、构建与启动命令、健康检查与服务验证、常见部署问题解决方案，以及生产环境安全配置建议与最佳实践。
## 项目结构
- 前端采用 Nginx 静态托管，后端为 Node.js API，通过 Docker Compose 统一编排。
- 前端静态资源挂载至 Nginx 容器，Nginx 将 /api 代理到后端容器。
- 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
- 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
- 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
```mermaid
graph TB
subgraph "服务器"
FE["Nginx 前端<br/>端口 80 映射 8082"]
BE["Node.js 后端<br/>端口 8000 映射 8083"]
VOL1["/data/project/dashboard/frontend/dist"]
VOL2["/data/projects/source"]
end
FE --> |"/api 代理"| BE
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)
- [DEPLOY.md:1-16](file://DEPLOY.md#L1-L16)
## 核心组件
- 后端服务（Node.js）
- 基于 Node.js 22 Alpine，使用 pnpm 作为包管理器，生产依赖安装在容器内完成。
- 通过环境变量 PORT=8000 固定容器内端口，与 Nginx 代理保持一致。
- 日志目录在容器内创建，便于持久化与查看。
- 前端服务（Nginx）
- 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 与 nginx.conf。
- Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
- 支持静态资源缓存与上传大小限制。
- 上传脚本（upload.sh）
- 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
- 提供虚拟执行（-n）预览能力，便于确认同步范围。
- 环境变量与配置
- 根目录 .env 由 Docker Compose 注入后端容器，前端通过 Nginx 挂载配置。
- 后端支持通过 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/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)
## 架构总览
- 前端通过 Nginx 将 /api 代理到后端容器的 8000 端口。
- 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
- 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
- Docker Compose 控制服务生命周期与网络隔离。
```mermaid
graph TB
U["用户浏览器"] --> P["宿主机端口 8082/Nginx"]
P --> |"/api 代理"| B["后端容器 8000"]
P --> |静态资源"| D["/data/project/dashboard/frontend/dist"]
B --> S["OTA 存储卷 /data/projects/source"]
```
图表来源
- [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)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
## 详细组件分析
### 首次部署（服务器准备）
- 创建目录
- 前端 dist 目录：用于存放构建产物
- OTA 升级包存储目录：用于本地存储 X9 升级包
- 配置环境变量
- 在服务器根目录创建 .env，内容参考项目根目录 .env.example
- 关键点：PORT=8000（容器内固定）、JWT_SECRET、DASHBOARD_ADMIN_PASSWORD、数据库、搜索、S3、Redis、OTA 等参数
- .env 不会被上传脚本自动上传，需在服务器单独维护
- 上传代码并启动
- 参考“本地构建 + 上传”章节
章节来源
- [DEPLOY.md:18-46](file://DEPLOY.md#L18-L46)
### 本地构建 + 上传（推荐）
- 前端构建
- 在 frontend 目录执行安装与构建，产物输出至 dist
- 上传到服务器
- 使用上传脚本（推荐）：支持 all、frontend、backend、compose 等目标
- 支持自定义路径上传，如单独上传 nginx.conf 或 Dockerfile
- 虚拟执行（-n）可用于预览同步范围
- 服务器构建与启动
- 首次或依赖变更时，执行后端镜像构建
- 启动/更新：docker compose up -d
- 验证
- docker compose ps 查看状态
- docker compose logs -f backend 查看后端日志
- curl http://localhost:8083/health 进行健康检查
- 访问地址：
- 前端：http://服务器 IP:8082
- 后端 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)
### 更新部署
- 仅更新前端
- 本地构建后上传前端 dist，服务器重启前端容器
- 仅更新后端
- 上传后端代码与依赖文件，服务器重新构建并启动后端
- 一键流程
- 本地构建前端并上传，服务器执行后端镜像构建与启动
章节来源
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
### docker-compose.yml 说明
- backend
- env_file: .env 读取根目录环境变量
- environment: 设置 PORT=8000，覆盖容器内端口
- ports: 8083:8000（宿主:容器）
- volumes: 挂载 OTA 存储目录
- frontend
- image: nginx:alpine
- ports: 8082:80
- volumes: 挂载 dist 与 nginx.conf
- depends_on: 依赖后端容器
- 日志轮转
- 每个服务启用 json-file，单文件最大 10MB，最多 5 份
- 网络
- 使用自定义桥接网络 audio-network，便于容器间通信
章节来源
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
### 后端部署文件清单
- 后端镜像构建所需文件
- Dockerfile、package.json、pnpm-lock.yaml、src/
章节来源
- [DEPLOY.md:174-187](file://DEPLOY.md#L174-L187)
### 环境变量参考
- 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD
- 应用：APP_NAME、APP_ENV
- 认证：JWT_SECRET、DASHBOARD_ADMIN_USERNAME、DASHBOARD_ADMIN_PASSWORD
- 搜索：MEILISEARCH_URL、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- S3：AWS_REGION、AWS_S3_OTA_BUCKET、AWS_S3_MEASUREMENT_BUCKET
- 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)
### 目录结构（服务器）
- /data/project/dashboard/
- .env（服务器维护）
- docker-compose.yml
- backend/
- Dockerfile
- package.json
- pnpm-lock.yaml
- src/
- frontend/
- dist/
- nginx.conf
- /data/projects/source/（OTA 升级包存储）
章节来源
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
### 上传脚本使用方法
- 用法与选项
- 目标：frontend（f）、backend（b）、compose（c）、all（a）
- 自定义路径：可传入任意本地路径，映射到服务器对应位置
- 虚拟执行：-n 预览同步范围
- 默认同步范围
- all：包含前端 dist、后端 src、package.json、pnpm-lock.yaml、docker-compose.yml
- 注意事项
- 默认不同步 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)
### 手动 rsync 上传方式
- 前端
- rsync 前端 dist 至服务器 dist 目录
- scp nginx.conf 至服务器前端目录
- 后端
- rsync backend/src 至服务器 backend/src
- scp backend/Dockerfile、backend/package.json、backend/pnpm-lock.yaml 至服务器 backend/
- Compose
- scp docker-compose.yml 至服务器根目录
章节来源
- [DEPLOY.md:77-91](file://DEPLOY.md#L77-L91)
### 构建与启动命令
- 本地
- 前端：cd frontend && pnpm install && pnpm build
- 服务器
- 首次或依赖变更：docker compose build --no-cache backend
- 启动/更新：docker compose up -d
- 停止服务
- docker compose down
章节来源
- [DEPLOY.md:92-103](file://DEPLOY.md#L92-L103)
- [DEPLOY.md:251-256](file://DEPLOY.md#L251-L256)
### 健康检查与服务验证
- 健康检查
- curl http://localhost:8083/health
- 状态与日志
- docker compose ps
- docker compose logs -f backend
- 访问地址
- 前端：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083/api/...
章节来源
- [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
### 后端本地脚本（非 Docker）
- start.sh：在本地直接启动后端服务
- 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)
### 前端开发与 Nginx 配置
- 前端开发
- 本地开发使用 Vite，默认端口 3000，/api 代理到后端 8083
- Nginx 配置
- 监听 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)
## 依赖关系分析
- 组件耦合
- 前端依赖后端 API，通过 Nginx 代理实现解耦
- 后端依赖数据库、搜索、对象存储、Redis 等外部服务
- 直接与间接依赖
- 后端镜像构建依赖 package.json 与 pnpm-lock.yaml
- 前端镜像构建依赖 package.json 与 pnpm-lock.yaml
- 外部依赖与集成点
- Docker Compose 管理服务生命周期与网络
- Nginx 作为反向代理与静态资源服务
```mermaid
graph LR
FE["前端(dist)"] --> NGINX["Nginx 反向代理"]
NGINX --> BE["后端容器(8000)"]
BE --> DB["数据库"]
BE --> MEILI["Meilisearch"]
BE --> S3["S3 对象存储"]
BE --> REDIS["Redis"]
```
图表来源
- [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)
## 性能考虑
- 日志轮转
- 每个服务启用 JSON 文件轮转，单文件最大 10MB，最多 5 份，避免日志无限增长
- 静态资源优化
- Nginx 对静态资源进行缓存与压缩，提升前端加载速度
- 端口与网络
- 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
章节来源
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-L32)
## 故障排查指南
- 前端页面空白
- 检查 dist 是否上传成功、路径是否正确
- 查看浏览器控制台是否存在 404 或 API 错误
- 查看前端容器日志
- API 请求失败
- 确认后端容器处于 running 状态
- 查看后端日志，定位数据库、Redis、Meilisearch 连接问题
- 确认 Nginx 代理目标为 http://backend:8000
- 后端构建失败（pnpm / Node 版本）
- 后端镜像基于 node:22-alpine，确保上传了 package.json 与 pnpm-lock.yaml
- 修改 .env 后不生效
- 通过 docker compose up -d --force-recreate 使新环境变量生效
- 停止服务
- docker compose down
章节来源
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
## 结论
本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。
## 附录
### 环境变量与安全配置建议
- 生产环境必须替换的敏感项
- JWT_SECRET：强随机密钥，避免使用默认值
- DASHBOARD_ADMIN_PASSWORD：初始管理员密码，部署后立即修改
- 最小权限原则
- S3 通常通过云服务 IAM 角色访问，避免在 .env 中硬编码密钥
- 网络与端口
- 仅开放必要端口，防火墙策略最小化
- 日志与监控
- 结合日志轮转与容器日志采集，定期巡检
- 配置加载
- 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
章节来源
- [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/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)