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

348 lines
14 KiB
Markdown
Raw Blame History

# 监控运维
<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)
Reference in New Issue View Git Blame Copy Permalink