audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2a8ef2f2df60c43578d582f3eeb91ad37f10362
dashboard/.qoder/repowiki/zh/content/部署与运维/部署指南.md
T
eafonyang d2a8ef2f2d 优化新增耳机流程，优化界面
2026-07-20 15:45:52 +08:00

432 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署指南
<cite>
**本文引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
- [backend/Dockerfile](file://backend/Dockerfile)
- [scripts/upload.sh](file://scripts/upload.sh)
- [backend/start.sh](file://backend/start.sh)
- [backend/restart.sh](file://backend/restart.sh)
- [backend/stop.sh](file://backend/stop.sh)
- [frontend/vite.config.ts](file://frontend/vite.config.ts)
- [frontend/package.json](file://frontend/package.json)
- [backend/package.json](file://backend/package.json)
</cite>
## 更新摘要
**变更内容**
- 移除了前端Dockerfile和nginx.conf，改为纯静态资源托管模式
- 删除了批处理脚本（build-and-deploy.bat、install.bat、start.bat）
- 采用TypeScript-based构建系统，使用Vite进行前端构建
- 简化了部署流程，专注于Docker Compose编排和手动上传方式
- 更新了构建命令和环境配置说明
- **新增**：部署脚本upload.sh进行了清理，移除了12行废弃功能代码，简化了部署流程
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向首次部署、本地构建上传以及后续更新部署的全流程操作，覆盖服务器准备工作、目录结构创建、环境变量配置、Docker Compose 配置说明、服务端口映射与网络设置、上传脚本使用方法、手动 rsync 方式、构建与启动命令、健康检查与服务验证、常见部署问题解决方案，以及生产环境安全配置建议与最佳实践。
**更新**：本项目已移除传统的前端Dockerfile和nginx.conf配置，采用更简洁的静态资源托管模式，通过Nginx镜像直接挂载构建产物。同时，部署脚本upload.sh经过清理优化，移除了废弃功能代码，进一步简化了部署流程。
## 项目结构
- 前端采用Nginx静态托管，后端为Node.js API，通过 Docker Compose 统一编排。
- 前端静态资源通过rsync或上传脚本部署到服务器dist目录，Nginx容器直接挂载该目录。
- 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
- 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
- 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
- **更新**：前端不再需要独立的Dockerfile，直接使用nginx:alpine镜像挂载静态资源。
```mermaid
graph TB
subgraph "Docker 网络 audio-network"
FE["Nginx 前端<br/>端口 80 映射 8082"]
BE["Node.js 后端<br/>端口 8000 映射 8083"]
VOL1["/data/project/dashboard/frontend/dist"]
VOL2["/data/projects/source"]
end
FE --> |"/api 代理"| BE
FE --- VOL1
BE --- VOL2
```
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
**章节来源**
- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
- [DEPLOY.md:1-16](file://DEPLOY.md#L1-L16)
## 核心组件
- 后端服务（Node.js）
- 基于 Node.js 22 Alpine，使用 pnpm 作为包管理器，生产依赖安装在容器内完成。
- 通过环境变量 PORT=8000 固定容器内端口，与 Nginx 代理保持一致。
- 日志目录在容器内创建，便于持久化与查看。
- **新增**：加入 `extra_hosts` 配置支持 `host.docker.internal` 访问宿主机。
- 前端服务（Nginx）
- 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 目录。
- Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
- 支持静态资源缓存与上传大小限制。
- **更新**：移除了自定义nginx.conf，使用Nginx默认配置。
- 上传脚本（upload.sh）
- 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
- 提供虚拟执行（-n）预览能力，便于确认同步范围。
- **更新**：脚本经过清理优化，移除了废弃功能代码，简化了部署流程。
- 环境变量与配置
- 根目录 .env 由 Docker Compose 注入后端容器。
- 后端支持通过 APP_ENV 切换开发/生产环境行为。
- JWT 密钥、管理员密码等敏感信息需在生产环境强制替换。
**章节来源**
- [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
- [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)
## 架构总览
- 前端通过 Nginx 将 /api 代理到后端容器的 8000 端口。
- 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
- 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
- Docker Compose 控制服务生命周期与网络隔离。
- **更新**：前端不再需要独立构建镜像，直接使用官方nginx:alpine镜像。
```mermaid
graph TB
U["用户浏览器"] --> P["宿主机端口 8082/Nginx"]
P --> |"/api 代理"| B["后端容器 8000"]
P --> |静态资源| D["/data/project/dashboard/frontend/dist"]
B --> S["OTA 存储卷 /data/projects/source"]
subgraph "Docker 网络 audio-network"
B
P
end
```
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
**章节来源**
- [DEPLOY.md:5-16](file://DEPLOY.md#L5-L16)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
## 详细组件分析
### 首次部署（服务器准备）
- 创建目录
- 前端 dist 目录：用于存放构建产物
- OTA 升级包存储目录：用于本地存储 X9 升级包
- 配置环境变量
- 在服务器根目录创建 .env，内容参考项目根目录 .env.example
- 关键点：PORT=8000（容器内固定）、JWT_SECRET、DASHBOARD_ADMIN_PASSWORD、数据库、搜索、S3、Redis、OTA 等参数
- .env 不会被上传脚本自动上传，需在服务器单独维护
- 上传代码并启动
- 参考"本地构建 + 上传"章节
**章节来源**
- [DEPLOY.md:18-46](file://DEPLOY.md#L18-L46)
### 本地构建 + 上传（推荐）
- 前端构建
- **更新**：使用Vite构建系统，在 frontend 目录执行安装与构建，产物输出至 dist
- 构建命令：`cd frontend && pnpm install && pnpm build`
- 上传到服务器
- 使用上传脚本（推荐）：支持 all、frontend、backend、compose 等目标
- 支持自定义路径上传，如单独上传配置文件
- 虚拟执行（-n）可用于预览同步范围
- **更新**：上传脚本经过清理优化，移除了废弃功能代码，提供更简洁的部署体验
- 服务器构建与启动
- 首次或依赖变更时，执行后端镜像构建
- 启动/更新：docker compose up -d
- 验证
- docker compose ps 查看状态
- docker compose logs -f backend 查看后端日志
- curl http://localhost:8083/health 进行健康检查
- 访问地址：
- 前端：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083/api/...
- 健康检查：http://服务器 IP:8083/health
**章节来源**
- [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)
### 更新部署
- 仅更新前端
- 本地构建后上传前端 dist，服务器重启前端容器
- 仅更新后端
- 上传后端代码与依赖文件，服务器重新构建并启动后端
- 一键流程
- 本地构建前端并上传，服务器执行后端镜像构建与启动
**章节来源**
- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
### docker-compose.yml 说明
- backend
- env_file: .env 读取根目录环境变量
- environment: 设置 PORT=8000，覆盖容器内端口
- ports: 8083:8000（宿主:容器）
- volumes: 挂载 OTA 存储目录
- **新增**：networks: audio-network 加入自定义网络
- **新增**：extra_hosts: host.docker.internal:host-gateway 支持宿主机访问
- frontend
- image: nginx:alpine
- ports: 8082:80
- volumes: 挂载 dist 目录（只读模式 :ro）
- depends_on: 依赖后端容器
- **新增**：networks: audio-network 加入自定义网络
- **更新**：移除了自定义nginx.conf挂载，使用Nginx默认配置
- 日志轮转
- 每个服务启用 json-file，单文件最大 10MB，最多 5 份
- 网络
- **新增**：使用自定义桥接网络 audio-network，便于容器间通信
- **新增**：网络驱动为 bridge，提供容器间隔离和通信
**章节来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
- [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
### 后端部署文件清单
- 后端镜像构建所需文件
- Dockerfile、package.json、pnpm-lock.yaml、src/
**章节来源**
- [DEPLOY.md:174-187](file://DEPLOY.md#L174-L187)
### 环境变量参考
- 数据库：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)
### 目录结构（服务器）
- /data/project/dashboard/
- .env（服务器维护）
- docker-compose.yml
- backend/
- Dockerfile
- package.json
- pnpm-lock.yaml
- src/
- frontend/
- dist/
- /data/projects/source/（OTA 升级包存储）
**更新**：移除了frontend/nginx.conf文件，前端配置现在完全依赖Nginx默认行为。
**章节来源**
- [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
### 上传脚本使用方法
- 用法与选项
- 目标：frontend（f）、backend（b）、compose（c）、all（a）
- 自定义路径：可传入任意本地路径，映射到服务器对应位置
- 虚拟执行：-n 预览同步范围
- 默认同步范围
- all：包含前端 dist、后端 src、package.json、pnpm-lock.yaml、docker-compose.yml
- 注意事项
- **更新**：默认不同步nginx.conf（已移除）与Dockerfile，需要时需显式指定
- 路径不在项目内会被跳过
- **新增**：脚本经过清理优化，移除了废弃功能代码，提供更简洁的使用体验
**章节来源**
- [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
- [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
### 手动 rsync 上传方式
- 前端
- rsync 前端 dist 至服务器 dist 目录
- **更新**：无需上传nginx.conf文件
- 后端
- rsync backend/src 至服务器 backend/src
- scp backend/Dockerfile、backend/package.json、backend/pnpm-lock.yaml 至服务器 backend/
- Compose
- scp docker-compose.yml 至服务器根目录
**章节来源**
- [DEPLOY.md:77-91](file://DEPLOY.md#L77-L91)
### 构建与启动命令
- 本地
- **更新**：前端使用Vite构建：cd frontend && pnpm install && pnpm build
- 服务器
- 首次或依赖变更：docker compose build --no-cache backend
- 启动/更新：docker compose up -d
- 停止服务
- docker compose down
**章节来源**
- [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)
### 健康检查与服务验证
- 健康检查
- curl http://localhost:8083/health
- 状态与日志
- docker compose ps
- docker compose logs -f backend
- 访问地址
- 前端：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083/api/...
**章节来源**
- [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
### 后端本地脚本（非 Docker）
- start.sh：在本地直接启动后端服务
- restart.sh：停止占用 8083 端口的进程并重启服务
- stop.sh：查找并终止占用 8083 端口的进程
**章节来源**
- [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)
### 前端开发与构建配置
- **更新**：前端开发
- 本地开发使用 Vite，默认端口 3000，/api 代理到后端 8083
- 构建产物输出到 dist 目录
- **更新**：Nginx 配置
- 使用Nginx默认配置，监听 80 端口
- 通过Docker Compose中的location指令实现API代理
- 支持静态资源缓存与上传大小限制
**章节来源**
- [frontend/vite.config.ts:1-50](file://frontend/vite.config.ts#L1-L50)
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
## 依赖关系分析
- 组件耦合
- 前端依赖后端 API，通过 Nginx 代理实现解耦
- 后端依赖数据库、搜索、对象存储、Redis 等外部服务
- 直接与间接依赖
- 后端镜像构建依赖 package.json 与 pnpm-lock.yaml
- **更新**：前端不再需要独立镜像构建，直接使用nginx:alpine镜像
- 外部依赖与集成点
- Docker Compose 管理服务生命周期与网络
- Nginx 作为反向代理与静态资源服务
- **新增**：自定义网络 audio-network 提供容器间通信
```mermaid
graph LR
FE["前端(dist)"] --> NGINX["Nginx 反向代理"]
NGINX --> BE["后端容器(8000)"]
BE --> DB["数据库"]
BE --> MEILI["Meilisearch"]
BE --> S3["S3 对象存储"]
BE --> REDIS["Redis"]
subgraph "Docker 网络 audio-network"
NGINX
BE
end
```
**图表来源**
- [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
**章节来源**
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
## 性能考虑
- 日志轮转
- 每个服务启用 JSON 文件轮转，单文件最大 10MB，最多 5 份，避免日志无限增长
- 静态资源优化
- Nginx 对静态资源进行缓存与压缩，提升前端加载速度
- 端口与网络
- 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
- **更新**：卷挂载优化
- 前端卷挂载使用只读模式 (:ro)，提升安全性和性能
- 后端 OTA 存储卷直接映射宿主机目录，避免额外开销
- **新增**：网络优化
- 自定义桥接网络减少网络延迟
- 容器间通信通过内部网络，不经过宿主机网络栈
**章节来源**
- [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
## 故障排查指南
- 前端页面空白
- 检查 dist 是否上传成功、路径是否正确
- 查看浏览器控制台是否存在 404 或 API 错误
- 查看前端容器日志
- API 请求失败
- 确认后端容器处于 running 状态
- 查看后端日志，定位数据库、Redis、Meilisearch 连接问题
- 确认 Nginx 代理目标为 http://backend:8000
- **新增**：检查容器是否在同一个网络中：`docker network inspect audio-network`
- 后端构建失败（pnpm / Node 版本）
- 后端镜像基于 node:22-alpine，确保上传了 package.json 与 pnpm-lock.yaml
- 修改 .env 后不生效
- 通过 docker compose up -d --force-recreate 使新环境变量生效
- 网络相关问题
- **新增**：检查网络连通性：`docker exec dashboard-frontend ping backend`
- **新增**：查看网络配置：`docker network ls`
- **新增**：检查容器网络：`docker inspect dashboard-backend | grep NetworkMode`
- **更新**：前端构建问题
- 确认Vite构建成功，dist目录存在且包含必要的静态资源
- 检查前端构建日志，确认没有编译错误
- **更新**：上传脚本问题
- 如果上传脚本出现异常，检查SSH连接权限和目标服务器路径
- 使用虚拟执行模式（-n）预览同步范围，确认文件列表正确
- 停止服务
- docker compose down
**章节来源**
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-256)
## 结论
本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。
**更新**：通过移除复杂的前端Dockerfile和nginx.conf配置，采用更简洁的静态资源托管模式，部署流程得到了显著简化。同时，部署脚本upload.sh经过清理优化，移除了废弃功能代码，进一步提升了用户体验。通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面也得到了提升。
## 附录
### 环境变量与安全配置建议
- 生产环境必须替换的敏感项
- JWT_SECRET：强随机密钥，避免使用默认值
- DASHBOARD_ADMIN_PASSWORD：初始管理员密码，部署后立即修改
- 最小权限原则
- S3 通常通过云服务 IAM 角色访问，避免在 .env 中硬编码密钥
- 网络与端口
- 仅开放必要端口，防火墙策略最小化
- **新增**：利用 Docker 网络隔离，避免不必要的端口暴露
- 日志与监控
- 结合日志轮转与容器日志采集，定期巡检
- 配置加载
- 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
- **更新**：卷挂载安全
- 前端静态资源使用只读挂载 (:ro)，防止运行时修改
- 后端数据卷根据业务需求选择合适的挂载模式
- **新增**：构建安全
- 前端使用Vite构建，确保生产环境构建产物不包含开发依赖
- 定期更新前端依赖，修复已知安全漏洞
- **新增**：脚本安全
- 上传脚本经过清理优化，减少了潜在的安全风险点
- 建议使用虚拟执行模式（-n）先预览同步范围，避免误操作
**章节来源**
- [DEPLOY.md:36-42](file://DEPLOY.md#L36-L42)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)
Reference in New Issue View Git Blame Copy Permalink