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 DEPLOY.md backend/package.json frontend/package.json frontend/vite.config.js frontend_v2/package.json

构建系统概览

本项目采用 Docker Compose 作为统一的编排与部署方案，将前端（Nginx 静态站点）与后端（Node.js API）打包为两个容器服务，通过 .env 文件集中注入运行时配置。

核心工具链

• 包管理: pnpm v11.5.2（通过 packageManager 字段锁定版本）
• 前端构建: Vite 6 + Vue3，输出到 frontend/dist/
• 后端运行: Node.js 22 Alpine 镜像，直接执行 src/app.js
• 容器编排: docker-compose.yml 定义 backend、frontend 两个服务
• 部署脚本: scripts/upload.sh 基于 rsync 同步代码到远程服务器

构建流程

前端（frontend）：

• 本地 pnpm build 生成静态资源至 dist/
• Dockerfile 使用多阶段构建：node:18-alpine 构建 → nginx:alpine 托管
• 生产环境通过 Nginx 提供静态文件，并将 /api 反向代理到后端

后端（backend）：

• Dockerfile 基于 node:22-alpine，仅安装 --prod 依赖
• 入口为 src/app.js，监听端口 8000（由 compose 覆盖）
• 支持本地开发 pnpm dev（nodemon 热重载）

前端_v2（Soybean Admin 模板）：

• 独立的 pnpm workspace 工程，包含 packages/ 共享模块
• 使用 TypeScript + UnoCSS + NaiveUI，构建命令 vite build --mode prod
• 当前未集成到主部署流程，属于独立演进分支

部署架构

客户端 → Nginx(8082) → /api → backend:8000 (Node.js) ↘ 静态文件 ← frontend/dist/

环境变量统一通过根目录 .env 注入（数据库、JWT、S3、Redis、OTA 等） OTA 升级包通过卷挂载 /data/projects/source 持久化 日志使用 json-file 驱动，限制单文件 10MB、最多 5 个文件

发布流程

1. 本地构建前端：cd frontend && pnpm build
2. 上传代码：./scripts/upload.sh all（rsync 同步 dist、src、compose）
3. 服务器构建并启动：docker compose build --no-cache backend && docker compose up -d

也可分别更新：仅前端 restart frontend，仅后端 build backend && up backend。

开发者约定

• 所有构建产物不提交 Git（dist/、node_modules/ 在 .gitignore）
• 依赖锁定文件 pnpm-lock.yaml 必须随源码一起上传
• 环境变量 .env 仅在服务器维护，不纳入版本控制
• 修改 compose 后需重新上传 docker-compose.yml 并重启服务