更新 wiki

.qoder/repowiki/knowledge/zh/Docker Compose 编排与多阶段构建部署/Docker Compose 编排与多阶段构建部署.md

@@ -0,0 +1,66 @@
+---
+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 并重启服务