dashboard/.qoder/repowiki/knowledge/zh/Docker Compose 编排与 rsync 增量部署/Docker Compose 编排与 rsync 增量部署.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
build_system	Docker Compose 编排与 rsync 增量部署	build_system	**	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 容器即可，无需重建镜像。