Migration Manual

# Preface

This document is the migration manual for the Kingdee Apusic Distributed Message Queue for MQTT (Apusic Distributed Message Queue, ADMQ for MQTT), detailing how to migrate from an existing MQTT Broker to ADMQ for MQTT.

# Target Audience

This document is intended for IT business leaders, R&D managers, software project managers, software architects, and operations engineers.

To learn more about ADMQ for MQTT, please refer to the following ADMQ for MQTT product documentation set:

No.	Document	Description
1	ADMQ for MQTT Quick Start Guide	Briefly introduces how to quickly get started with ADMQ for MQTT.
2	ADMQ for MQTT Installation Manual	Details how to install ADMQ for MQTT on various operating systems and how to start/stop ADMQ for MQTT services.
3	ADMQ for MQTT Message Engine User Manual	Details the usage, configuration, management, and supporting tools of ADMQ for MQTT message engine features.
4	ADMQ for MQTT Console User Manual	Details the usage and operation instructions of the ADMQ for MQTT console.
5	ADMQ for MQTT Development Manual	Details ADMQ for MQTT client application development based on various programming languages.
6	ADMQ for MQTT Migration Manual	Details the migration from MQTT Broker to ADMQ for MQTT.
7	ADMQ for MQTT Operations Manual	Details ADMQ for MQTT monitoring, operations, security hardening, and other operational tasks.
8	ADMQ for MQTT Performance Tuning Manual	Details ADMQ for MQTT performance tuning guidelines.

# Technical Support

ADMQ for MQTT provides comprehensive technical support services. You can obtain technical support through the following channels:

Website: www.apusic.com
Phone: 400-855-5800
Email: support@apusic.com
Kingdee Cloud Community: https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

When contacting technical support, please provide the following information:

Your name
Company information and contact details
Operating system and its version
Product version number
Detailed information such as logs and screenshots of the exception or error

# Migration Overview

# Migration Principles

ADMQ for MQTT is fully compatible with MQTT 3.1, 3.1.1, and 5.0 protocols. The migration process follows these principles:

Zero code changes: Clients do not need to modify code, only need to change the connection address
Configuration compatibility: Supports standard MQTT client and configuration parameters
Data migratable: Supports migration of users, ACL rules, retained messages, and other configuration
Smooth switchover: Supports dual-write and gray-scale switchover to reduce migration risk

# Migration Scope

Migration Item	Supported	Description
Application code	Yes	No modification required, only change Broker address
Client configuration	Yes	Supports standard MQTT clients
User accounts	Yes	Supports built-in database user migration
ACL rules	Yes	Supports ACL permission rule migration
Retained messages	Yes	Supports retained message migration
Listener configuration	Yes	Supports TCP/SSL/WebSocket listener configuration
System configuration	Partial	Some advanced configurations may need manual adjustment

# Pre-migration Checklist

# Protocol Compatibility Check

Source MQTT Broker	Compatibility	Description
EMQX	Fully compatible	Recommended migration version
Mosquitto	Fully compatible	Basic MQTT features
HiveMQ	Fully compatible	Enterprise MQTT features
RabbitMQ MQTT Plugin	Fully compatible	Basic MQTT features

# Client Compatibility Check

Client Type	Compatible Version	Description
Eclipse Paho	1.2.x+	Fully compatible
MQTT.js	4.x+	Fully compatible
EMQX Client	5.x+	Fully compatible
Other standard MQTT clients	-	Fully compatible

# Migration Plans

# Plan 1: Dual-Write Migration (Recommended)

Suitable for business scenarios that cannot tolerate downtime. Ensures data consistency through dual-write.

Steps:

Deploy ADMQ for MQTT Cluster
- Deploy the new cluster according to the installation manual
- Configure network and firewall
Configure Dual-Write
- Connect to both the original MQTT Broker and ADMQ for MQTT in the application
- Send messages to both clusters simultaneously when publishing
Synchronize Configuration
- Create users and ACL rules in ADMQ for MQTT
- Configure listeners and system parameters
Switch Subscribers
- First switch some subscribers to ADMQ for MQTT
- Observe whether the business is functioning normally
Full Switchover
- After confirmation, switch all subscribers
- Stop sending messages to the original MQTT Broker
Decommission the Original Cluster
- Keep it for a period for data query purposes
- Decommission after confirming no issues

# Plan 2: Downtime Migration

Suitable for business scenarios that can tolerate a brief downtime. Faster migration speed.

Steps:

Stop the Business System
- Pause all MQTT client connections
Export Original Broker Configuration
- Export users, ACL rules, retained messages, etc.
Migrate Configuration to ADMQ for MQTT
- Create corresponding resources via the console or command line
Switch Connection Address
- Modify application configuration to point to ADMQ for MQTT
Start the Business System
- Restore MQTT client connections

# Plan 3: Gray-Scale Migration

Suitable for large-scale systems, migrating different business modules gradually.

Steps:

Divide migration batches by business module
Execute each batch following the dual-write migration plan
Proceed to the next batch after verification
Decommission the original cluster after all batches are complete

# Configuration Migration

# User Migration

# Export Users from Original Broker

# EMQX example
emqx ctl admins list
# Or export using Dashboard

1
2
3

# Create Users in ADMQ for MQTT

Log in to the console
Navigate to the "Users" page
Create a built-in database authenticator (if not yet created)
Batch import or create users one by one
Click "Sync to MQTT"

# ACL Rule Migration

# Export ACL Rules from Original Broker

# EMQX example
cat etc/acl.conf

1
2

