dashboard/.qoder/repowiki/knowledge/zh/Docker Compose 多阶段构建与脚本化部署/Docker Compose 多阶段构建与脚本化部署.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
build_system	Docker Compose 多阶段构建与脚本化部署	build_system	**	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/)：

cd frontend && pnpm install && pnpm build
# 产物输出至 frontend/dist/

Vite 配置关键特性：

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

后端构建 (backend/)：

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

本地开发工作流

# 后端开发
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 凭证