維運手冊

# 前言

本文檔為金蝶Apusic分佈式消息隊列for MQTT（Apusic Distributed Message Queue，簡稱：ADMQ for MQTT）的運維手冊，旨在為中間件運維人員提供ADMQ for MQTT標準化運維指南，涵蓋安裝部署、配置優化、日常運維、故障排查、安全加固等核心場景，確保ADMQ for MQTT產品服務穩定、高效、安全運行。

# 適用對象

本文檔適用於IT信息化業務負責人、研發經理、軟件項目經理、軟件架構師、運維工程師。

# 相關文檔

瞭解更多ADMQ for MQTT產品相關的信息，請參閱以下ADMQ for MQTT產品手冊文檔集：

序號 手冊文檔 說明
1 金蝶Apusic分佈式消息隊列for MQTT 快速使用手冊 簡單介紹瞭如何快速上手使用ADMQ for MQTT 。
2 金蝶Apusic分佈式消息隊列for MQTT 安裝手冊 詳細介紹如何在各操作系統上安裝ADMQ for MQTT，以及ADMQ for MQTT服務啟停等操作。
3 金蝶Apusic分佈式消息隊列for MQTT 消息引擎用戶手冊 詳細介紹 ADMQ for MQTT 消息引擎相關功能的使用、配置、管理及配套工具的使用方法。
4 金蝶Apusic分佈式消息隊列for MQTT 管控臺用戶手冊 詳細介紹ADMQ for MQTT管控臺相關功能的使用和操作說明。
5 金蝶Apusic分佈式消息隊列for MQTT 開發手冊 詳細介紹基於各開發語言進行ADMQ for MQTT客戶端應用開發的說明。
6 金蝶Apusic分佈式消息隊列for MQTT 遷移手冊 詳細介紹從MQTT Broker遷移到ADMQ for MQTT的說明。
7 金蝶Apusic分佈式消息隊列for MQTT 運維手冊 詳細介紹ADMQ for MQTT的監控、運維、安全加固等運維說明。
8 金蝶Apusic分佈式消息隊列for MQTT 性能優化手冊 詳細介紹ADMQ for MQTT性能調優的說明。

# 技術支持

ADMQ for MQTT產品提供全面的技術支持服務，您可以通過以下方式獲得技術支持：

  • 網址：www.apusic.com
  • 電話：400-855-5800
  • 郵箱：support@apusic.com
  • 金蝶雲社區：https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

您在取得技術支持時，請提供如下信息：

  1. 您的姓名
  2. 公司信息與聯繫方式
  3. 操作系統及其版本
  4. 產品版本號
  5. 出現異常及錯誤的日誌、截圖等詳細信息

# 日常運維

# 服務管理

# 啟動服務

# 启动 MQTT 服务
bin/admq-service start

# 启动应用
bin/admq-mqtt start
1
2
3
4
5

# 停止服務

# 停止应用
bin/admq-mqtt stop

# 停止 MQTT 服务
bin/admq-service stop
1
2
3
4
5

# 查看服務狀態

# 查看服务状态
bin/admq-service status

# 查看节点状态
bin/admq-mqtt ctl status

# 查看集群状态
bin/admq-mqtt ctl cluster status
1
2
3
4
5
6
7
8

# 重啟服務

# 重启服务
bin/admq-service restart
1
2

# 日誌管理

# 日誌位置

日誌類型 路徑 說明
服務日誌 log/admq-mqtt.log MQTT Broker 主日誌
崩潰日誌 log/erlang.log.* Erlang VM 崩潰日誌
管控臺日志 /opt/admq-manager-V3.0.2/logs/ 管控臺運行日誌

# 日誌級別配置

# 查看当前日志级别
bin/admq-mqtt ctl log handlers list

# 动态调整日志级别
bin/admq-mqtt ctl log set-level debug
bin/admq-mqtt ctl log set-level info
bin/admq-mqtt ctl log set-level warning
bin/admq-mqtt ctl log set-level error
1
2
3
4
5
6
7
8

# 日誌輪轉

# etc/admq-mqtt.conf
log.file {
  path = "log/admq-mqtt.log"
  rotation_size = "10MB"
  rotation_count = 5
  level = warning
}
1
2
3
4
5
6
7

# 監控檢查

# 日常檢查清單

檢查項 檢查命令 正常標準
節點狀態 admq-mqtt ctl cluster status 所有節點在線
連接數 admq-mqtt ctl stats 在正常範圍內
內存使用 admq-mqtt ctl status 低於內存上限
磁盤空間 df -h 高於最低要求
消息吞吐 運行時監控 無異常波動
慢訂閱 慢訂閱管理 無大量慢訂閱

