MQE 詳細規範指南 (技術用)

引導您了解 GIIP 消息隊列引擎 (MQE) 的協議、數據結構及可靠性保證機制的技术詳細規範。

🔔 前往訊息佇列設定 →

📋 概述

MQE (Message Queue Engine) 承擔著 GIIP 生態系統神經網絡的角色。它專為分佈式代理與中央伺服器之間的高性能、高可靠通信而設計，包含了即使在網絡不穩定的情況下也能最大限度減少數據流失的技術機制。

🛠️ 技術規格

1. 通信協議與端口

主協議 (Primary Protocol): 基於 AMQP 0-9-1 (RabbitMQ) 或 AMQP 1.0 (Azure Service Bus)。
端口: 5671（必須使用 TLS 加密通信）。
備用方案 (Fallback): 支持基於 WebSocket 的 HTTPS (443) 通信，以應對防火牆環境。

2. 消息負載結構 (JSON)

所有消息均包含以下通用頭部：

{
  "header": {
    "msgId": "UUID",
    "timestamp": "ISO8601",
    "originNode": "AgentID",
    "priority": "0-9"
  },
  "payload": {
    "type": "METRIC | ISSUE | COMMAND",
    "data": { ... }
  }
}

3. 可靠性與安全

至少交付一次 (At-Least-Once Delivery): 在消費者完成消息處理並發送
```
ACK
```
之前，消息不會從隊列中刪除。
端到端加密: 負載數據區域可在發送端使用 AES-256 進行加密傳輸。
斷路器 (Circuit Breaker): 當特定節點產生超額流量時自動攔截進入，以保護整個系統。

⚙️ 開發者注意事項

代理開發: 若開發新代理，務必使用 MQE SDK 實現心跳 (Heartbeat) 及重連 (Reconnection) 邏輯。
應對處理延遲: 若消費者端的處理速度變慢，會導致
```
Queue Depth
```
增加，請通過水平擴展 (Scale-out) 提高效率。

疑難排解

症狀	原因	解決
透過 5671 埠連接 MQE 失敗	防火牆攔截了 AMQP(5671) 埠	切換至基於 WebSocket 的 HTTPS(443) 備用通信
同一則消息被重複處理	At-Least-Once 交付特性會在 `ACK` 之前重送	在消費者端基於 `msgId` 實現冪等處理
`Queue Depth` 持續增加	消費者處理速度跟不上流入速度	透過水平擴展 (Scale-out) 增設消費者
特定節點的消息流入被攔截	超額流量觸發了斷路器 (Circuit Breaker)	流量恢復正常後透過心跳/重連邏輯重新連接

版本: 1.0 最後更新: 2026-03-19 源文件:

giipv3/public/help/mqe-spec.zh-TW.md