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

18 KiB
Raw Blame History

故障排除

**本文引用的文件** - [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)

目录

  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 读取并注入到容器。
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

图表来源

章节来源

核心组件

  • 前端请求封装与拦截器：统一设置 /api 基础路径、Token 注入、401/403 处理与错误提示。
  • 后端入口与健康检查：Express 应用、CORS、Body 解析、/health 健康检查、表初始化与启动日志。
  • 日志系统：Winston 控制台与文件输出，按时间戳格式化。
  • 数据库连接：Sequelize 初始化，开发/生产日志开关。
  • 环境变量：APP_ENV 切换开发/生产，PORT 控制监听端口。
  • Nginx 代理：/api 代理到 backend:8000，静态缓存与上传大小限制。
  • 上传脚本：rsync 同步前端 dist、后端 src/package/pnpm-lock、compose 文件。

章节来源

架构总览

  • 前端通过 Nginx 将 /api 请求转发至 backend:8000。
  • 后端监听容器内 8000 端口，宿主机映射 8083。
  • 健康检查端点 /health 用于快速验证后端状态。
  • 环境变量 .env 通过 env_file 注入，确保数据库、Redis、S3 等配置一致。
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"

图表来源

详细组件分析

前端请求与错误处理

  • 基础路径：/api，超时 10 秒。
  • Token 注入：除登录接口外自动附加 Authorization。
  • 401：清理本地认证并重定向到登录页。
  • 403：提示无权限。
  • 通用错误：控制台记录并全局消息提示。
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

图表来源

章节来源

后端启动与健康检查

  • CORS 开放，支持 JSON/URL 编码请求体。
  • /health 返回健康状态。
  • 启动时尝试同步数据库表并引导超级管理员账户。
  • 日志输出包含时间戳与元信息。
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' }"

图表来源

章节来源

数据库连接与环境变量

  • 通过 DATABASE_* 环境变量配置主机、端口、库名、账号、密码。
  • 生产环境关闭 Sequelize 日志，开发环境开启。
  • 定义冻结表名与禁用时间戳，减少迁移成本。
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["应用可用"]

图表来源

章节来源

Nginx 代理与静态资源

  • /api 代理到 http://backend:8000。
  • 支持 Vue Router 历史模式回退到 index.html。
  • 静态资源缓存一年，Gzip 压缩常用类型。
  • 上传文件最大 8MB。
flowchart TD
Req["浏览器请求"] --> Path{"路径匹配"}
Path --> |/api*| Proxy["代理到 backend:8000"]
Path --> |/| HTML["返回 index.html"]
Path --> |静态资源| Cache["缓存一年 + Gzip"]
Proxy --> Resp["返回后端响应"]
HTML --> Resp
Cache --> Resp

图表来源

章节来源

上传与部署脚本

  • 支持同步前端 dist、后端 src/package/pnpm-lock、compose 文件。
  • 默认目标服务器与密钥可配置。
  • 支持虚拟执行预览同步内容。
flowchart TD
Run["执行 upload.sh"] --> Resolve["解析预设/自定义路径"]
Resolve --> Sync["rsync 同步到远端"]
Sync --> Done["完成"]

图表来源

章节来源

依赖关系分析

  • 前端依赖 axios、Vue、Element Plus 等，构建后由 Nginx 提供。
  • 后端依赖 Express、Sequelize、MySQL2、Winston、ioredis、@aws-sdk 等。
  • Compose 将 .env 注入后端容器，前端挂载 dist 与 nginx.conf。
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

图表来源

章节来源

性能考虑

  • 日志轮转：单文件最大 10MB，最多 5 个文件，避免磁盘占用过大。
  • Nginx 缓存：静态资源一年缓存，降低带宽与后端压力。
  • Gzip 压缩：对文本与 JS/CSS/JSON 启用压缩。
  • 上传大小限制：8MB，避免大体积请求导致内存压力。
  • 健康检查：/health 快速定位后端存活状态。

章节来源

故障排除指南

一、前端页面空白

  • 检查点
    • 前端构建产物是否上传至 /data/project/dashboard/frontend/dist。
    • Nginx 是否加载正确的 default.conf。
    • 浏览器控制台是否存在 404 或跨域错误。
    • 健康检查 /health 是否可达。
  • 排查步骤
    • 登录服务器，确认 dist 目录存在且内容完整。
    • 查看 Nginx 日志与容器日志。
    • 确认 /api 代理指向 backend:8000。
  • 快速修复
    • 重新构建并上传前端，或重启 frontend 容器。