# 健康檢查腳本

#!/bin/bash

# 节点健康检查
bin/admq-mqtt ctl status

# 连接数检查
CONN_COUNT=$(bin/admq-mqtt ctl stats | grep connections.count | awk '{print $2}')
if [ "$CONN_COUNT" -gt 500000 ]; then
    echo "WARNING: Connection count $CONN_COUNT exceeds threshold"
fi

# 内存使用检查
MEM_USAGE=$(bin/admq-mqtt ctl status | grep memory.used | awk '{print $2}')
echo "Memory usage: $MEM_USAGE"
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 配置管理

# 配置文件

# admq-mqtt.conf

主配置文件，位於 etc/admq-mqtt.conf。

# 节点配置
node.name = admq@mqtt-node1
node.cookie = your-secret-cookie

# 集群配置
cluster.discovery = static
cluster.static.seeds = admq@mqtt-node1,admq@mqtt-node2,admq@mqtt-node3

# 监听器配置
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  max_connections = 1024000
}

listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "etc/certs/server.crt"
    keyfile = "etc/certs/server.key"
    cacertfile = "etc/certs/ca.crt"
  }
}

# 认证器配置
authentication = [
  {
    mechanism = password_based
    backend = built_in_database
    enable = true
  }
]

# 授权源配置
authorization {
  sources = [
    {
      type = built_in_database
      enable = true
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 動態配置

# 查看当前配置
bin/admq-mqtt ctl conf show

# 更新配置
bin/admq-mqtt ctl conf update "log.level=info"

# 重置配置
bin/admq-mqtt ctl conf reset
1
2
3
4
5
6
7
8

# 故障排查

# 常見問題及解決方案

# 服務無法啟動

現象 可能原因 解決方案
端口被佔用 1883/8883/8083 端口被佔用 查找並停止佔用進程，或修改監聽端口
Erlang Cookie 不一致 集群節點 Cookie 不匹配 同步 .erlang.cookie 文件
內存不足 系統內存不足 增加內存或優化配置
配置錯誤 admq-mqtt.conf 格式錯誤 檢查配置文件語法

# 客戶端無法連接

現象 可能原因 解決方案
認證失敗 用戶名密碼錯誤 檢查用戶配置
ACL 拒絕 權限不足 檢查 ACL 規則
監聽器未啟動 監聽器未啟用 檢查監聽器狀態
網絡不通 防火牆或網絡問題 檢查網絡連通性

# 消息投遞異常

現象 可能原因 解決方案
訂閱者收不到消息 主題不匹配 檢查主題和通配符
消息重複 QoS 1 正常行為 業務側實現冪等處理
消息丟失 QoS 0 不保證到達 改用 QoS 1/2
消費延遲 慢訂閱或網絡延遲 檢查慢訂閱和網絡狀況

# 集群異常

現象 可能原因 解決方案
節點離線 網絡故障或服務異常 檢查網絡連通性，重啟服務
腦裂 網絡分區導致集群分裂 檢查網絡分區，必要時重建集群
會話不同步 網絡延遲 等待自動同步

# 故障排查命令

# 查看节点状态
bin/admq-mqtt ctl status

# 查看集群状态
bin/admq-mqtt ctl cluster status

# 查看在线客户端
bin/admq-mqtt ctl clients list

# 查看订阅列表
bin/admq-mqtt ctl subscriptions list

# 查看保留消息
bin/admq-mqtt ctl retained list

# 查看告警
bin/admq-mqtt ctl alarms list

# 查看日志
bin/admq-mqtt ctl log handlers list
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 備份與恢復

# 配置備份

# 导出当前配置
bin/admq-mqtt ctl conf show > admq-mqtt-config-backup.json

# 备份配置文件
cp etc/admq-mqtt.conf backup/admq-mqtt.conf.$(date +%Y%m%d)
1
2
3
4
5

# 數據備份

# 创建数据备份
bin/admq-mqtt ctl data backup

# 查看备份列表
bin/admq-mqtt ctl data backup list
1
2
3
4
5

# 定期備份腳本

#!/bin/bash

BACKUP_DIR="/backup/mqtt/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# 备份配置
bin/admq-mqtt ctl conf show > $BACKUP_DIR/config.json
cp etc/admq-mqtt.conf $BACKUP_DIR/

# 创建数据备份
bin/admq-mqtt ctl data backup $BACKUP_DIR/data-backup

# 压缩备份
tar czf $BACKUP_DIR.tar.gz $BACKUP_DIR
rm -rf $BACKUP_DIR

# 保留最近7天备份
find /backup/mqtt -name "*.tar.gz" -mtime +7 -delete
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 安全加固

# 網絡安全

# 防火牆配置

# 开放必要端口
firewall-cmd --permanent --add-port=1883/tcp    # MQTT TCP
firewall-cmd --permanent --add-port=8883/tcp    # MQTT over SSL
firewall-cmd --permanent --add-port=8083/tcp    # MQTT over WebSocket
firewall-cmd --permanent --add-port=8084/tcp    # MQTT over WSS
firewall-cmd --permanent --add-port=14567/tcp   # MQTT over QUIC
firewall-cmd --permanent --add-port=18083/tcp   # Dashboard
firewall-cmd --permanent --add-port=12305/tcp   # 管控台 HTTP
firewall-cmd --permanent --add-port=12306/tcp   # 管控台 HTTPS
firewall-cmd --permanent --add-port=4370/tcp    # Erlang Distribution
firewall-cmd --permanent --add-port=5370/tcp    # Erlang Distribution SSL
firewall-cmd --reload
1
2
3
4
5
6
7
8
9
10
11
12

# SSL/TLS 配置

# etc/admq-mqtt.conf
listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "etc/certs/server.crt"
    keyfile = "etc/certs/server.key"
    cacertfile = "etc/certs/ca.crt"
    verify = verify_peer
    fail_if_no_peer_cert = false
    versions = ["tlsv1.2", "tlsv1.3"]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

# 訪問控制

# 默認拒絕策略

# etc/admq-mqtt.conf
authorization {
  no_match = deny
  deny_action = ignore
  sources = [
    {
      type = built_in_database
      enable = true
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

# 超級用戶管理

# 创建超级用户
bin/admq-mqtt ctl admins add admin password

# 谨慎使用超级用户权限
1
2
3
4

# 審計日誌

# etc/admq-mqtt.conf
log.audit {
  enable = true
  path = "log/audit.log"
  rotation_size = "10MB"
  rotation_count = 10
}
1
2
3
4
5
6
7

# 性能監控

# Prometheus 監控

# 啟用 Prometheus 指標

# etc/admq-mqtt.conf
prometheus {
  enable = true
  bind = "0.0.0.0:18083"
  push_gateway_server = "http://localhost:9091"
  interval = "15s"
}
1
2
3
4
5
6
7

# 監控指標

指標 說明
emqx_connections_count 當前連接數
emqx_sessions_count 當前會話數
emqx_topics_count 當前主題數
emqx_subscriptions_count 當前訂閱數
emqx_messages_received 接收消息數
emqx_messages_sent 發送消息數
emqx_messages_dropped 丟棄消息數
emqx_bytes_received 接收字節數
emqx_bytes_sent 發送字節數

# Grafana 儀表盤

導入 EMQX 官方 Grafana 儀表盤，監控集群狀態。

# 告警規則

# Prometheus 告警规则示例
groups:
  - name: mqtt_alerts
    rules:
      - alert: MQTTNodeDown
        expr: up{job="admq-mqtt"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "MQTT node is down"
      
      - alert: MQTTHighConnections
        expr: emqx_connections_count > 800000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MQTT connection count is high"
      
      - alert: MQTTMessagesDropped
        expr: rate(emqx_messages_dropped[5m]) > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MQTT messages are being dropped"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 升級維護

# 版本升級

# 升級前準備

  1. 備份配置文件和數據
  2. 查看版本發佈說明
  3. 在測試環境驗證升級流程

# 升級步驟

# 1. 停止服务
bin/admq-service stop

# 2. 备份数据
cp -r data /backup/mqtt-data-$(date +%Y%m%d)

# 3. 升级软件包
# 下载新版本安装包并解压
tar zxvf admq-mqtt-V2.0.7.tar.gz -C /opt/

# 4. 迁移配置
cp etc/admq-mqtt.conf /opt/admq-mqtt-V2.0.7/etc/

# 5. 启动服务
cd /opt/admq-mqtt-V2.0.7
bin/admq-service start

# 6. 验证升级
bin/admq-mqtt ctl status
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 集群滾動升級

  1. 一次升級一個節點
  2. 確認節點恢復正常後再升級下一個
  3. 確保集群始終有可用的節點

# 運維最佳實踐

  1. 定期檢查：建立日常檢查機制，及時發現潛在問題
  2. 監控告警：配置完善的監控和告警體系
  3. 備份策略：制定定期備份策略，確保數據安全
  4. 文檔記錄：記錄所有運維操作和變更
  5. 容量規劃：定期評估集群容量，提前擴容
  6. 安全更新：及時更新安全補丁
  7. 災難演練：定期進行故障恢復演練
编辑页面 (opens new window)
#運維手冊

← 效能調優→