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

# 部署指南

<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)