確認 VUE_APP_MQTT_SERVER_URL 設定正確（開發環境 ws://localhost:8083/mqtt）確認內建 Broker 已啟動（server.broker.enabled: true + server.broker.websocket-port: 8083）檢查 Token 是否有效（mqttTool 用 Token 作為 MQTT password）

物聯網系統

Q: npm install 後啟動報 patch-package 相關錯誤？

原因：node_modules 未完整安裝或快取問題。 # 清除快取重裝 rm -rf node_modules package-lock.json npm cache clean --force npm install

Q: 開發環境介面 404？

檢查 .env.development 中 VUE_APP_SERVER_API_URL 是否正確指向後端，並確認後端已啟動。

Q: Element UI 彈出視窗（MessageBox）無法彈出？

確認元件已全域註冊，專案中透過 Vue.use(Element) 在 main.js 中完成註冊，不需要單獨引入。

Q: vue-treeselect 出現版本衝突？

專案中統一使用 @riophae/vue-treeselect@0.4.0，不要混用其他版本。

Q: vue-qr 元件匯入報錯？

// ✅ 正確方式（預設匯入） import vueQr from 'vue-qr'; // ❌ 錯誤方式（具名匯入會失敗） import { VueQr } from 'vue-qr';

Q: 啟動報 license 相關錯誤？

在 application-dev.yml 中設定正確的憑證路徑： license: subject: common licensePath: classpath:license.lic 向官方申請憑證檔案（license.lic）放入 resources 目錄。

Q: TDengine 報連線逾時？

確認 TDengine 已啟動（預設連接埠 6041） 檢查 application-dev.yml 中 taos 資料來源設定 如不需要時序資料庫，可將 taos.enabled: false 略過

Q: 設備上線但後台看不到線上狀態？

檢查 MQTT 認證（EMQX Webhook 設定） 確認設備 serialNumber 與系統錄入一致 查看後端日誌是否有設備狀態處理記錄

FastBee物聯網平台是一個功能豐富的物聯網解決方案，專為中小企業和個人使用者設計。該平台透過提供一系列易於使用的工具和功能，讓使用者能夠有效地管理和控制各種智慧設備。以下是對FastBee物聯網平台的詳細介紹：

頁面導讀

頁面內容FastBee 物聯網平台的整體介紹：專案背景、系統功能、技術堆疊、應用場景與系統架構。

適用場景適合初次了解商業版平台能力與架構的讀者，建立對產品的整體認知。

前置條件無；後續可依建議路徑繼續閱讀架構設計與安裝部署章節。

版本對比

FastBee 提供開源版、商業版、叢集版三個版本，核心差異如下；完整授權政策與逐項功能清單見商用授權。

維度	開源版	商業版	叢集版
授權協議	AGPL v3，免費、限非商業用途	永久商業授權（安裝憑證）	永久商業授權（安裝憑證）
原始碼與更新	原始碼公開，Gitee/GitHub 更新	授權後經 Git 私服更新，贈送一年原始碼更新	同商業版
部署形態	Docker Compose 單機一鍵部署	單機部署（支援 Docker Compose 快速安裝）	FMQ 服務叢集 + Web 叢集，搭配 Kafka 與負載平衡實現高可用性
接入協定	MQTT、GB/T 28181（僅直播）	增加 TCP、UDP、CoAP、HTTP、Modbus、JT808 等協定	與商業版相同
功能範圍	產品/設備/物模型、規則指令碼、權限管理等核心能力	增加視覺化大螢幕、告警中心、多租戶、OTA 韌體升級、資料橋接、工單管理、物聯卡管理等（Web 組態、智慧音箱為可選配模組）	與商業版功能相同，支援設備量不同
適用場景	個人學習與非商業使用	中小企業商業專案	設備接入規模大、要求高可用性的商業專案

一、平台簡介

專案背景：原名為物美智慧（wumei-smart），後更名為蜂信物聯（FastBee）。這一變更不僅反映了品牌的更新，也標誌著其在物聯網領域的發展和服務範圍的擴展。
主要支援：平台後端採用Spring Boot框架，前端使用Vue技術等，這些技術的選擇確保了平台的易用性和良好的使用者體驗。

二、系統功能

