2. 开发环境搭建

数字工地看板项目依赖一套完整的技术栈：后端使用 Python Flask 提供 REST API，前端使用 ECharts 渲染可视化图表，设备数据通过 MQTT 协议实时上报。本节将逐步搭建本地开发环境，确保所有组件正确安装并能够协同工作。

2.1 环境总览与技术选型

下表列出本课程使用的核心工具及其版本要求（以稳定版为准）：

组件	版本要求	用途
Python	≥ 3.9	后端开发语言
Flask	≥ 2.3	Web 框架，提供 API 接口
Node.js	≥ 18 LTS	前端构建与开发服务器
npm	≥ 9	前端包管理器
ECharts	≥ 5.4	数据可视化图表库
Mosquitto	≥ 2.0	MQTT Broker，消息中间件

2.2 Python 虚拟环境配置

虚拟环境用于隔离项目依赖，避免与系统全局 Python 包冲突。推荐使用 Python 内置的 venv 模块。

操作步骤：

1. 打开终端，进入项目根目录（例如 digital-construction-board）。
2. 执行以下命令创建虚拟环境：

python -m venv venv

3. 激活虚拟环境：

# Windows (CMD/PowerShell)
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

4. 验证激活成功：终端提示符前会出现 (venv) 标识。

2.3 Flask 框架安装

在激活的虚拟环境中，使用 pip 安装 Flask 及其常用扩展：

pip install flask flask-cors flask-socketio

参数说明：

• flask：核心 Web 框架。
• flask-cors：解决前后端跨域请求问题。
• flask-socketio：用于后续实现 WebSocket 实时推送（可选，但推荐安装）。

验证安装：

python -c "import flask; print(flask.__version__)"

输出应显示类似 2.3.3 的版本号。

2.4 Node.js 与 npm 安装

Node.js 用于运行前端开发服务器和打包工具。npm 随 Node.js 一同安装。

安装方式：

• 推荐： 从 nodejs.org 下载 LTS 版本安装包，直接安装。
• 包管理器： macOS 可使用 brew install node@18，Linux 可使用 apt install nodejs npm。

验证安装：

node -v
npm -v

输出示例：

v18.20.4
10.7.0

2.5 ECharts 库引入

ECharts 是一个纯 JavaScript 的图表库，我们通过 npm 将其安装到前端项目中。

步骤：

1. 在项目根目录下创建 frontend 文件夹并进入：

mkdir frontend
cd frontend

2. 初始化 npm 项目：

npm init -y

3. 安装 ECharts：

npm install echarts

4. 在 HTML 文件中通过 <script> 标签引入：

<script src="node_modules/echarts/dist/echarts.min.js"></script>

2.6 MQTT Broker (Mosquitto) 安装与配置

Mosquitto 是一个轻量级的开源 MQTT Broker，负责接收工地设备上报的数据并转发给后端服务。

安装命令：

操作系统	安装命令
Windows	下载安装包 mosquitto-2.x.x-install-windows-x64.exe，默认安装即可
macOS	brew install mosquitto
Ubuntu/Debian	sudo apt install mosquitto mosquitto-clients
CentOS/RHEL	sudo yum install mosquitto

基本配置：

Mosquitto 默认配置文件位于 /etc/mosquitto/mosquitto.conf（Linux/macOS）或安装目录下的 mosquitto.conf（Windows）。

创建一个最小配置，允许匿名访问（开发环境使用）：

# 文件: mosquitto.conf
listener 1883
allow_anonymous true

启动服务：

# Linux/macOS
mosquitto -c /etc/mosquitto/mosquitto.conf -d

# Windows (以管理员身份运行CMD)
net start mosquitto

验证 Broker 是否运行：

打开另一个终端，订阅一个测试主题：

mosquitto_sub -h localhost -t "test/topic"

再打开一个终端，发布一条消息：

mosquitto_pub -h localhost -t "test/topic" -m "Hello, Digital Construction!"

如果订阅终端收到消息，则说明 Broker 安装配置成功。

2.7 整体架构与数据流

下图展示了开发环境中各组件之间的通信关系：

2.8 环境验证清单

完成上述所有安装后，请逐项检查确认：

检查项	验证命令 / 方法	预期结果
Python 虚拟环境	which python (Linux/macOS) 或 where python (Windows)	路径指向项目目录下的 venv 文件夹
Flask 安装	python -c "import flask; print(flask.__version__)"	输出 ≥ 2.3
Node.js 安装	node -v	输出 ≥ v18
npm 安装	npm -v	输出 ≥ 9
ECharts 引入	检查 frontend/node_modules/echarts 目录是否存在	目录存在且包含 dist/echarts.min.js
Mosquitto 运行	mosquitto_sub -h localhost -t "test" 无报错	终端等待消息，无连接拒绝错误