dashboard/.qoder/repowiki/zh/content/部署与运维/部署指南.md

部署指南

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

更新摘要

变更内容

• 移除了前端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镜像挂载静态资源。

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

章节来源

• docker-compose.yml:1-48
• DEPLOY.md:1-16

核心组件

• 后端服务（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
• scripts/upload.sh:1-191
• backend/src/config/env.js:1-13
• backend/src/config/loadEnv.js:1-14
• backend/src/utils/jwt.js:1-27

架构总览

• 前端通过 Nginx 将 /api 代理到后端容器的 8000 端口。
• 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
• 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
• Docker Compose 控制服务生命周期与网络隔离。
• 更新：前端不再需要独立构建镜像，直接使用官方nginx:alpine镜像。

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

章节来源

• DEPLOY.md:5-16
• docker-compose.yml:7-46

详细组件分析

首次部署（服务器准备）

• 创建目录
  • 前端 dist 目录：用于存放构建产物
  • OTA 升级包存储目录：用于本地存储 X9 升级包
• 配置环境变量
  • 在服务器根目录创建 .env，内容参考项目根目录 .env.example
  • 关键点：PORT=8000（容器内固定）、JWT_SECRET、DASHBOARD_ADMIN_PASSWORD、数据库、搜索、S3、Redis、OTA 等参数
  • .env 不会被上传脚本自动上传，需在服务器单独维护
• 上传代码并启动
  • 参考"本地构建 + 上传"章节

章节来源

• DEPLOY.md:18-46

本地构建 + 上传（推荐）

• 前端构建
  • 更新：使用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
• scripts/upload.sh:39-75
• scripts/upload.sh:142-187
• frontend/vite.config.ts:1-50

更新部署

• 仅更新前端
  • 本地构建后上传前端 dist，服务器重启前端容器
• 仅更新后端
  • 上传后端代码与依赖文件，服务器重新构建并启动后端
• 一键流程
  • 本地构建前端并上传，服务器执行后端镜像构建与启动

章节来源

• DEPLOY.md:122-154

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
• DEPLOY.md:157-171

后端部署文件清单

• 后端镜像构建所需文件
  • Dockerfile、package.json、pnpm-lock.yaml、src/

章节来源

• DEPLOY.md:174-187

环境变量参考

• 数据库：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

目录结构（服务器）

• /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

上传脚本使用方法

• 用法与选项
  • 目标：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
• scripts/upload.sh:142-187

手动 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

构建与启动命令

• 本地
  • 更新：前端使用Vite构建：cd frontend && pnpm install && pnpm build
• 服务器
  • 首次或依赖变更：docker compose build --no-cache backend
  • 启动/更新：docker compose up -d
• 停止服务
  • docker compose down

章节来源

• DEPLOY.md:92-103
• DEPLOY.md:251-256
• frontend/vite.config.ts:1-50

健康检查与服务验证

• 健康检查
  • 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

后端本地脚本（非 Docker）

• start.sh：在本地直接启动后端服务
• restart.sh：停止占用 8083 端口的进程并重启服务
• stop.sh：查找并终止占用 8083 端口的进程

章节来源

• backend/start.sh:1-5
• backend/restart.sh:1-43
• backend/stop.sh:1-14

前端开发与构建配置

• 更新：前端开发
  • 本地开发使用 Vite，默认端口 3000，/api 代理到后端 8083
  • 构建产物输出到 dist 目录
• 更新：Nginx 配置
  • 使用Nginx默认配置，监听 80 端口
  • 通过Docker Compose中的location指令实现API代理
  • 支持静态资源缓存与上传大小限制

章节来源

• frontend/vite.config.ts:1-50
• docker-compose.yml:7-46

依赖关系分析

• 组件耦合
  • 前端依赖后端 API，通过 Nginx 代理实现解耦
  • 后端依赖数据库、搜索、对象存储、Redis 等外部服务
• 直接与间接依赖
  • 后端镜像构建依赖 package.json 与 pnpm-lock.yaml
  • 更新：前端不再需要独立镜像构建，直接使用nginx:alpine镜像
• 外部依赖与集成点
  • Docker Compose 管理服务生命周期与网络
  • Nginx 作为反向代理与静态资源服务
  • 新增：自定义网络 audio-network 提供容器间通信

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

章节来源

• backend/package.json:1-29
• frontend/package.json:1-24

性能考虑

• 日志轮转
  • 每个服务启用 JSON 文件轮转，单文件最大 10MB，最多 5 份，避免日志无限增长
• 静态资源优化
  • Nginx 对静态资源进行缓存与压缩，提升前端加载速度
• 端口与网络
  • 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
• 更新：卷挂载优化
  • 前端卷挂载使用只读模式 (:ro)，提升安全性和性能
  • 后端 OTA 存储卷直接映射宿主机目录，避免额外开销
• 新增：网络优化
  • 自定义桥接网络减少网络延迟
  • 容器间通信通过内部网络，不经过宿主机网络栈

章节来源

• docker-compose.yml:1-5

故障排查指南

• 前端页面空白
  • 检查 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

结论

本指南提供了从服务器准备、目录与环境配置、本地构建与上传、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
• backend/src/config/env.js:1-13
• backend/src/utils/jwt.js:1-27