產品管理：支援產品詳情、物模型、分類及設備授權等功能，有助於企業更好地組織和管理其智慧產品。
設備管理：提供設備詳情、分組、日誌記錄、即時狀態監控等管理功能，確保設備運作的高效與安全。
物模型管理：允許定義設備的屬性、功能和事件，實現設備與雲端的有效互動。
規則引擎：支援基於groovy(語法同java)的規則編寫，讓系統能夠自動處理複雜的業務邏輯。
場景聯動：支援直接或視覺化設定自動化場景，實現智慧設備之間的無縫協作。
告警中心：能夠對接多種通訊方式如語音、簡訊和企業微信，及時通知設備異常或故障，保證快速回應。
多租戶系統：支援資料隔離和獨立設定，適合多租戶環境，增強系統的彈性和安全性。
影像監控接入：支援GB/T28181協定的監控設備，提供直播、錄影回放及雲台控制功能，適用於安防監控需求。
場景管理：支援聚合多個設備展示，同時可擴充錄入、運算型變數，支援複雜的資料運算。
資料橋接：作為與外部資料系統的橋樑，支援資料的輸入輸出等功能。
資料中心：支援產生資料報表，查看歷史資料，對設備進行資料分析。
通訊協定：支援豐富的設備通訊協定，包括：Mqtt、Modbus、Tcp、GB28182、Http、Coap等。
物聯網卡：管理設備連線的SIM卡，支援對接不同經銷商平台，可查看卡狀態、流量，支援流量告警。
工單管理：支援對設備或資產的維護、維修、檢查等任務進行自動化、智慧化和全流程化管理。

三、技術堆疊

後端技術：包括Spring Boot, MyBatis, Spring Security, Jwt, Redis, TDengine等，確保了後端服務的穩定性和高效性。
前端技術：使用ES6, ES7, Vue, Vuex, uView, H5等現代前端技術，提升了使用者介面的互動性和視覺體驗。
行動端支援：支援微信小程式、Android和iOS等多種行動平台，透過Uniapp實現跨平台應用開發，方便使用者在不同設備上進行操作和管理。

四、應用場景

FastBee適用於智慧家庭、智慧辦公、智慧社區、農業監測、水利監測以及工業控制等多種場景。這些應用場景涵蓋了從家庭到工業等級的廣泛需求，展示了FastBee在物聯網領域的廣泛應用潛力。

五、系統架構

┌──────────────────────────────────────────────────────────────────┐
│                        瀏覽器/行動端                              │
│         Vue2 Web（PC）    +    Vant（H5 / 小程式）               │
└───────────────────────────────┬──────────────────────────────────┘
                                │ HTTP REST / WebSocket(MQTT)
                                ▼
┌──────────────────────────────────────────────────────────────────┐
│                       Nginx（反向代理）                           │
│           /  → 靜態前端資源          /prod-api/ → 後端           │
└───────────────────────────────┬──────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────┐
│                  Spring Boot 服務（8080）                         │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                fastbee-open-api（Controller 層）           │  │
│  │  device / product / ruleEngine / media / system / ...     │  │
│  └────────────────────────┬───────────────────────────────────┘  │
│  ┌─────────────────────────▼──────────────────────────────────┐  │
│  │               fastbee-service（Service 層）                │  │
│  │     IotService / SceneService / NotifyService / ...        │  │
│  └────────────────────────┬───────────────────────────────────┘  │
│  ┌─────────────────────────▼──────────────────────────────────┐  │
│  │                  fastbee-server（協定接入）                 │  │
│  │   MQTT Broker(1883) / HTTP(8081) / CoAP(5683) / TCP(8888) │  │
│  └────────────────────────────────────────────────────────────┘  │
└───────────┬──────────────────┬────────────────────┬──────────────┘
            │                  │                    │
         MySQL              Redis              TDengine
      (中繼資料/設定)       (快取/即時值)      (時序歷史資料)

六、程式碼結構

