audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1a9003261d85370ce2cd8c76b88a1d681ce4e78e
dashboard/.qoder/repowiki/zh/content/部署与运维/故障排除.md
T
eafonyang 08da279275 新增项目文档
2026-06-30 14:46:52 +08:00

507 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 故障排除
<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)
Reference in New Issue View Git Blame Copy Permalink