# RemoteBuildSystem

**Repository Path**: deshuofa/remote-build-system

## Basic Information

- **Project Name**: RemoteBuildSystem
- **Description**: 远程编译
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Remote Build System 使用文档

## 📖 项目简介

Remote Build System 是一个**分布式前端编译系统**，通过将编译任务从低配机（主控端）分发到高配机（被控端）执行，解决本地开发热更新缓慢的问题。

### 核心特性

- ✅ 支持 **Vue 2 / Vue 3**（含 Vapor Mode）、**React**、**SolidJS**、**Svelte**
- ✅ 支持 **TypeScript**、**JavaScript**、**SCSS**、**Less**
- ✅ 自动检测文件类型，智能分发到对应环境的被控端
- ✅ 多被控端负载均衡，并行编译
- ✅ 实时状态监控（CPU、内存、任务进度）
- ✅ 跨平台支持（Windows / macOS / Linux）
- ✅ Web 界面管理，操作简单直观

---

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     系统架构图                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐     WebSocket      ┌─────────────────────┐   │
│   │  低配机      │ ◄──────────────► │  高配机 (被控端)     │   │
│   │  (主控端)    │    分发编译任务    │  Worker-1           │   │
│   │              │    返回编译结果    │  Worker-2           │   │
│   │  ┌─────────┐ │                   │  Worker-N           │   │
│   │  │Vite插件 │ │                   └─────────────────────┘   │
│   │  └─────────┘ │                                             │
│   │              │    Web 界面                                  │
│   │  ┌─────────┐ │    http://localhost:5173                    │
│   │  │ Web界面 │ │                                             │
│   │  └─────────┘ │                                             │
│   └─────────────┘                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

| 组件 | 说明 |
|------|------|
| **主控端 (Master)** | 运行在开发机（低配机），提供 Web 界面、任务调度、被控端管理 |
| **被控端 (Worker)** | 运行在高配机，接收编译任务并执行 |
| **Vite 插件** | 集成到 Vite 项目中，拦截文件变更并发送到主控端 |
| **Web 界面** | 实时查看被控端状态、任务进度、CPU/内存折线图 |

---

## 🚀 快速开始

### 前置要求

| 依赖 | 版本要求 |
|------|----------|
| Node.js | >= 18.0.0 |
| pnpm | >= 8.0.0（推荐）或 npm |
| 操作系统 | Windows 10+ / macOS / Linux |

### 下载项目

```bash
git clone <repository-url>
cd RemoteBuildSystem
```

### 安装依赖

```bash
# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install
```

---

## 🔧 被控端配置（高配机）

被控端运行在高配机上，负责接收并执行编译任务。

### 启动被控端

```bash
cd packages/worker

# 启动服务（默认端口 3000）
node src/gui/index.js start

# 指定端口启动
node src/gui/index.js start --port 3001
```

### 被控端 CLI 命令

| 命令 | 说明 |
|------|------|
| `node src/gui/index.js start` | 启动被控端服务 |
| `node src/gui/index.js start --port 3001` | 指定端口启动 |
| `node src/gui/index.js stop` | 停止被控端服务 |
| `node src/gui/index.js status` | 查看被控端状态 |
| `node src/gui/index.js config` | 查看当前配置 |

### 被控端 Web 界面

启动后访问：`http://localhost:3000`

显示内容：
- 已连接的主控端列表
- 各主控端的任务进度
- CPU / 内存使用率折线图
- 悬浮窗开关和透明度控制

---

## 🖥️ 主控端配置（低配机）

主控端运行在开发机（低配机）上，负责调度和分发任务。

### 启动主控端

```bash
cd packages/master

# 启动服务（默认端口 5173）
node src/gui/index.js start

# 指定端口启动
node src/gui/index.js start --port 5174
```

### 主控端 CLI 命令

| 命令 | 说明 |
|------|------|
| `node src/gui/index.js start` | 启动主控端服务 |
| `node src/gui/index.js start --port 5174` | 指定端口启动 |
| `node src/gui/index.js stop` | 停止主控端服务 |
| `node src/gui/index.js status` | 查看主控端状态 |
| `node src/gui/index.js connect ws://IP:PORT` | 连接被控端 |
| `node src/gui/index.js connect ws://IP:PORT -e vue3` | 指定环境连接 |
| `node src/gui/index.js remove <id>` | 移除被控端 |
| `node src/gui/index.js env <id> <env>` | 设置被控端编译环境 |
| `node src/gui/index.js config` | 查看配置 |
| `node src/gui/index.js config -p 5174` | 修改端口 |