章节来源

二、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 容器。

章节来源

三、后端构建失败（pnpm / Node 版本）

  • 检查点
    • 后端镜像基于 node:22-alpine。
    • package.json 与 pnpm-lock.yaml 是否随后端一起上传。
  • 排查步骤
    • 确认上传脚本包含 backend 相关文件。
    • 在服务器执行 docker compose build --no-cache backend。
  • 快速修复
    • 重新上传后端文件并重新构建。

章节来源

四、修改 .env 后不生效

  • 现象
    • 更改环境变量后，容器未感知。
  • 排查步骤
    • docker compose up -d --force-recreate backend。
  • 快速修复
    • 强制重建后端容器以加载新 .env。

章节来源

五、停止与重启服务

  • 停止
    • docker compose down。
  • 仅重启前端
    • docker compose restart frontend。
  • 仅更新后端
    • 上传后端文件，build 并 up -d backend。

章节来源

六、Docker 相关问题

  • 端口冲突
    • 检查宿主机 8082/8083 是否被占用。
  • 权限问题
    • 确认 dist 与 nginx.conf 挂载权限。
  • 日志过大
    • 使用日志轮转配置，必要时清理历史日志。

章节来源

七、网络连接问题

  • 前端无法访问 /api
    • 检查 Nginx 代理配置与 backend 容器连通性。
    • 确认容器网络 audio-network 是否创建成功。
  • 后端无法访问外部服务
    • 检查 DNS、防火墙、安全组规则。
    • 确认 AWS 凭证或 IAM 角色配置。

章节来源

八、数据库连接问题

  • 检查点
    • DATABASE_HOST/PORT/NAME/USER/PASSWORD 是否正确。
    • MySQL 服务可达，账号具备权限。
    • 容器内网络与端口映射是否正确。
  • 排查步骤
    • 在 backend 容器内测试连接（nslookup/mysql 命令）。
    • 查看后端启动日志中的数据库连接错误。
  • 快速修复
    • 修正 .env 中数据库配置并重建后端容器。

章节来源

九、日志分析方法

  • 后端日志
    • 控制台与文件同时输出，查看启动阶段的表同步与错误信息。
  • 前端日志
    • 浏览器开发者工具 Network/Console。
  • Nginx 日志
    • 容器标准输出，关注 4xx/5xx 与代理错误。
  • 建议
    • 结合时间戳定位问题发生时段，优先查看 ERROR/异常堆栈。

章节来源

十、错误代码含义与调试技巧

  • 响应结构
    • code=1：成功；code=0：业务错误；code=2：无数据。
  • 前端拦截器
    • code=0：统一错误提示与拒绝 Promise。
    • 401：清除本地认证并跳转登录。
    • 403：提示无权限。
  • 调试技巧
    • 打开浏览器 Network 面板，观察请求头与响应体。
    • 在后端添加最小复现接口，逐步缩小范围。
    • 使用 curl 直连 /health 与关键业务接口验证后端状态。

章节来源

十一、性能问题诊断

  • CPU/内存飙升
    • 检查后端日志中慢查询与异常堆栈。
    • 关注 Nginx 代理错误与后端队列积压。
  • 静态资源加载慢
    • 确认缓存头与 Gzip 是否生效。
    • 检查 dist 是否最新版本。
  • 数据库慢
    • 查看数据库连接数与锁等待。
    • 优化查询与索引。

章节来源

十二、内存泄漏检测与系统瓶颈分析

  • 方法
    • 使用 Node.js 内置分析工具生成 Heap/Profile 快照。
    • 持续监控容器资源使用率与错误日志。
    • 逐步禁用功能模块定位可疑代码段。
  • 建议
    • 限制并发与批量操作，增加重试与熔断机制。

[本节为通用指导，无需特定文件引用]

十三、紧急恢复与回滚策略

  • 快速恢复
    • 重启 frontend 与 backend 容器。
    • 回滚到上一个稳定版本的 dist 与后端镜像。
  • 回滚步骤
    • 前端：恢复上一版 dist。
    • 后端：切换镜像标签或重新 build 上一版。
  • 预案
    • 保留最近一次构建产物与镜像快照。
    • 使用只读挂载与备份卷保障数据安全。

章节来源

结论

通过统一的日志输出、清晰的 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
  • 健康检查

章节来源

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

章节来源

Reference in New Issue View Git Blame Copy Permalink