audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新 wiki

Browse Source
This commit is contained in:
eafonyang
2026-07-17 17:17:22 +08:00
parent 1da6d72544
commit d292c23dc0
159 changed files with 2918 additions and 2735 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/zh/content/部署与运维/部署指南.md
+48 -44
View File
@@ -5,27 +5,22 @@
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [scripts/upload.sh](file://scripts/upload.sh)
- [frontend/nginx.conf](file://frontend/nginx.conf)
- [backend/start.sh](file://backend/start.sh)
- [backend/restart.sh](file://backend/restart.sh)
- [backend/stop.sh](file://backend/stop.sh)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
- [backend/src/utils/jwt.js](file://backend/src/utils/jwt.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/package.json](file://backend/package.json)
- [frontend/vite.config.ts](file://frontend/vite.config.ts)
- [frontend/package.json](file://frontend/package.json)
- [frontend/vite.config.js](file://frontend/vite.config.js)
- [backend/package.json](file://backend/package.json)
</cite>
## 更新摘要
**变更内容**
- 更新了Docker Compose配置说明，突出网络和卷挂载优化
- 增强了前后端服务连接稳定性的配置细节
- 添加了网络隔离和容器间通信的配置说明
- 完善了卷挂载的安全性和性能考虑
- 移除了前端Dockerfile和nginx.conf，改为纯静态资源托管模式
- 删除了批处理脚本（build-and-deploy.bat、install.bat、start.bat）
- 采用TypeScript-based构建系统，使用Vite进行前端构建
- 简化了部署流程，专注于Docker Compose编排和手动上传方式
- 更新了构建命令和环境配置说明
## 目录
1. [简介](#简介)
@@ -42,13 +37,15 @@
## 简介
本指南面向首次部署、本地构建上传以及后续更新部署的全流程操作，覆盖服务器准备工作、目录结构创建、环境变量配置、Docker Compose 配置说明、服务端口映射与网络设置、上传脚本使用方法、手动 rsync 方式、构建与启动命令、健康检查与服务验证、常见部署问题解决方案，以及生产环境安全配置建议与最佳实践。
**更新**：本项目已移除传统的前端Dockerfile和nginx.conf配置，采用更简洁的静态资源托管模式，通过Nginx镜像直接挂载构建产物。
## 项目结构
- 前端采用 Nginx 静态托管，后端为 Node.js API，通过 Docker Compose 统一编排。
- 前端静态资源挂载至 Nginx 容器，Nginx 将 /api 代理到后端容器。
- 前端采用Nginx静态托管，后端为Node.js API，通过 Docker Compose 统一编排。
- 前端静态资源通过rsync或上传脚本部署到服务器dist目录，Nginx容器直接挂载该目录。
- 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
- 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
- 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
- **新增**：使用自定义桥接网络 `audio-network` 确保容器间通信的稳定性和安全性。
- **更新**：前端不再需要独立的Dockerfile，直接使用nginx:alpine镜像挂载静态资源。
```mermaid
graph TB
@@ -65,7 +62,6 @@ BE --- VOL2
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
**章节来源**
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
@@ -78,23 +74,21 @@ BE --- VOL2
- 日志目录在容器内创建，便于持久化与查看。
- **新增**：加入 `extra_hosts` 配置支持 `host.docker.internal` 访问宿主机。
- 前端服务（Nginx）
- 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 与 nginx.conf。
- 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 目录。
- Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
- 支持静态资源缓存与上传大小限制。
- **新增**：卷挂载使用只读模式 (`:ro`) 提升安全性。
- **更新**：移除了自定义nginx.conf，使用Nginx默认配置。
- 上传脚本（upload.sh）
- 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
- 提供虚拟执行（-n）预览能力，便于确认同步范围。
- 环境变量与配置
- 根目录 .env 由 Docker Compose 注入后端容器，前端通过 Nginx 挂载配置。
- 根目录 .env 由 Docker Compose 注入后端容器。
- 后端支持通过 APP_ENV 切换开发/生产环境行为。
- JWT 密钥、管理员密码等敏感信息需在生产环境强制替换。
**章节来源**
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
- [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/loadEnv.js:1-14](file://backend/src/config/loadEnv.js#L1-L14)
- [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)
@@ -104,7 +98,7 @@ BE --- VOL2
- 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
- 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
- Docker Compose 控制服务生命周期与网络隔离。
- **新增**：所有服务加入自定义桥接网络 `audio-network`，确保容器间通信的稳定性和安全性。
- **更新**：前端不再需要独立构建镜像，直接使用官方nginx:alpine镜像。
```mermaid
graph TB
@@ -120,7 +114,6 @@ end
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
**章节来源**
- [DEPLOY.md:5-16](file://DEPLOY.md#L5-L16)
@@ -144,10 +137,11 @@ end
### 本地构建 + 上传（推荐）
- 前端构建
- 在 frontend 目录执行安装与构建，产物输出至 dist
- **更新**：使用Vite构建系统，在 frontend 目录执行安装与构建，产物输出至 dist
- 构建命令：`cd frontend && pnpm install && pnpm build`
- 上传到服务器
- 使用上传脚本（推荐）：支持 all、frontend、backend、compose 等目标
- 支持自定义路径上传，如单独上传 nginx.conf 或 Dockerfile
- 支持自定义路径上传，如单独上传配置文件
- 虚拟执行（-n）可用于预览同步范围
- 服务器构建与启动
- 首次或依赖变更时，执行后端镜像构建
@@ -165,6 +159,7 @@ end
- [DEPLOY.md:49-120](file://DEPLOY.md#L49-L120)
- [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
- [frontend/vite.config.ts:1-50](file://frontend/vite.config.ts#L1-L50)
### 更新部署
- 仅更新前端
@@ -175,7 +170,7 @@ end
- 本地构建前端并上传，服务器执行后端镜像构建与启动
**章节来源**
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-154)
### docker-compose.yml 说明
- backend
@@ -188,9 +183,10 @@ end
- frontend
- image: nginx:alpine
- ports: 8082:80
- volumes: 挂载 dist 与 nginx.conf（只读模式 :ro）
- volumes: 挂载 dist 目录（只读模式 :ro）
- depends_on: 依赖后端容器
- **新增**：networks: audio-network 加入自定义网络
- **更新**：移除了自定义nginx.conf挂载，使用Nginx默认配置
- 日志轮转
- 每个服务启用 json-file，单文件最大 10MB，最多 5 份
- 网络
@@ -218,7 +214,7 @@ end
- Redis EQ：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_EQ_DB
**章节来源**
- [DEPLOY.md:190-203](file://DEPLOY.md#L190-L203)
- [DEPLOY.md:190-203](file://DEPLOY.md#L190-203)
### 目录结构（服务器）
- /data/project/dashboard/
@@ -231,9 +227,10 @@ end
- src/
- frontend/
- dist/
- nginx.conf
- /data/projects/source/（OTA 升级包存储）
**更新**：移除了frontend/nginx.conf文件，前端配置现在完全依赖Nginx默认行为。
**章节来源**
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
@@ -245,7 +242,7 @@ end
- 默认同步范围
- all：包含前端 dist、后端 src、package.json、pnpm-lock.yaml、docker-compose.yml
- 注意事项
- 默认不同步 nginx.conf 与 Dockerfile，需要时需显式指定
- **更新**：默认不同步nginx.conf（已移除）与Dockerfile，需要时需显式指定
- 路径不在项目内会被跳过
**章节来源**
@@ -255,7 +252,7 @@ end
### 手动 rsync 上传方式
- 前端
- rsync 前端 dist 至服务器 dist 目录
- scp nginx.conf 至服务器前端目录
- **更新**：无需上传nginx.conf文件
- 后端
- rsync backend/src 至服务器 backend/src
- scp backend/Dockerfile、backend/package.json、backend/pnpm-lock.yaml 至服务器 backend/
@@ -267,7 +264,7 @@ end
### 构建与启动命令
- 本地
- 前端：cd frontend && pnpm install && pnpm build
- **更新**：前端使用Vite构建：cd frontend && pnpm install && pnpm build
- 服务器
- 首次或依赖变更：docker compose build --no-cache backend
- 启动/更新：docker compose up -d
@@ -277,6 +274,7 @@ end
**章节来源**
- [DEPLOY.md:92-103](file://DEPLOY.md#L92-L103)
- [DEPLOY.md:251-256](file://DEPLOY.md#L251-L256)
- [frontend/vite.config.ts:1-50](file://frontend/vite.config.ts#L1-L50)
### 健康检查与服务验证
- 健康检查
@@ -301,16 +299,18 @@ end
- [backend/restart.sh:1-43](file://backend/restart.sh#L1-L43)
- [backend/stop.sh:1-14](file://backend/stop.sh#L1-L14)
### 前端开发与 Nginx 配置
- 前端开发
### 前端开发与构建配置
- **更新**：前端开发
- 本地开发使用 Vite，默认端口 3000，/api 代理到后端 8083
- Nginx 配置
- 监听 80，将 /api 代理到后端容器 8000
- 构建产物输出到 dist 目录
- **更新**：Nginx 配置
- 使用Nginx默认配置，监听 80 端口
- 通过Docker Compose中的location指令实现API代理
- 支持静态资源缓存与上传大小限制
**章节来源**
- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
- [frontend/vite.config.ts:1-50](file://frontend/vite.config.ts#L1-L50)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
## 依赖关系分析
- 组件耦合
@@ -318,7 +318,7 @@ end
- 后端依赖数据库、搜索、对象存储、Redis 等外部服务
- 直接与间接依赖
- 后端镜像构建依赖 package.json 与 pnpm-lock.yaml
- 前端镜像构建依赖 package.json 与 pnpm-lock.yaml
- **更新**：前端不再需要独立镜像构建，直接使用nginx:alpine镜像
- 外部依赖与集成点
- Docker Compose 管理服务生命周期与网络
- Nginx 作为反向代理与静态资源服务
@@ -340,7 +340,6 @@ end
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
**章节来源**
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
@@ -353,7 +352,7 @@ end
- Nginx 对静态资源进行缓存与压缩，提升前端加载速度
- 端口与网络
- 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
- **新增**：卷挂载优化
- **更新**：卷挂载优化
- 前端卷挂载使用只读模式 (:ro)，提升安全性和性能
- 后端 OTA 存储卷直接映射宿主机目录，避免额外开销
- **新增**：网络优化
@@ -362,7 +361,6 @@ end
**章节来源**
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-32)
## 故障排查指南
- 前端页面空白
@@ -382,6 +380,9 @@ end
- **新增**：检查网络连通性：`docker exec dashboard-frontend ping backend`
- **新增**：查看网络配置：`docker network ls`
- **新增**：检查容器网络：`docker inspect dashboard-backend | grep NetworkMode`
- **更新**：前端构建问题
- 确认Vite构建成功，dist目录存在且包含必要的静态资源
- 检查前端构建日志，确认没有编译错误
- 停止服务
- docker compose down
@@ -391,7 +392,7 @@ end
## 结论
本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。
**新增**：通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面得到了显著提升。
**更新**：通过移除复杂的前端Dockerfile和nginx.conf配置，采用更简洁的静态资源托管模式，部署流程得到了显著简化。同时，通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面也得到了提升。
## 附录
@@ -408,9 +409,12 @@ end
- 结合日志轮转与容器日志采集，定期巡检
- 配置加载
- 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
- **新增**：卷挂载安全
- **更新**：卷挂载安全
- 前端静态资源使用只读挂载 (:ro)，防止运行时修改
- 后端数据卷根据业务需求选择合适的挂载模式
- **新增**：构建安全
- 前端使用Vite构建，确保生产环境构建产物不包含开发依赖
- 定期更新前端依赖，修复已知安全漏洞
**章节来源**
- [DEPLOY.md:36-42](file://DEPLOY.md#L36-L42)