### 主控端 Web 界面

启动后访问：`http://localhost:5173`

功能：
- 添加/移除被控端
- 设置每个被控端的编译环境
- 实时查看被控端状态（CPU/内存/任务进度）
- CPU/内存折线图
- 按编译环境统计被控端数量

---

## 🔌 Vite 插件集成

在 Vite 项目中安装插件，自动将编译任务分发到被控端。

### 1. 安装插件

将 `vite-plugin-remote-build.js` 复制到项目根目录，或发布为 npm 包安装。

### 2. 配置 Vite

```javascript
// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import remoteBuild from './vite-plugin-remote-build.js';

export default defineConfig({
  plugins: [
    remoteBuild({
      // 主控端地址
      masterHost: 'localhost',
      masterPort: 5173,
      
      // 是否启用远程编译
      enabled: true,
      
      // 需要远程编译的文件类型
      include: /\.(vue|jsx?|tsx?|svelte|mjs|cjs)$/,
      
      // 排除的文件
      exclude: /node_modules/,
      
      // 主控端不可用时降级本地编译
      fallbackLocal: true,
      
      // 默认编译环境 (vue2/vue3/react/solid/svelte/auto)
      env: 'auto',
      
      // 任务超时时间（毫秒）
      taskTimeout: 30000,
      
      // 是否启用缓存
      enableCache: true,
    }),
    vue(),
  ],
});
```

### 3. 环境变量控制

```javascript
remoteBuild({
  masterHost: process.env.REMOTE_MASTER_HOST || 'localhost',
  masterPort: parseInt(process.env.REMOTE_MASTER_PORT) || 5173,
  enabled: process.env.REMOTE_BUILD !== 'false',
  fallbackLocal: process.env.REMOTE_FALLBACK !== 'false',
})
```

---

## 📋 编译环境说明

### 支持的环境类型

| 环境 | 说明 | 文件类型 |
|------|------|----------|
| `vue2` | Vue 2 | `.vue` |
| `vue3` | Vue 3（含 Vapor Mode） | `.vue` |
| `react` | React | `.jsx`, `.tsx` |
| `solid` | SolidJS | `.jsx`, `.tsx` |
| `svelte` | Svelte | `.svelte` |
| `auto` | 自动检测 | 所有文件 |
| `script` | 普通 JS/TS（esbuild 转译） | `.js`, `.ts`, `.mjs`, `.cjs` |
| `style` | 样式文件（sass/less 编译） | `.scss`, `.sass`, `.less`, `.css` |

### 智能检测规则

| 检测项 | 识别规则 |
|--------|----------|
| Vue 3 | `<script setup>` 或 `<template vapor>` |
| Vue 2 | 普通 `<script>` + `<template>` |
| React | `import react` 或 `useState`/`useEffect` |
| SolidJS | `solid-js` 或 `createSignal`/`createMemo` |
| Vue 宏 | `defineProps`/`defineEmits`/`withDefaults` 等 |
| Vue 运行时 | `ref`/`reactive`/`onMounted`/`watch` 等 |

### 环境匹配规则

1. `.vue` 文件优先使用用户指定的 `vue2`/`vue3` 环境
2. `.js`/`.ts` 文件自动检测是否包含 Vue 宏或模板语法
3. 包含 Vue 宏的文件使用 Vue 编译器，否则使用 esbuild 转译
4. 没有匹配的被控端时自动降级本地编译

---

## 🔧 配置文件

配置文件位于用户目录下：`~/.remote-build/config.json`

### 被控端配置 (`workerPort` 等)

```json
{
  "workerPort": 3000,
  "heartbeatInterval": 3000,
  "cacheMaxSize": 500,
  "cacheTTL": 3600000,
  "taskTimeout": 30000,
  "maxConcurrent": 4
}
```

### 主控端配置 (`masterPort` 等)

