ui 优化

2026-07-14 18:56:13 +08:00
parent 4f10cc1648
commit 003b44e2bd
32 changed files with 1082 additions and 375 deletions
@@ -0,0 +1,88 @@
+---
+kind: build_system
+name: 构建与部署体系（Docker Compose + pnpm + rsync）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/vite.config.js
+    - backend/src/config/env.js
+    - scripts/upload.sh
+    - DEPLOY.md
+---
+
+## 1. 构建系统概览
+
+本项目采用 **多阶段 Docker 构建 + Docker Compose 编排** 的容器化部署方案，前端基于 Vite 静态资源构建，后端基于 Node.js 22 Alpine 镜像运行。开发环境通过 pnpm 管理依赖，生产环境通过 `scripts/upload.sh` 将代码同步至远端 EC2 服务器后由 Docker Compose 拉起服务。
+
+- **包管理器**：pnpm@11.5.2（前后端均声明 `packageManager` 字段锁定版本）
+- **前端构建**：Vite 6，产物输出到 `frontend/dist/`，使用 Rollup `manualChunks` 拆分 vendor 包
+- **后端运行**：Node.js 22-alpine，直接执行 `src/app.js`
+- **编排工具**：docker-compose.yml 定义 frontend（nginx:alpine）与 backend 两个服务
+- **发布脚本**：`scripts/upload.sh` 基于 rsync+ssh 增量同步代码到 AWS EC2
+
+## 2. 关键文件与职责
+
+| 文件 | 作用 |
+|------|------|
+| `docker-compose.yml` | 服务编排、端口映射、环境变量注入、日志轮转策略、OTA 数据卷挂载 |
+| `backend/Dockerfile` | 后端镜像构建：仅安装 prod 依赖，暴露 8000 端口 |
+| `frontend/Dockerfile` | 多阶段构建：node:18 构建 → nginx:alpine 托管 dist |
+| `frontend/vite.config.js` | 开发代理 `/api→localhost:8083`、手动分包、别名 `@` |
+| `backend/src/config/env.js` | 统一 APP_ENV 判断（development / production） |
+| `scripts/upload.sh` | 支持 `frontend/backend/compose/all` 目标及 `-n` 干跑模式 |
+| `DEPLOY.md` | 完整部署文档：目录结构、环境变量、更新流程、排错 |
+
+## 3. 架构与约定
+
+### 3.1 服务拓扑
+
+```
+浏览器 :8082 (Nginx) ──/api──▶ 容器内 backend:8000 (Express)
+                              ├── MySQL
+                              ├── Redis (EQ 缓存)
+                              └── S3 (OTA/测量数据)
+```
+
+- 宿主机端口：frontend 8082、backend 8083；容器内端口固定为 80 与 8000
+- 前端通过 Nginx 反向代理 `/api` 到 `http://backend:8000`
+- OTA 升级包通过宿主机卷 `/data/projects/source` 持久化
+
+### 3.2 构建流水线
+
+1. **本地开发**：`pnpm dev`（Vite 热重载，代理 API 到 8083）
+2. **本地构建**：`pnpm build` → 生成 `frontend/dist/`
+3. **上传**：`./scripts/upload.sh all` → rsync 同步 dist、backend/src、compose 到服务器
+4. **服务器部署**：`docker compose build --no-cache backend && docker compose up -d`
+
+### 3.3 环境变量策略
+
+- 所有配置集中在根目录 `.env`，Compose 通过 `env_file` 注入
+- 后端通过 `APP_ENV` 区分 development/production，影响日志、数据库等配置
+- `.env` 不被 Git 跟踪，也不被 `upload.sh` 上传，需在服务器单独维护
+
+### 3.4 镜像优化
+
+- 后端仅拷贝 `package.json`、`pnpm-lock.yaml`、`src/`，不拷贝测试/文档
+- 使用 `--frozen-lockfile` 确保依赖可重现
+- 前端多阶段构建，最终镜像仅包含静态资源与 Nginx
+
+## 4. 开发者应遵循的规则
+
+1. **依赖锁定**：修改 `package.json` 后必须重新生成 `pnpm-lock.yaml`，否则 Docker 构建会失败
+2. **环境变量**：新增配置需同步更新 `.env.example` 和 `DEPLOY.md` 的环境变量表
+3. **端口约定**：容器内后端固定 8000，不要随意修改，否则 Nginx 代理与健康检查会失效
+4. **OTA 存储路径**：后端读取的 OTA 包目录 `/data/projects/source` 必须在宿主机存在且对容器可写
+5. **上传范围**：默认不同步 `nginx.conf` 与 `Dockerfile`，如需变更请显式指定路径
+6. **重启策略**：修改 `.env` 后需 `docker compose up -d --force-recreate backend` 才能生效
+7. **日志查看**：使用 `docker compose logs -f backend` 或 `docker compose logs -f frontend`
+
+## 5. 未覆盖的领域
+
+- 无 CI/CD 流水线（GitHub Actions / GitLab CI 等），部署完全依赖本地脚本
+- 无 Makefile、Gradle、Maven 等传统构建工具
+- 无自动化测试脚本集成到构建流程
+- 版本号管理停留在 `package.json` 的 `version` 字段，无语义化版本发布流程