dashboard/.qoder/repowiki/zh/content/部署与运维/故障排除.md

# 故障排除

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