Core Engine User Manual

# Preface

This document is the user manual for the Kingdee Apusic Distributed Message Queue for RabbitMQ (Apusic Distributed Message Queue,简称：ADMQ for RabbitMQ) message engine, detailing the functional usage, configuration methods, and management operations of the ADMQ for RabbitMQ message engine.

# Target Audience

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

For more information about ADMQ for RabbitMQ products, please refer to the following ADMQ for RabbitMQ product documentation set:

No. Document Description
1 Kingdee Apusic Distributed Message Queue for RabbitMQ Quick Start Guide A brief introduction on how to quickly get started with ADMQ for RabbitMQ.
2 Kingdee Apusic Distributed Message Queue for RabbitMQ Installation Guide Detailed instructions on installing ADMQ for RabbitMQ on various operating systems, as well as starting and stopping ADMQ for RabbitMQ services.
3 Kingdee Apusic Distributed Message Queue for RabbitMQ Message Engine User Manual Detailed description of the usage, configuration, management, and supporting tools of ADMQ for RabbitMQ message engine related features.
4 Kingdee Apusic Distributed Message Queue for RabbitMQ Console User Manual Detailed description of the usage and operation instructions for ADMQ for RabbitMQ console related functions.
5 Kingdee Apusic Distributed Message Queue for RabbitMQ Developer Guide Detailed instructions for developing ADMQ for RabbitMQ client applications in various programming languages.
6 Kingdee Apusic Distributed Message Queue for RabbitMQ Migration Guide Detailed instructions on migrating from RabbitMQ to ADMQ for RabbitMQ.
7 Kingdee Apusic Distributed Message Queue for RabbitMQ Operations Manual Detailed description of ADMQ for RabbitMQ monitoring, operations, security hardening, and other operational instructions.
8 Kingdee Apusic Distributed Message Queue for RabbitMQ Performance Optimization Guide Detailed description of ADMQ for RabbitMQ performance tuning.

# Technical Support

ADMQ for RabbitMQ provides comprehensive technical support services. You can obtain technical support through the following methods:

  • 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 seeking technical support, please provide the following information:

  1. Your name

  2. Company information and contact details

  3. Operating system and its version

  4. Product version number

  5. Detailed logs, screenshots, etc. of the anomalies and errors

# Core Concepts

# AMQP Protocol

ADMQ for RabbitMQ is fully compatible with the AMQP 0-9-1 protocol and supports the following core concepts:

Concept Description
Producer Producer, responsible for sending messages to Exchange
Consumer Consumer, responsible for receiving messages from Queue
Exchange Exchange, responsible for receiving and routing messages to Queue
Queue Queue, responsible for storing messages
Binding Binding, defines the routing rules from Exchange to Queue
Routing Key Routing key, used for message routing matching
Channel Channel, a lightweight connection built on top of a real connection

# Message Model

Producer -> Exchange -> [Binding/Routing Key] -> Queue -> Consumer
1
  1. The producer sends a message to the Exchange
  2. The Exchange determines how to route the message based on its type and Routing Key
  3. The message is routed to the matching Queue through a Binding
  4. The consumer receives the message from the Queue

# Exchange

# Exchange Types

# Direct Exchange

  • Routing method: Exact match of Routing Key
  • Use case: Point-to-point messaging, simple routing
  • Example: A message with Routing Key "order.create" will only be routed to queues bound with the key "order.create"

# Fanout Exchange

  • Routing method: Broadcasts to all bound queues, ignores Routing Key
  • Use case: Broadcast notifications, group messaging, cache invalidation
  • Example: Sending a message to a Fanout Exchange delivers it to all bound queues

# Topic Exchange

  • Routing method: Pattern matching of Routing Key, supports wildcards
    • * matches exactly one word
    • # matches zero or more words
  • Use case: Log classification, business event routing, multi-level subscriptions
  • Example:
    • Binding key order.* matches order.create, order.update
    • Binding key order.# matches order.create, order.create.success

# Headers Exchange

  • Routing method: Matches based on message headers
  • Use case: Complex conditional routing, independent of Routing Key
  • Example: Matches headers with x-match=all and type=order, status=paid

# Exchange Properties

Property Description
Durable Whether the exchange persists after service restart
Auto-delete Automatically deleted when the last queue is unbound
Internal Only allows other exchanges to bind, does not allow direct message publishing