```json
{
  "masterPort": 5173,
  "dispatchStrategy": "env-first",
  "autoReconnect": true,
  "fallbackLocal": true,
  "connectTimeout": 10000,
  "retryCount": 2
}
```

### 配置项说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `workerPort` | 被控端监听端口 | 3000 |
| `masterPort` | 主控端监听端口 | 5173 |
| `heartbeatInterval` | 心跳上报间隔（毫秒） | 3000 |
| `cacheMaxSize` | 最大缓存条目数 | 500 |
| `cacheTTL` | 缓存过期时间（毫秒） | 3600000 |
| `taskTimeout` | 任务超时时间（毫秒） | 30000 |
| `maxConcurrent` | 每个主控端最大并发任务数 | 4 |
| `dispatchStrategy` | 调度策略 (`env-first`/`least-load`/`round-robin`) | `env-first` |
| `autoReconnect` | 被控端断开后自动重连 | true |
| `fallbackLocal` | 被控端不可用时降级本地编译 | true |
| `connectTimeout` | 连接被控端超时（毫秒） | 10000 |
| `retryCount` | 任务失败重试次数 | 2 |

---

## 🐛 常见问题

### 1. 主控端无法连接被控端

**检查步骤：**

```bash
# 1. 确认被控端已启动
cd packages/worker
node src/gui/index.js status

# 2. 测试网络连通性
curl http://被控端IP:3000/health

# 3. 检查防火墙是否允许端口访问
```

**常见原因：**
- 被控端未启动
- 端口号输入错误
- 防火墙阻止连接
- 不在同一局域网（需要内网穿透）

### 2. 编译任务超时

**原因：** 文件较大或被控端负载过高

**解决方案：**
- 增加 `taskTimeout` 配置值
- 检查被控端 CPU/内存使用情况
- 减少并发任务数 `maxConcurrent`
- 增加更多被控端分担负载

### 3. Vue 文件编译报错

**原因：** 编译环境设置不正确

**解决方案：**
- 在主控端 Web 界面为被控端设置正确的环境（Vue 2 / Vue 3）
- 对于包含 `<script setup>` 的文件，必须使用 Vue 3 环境
- 检查 Vue 版本是否匹配

### 4. 热更新仍然慢

**检查项：**
- 被控端是否在线（查看主控端 Web 界面）
- 网络延迟是否过高（尽量在同一局域网）
- 是否降级到本地编译（查看主控端日志）
- 被控端 CPU/内存是否充足

### 5. 插件没有触发远程编译

**检查项：**
- `vite.config.js` 中插件是否正确配置
- 主控端是否已启动
- 文件类型是否匹配 `include` 规则
- 是否被 `exclude` 规则排除

### 6. 找不到模块 `commander` 等依赖

**解决方案：**

```bash
# 在项目根目录重新安装依赖
cd D:\java\RemoteBuildSystem
rm -rf node_modules packages/*/node_modules
pnpm install
```

---

## 📊 性能优化建议

### 被控端（高配机）

| 优化项 | 建议 |
|--------|------|
| 并发数 | `maxConcurrent` 设置为 CPU 核心数 |
| 缓存大小 | `cacheMaxSize` 设置为 1000+ |
| 磁盘 | 使用 SSD 存储项目文件 |
| 内存 | 确保有足够内存（建议 8GB+） |

### 主控端（低配机）

| 优化项 | 建议 |
|--------|------|
| 环境设置 | 使用 `auto` 自动检测，减少手动配置 |
| 缓存 | 开启 `enableCache`，减少重复编译 |
| 多被控端 | 连接多台高配机实现负载均衡 |
| 调度策略 | 使用 `env-first` 优先匹配环境 |

### 网络优化

- 主控端和被控端尽量在同一局域网
- 使用有线网络代替 Wi-Fi
- 避免跨运营商网络连接

---

## 📝 开发调试

### 查看日志

被控端日志直接在终端输出，包含：
- 连接/断开事件
- 编译任务接收和执行
- 编译结果和错误信息

主控端日志包含：
- 被控端连接/断开
- 任务分发和结果
- 调度决策信息

### 调试模式

```bash
# 被控端调试模式（输出更详细日志）
node src/gui/index.js start --verbose

# 主控端调试模式
node src/gui/index.js start --verbose
```