---
kind: build_system
name: Docker Compose 编排与 rsync 增量部署
category: build_system
scope:
    - '**'
source_files:
    - docker-compose.yml
    - backend/Dockerfile
    - frontend/Dockerfile
    - frontend/nginx.conf
    - scripts/upload.sh
    - DEPLOY.md
    - backend/package.json
    - frontend/package.json
---

## 1. 构建系统与工具链
项目采用 **Docker Compose** 作为核心编排工具，结合 **pnpm** 进行依赖管理。整体架构分为前端（Vue 3 + Vite）和后端（Node.js + Express）两个独立服务。

- **包管理器**：前后端均使用 `pnpm`，并在 `package.json` 中通过 `packageManager` 字段锁定版本（`pnpm@11.5.2`），确保环境一致性。
- **前端构建**：使用 `Vite` 进行编译打包，产物输出至 `frontend/dist`。
- **后端运行**：基于 `node:22-alpine` 镜像，直接运行 `src/app.js`。

## 2. 容器化策略
### 后端 (backend/Dockerfile)
- **基础镜像**：`node:22-alpine`。
- **构建逻辑**：采用单层结构，先安装生产依赖（`pnpm install --prod`），再拷贝源码。
- **端口**：容器内固定监听 `8000` 端口。

### 前端 (frontend/Dockerfile & docker-compose.yml)
- **混合模式**：虽然提供了多阶段构建的 `Dockerfile`（Builder -> Nginx），但在生产环境的 `docker-compose.yml` 中，前端服务直接使用官方 `nginx:alpine` 镜像。
- **挂载部署**：通过 Volume 将宿主机的 `frontend/dist` 和 `nginx.conf` 挂载到容器中。这种方式避免了每次前端更新都重新构建 Docker 镜像，提升了部署效率。
- **反向代理**：Nginx 配置了 `/api` 路径的反向代理，将请求转发至 `http://backend:8000`，解决了跨域问题并统一了入口。

## 3. 部署流程与自动化
项目实现了一套基于 **rsync** 的半自动化部署方案，核心脚本为 `scripts/upload.sh`。

### 部署步骤
1. **本地构建**：在本地执行 `pnpm build` 生成前端静态资源。
2. **代码同步**：运行 `./scripts/upload.sh all`，通过 SSH/rsync 将前端产物、后端源码及 `docker-compose.yml` 同步至远程服务器（默认路径 `/data/project/dashboard`）。
3. **远程启动**：在服务器上执行 `docker compose build --no-cache backend` 和 `docker compose up -d` 完成服务重启。

### 关键约定
- **环境变量**：所有配置统一由根目录的 `.env` 文件管理，并通过 `env_file` 注入后端容器。`.env` 文件不随脚本上传，需在服务器手动维护。
- **日志管理**：Compose 文件中定义了 `json-file` 驱动，限制日志最大大小为 10MB，保留 5 个文件，防止磁盘爆满。
- **OTA 存储**：通过 Volume 将宿主机的 `/data/projects/source` 映射到后端容器，用于存储大型 OTA 升级包。

## 4. 开发者规范
- **端口映射**：本地开发时后端默认使用 `8083`，而容器内固定为 `8000`。开发者需注意 `PORT` 环境变量在不同环境下的覆盖逻辑。
- **依赖更新**：若修改了 `package.json`，必须同步更新 `pnpm-lock.yaml` 并重新上传后端相关文件，否则 Docker 构建可能失败或使用旧依赖。
- **前端更新**：仅更新前端时，只需重新构建并同步 `dist` 目录，然后重启 `frontend` 容器即可，无需重建镜像。