添加 uipro，更新 wiki

.qoder/repowiki/knowledge/zh/构建与部署体系（Docker Compose + pnpm + Vite）/构建与部署体系（Docker Compose + pnpm + Vite）.md

@@ -0,0 +1,89 @@
+---
+kind: build_system
+name: 构建与部署体系（Docker Compose + pnpm + Vite）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/vite.config.js
+    - scripts/upload.sh
+    - DEPLOY.md
+    - backend/package.json
+    - frontend/package.json
+---
+
+## 1. 使用的系统与方法
+
+- **包管理器**：pnpm@11.5.2，前后端均通过 `packageManager` 字段锁定版本。
+- **前端构建**：Vite 6 + Vue 3，开发端口 3000，生产构建产物输出到 `frontend/dist/`，并通过 Rollup `manualChunks` 将 vue、element-plus 等拆分为独立 chunk。
+- **后端运行**：Express + Sequelize，入口 `backend/src/app.js`，默认监听 8000（容器内），本地开发可通过 `.env` 的 `PORT=8083` 覆盖。
+- **容器编排**：Docker Compose 定义两个服务——`backend`（node:22-alpine）和 `frontend`（nginx:alpine），共享自定义 bridge 网络 `audio-network`。
+- **发布脚本**：`scripts/upload.sh` 基于 rsync+ssh 将前端 dist、后端源码、compose 文件同步至远程服务器 `/data/project/dashboard/`。
+
+## 2. 关键文件与位置
+
+| 类别 | 文件 | 作用 |
+|------|------|------|
+| 编排 | `docker-compose.yml` | 定义 backend/frontend 服务、端口映射、日志轮转、数据卷挂载 |
+| 后端镜像 | `backend/Dockerfile` | node:22-alpine，仅安装 prod 依赖，CMD 启动 `src/app.js` |
+| 前端镜像 | `frontend/Dockerfile` | 多阶段构建：node:18-alpine 构建 → nginx:alpine 托管静态资源 |
+| 前端构建配置 | `frontend/vite.config.js` | 开发代理 `/api→localhost:8083`、chunk 拆分、别名 `@` |
+| 上传脚本 | `scripts/upload.sh` | rsync 推送 frontend/backend/compose 三套预设目标 |
+| 部署文档 | `DEPLOY.md` | 完整的首次部署、增量更新、环境变量说明、目录结构约定 |
+| 后端脚本 | `backend/start.sh / stop.sh / restart.sh` | 非 Docker 场景下的进程启停辅助 |
+
+## 3. 架构与约定
+
+### 3.1 构建流水线
+
+```
+本地开发
+  ├─ frontend/pnpm dev (vite, :3000) → 代理 /api → localhost:8083
+  └─ backend/pnpm start (node src/app.js, :8000 或 .env PORT)
+
+本地构建
+  ├─ pnpm --dir frontend build → frontend/dist/
+  └─ scripts/upload.sh [frontend|backend|compose|all]
+
+服务器部署
+  ├─ docker compose build --no-cache backend   # 首次或依赖变更
+  ├─ docker compose up -d                      # 启动全部服务
+  └─ docker compose restart frontend           # 仅前端热更
+```
+
+- 前端采用**多阶段 Docker 构建**，最终镜像仅包含 nginx + 静态文件，体积最小化。
+- 后端镜像使用 `--frozen-lockfile --prod` 安装，确保构建可重复且不携带 devDependencies。
+- 宿主机通过 volume 挂载 `/data/projects/source` 给后端容器，用于 X9 OTA 升级包本地存储；前端 `dist/` 与 `nginx.conf` 也通过 volume 挂载，避免重建镜像。
+
+### 3.2 端口与环境变量约定
+
+| 组件 | 容器内端口 | 宿主机映射 | 备注 |
+|------|-----------|-----------|------|
+| frontend (nginx) | 80 | 8082 | 反向代理 `/api` 到 `http://backend:8000` |
+| backend (Node) | 8000 | 8083 | 由 Compose 强制覆盖 `PORT=8000` |
+| 本地开发 (vite) | 3000 | — | 通过 proxy 转发 `/api` 到 8083 |
+
+- 所有环境变量统一放在根目录 `.env`，Compose 通过 `env_file` 注入，不再各自维护 `.env`。
+- 敏感信息（JWT_SECRET、数据库密码等）不随 `upload.sh` 上传，需在服务器单独维护。
+
+### 3.3 上传策略
+
+`scripts/upload.sh` 定义了三个预设集合：
+- `frontend`：仅 `frontend/dist/`
+- `backend`：`backend/src/` + `package.json` + `pnpm-lock.yaml`（不含 Dockerfile）
+- `compose`：`docker-compose.yml`
+
+支持 `-n` dry-run 预览、任意路径透传、自动创建远端目录。
+
+## 4. 开发者应遵循的规则
+
+1. **新增依赖**：在对应子模块执行 `pnpm add ...`，确保 `pnpm-lock.yaml` 提交到 Git，以便 `--frozen-lockfile` 构建成功。
+2. **修改前端路由/样式**：直接 `pnpm dev` 本地调试，无需重新构建镜像；生产发布前执行 `pnpm build` 并 `./scripts/upload.sh frontend`。
+3. **修改后端接口**：`./scripts/upload.sh backend` 后在服务器执行 `docker compose build --no-cache backend && docker compose up -d backend`。
+4. **修改 Compose 配置**：`./scripts/upload.sh compose` 后 `docker compose up -d` 即可生效。
+5. **不要**在代码中硬编码端口或路径，一律通过 `.env` 或 Compose `environment` 注入。
+6. **OTA 包存放**：仅通过 volume 挂载的 `/data/projects/source` 写入，不要改动 Dockerfile 中的 COPY 范围。
+7. **本地非 Docker 开发**：先 `cd backend && pnpm start`，再 `cd frontend && pnpm dev`，确保根目录 `.env` 中 `PORT=8083`。