fastbee/
├── vue/                        ← 前端 Vue2 專案
│   ├── src/
│   │   ├── api/                ← 各模組 API 請求函式
│   │   ├── assets/             ← 靜態資源（圖片/圖示/樣式）
│   │   ├── components/         ← 全域公共元件（28 個）
│   │   ├── directive/          ← 全域自訂指令
│   │   ├── lang/               ← 國際化語言套件
│   │   ├── layout/             ← 主框架版面配置
│   │   ├── plugins/            ← Vue 外掛註冊
│   │   ├── router/             ← 路由設定
│   │   ├── store/              ← Vuex 狀態管理
│   │   ├── utils/              ← 工具函式（request/mqttTool 等）
│   │   └── views/              ← 業務頁面視圖
│   ├── package.json
│   └── vue.config.js
│
├── springboot/                 ← 後端 Spring Boot 多模組專案
│   ├── fastbee-admin/          ← 管理端控制器 + 設定
│   ├── fastbee-open-api/       ← Open API 介面層（IoT 業務 Controller）
│   ├── fastbee-service/        ← 業務服務層（iot-service / system-service）
│   ├── fastbee-server/         ← 協定接入服務
│   │   ├── iot-server-core/    ← IoT 核心服務邏輯
│   │   ├── mqtt-broker/        ← 內建 Netty MQTT Broker
│   │   ├── http-server/        ← HTTP 設備接入
│   │   ├── coap-server/        ← CoAP 設備接入
│   │   ├── sip-server/         ← SIP 影像接入
│   │   └── boot-strap/         ← 啟動入口
│   ├── fastbee-protocol/       ← 協定解析（Modbus/自訂）
│   ├── fastbee-mq/             ← 訊息佇列整合
│   ├── fastbee-notify/         ← 通知服務（簡訊/電子郵件/微信等）
│   ├── fastbee-plugs/          ← 外掛（OSS/OAuth/Quartz/程式碼產生）
│   ├── fastbee-iot-data/       ← IoT 資料處理
│   ├── fastbee-record/         ← 錄影服務
│   ├── fastbee-common-extend/  ← 公共工具擴充
│   └── sql/                    ← 資料庫初始化/升級指令碼
│
├── docker/                     ← Docker Compose 部署檔案
└── sdk/                        ← 設備端 SDK

七、功能模組說明

設備管理

功能	說明
設備註冊/匯入	手動新增或批次 Excel 匯入設備
設備分配/回收	依機構/使用者維度分配設備，支援回收
狀態即時更新	透過 MQTT 訂閱 `/+/{sn}/status/post` 即時更新線上/離線狀態
設備 QR Code	產生綁定 QR Code，支援列印
OTA 韌體升級	版本管理 + 升級任務下發
指令下發	物模型屬性下發 / 功能呼叫
影子模式	設備離線時透過影子快取最新值

頁面路由：/iot/device/list → views/iot/device/index.vue

產品管理

功能	說明
產品範本	定義設備類型及物模型
物模型	屬性（Property）/ 功能（Function）/ 事件（Event）三元素
協定設定	MQTT / HTTP / CoAP / TCP / Modbus / JT808
產品發佈	發佈後設備不可再修改物模型
拖曳編輯器	視覺化設定設備運行狀態面板

規則引擎

功能	說明
場景聯動	觸發器 → 條件 → 動作視覺化編排（LiteFlow 驅動）
設備告警	基於臨界值/範圍/布林觸發，支援靜默時間
規則指令碼	Groovy/JavaScript 指令碼處理原始資料
一鍵觸發	手動觸發場景聯動

資料中心

功能	說明
即時資料	設備最新上報的物模型值（Redis 快取）
歷史資料	依時間段查詢（TDengine 時序資料庫）
資料報表	定時產生 Excel，支援電子郵件通知
資料匯出	歷史資料下載

影像監控

功能	說明
設備接入	支援 GB28181（SIP）協定
即時播放	RTMP / RTSP / FLV / HLS / WebRTC
錄影回放	依時間段查詢歷史錄影（ZLMediaKit）
雲台控制	PTZ 指令下發
語音對講	SIP TCP 主動方式

通知服務

支援管道：簡訊（阿里雲/騰訊）、電子郵件、微信公眾號、企業微信、釘釘、HTTP 推送、MQTT 推送。

系統管理

使用者/角色/機構（多租戶）/ 選單/字典/日誌/系統監控/程式碼產生。

八. API 介面文件

完整介面文件可透過 Swagger 存取：http://localhost:8080/swagger-ui/index.html（開發環境）

所有介面統一回應格式：

json

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

分頁清單回應格式：

json

{
  "code": 200,
  "msg": "操作成功",
  "rows": [ ... ],
  "total": 100
}

認證介面

方法	路徑	說明
POST	`/login`	帳號密碼登入
POST	`/register`	使用者註冊
POST	`/logout`	登出
GET	`/getInfo`	取得目前使用者資訊
GET	`/captchaImage`	取得圖形驗證碼
POST	`/auth/sms/login`	簡訊驗證碼登入
GET	`/auth/login/{loginId}`	第三方社交登入
POST	`/auth/ssoLogin`	SSO 單一登入

