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

14 KiB
Raw Blame History

部署与运维

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

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介

本文件面向部署与运维工程师，系统性说明项目的容器化部署、环境配置、生产部署流程、容器编排、服务依赖与网络设置、部署脚本使用、自动化流程、环境变量与数据库/缓存配置、监控与日志、性能调优、故障排除、备份恢复与灾难恢复、CI/CD 与版本发布/回滚策略，以及安全配置与访问控制。

项目结构

  • 前端采用 Nginx 静态托管，后端为 Node.js API，二者通过 Docker Compose 在同一自定义桥接网络中通信。
  • 前端不构建镜像，直接挂载服务器上的构建产物与 Nginx 配置；后端以独立镜像运行。
  • 日志轮转策略在 Compose 层统一配置，便于生产环境管理。
  • OTA 升级包本地存储通过宿主机卷挂载到后端容器，确保升级资源可用性。
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

图表来源

章节来源

核心组件

  • 后端服务（Node.js）
    • 基于 Node.js 22 Alpine 镜像，使用 pnpm 生产依赖安装，工作目录包含日志目录，暴露 8000 端口。
    • 通过环境变量驱动数据库、Redis、搜索、S3、OTA 等配置。
  • 前端服务（Nginx）
    • 使用 Nginx Alpine 镜像，挂载静态资源与 Nginx 配置，不构建镜像，减少部署复杂度。
  • 容器编排与网络
    • Compose 定义自定义桥接网络，前后端在同一网络内通信；前端通过 Nginx 将 /api 代理到后端容器的 8000 端口。
  • 部署脚本
    • 提供一键上传前端、后端、Compose 的 rsync 脚本，支持虚拟执行与多目标组合。

章节来源

架构总览

  • 端口映射
    • 前端 Nginx 暴露 80，映射到宿主机 8082。
    • 后端 Node.js 暴露 8000，映射到宿主机 8083。
  • 服务依赖
    • 前端依赖后端 API；Compose 通过 depends_on 实现启动顺序。
  • 网络
    • 两容器加入同一自定义桥接网络，实现容器间通过服务名访问。
  • 日志
    • 每个服务启用 JSON 文件日志轮转，单文件最大 10MB，最多 5 个文件。
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 数据"

图表来源

章节来源

详细组件分析

后端容器与应用配置

  • 环境变量加载
    • 容器内通过根目录 .env 注入；本地开发与 Docker 部署共享同一 .env 加载逻辑，但 Docker 下容器内无 .env 文件，由 Compose 注入。
  • 环境类型
    • 通过 APP_ENV 判断开发/生产环境，影响日志输出等行为。
  • 数据库连接
    • 使用 Sequelize 连接 MySQL，支持主机、端口、用户名、密码、字符集、日志开关等配置项。
  • Redis 缓存
    • 提供 EQ 缓存客户端工厂方法，支持主机、端口、密码、数据库编号、超时与重试配置，并记录错误日志。
  • 日志
    • 使用 Winston 输出到控制台与文件，日志目录位于应用内部 logs 子目录。
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(["服务就绪"])

图表来源

章节来源

前端容器与 Nginx 配置

  • 镜像与构建
    • 使用 Nginx Alpine 镜像，挂载静态资源与 Nginx 配置文件，不构建前端镜像。
  • 代理规则
    • 前端通过 Nginx 将 /api 代理到后端容器的 8000 端口，确保 SPA 与 API 请求分离。
  • 卷挂载
    • 前端 dist 与 nginx.conf 通过宿主机卷挂载，便于快速更新与热替换。

章节来源

容器编排与网络

  • 自定义桥接网络
    • 两容器加入同一网络，实现通过服务名访问后端 API。
  • 端口映射
    • 前端 80:8082，后端 8000:8083，避免端口冲突。
  • 日志轮转
    • 每个服务启用 JSON 文件日志轮转，单文件 10MB，最多 5 份。

章节来源

部署脚本与自动化

  • 功能特性
    • 支持同步前端、后端、Compose 三类目标，也支持指定路径与虚拟执行。
    • 默认目标包含前端 dist、后端 src 与依赖锁文件、Compose 文件。
    • SSH 密钥与远程路径可配置，便于跨环境复用。
  • 使用场景
    • 本地构建前端后，一键上传前端与 Compose 并在服务器执行 docker compose up -d。
    • 后端代码变更后，上传后端文件并在服务器重建后端镜像并启动。
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 : "验证服务状态与日志"

图表来源

章节来源

本地开发与非容器部署

  • 本地开发
    • 后端在 8083 端口启动，前端在 3000 端口启动并通过代理转发 /api 到后端。
  • 非容器部署
    • 通过 start.sh/stop.sh/restart.sh 管理本地进程，便于调试与快速迭代。

章节来源

依赖分析

  • 后端依赖
    • Web 框架、ORM、MySQL 驱动、JWT、S3 SDK、Redis 客户端、日志、校验等。
  • 前端依赖
    • Vue 3、Element Plus、路由、HTTP 客户端等。
  • 版本锁定
    • 后端与前端均使用 pnpm 并固定版本，保证构建一致性。
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"]

图表来源

章节来源

性能考虑

  • 日志轮转
    • 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 管理本地进程。

章节来源

结论

本项目采用轻量化的容器化方案：前端 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

章节来源

目录结构（服务器）

  • /data/project/dashboard/
    • .env、docker-compose.yml、backend/（含 Dockerfile、package.json、pnpm-lock.yaml、src/）、frontend/（dist、nginx.conf）
  • /data/projects/source/（OTA 升级包存储）

章节来源

监控指标与日志管理

  • 指标
    • 建议采集容器 CPU/内存/IO、API 响应时间与错误率、数据库连接数、Redis 命中率等。
  • 日志
    • 后端日志写入容器内 logs 文件，结合 Compose 日志轮转；建议接入集中式日志系统进行检索与告警。

章节来源

备份与灾难恢复

  • 数据库
    • 定期导出 MySQL 数据，保存至安全位置或对象存储。
  • 配置与代码
    • .env 与源码版本化管理，确保可追溯与快速回滚。
  • OTA 存储
    • /data/projects/source 作为本地存储，建议异地复制或对象存储归档。
  • 灾难恢复
    • 准备最小化恢复步骤：拉起 Compose、恢复 .env、恢复数据库快照、恢复静态资源与 Nginx 配置。

CI/CD 流程、版本发布与回滚

  • 流程建议
    • 代码合并触发流水线：前端构建、后端构建、上传脚本执行、Compose 启动。
  • 发布与回滚
    • 以标签/分支为版本依据；回滚时使用相同镜像版本或恢复 .env 快照，必要时回退数据库迁移。

安全配置、防火墙与访问控制

  • 端口与防火墙
    • 仅开放 8082（前端）、8083（后端）与必要的系统端口；限制来源 IP。
  • 认证与密钥
    • 生产环境务必更换 JWT_SECRET、管理员密码；S3 优先使用 IAM 角色而非明文凭据。
  • 网络隔离
    • 将数据库与缓存置于隔离网络，仅允许后端容器访问；必要时启用网络策略。
Reference in New Issue View Git Blame Copy Permalink