# Create ACL Rules in ADMQ for MQTT

Log in to the console
Navigate to "Authentication & Authorization" - "Permissions" page
Select the built_in_database authorization source
Create ACL rules one by one
Click "Sync to MQTT"

# Listener Migration

# Export Listener Configuration from Original Broker

# EMQX example
cat etc/emqx.conf | grep listener

1
2

# Create Listeners in ADMQ for MQTT

Navigate to the "Listeners" page
Create TCP, SSL, WebSocket, WebSocket Secure listeners
SSL/WSS types require uploading certificate files

# Retained Message Migration

# Migration Using Client Scripts

For small-scale data, use client scripts to migrate retained messages:

import paho.mqtt.client as mqtt

# Connect to original Broker
src_client = mqtt.Client(client_id="migrate-src")
src_client.connect("old-mqtt-broker", 1883, 60)

# Connect to ADMQ for MQTT
dst_client = mqtt.Client(client_id="migrate-dst")
dst_client.connect("admq-mqtt", 1883, 60)

# Subscribe to all topics and receive retained messages
def on_message(client, userdata, msg):
    if msg.retain:
        # Forward to ADMQ for MQTT
        dst_client.publish(msg.topic, msg.payload, qos=msg.qos, retain=True)
        print(f"Migrated retained message: {msg.topic}")

src_client.on_message = on_message
src_client.subscribe("#", qos=1)
src_client.loop_forever()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Client Migration

# Connection Address Change

Only the Broker address in the application configuration file needs to be modified:

# Original configuration
mqtt.broker=old-mqtt-broker
mqtt.port=1883

# New configuration
mqtt.broker=admq-mqtt
mqtt.port=1883

1
2
3
4
5
6
7

# SSL/TLS Configuration Change

If SSL is enabled, certificates need to be updated:

# Original configuration
mqtt.ssl.ca-file=/path/to/old-ca.pem

# New configuration
mqtt.ssl.ca-file=/path/to/admq-ca.pem

1
2
3
4
5

# Common Client Configuration

# Java (Spring Boot)

spring:
  mqtt:
    host: admq-mqtt
    port: 1883
    username: device-service
    password: your-password
    client-id: spring-client-001

1
2
3
4
5
6
7

# Python

client = mqtt.Client(client_id="app-001")
client.username_pw_set("device-service", "your-password")
client.connect("admq-mqtt", 1883, 60)

1
2
3

# JavaScript

const client = mqtt.connect('mqtt://admq-mqtt:1883', {
    clientId: 'web-client-001',
    username: 'device-service',
    password: 'your-password'
});

1
2
3
4
5

# Migration Verification

# Functional Verification

Verification Item	Verification Method
Connection test	Connect to ADMQ for MQTT using a client, confirm connection is established
Message publishing	Send test messages, confirm they reach the Broker successfully
Message subscription	Start a subscriber, confirm messages are received normally
QoS 1/2	Test QoS 1/2 message delivery and acknowledgment
Retained messages	Send a retained message, confirm new subscribers receive it immediately
Will message	Simulate abnormal disconnection, confirm will message is published
ACL permissions	Test whether allow/deny rules take effect
Cluster functionality	Verify automatic failover when a node fails

# Performance Verification

Verification Item	Verification Method
Concurrent connections	Test a large number of clients connecting concurrently
Message throughput	Test message publish/subscribe rate
Latency	Measure the delay from message publish to receive
Stability	Run long-duration tests, observe for any anomalies

# Rollback Plan

If issues arise during migration, roll back to the original MQTT Broker:

Stop sending messages to ADMQ for MQTT
Switch the connection address back to the original MQTT Broker
Sync new messages from ADMQ for MQTT back to the original cluster (if needed)
Restore the business system

# Rollback Checklist

[ ] Original MQTT Broker is still running
[ ] Original cluster data has not been deleted
[ ] Application configuration can be quickly switched back
[ ] Business system supports fast rollback

# Migration Best Practices

Thoroughly test: Complete the full migration flow verification in a test environment
Back up data: Backup the original cluster configuration and data before migration
Monitor the migration process: Monitor various metrics in real-time during migration
Create a rollback plan: Ensure quick rollback if issues occur
Choose off-peak hours: Perform migration during business off-peak hours
Gradual switchover: First switch non-core services, verify before switching core services
Keep the original cluster: Retain the original cluster for some time after migration for query purposes

编辑页面

#Migration Manual

← Development Manual Operations Manual→

Migration Manual

# Preface

# Target Audience

# Related Documents

# Technical Support

# Migration Overview

# Migration Principles

# Migration Scope

# Pre-migration Checklist

# Protocol Compatibility Check

# Client Compatibility Check

# Migration Plans

# Plan 1: Dual-Write Migration (Recommended)

# Plan 2: Downtime Migration

# Plan 3: Gray-Scale Migration

# Configuration Migration

# User Migration

# Export Users from Original Broker

# Create Users in ADMQ for MQTT

# ACL Rule Migration

# Export ACL Rules from Original Broker

# Create ACL Rules in ADMQ for MQTT

# Listener Migration

# Export Listener Configuration from Original Broker

# Create Listeners in ADMQ for MQTT

# Retained Message Migration

# Migration Using Client Scripts

# Client Migration

# Connection Address Change

# SSL/TLS Configuration Change

# Common Client Configuration

# Java (Spring Boot)

# Python

# JavaScript

# Migration Verification

# Functional Verification

# Performance Verification

# Rollback Plan

# Rollback Checklist

# Migration Best Practices