更新 wiki

.qoder/repowiki/knowledge/zh/构建与部署系统（Docker Compose + pnpm_Vite）/构建与部署系统（Docker Compose + pnpm_Vite）.md

@@ -0,0 +1,60 @@
+---
+kind: build_system
+name: 构建与部署系统（Docker Compose + pnpm/Vite）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/vite.config.ts
+    - frontend/package.json
+    - backend/package.json
+    - scripts/upload.sh
+    - DEPLOY.md
+---
+
+## 1. 构建系统与工具链
+
+- **包管理器**：pnpm（根目录 `.pnpm-store`，前后端各自 `package.json` + `pnpm-lock.yaml`），后端固定 `packageManager: pnpm@11.5.2`。
+- **前端构建**：Vite 8，通过 `frontend/package.json` 的 `build`/`dev`/`build:test` 脚本驱动；TypeScript + Vue3 + UnoCSS + SCSS。
+- **后端运行**：Node.js 22 Alpine 镜像，直接 `node src/app.js`，开发使用 nodemon。
+- **容器编排**：docker-compose.yml 定义两个服务——`backend`（Node API，端口 8000）和 `frontend`（nginx:alpine 静态托管，端口 80）。
+
+## 2. 关键文件与职责
+
+- `docker-compose.yml`：编排 frontend/nginx 与 backend/node 服务、网络、日志轮转、卷挂载。
+- `backend/Dockerfile`：基于 node:22-alpine，仅拷贝 package.json/pnpm-lock.yaml/src，生产依赖安装。
+- `frontend/vite.config.ts`：Vite 配置入口，加载 `.env` 模式、别名、SCSS 全局注入、代理、sourcemap 开关。
+- `frontend/package.json`：前端脚本：`build`(prod)、`build:test`、`dev`、`lint`、`typecheck`、`release` 等。
+- `backend/package.json`：后端脚本：`start`、`dev`，声明 express/sequelize/mysql2/ioredis/winston 等依赖。
+- `scripts/upload.sh`：本地到 EC2 的 rsync 发布脚本，支持 `frontend`/`backend`/`compose`/`all` 目标与 `-n` 预览。
+- `DEPLOY.md`：完整部署手册：首次部署、更新流程、环境变量、目录结构、常见问题。
+- `backend/start.sh` / `restart.sh` / `stop.sh`：非 Docker 环境下的进程管理辅助脚本。
+
+## 3. 架构与约定
+
+### 多阶段构建策略
+- 前端在本地或 CI 执行 `pnpm build --mode prod`，产出 `frontend/dist/`；服务器只挂载该目录到 nginx，不构建前端镜像。
+- 后端每次代码变更都触发 `docker compose build --no-cache backend`，由 Dockerfile 内 `pnpm install --frozen-lockfile --prod` 锁定依赖版本。
+
+### 环境变量与环境隔离
+- 统一使用项目根 `.env`，Compose 通过 `env_file` 注入；容器内后端固定 `PORT=8000`，与 Nginx proxy_pass 一致。
+- 前端通过 Vite `loadEnv(mode)` 按 `--mode prod|test` 加载不同 `.env.*`，并暴露 `VITE_BASE_URL`、`VITE_SOURCE_MAP` 等构建期常量。
+
+### 存储与持久化
+- OTA 升级包：宿主机 `/data/projects/source` 以卷形式挂载到后端容器，供 X9 设备固件上传/下载。
+- 前端 dist 与 nginx.conf 也通过卷挂载，便于单独更新前端而不重建镜像。
+
+### 发布流水线
+本地 pnpm build (frontend) → scripts/upload.sh [frontend|backend|compose|all] → rsync 到 ubuntu@EC2:/data/project/dashboard/ → docker compose build --no-cache backend → docker compose up -d。脚本默认排除 `nginx.conf` 与 `Dockerfile`，需显式指定；`.env` 永远不在 Git 中提交，需在服务器单独维护。
+
+## 4. 开发者应遵循的规则
+
+1. 新增依赖：在后端 `backend/package.json` 中添加，提交后必须同步 `pnpm-lock.yaml`，否则 Docker 构建会失败。
+2. 修改前端构建产物：先 `cd frontend && pnpm build`，再调用 `./scripts/upload.sh frontend`，不要直接上传源码。
+3. 修改后端代码：只需 `./scripts/upload.sh backend`，服务器会自动重建 Node 镜像。
+4. 修改 Compose/Nginx 配置：通过 `./scripts/upload.sh compose` 或手动 scp 对应文件，然后 `docker compose up -d`。
+5. 环境变量：仅在服务器 `/data/project/dashboard/.env` 中编辑，不要放入 Git；修改后需 `--force-recreate` 重启容器。
+6. 端口约定：容器内后端固定 8000，Nginx 代理到此端口；宿主机对外暴露 8082(前端)/8083(后端)，勿随意改动。
+7. 日志：所有服务启用 json-file 驱动，单文件 10MB、最多 5 个，避免磁盘写满。