---
kind: build_system
name: Docker Compose 编排与多阶段构建部署
category: build_system
scope:
    - '**'
source_files:
    - 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 并重启服务