# Queue

# Queue Types

# Classic Queue

  • Features: Traditional queue type, supports mirrored mode
  • Use case: General business scenarios where extremely high throughput is not required
  • Configuration options:
    • Mirror mode: Synchronizes queue data across multiple nodes
    • Durable: Messages persisted to disk

# Quorum Queue

  • Features: High-availability queue based on the Raft consensus algorithm, automatically implements multiple replicas
  • Use case: Scenarios requiring high availability and data safety
  • Advantages:
    • Automatic failover
    • Strong consistency guarantees
    • No need to configure mirroring policies
  • Limitations:
    • Does not support exclusive queues
    • Does not support per-message TTL (queue-level TTL is supported)
    • Does not support priority queues

# Stream Queue

  • Features: Append-only log type queue, supports multiple reads
  • Use case: High throughput, message replay, log collection scenarios
  • Advantages:
    • Extremely high write throughput
    • Supports multiple consumers reading independently
    • Messages are not automatically deleted, configurable retention policy
  • Characteristics:
    • Offset-based consumption
    • Supports timestamp-based positioning
    • Persistent message storage

# Queue Properties

Property Description
Durable Whether the queue persists after service restart
Auto-delete Automatically deleted when the last consumer disconnects
Exclusive Only allows the creator's connection to use it
Message TTL Message time to live in the queue
Queue TTL How long the queue remains idle before auto-deletion
Max Length Maximum number of messages in the queue
Max Bytes Maximum byte size of the queue
Dead Letter Exchange (DLX) Exchange to forward messages when rejected or expired
Dead Letter Routing Key (DLK) Routing key used for dead letter messages

# Dead Letter Queue

A dead letter queue is used to handle messages that cannot be consumed normally.

Scenarios where messages become dead letters:

  1. The message is rejected by the consumer (basic.reject or basic.nack) with requeue=false
  2. The message expires (TTL expires)
  3. The queue reaches its maximum length and a new message pushes out old ones

Configuring a dead letter queue:

  1. Create a dead letter exchange (DLX)
  2. Create a dead letter queue and bind it to the DLX
  3. Set x-dead-letter-exchange and x-dead-letter-routing-key on the business queue

# Message Mechanism

# Message Acknowledgment

# Auto Ack

  • The message is immediately deleted from the queue after being sent to the consumer
  • Advantages: High performance, low latency
  • Disadvantages: Message loss if the consumer fails to process

# Manual Ack

  • The consumer sends an acknowledgment (basic.ack) after processing is complete
  • Supports batch acknowledgment (multiple=true)
  • Supports negative acknowledgment (basic.nack), with the option to requeue
  • Advantages: Guarantees no message loss
  • Disadvantages: Slightly lower performance

# Message Persistence

# Queue Persistence

Set durable=true when creating a queue; the queue metadata is persisted to disk.

# Message Persistence

Set delivery_mode=2 when sending a message; the message content is persisted to disk.

channel.basicPublish(EXCHANGE, ROUTING_KEY,
    MessageProperties.PERSISTENT_TEXT_PLAIN,
    message.getBytes());
1
2
3

# Message Priority

Supports setting priority (0-255) for messages.

  1. Set x-max-priority when creating the queue
  2. Set priority when sending the message
Map<String, Object> args = new HashMap<>();
args.put("x-max-priority", 10);
channel.queueDeclare(QUEUE, true, false, false, args);

AMQP.BasicProperties props = new AMQP.BasicProperties.Builder()
    .priority(5)
    .build();
channel.basicPublish(EXCHANGE, ROUTING_KEY, props, message.getBytes());
1
2
3
4
5
6
7
8

# Delayed Queue

Supports delayed message delivery.

  1. Use Dead Letter Exchange + TTL to implement a delayed queue
  2. Or use a plugin-supported delayed exchange (x-delayed-message)

# Cluster and High Availability

# Cluster Modes

# Normal Cluster

  • Nodes share metadata (Exchange, Binding, Queue definitions)
  • Queue data is only stored on the node where the queue was declared
  • Advantages: Low resource usage
  • Disadvantages: When a node fails, queues on that node become unavailable

# Mirrored Queues

  • Classic Queue supports mirroring mode
  • Queue data is synchronized across multiple nodes
  • Configuring policies:
# Mirror all queues to all nodes
bin/admq rabbitmq admin ctl set_policy ha-all "^" '{"ha-mode":"all"}'

# Mirror queues to a specified number of nodes
bin/admq rabbitmq admin ctl set_policy ha-two "^" '{"ha-mode":"exactly","ha-params":2}'
1
2
3
4
5

# Quorum Queue

  • Automatically implements multiple replicas based on the Raft consensus algorithm
  • No need to configure mirroring policies
  • Automatic Leader election and failover

# Cluster Operations Commands

# View cluster status
bin/admq rabbitmq admin ctl cluster_status

# Add a node to the cluster
bin/admq rabbitmq admin ctl join_cluster rabbit@node1

# Remove a node
bin/admq rabbitmq admin ctl forget_cluster_node rabbit@node2

# View queue details
bin/admq rabbitmq admin ctl list_queues name pid slave_pids synchronised_slave_pids

# View connections
bin/admq rabbitmq admin ctl list_connections peer_host peer_port state
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Security Configuration

# User Authentication

# Creating a User

bin/admq rabbitmq admin ctl add_user username password
bin/admq rabbitmq admin ctl set_user_tags username administrator
1
2

# Configuring Permissions

bin/admq rabbitmq admin ctl set_permissions -p /vhost username ".*" ".*" ".*"
1

Permission format:

  • First parameter: Configure permission (create/delete resources)
  • Second parameter: Write permission (send messages)
  • Third parameter: Read permission (receive messages)

# SSL/TLS Configuration

# Configure SSL listener
listeners.ssl.default = 5671
ssl_options.cacertfile = /path/to/ca_certificate.pem
ssl_options.certfile = /path/to/server_certificate.pem
ssl_options.keyfile = /path/to/server_key.pem
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = false
1
2
3
4
5
6
7

# Access Control

Supports Vhost-based resource isolation, where each user can have different permissions under different Vhosts.

# Performance Tuning Parameters

# Memory Management

Parameter Description Default
vm_memory_high_watermark Memory usage upper limit ratio 0.4
vm_memory_high_watermark_paging_ratio Memory ratio to start paging 0.5

# Disk Management

Parameter Description Default
disk_free_limit.absolute Disk space lower limit 50MB
disk_free_limit.relative Disk space lower limit ratio 2.0

# Connections and Channels

Parameter Description Default
channel_max Maximum channels per connection 2047
connection_max Maximum connections infinity
heartbeat Heartbeat interval (seconds) 60

# Queue Parameters

Parameter Description Default
queue_master_locator Queue Leader assignment strategy min-masters
lazy_queue_explicit_gc_run_operation_threshold Lazy queue GC threshold 1000

# Common Tools

# bin/admq rabbitmq admin ctl

RabbitMQ command-line management tool.

# Service management
bin/admq rabbitmq admin ctl start_app
bin/admq rabbitmq admin ctl stop_app
bin/admq rabbitmq admin ctl status

# User management
bin/admq rabbitmq admin ctl list_users
bin/admq rabbitmq admin ctl add_user user password
bin/admq rabbitmq admin ctl delete_user user
bin/admq rabbitmq admin ctl change_password user newpassword

# Queue management
bin/admq rabbitmq admin ctl list_queues
bin/admq rabbitmq admin ctl list_queues name messages consumers

# Exchange management
bin/admq rabbitmq admin ctl list_exchanges name type

# Connection management
bin/admq rabbitmq admin ctl list_connections peer_host state
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# bin/admq rabbitmq admin diagnostics

Diagnostic tool.

# Check node health
bin/admq rabbitmq admin diagnostics health_check

# View node status
bin/admq rabbitmq admin diagnostics status

# View memory usage
bin/admq rabbitmq admin diagnostics memory_breakdown

# View cluster status
bin/admq rabbitmq admin diagnostics cluster_status
1
2
3
4
5
6
7
8
9
10
11

# rabbitmq-plugins

Plugin management tool.

# List plugins
rabbitmq-plugins list

# Enable plugins
rabbitmq-plugins enable rabbitmq_management
rabbitmq-plugins enable rabbitmq_shovel
rabbitmq-plugins enable rabbitmq_federation

# Disable plugins
rabbitmq-plugins disable rabbitmq_management
1
2
3
4
5
6
7
8
9
10
编辑页面 (opens new window)
#消息引擎用户手册

← Development Manual→