登入範例：

bash

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123",
  "code": "1234",
  "uuid": "xxx-xxx-xxx",
  "sourceType": 1
}

json

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

後續請求需攜帶標頭：Authorization: Bearer {token}

設備介面（`/iot/device`）

方法	路徑	權限	說明
GET	`/iot/device/list`	`iot:device:list`	設備分頁清單
GET	`/iot/device/shortList`	`iot:device:list`	設備簡短清單（首頁）
GET	`/iot/device/all`	`iot:device:list`	所有設備簡短清單
GET	`/iot/device/{deviceId}`	`iot:device:query`	設備詳情
GET	`/iot/device/getDeviceBySerialNumber/{sn}`	`iot:device:query`	依序號查詢
POST	`/iot/device`	`iot:device:add`	新增設備
PUT	`/iot/device`	`iot:device:edit`	修改設備
DELETE	`/iot/device/{deviceId}`	`iot:device:remove`	刪除設備
POST	`/iot/device/export`	`iot:device:export`	匯出 Excel
POST	`/iot/device/assignment`	`iot:device:assignment`	分配設備給機構
POST	`/iot/device/user/assignment`	`iot:device:assignment`	分配設備給使用者
POST	`/iot/device/recovery`	`iot:device:recovery`	回收設備
GET	`/iot/device/runningStatus`	`iot:device:query`	運行狀態
GET	`/iot/device/thingsModelValue/{deviceId}`	`iot:device:query`	物模型即時值
GET	`/iot/device/statistic`	-	監測資料統計

產品介面（`/iot/product`）

方法	路徑	說明
GET	`/iot/product/list`	產品分頁清單
GET	`/iot/product/shortList`	產品簡短清單
GET	`/iot/product/{productId}`	產品詳情
POST	`/iot/product`	新增產品
PUT	`/iot/product`	修改產品
DELETE	`/iot/product/{productId}`	刪除產品
PUT	`/iot/product/status`	發佈/下架產品
POST	`/iot/product/copy?productId=`	複製產品

物模型介面（`/iot/thingsModel`）

方法	路徑	說明
GET	`/iot/thingsModel/list`	物模型清單
POST	`/iot/thingsModel`	新增物模型
PUT	`/iot/thingsModel`	修改物模型
DELETE	`/iot/thingsModel/{modelId}`	刪除物模型
POST	`/iot/thingsModel/sync`	同步到設備

規則引擎介面（`/iot/scene`）

方法	路徑	說明
GET	`/iot/scene/list`	場景聯動清單
POST	`/iot/scene`	新增場景
PUT	`/iot/scene`	修改場景
DELETE	`/iot/scene/{sceneId}`	刪除場景
POST	`/iot/scene/trigger/{sceneId}`	手動觸發

資料中心介面（`/iot/datacenter`）

方法	路徑	說明
GET	`/iot/datacenter/latestData`	最新資料
GET	`/iot/datacenter/historyData`	歷史資料

九、開發規範

前端命名規範

類型	規範	範例
檔案/目錄	kebab-case	`device-edit.vue`
元件名	PascalCase	`DeviceCard`
變數/方法	camelCase	`deviceList`, `handleQuery()`
常數	UPPER_CASE	`MAX_PAGE_SIZE`
API 檔案	camelCase	`device.js`, `product.js`
CSS 類別名	kebab-case	`.device-item`

後端命名規範

類型	規範	範例
套件名	全小寫，點分隔	`com.fastbee.iot.service`
類別名	PascalCase	`DeviceServiceImpl`
介面名	I + PascalCase	`IDeviceService`
方法名	camelCase	`listDeviceByGroup()`
常數	UPPER_SNAKE	`MAX_RETRY_COUNT`
資料表	小寫底線	`iot_device`
資料欄位	小寫底線	`serial_number`

API 設計規範

RESTful 風格，資源名使用名詞複數
路由前綴統一：/iot/（IoT 模組）、/system/（系統模組）
Controller 繼承 BaseController，使用 @PreAuthorize 做權限驗證
使用 @Log 註釋記錄操作日誌
回傳統一用 AjaxResult.success() / getDataTable()

java

@PreAuthorize("@ss.hasPermi('iot:device:add')")
@Log(title = "設備", businessType = BusinessType.INSERT)
@PostMapping
@ApiOperation("新增設備")
public AjaxResult add(@Validated @RequestBody Device device) {
    return toAjax(deviceService.insertDevice(device));
}

