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

部署指南

**本文引用的文件** - [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/package.json](file://frontend/package.json) - [frontend/vite.config.js](file://frontend/vite.config.js)

更新摘要

变更内容

• 更新了Docker Compose配置说明，突出网络和卷挂载优化
• 增强了前后端服务连接稳定性的配置细节
• 添加了网络隔离和容器间通信的配置说明
• 完善了卷挂载的安全性和性能考虑

目录

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

简介

本指南面向首次部署、本地构建上传以及后续更新部署的全流程操作，覆盖服务器准备工作、目录结构创建、环境变量配置、Docker Compose 配置说明、服务端口映射与网络设置、上传脚本使用方法、手动 rsync 方式、构建与启动命令、健康检查与服务验证、常见部署问题解决方案，以及生产环境安全配置建议与最佳实践。

项目结构

• 前端采用 Nginx 静态托管，后端为 Node.js API，通过 Docker Compose 统一编排。
• 前端静态资源挂载至 Nginx 容器，Nginx 将 /api 代理到后端容器。
• 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
• 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
• 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
• 新增：使用自定义桥接网络 audio-network 确保容器间通信的稳定性和安全性。

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
• frontend/nginx.conf:11-21

章节来源

• 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.conf。
  • Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
  • 支持静态资源缓存与上传大小限制。
  • 新增：卷挂载使用只读模式 (:ro) 提升安全性。
• 上传脚本（upload.sh）
  • 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
  • 提供虚拟执行（-n）预览能力，便于确认同步范围。
• 环境变量与配置
  • 根目录 .env 由 Docker Compose 注入后端容器，前端通过 Nginx 挂载配置。
  • 后端支持通过 APP_ENV 切换开发/生产环境行为。
  • JWT 密钥、管理员密码等敏感信息需在生产环境强制替换。

章节来源

• backend/Dockerfile:1-20
• frontend/Dockerfile:1-32
• scripts/upload.sh:1-191
• frontend/nginx.conf:1-34
• 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 控制服务生命周期与网络隔离。
• 新增：所有服务加入自定义桥接网络 audio-network，确保容器间通信的稳定性和安全性。

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
• frontend/nginx.conf:11-21

章节来源

• 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

本地构建 + 上传（推荐）

• 前端构建
  • 在 frontend 目录执行安装与构建，产物输出至 dist
• 上传到服务器
  • 使用上传脚本（推荐）：支持 all、frontend、backend、compose 等目标
  • 支持自定义路径上传，如单独上传 nginx.conf 或 Dockerfile
  • 虚拟执行（-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

更新部署

• 仅更新前端
  • 本地构建后上传前端 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 与 nginx.conf（只读模式 :ro）
  • depends_on: 依赖后端容器
  • 新增：networks: audio-network 加入自定义网络
• 日志轮转
  • 每个服务启用 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/
    • nginx.conf
• /data/projects/source/（OTA 升级包存储）

章节来源

• 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 目录
  • scp 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

构建与启动命令

• 本地
  • 前端：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

健康检查与服务验证

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

前端开发与 Nginx 配置

• 前端开发
  • 本地开发使用 Vite，默认端口 3000，/api 代理到后端 8083
• Nginx 配置
  • 监听 80，将 /api 代理到后端容器 8000
  • 支持静态资源缓存与上传大小限制

章节来源

• frontend/vite.config.js:17-25
• frontend/nginx.conf:11-21

依赖关系分析

• 组件耦合
  • 前端依赖后端 API，通过 Nginx 代理实现解耦
  • 后端依赖数据库、搜索、对象存储、Redis 等外部服务
• 直接与间接依赖
  • 后端镜像构建依赖 package.json 与 pnpm-lock.yaml
  • 前端镜像构建依赖 package.json 与 pnpm-lock.yaml
• 外部依赖与集成点
  • 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
• frontend/nginx.conf:11-21

章节来源

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

性能考虑

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

章节来源

• docker-compose.yml:1-5
• frontend/nginx.conf:7-32

故障排查指南

• 前端页面空白
  • 检查 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
• 停止服务
  • docker compose down

章节来源

• DEPLOY.md:226-256

结论

本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。

新增：通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面得到了显著提升。

附录

环境变量与安全配置建议

• 生产环境必须替换的敏感项
  • JWT_SECRET：强随机密钥，避免使用默认值
  • DASHBOARD_ADMIN_PASSWORD：初始管理员密码，部署后立即修改
• 最小权限原则
  • S3 通常通过云服务 IAM 角色访问，避免在 .env 中硬编码密钥
• 网络与端口
  • 仅开放必要端口，防火墙策略最小化
  • 新增：利用 Docker 网络隔离，避免不必要的端口暴露
• 日志与监控
  • 结合日志轮转与容器日志采集，定期巡检
• 配置加载
  • 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
• 新增：卷挂载安全
  • 前端静态资源使用只读挂载 (:ro)，防止运行时修改
  • 后端数据卷根据业务需求选择合适的挂载模式

章节来源

• DEPLOY.md:36-42
• backend/src/config/env.js:1-13
• backend/src/utils/jwt.js:1-27