Single-Node Deployment

In the distributed architecture ecosystem of RocketMQ, single-node deployment represents the foundational form for building message middleware systems. It refers to a configuration mode where core components such as Broker and NameServer (optional) are operated using only a single server. This deployment approach significantly simplifies the initial setup process, reduces operational complexity, and is highly suitable for development environment testing, lightweight business scenarios, or as a transitional phase towards a distributed cluster.

The core advantage of single-node deployment lies in its extremely high resource utilization rate and rapid go-live capability. Since there is no need to coordinate data synchronization and load balancing between multiple nodes, administrators can focus on validating the business logic of the message queue itself. However, it must be clearly recognized that the single-node architecture inherently carries the risk of a Single Point of Failure (SPOF). Should this node experience hardware failure or network interruption, the entire message service will become unavailable, and cross-datacenter disaster recovery cannot be implemented. Therefore, when relying on single-node deployment in production environments for extended periods, it is necessary to complement its shortcomings by pairing it with high-availability databases, external monitoring systems, and comprehensive emergency response plans.

Core Component Configuration and Startup Process

The single-node deployment of RocketMQ primarily involves the configuration of two core roles: Broker and NameServer. Typically, to simplify the architecture, the NameServer can also be deployed on the same server, or its independent deployment can be skipped entirely during the development phase (some versions support direct connection modes). The following is a single-node configuration example based on a standard Docker Compose environment, which can clearly demonstrate resource allocation and startup logic.

First, plan the hardware resources for the server carefully. For production-grade single nodes, it is recommended to equip at least 8GB of memory and 20GB of disk space; for development and testing environments, 4GB of memory and 10GB of disk usually suffice to meet requirements. In the configuration files, it is necessary to explicitly specify the JVM heap memory size to avoid OOM (Out Of Memory) errors caused by default values.

Second, the startup order is critical. The RocketMQ Broker component relies on the metadata service provided by NameServer to register Topic and ConsumerGroup information. Therefore, NameServer must be started first; once its port listening status is normal, the Broker can then be started. In the Docker Compose file, this dependency relationship can be explicitly defined using the depends_on keyword.

Here is a typical single-node Docker Compose configuration snippet:

version: '3.8'
services:
  nameserver:
    image: apache/rocketmq:5.x-latest
    container_name: rocketmq-nameserver
    ports:
      - "9876:9876"
    environment:
      - NAMESERVER_PORT=9876
      - STORE_PATH.home=/data/rocketmq/store
    volumes:
      - ./nameserver.conf:/opt/rocketmq/bin/nameserver.conf
      - data-nameserver:/data/rocketmq

  broker:
    image: apache/rocketmq:5.x-latest
    container_name: rocketmq-broker
    depends_on:
      nameserver:
        condition: service_healthy
    ports:
      - "10911:10911"
      - "10909:10909"
    environment:
      - NAMESERVER_ADDR=nameserver:9876
      - STORE_PATH.home=/data/rocketmq/store
    volumes:
      - ./broker.conf:/opt/rocketmq/bin/broker.conf
      - data-broker:/data/rocketmq

During the startup process, special attention must be paid to log output. When starting, the Broker sends a registration request to NameServer; if the connection fails, it will directly report an error and exit. At this time, one should check whether NameServer is fully ready and confirm that the network firewall has not intercepted the relevant ports.

Data Persistence Strategy and Storage Planning

The reliability of RocketMQ largely depends on its message data persistence mechanism. In single-node deployments, due to the lack of multi-replica synchronization mechanisms, all message data is stored directly on the disk of that node. Therefore, reasonable storage path planning and filesystem configuration are key to ensuring data non-loss.

By default, RocketMQ stores message data in the /data/rocketmq/store directory, which contains DefaultLiteMessageStore (default lightweight message store) and DefaultMessageStore (default full-featured message store). For single-node deployments, it is recommended to prioritize using DefaultLiteMessageStore, as it offers superior write performance and has relatively lower requirements for disk space.

Configuration should focus on the following storage parameters:

  • CommitLog Path: Used to store committed message data on disk; ensure that read/write permissions for this directory are correct.
  • ConsumeQueue Path: Used to store consumer queue indexes, typically located in the same directory as CommitLog.
  • Flush Disk Rate: Controls the frequency of message flushing to disk; for single nodes, a lower value can be set to balance performance and stability.

Additionally, single-node deployments place significant pressure on disk I/O. If business throughput is high, it is recommended to store CommitLog and ConsumeQueue on different physical disks to reduce I/O contention. Furthermore, regularly deleting expired messages (via deleteExpiredMessage) is also an important step in maintaining single-node performance, preventing service blocking caused by historical data filling up the disk space.

Operations Monitoring and Troubleshooting Guide

Although single-node deployment simplifies the architecture, it does not mean that operations monitoring can be ignored. Due to the lack of automatic recovery capabilities at the cluster level, any anomaly could lead to business interruption; therefore, establishing a comprehensive monitoring metrics system is crucial.

In a single-node environment, the following core metrics should be monitored in particular:

  1. Broker存活状态 (Survival Status): Real-time check Broker health via the curl http://localhost:8080/broker/admin/health interface.
  2. Message Accumulation: Monitor PendingMsgs (pending message count) and TotalMsgs (total message count) for each Topic to prevent consumer timeouts caused by message backlog.
  3. Disk Usage Rate: Real-time monitoring of the usage rate of the /data/rocketmq/store directory; set threshold alerts to prevent disk write exhaustion.
  4. JVM Memory Status: Monitor the ratio of Heap Used to Max Heap Size to prevent process crashes caused by memory overflow.

When encountering Broker startup failures or message delivery anomalies, follow these troubleshooting steps:

  • First, check if NameServer is running normally and confirm that the registration interface is accessible.
  • View Broker log files (usually located in the logs directory) and search for keywords like Error or Exception to locate specific causes.
  • Verify that port, path, and permission settings in the configuration files match expectations.
  • If disk issues are suspected, use the df -h command to check remaining space in the storage directory.

Through the above configuration and monitoring methods, single-node RocketMQ deployment can provide stable and reliable message services with minimal cost, laying a solid foundation for subsequent evolution towards distributed clusters.