十、常見問題解答

前端

Q：npm install 後啟動報 patch-package 相關錯誤？

原因：node_modules 未完整安裝或快取問題。

bash

# 清除快取重裝
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Q：開發環境介面 404？

檢查 .env.development 中 VUE_APP_SERVER_API_URL 是否正確指向後端，並確認後端已啟動。

Q：Element UI 彈出視窗（MessageBox）無法彈出？

確認元件已全域註冊，專案中透過 Vue.use(Element) 在 main.js 中完成註冊，不需要單獨引入。

Q：MQTT 連線失敗？

確認 VUE_APP_MQTT_SERVER_URL 設定正確（開發環境 ws://localhost:8083/mqtt）
確認內建 Broker 已啟動（server.broker.enabled: true + server.broker.websocket-port: 8083）
檢查 Token 是否有效（mqttTool 用 Token 作為 MQTT password）

Q：vue-treeselect 出現版本衝突？

專案中統一使用 @riophae/vue-treeselect@0.4.0，不要混用其他版本。

Q：vue-qr 元件匯入報錯？

javascript

// ✅ 正確方式（預設匯入）
import vueQr from 'vue-qr';
// ❌ 錯誤方式（具名匯入會失敗）
import { VueQr } from 'vue-qr';

後端

Q：啟動報 license 相關錯誤？

在 application-dev.yml 中設定正確的憑證路徑：

yaml

license:
  subject: common
  licensePath: classpath:license.lic

向官方申請憑證檔案（license.lic）放入 resources 目錄。

Q：TDengine 報連線逾時？

確認 TDengine 已啟動（預設連接埠 6041）
檢查 application-dev.yml 中 taos 資料來源設定
如不需要時序資料庫，可將 taos.enabled: false 略過

Q：規則引擎不觸發？

確認場景聯動狀態為「已啟用」
檢查觸發器條件（數值範圍、比較符號）
查看日誌中 LiteFlow 執行鏈路

Q：設備上線但後台看不到線上狀態？

檢查 MQTT 認證（EMQX Webhook 設定）
確認設備 serialNumber 與系統錄入一致
查看後端日誌是否有設備狀態處理記錄

Q：如何切換 EMQX 和內建 Broker？

yaml

# application.yml
server:
  broker:
    enabled: true   # true = 內建 Netty Broker
                    # false = 使用外部 EMQX（需設定 spring.mqtt.host-url）

Q：多租戶資料隔離如何實現？

平台透過 tenant_id（機構 ID）欄位隔離資料。Controller 層從 SecurityUtils.getLoginUser() 取得目前登入使用者的機構資訊，Service 層查詢時自動過濾。

Q：Druid 監控頁面如何存取？

瀏覽器存取 http://localhost:8080/druid/index.html，預設帳號密碼均為 fastbee（可在 application.yml 中修改）。

物聯網系統 ​

頁面導讀 ​

版本對比 ​

一、平台簡介 ​

二、系統功能 ​

三、技術堆疊 ​

四、應用場景 ​

五、系統架構 ​

六、程式碼結構 ​

七、功能模組說明 ​

設備管理 ​

產品管理 ​

規則引擎 ​

資料中心 ​

影像監控 ​

通知服務 ​

系統管理 ​

八. API 介面文件 ​

認證介面 ​

設備介面（/iot/device） ​

產品介面（/iot/product） ​

物模型介面（/iot/thingsModel） ​

規則引擎介面（/iot/scene） ​

資料中心介面（/iot/datacenter） ​

九、開發規範 ​

前端命名規範 ​

後端命名規範 ​

API 設計規範 ​

十、常見問題解答 ​

前端 ​

後端 ​

物聯網系統

頁面導讀

版本對比

一、平台簡介

二、系統功能

三、技術堆疊

四、應用場景

五、系統架構

六、程式碼結構

七、功能模組說明

設備管理

產品管理

規則引擎

資料中心

影像監控

通知服務

系統管理

八. API 介面文件

認證介面

設備介面（`/iot/device`）

產品介面（`/iot/product`）

物模型介面（`/iot/thingsModel`）

規則引擎介面（`/iot/scene`）

資料中心介面（`/iot/datacenter`）

九、開發規範

前端命名規範

後端命名規範

API 設計規範

十、常見問題解答

前端

後端