# DashboardGenerator 本地部署环境要求

> 适用版本: v4.0+
> 更新时间: 2026-05-07

---

## 一、DashboardGenerator.exe（编辑器主程序）

主程序 DashboardGenerator.exe 使用 pkg 打包，**Node.js 运行时已内嵌**，无需额外安装。

| 要求 | 说明 |
|------|------|
| 操作系统 | Windows 10/11 x64，Windows Server 2016+ |
| 内存 | 最低 2GB，推荐 4GB+ |
| 磁盘 | 100MB（程序本身），实际随项目数据增长 |
| 端口 | 3002（编辑器服务端口，默认） |
| 数据库 | PostgreSQL（自动连接默认数据库，也可自行配置） |
| 浏览器 | Chrome 90+ / Edge 90+ / Firefox 88+（用于访问编辑器界面） |

**启动方式**: 双击 `DashboardGenerator.exe`，浏览器打开 `http://localhost:3002`。

---

## 二、导出项目（用户生成的看板）

用户在 DashboardGenerator 编辑器导出的项目是一个完整的 **Node.js 前后端项目**，需要在目标服务器上安装 Node.js 运行环境。

### 2.1 导出项目结构

```
导出目录/
├── index.html          # 看板前端页面
├── server.js           # 后端服务（Express + Socket.IO）
├── package.json        # 依赖配置
├── interface.md        # 数据推送接口文档
├── test-client.html    # 测试客户端
├── README.md           # 说明文档
├── device/             # 设备图片资源
└── 3Dmodel/            # 3D模型文件（如有3D控件）
```

### 2.2 Node.js 安装

#### 下载地址

Node.js 官方网站: **https://nodejs.org**

#### 版本选择

| 版本类型 | 推荐场景 | 当前推荐版本 |
|----------|----------|-------------|
| **LTS（长期支持）** | 生产部署，稳定优先 | **Node.js 20.x LTS** |
| Current | 尝鲜体验 | Node.js 22.x |

> 导出项目依赖 express ^4.18 和 socket.io ^4.7，Node.js 18+ 即可运行。推荐使用 Node.js 20 LTS，支持周期最长。

#### Windows 安装步骤

1. 打开 https://nodejs.org
2. 点击左侧绿色 **LTS** 按钮下载安装包（`.msi` 文件）
3. 双击运行安装包，一路 **Next** 默认安装即可
4. **务必勾选** "Automatically install the necessary tools"（自动安装编译工具，某些 npm 包需要）
5. 安装完成后，打开 **命令提示符** 或 **PowerShell**，验证安装:

```bash
node --version   # 应显示 v20.x.x
npm --version    # 应显示 10.x.x
```

#### Linux (Ubuntu/Debian) 安装

```bash
# 使用 NodeSource 官方源安装 Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version
npm --version
```

#### Linux (CentOS/RHEL) 安装

```bash
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
```

### 2.3 启动导出项目

```bash
# 1. 进入导出目录
cd 导出目录

# 2. 安装依赖（首次运行）
npm install

# 3. 启动服务
npm start
```

启动后默认监听 **端口 3000**，浏览器访问 `http://localhost:3000`。

### 2.4 导出项目依赖列表

| 依赖 | 版本 | 用途 |
|------|------|------|
| express | ^4.18.2 | Web 服务框架 |
| socket.io | ^4.7.4 | WebSocket 实时数据推送 |
| cors | ^2.8.5 | 跨域请求处理 |

---

## 三、端口说明

| 端口 | 服务 | 说明 |
|------|------|------|
| 3002 | DashboardGenerator 编辑器 | 主程序默认端口，可在 .env 中修改 |
| 3000 | 导出的看板项目 | 生成的项目默认端口，可在 server.js 中修改 |

> 如果端口被占用，启动时会报错 `EADDRINUSE`，请修改端口号或关闭占用程序。

---

## 四、常见问题

### Q1: 双击 exe 提示缺少 VCRUNTIME140.dll

**原因**: 缺少 Visual C++ 运行库。

**解决**: 下载安装 [Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe) (微软官方)。

### Q2: npm install 报错或卡住

**原因**: 网络问题或 npm 源慢。

**解决**: 设置国内镜像源:

```bash
npm config set registry https://registry.npmmirror.com
```

### Q3: 端口被占用

**解决**: 修改 `server.js` 中的 `PORT` 变量，或修改 `.env` 中的 `PORT` 值。

### Q4: 能否部署到云服务器

可以。将导出目录整体上传到云服务器，安装 Node.js 后执行 `npm install && npm start` 即可。推荐使用 `pm2` 进行进程守护:

```bash
npm install -g pm2
pm2 start server.js --name "dashboard"
pm2 save
pm2 startup
```

---

## 五、运行环境速查表

| | DashboardGenerator.exe（编辑器） | 导出项目（看板） |
|------|------|------|
| OS | Windows 10/11 x64 | Windows / Linux / macOS |
| Node.js | 不需要（已内嵌） | **需要 Node.js 18+（推荐 20 LTS）** |
| npm | 不需要 | 需要（随 Node.js 安装） |
| 数据库 | PostgreSQL（自动连接） | 不需要 |
| 浏览器 | Chrome/Edge/Firefox | Chrome/Edge/Firefox |
| 端口 | 3002 | 3000 |