---
kind: build_system
name: Docker Compose 多阶段构建与脚本化部署
category: build_system
scope:
    - '**'
source_files:
    - docker-compose.yml
    - backend/Dockerfile
    - frontend/Dockerfile
    - scripts/upload.sh
    - frontend/vite.config.js
    - frontend/nginx.conf
    - DEPLOY.md
---

## 构建系统概览

项目采用 pnpm + Vite + Docker Compose 的现代化 Node.js/Vue 3 单体仓库构建方案，通过多阶段 Docker 镜像实现前后端分离部署。

### 核心构建工具链

- 包管理: pnpm@11.5.2（通过 packageManager 字段锁定版本）
- 前端构建: Vite 6.x + Vue 3，支持手动分包（manualChunks）优化
- 后端运行: Node.js 22 Alpine，Express + Sequelize
- 容器编排: Docker Compose，双服务架构（frontend: nginx, backend: node）

### 构建流程

前端构建 (frontend/)：
```bash
cd frontend && pnpm install && pnpm build
# 产物输出至 frontend/dist/
```

Vite 配置关键特性：
- 开发服务器端口 3000，自动代理 /api 到 localhost:8083
- 生产环境启用 Gzip、静态资源长期缓存（1年 immutable）
- 手动分包策略：vendor-vue、vendor-element-plus、vendor-lucide

后端构建 (backend/)：
```bash
cd backend && pnpm install --prod && node src/app.js
```

### Docker 多阶段镜像

后端镜像 (backend/Dockerfile)：
- 基础镜像：node:22-alpine
- 仅安装生产依赖（--frozen-lockfile --prod）
- 暴露端口 8000，启动命令 node src/app.js

前端镜像 (frontend/Dockerfile)：
- 构建阶段：node:18-alpine + pnpm 全局安装
- 运行阶段：nginx:alpine，仅包含静态文件
- 通过 COPY --from=builder 复制构建产物

### 服务编排

docker-compose.yml 定义两个服务：
- backend: 端口映射 8083->8000，挂载 OTA 存储卷 /data/projects/source
- frontend: 端口映射 8082->80，挂载 dist 和 nginx.conf
- 自定义网络 audio-network 实现服务间通信
- 统一日志轮转配置（单文件 10MB，保留 5 个文件）

Nginx 反向代理将 /api 请求转发至 http://backend:8000，支持 Vue Router history 模式和 8MB 文件上传。

### 部署脚本

scripts/upload.sh 提供一键同步能力：
- 预设目标：frontend、backend、compose、all
- 基于 rsync + SSH 密钥认证
- 支持 dry-run 模式预览同步内容
- 默认上传路径：ubuntu@ec2:/data/project/dashboard/

### 环境变量管理

- 开发环境：根目录 .env，通过 dotenv 加载
- 生产环境：Compose env_file 指定 .env，覆盖容器内 PORT=8000
- 敏感信息（JWT_SECRET、数据库密码等）不提交 Git

### 本地开发工作流

```bash
# 后端开发
cd backend && pnpm dev  # nodemon 热重载，端口 8083

# 前端开发
cd frontend && pnpm dev  # Vite 开发服务器，端口 3000
```

### 版本策略

- 前后端均使用 1.0.0 版本号（语义化版本占位）
- 无自动化发布流水线，通过脚本手动触发部署
- 依赖锁定文件（pnpm-lock.yaml）确保构建可重现性

### 注意事项

- 前端 Dockerfile 使用 Node 18，但 packageManager 指定 pnpm@11.5.2，需确保兼容性
- 后端 Dockerfile 使用 Node 22，与 packageManager 版本一致
- OTA 升级包通过宿主机卷持久化，避免容器重启丢失
- 生产环境建议通过 EC2 IAM 角色访问 S3，无需硬编码 AWS 凭证