RocketMQ Studio

English | 中文

Cross-cluster · Cross-architecture unified RocketMQ management platform

RocketMQ Studio is a unified management platform for RocketMQ, supporting multi-cluster and multi-architecture environments. It provides instance management, cluster operations, Topic / Consumer Group CRUD, ACL permission control, message query and tracing, dead letter queue handling, monitoring alerts, audit logs, and an AI assistant.

Start with AI

You can use an AI coding agent (Claude Code, Qoder, Cursor, etc.) to set up and launch Studio. Open the agent at the repository root and paste the prompt below:

Set up and run RocketMQ Studio locally from this repository:
1. Check that Docker and Docker Compose are installed. If not, tell me how to install them and stop.
2. Create the shared network: `docker network create rocketmq_net` (ignore the error if it already exists).
3. Build and start Studio: `docker compose -f deploy/docker-compose.yml up -d --build`.
4. Wait for the backend to become healthy, then open http://127.0.0.1:6789 and confirm the page loads.
Report the running containers and any errors. Do not modify source code or create commits.

To also start the optional bundled RocketMQ demo cluster, insert docker compose -f deploy/rocketmq/docker-compose.yml up -d before step 3 and wait until its ps output is healthy.

Quick Start

Run from the repository root:

# 1. Create the shared Docker network (the compose files attach to it as external)
docker network create rocketmq_net

# 2. Build and start RocketMQ Studio (mysql + rocketmq-server + rocketmq-web)
docker compose -f deploy/docker-compose.yml up -d --build

Then visit http://127.0.0.1:6789.

This starts only Studio and its own MySQL database — enough to open the console, log in, and explore the UI. No RocketMQ cluster is bundled here; register an instance pointing at your own RocketMQ to manage real resources, or start the optional demo cluster in Bundled RocketMQ Cluster below.

The default schema creates only Studio tables. It does not seed instances, topics, consumer groups, or ACL records. Development-only sample data can be imported explicitly from deploy/mysql/; it is not part of the default deployment. Import upgrade-demo-instance.sql first and then upgrade-demo-acl.sql; both scripts target the current numeric-ID schema and are idempotent. They are sample-data loaders, not upgrade migrations, and should never be imported into a production database.

Studio ports: Frontend 6789 (Nginx), Backend 8888 (Spring Boot)

To enable login protection for a shared environment, copy deploy/.env.example to deploy/.env, set STUDIO_AUTH_LOGIN_REQUIRED=true, and configure STUDIO_AUTH_ADMIN_USERNAME / STUDIO_AUTH_ADMIN_PASSWORD. These configured credentials are a bootstrap seed: on the first login against an empty database Studio creates the configured users in the rmq_studio_user table, and the database becomes the source of truth afterwards. Administrators manage accounts (create users, enable/disable, reset passwords) on the user-management page; browsers authenticate with an HttpOnly session cookie, and API clients can request a bearer token explicitly. Disabling login protection only skips API interception for local development.

Bundled RocketMQ Cluster (Optional)

The Quick Start above runs only Studio and its database. To try it against a ready-made RocketMQ, start the bundled demo cluster — nameserver, two brokers, proxy, a producer/consumer load generator, and Prometheus — on the same rocketmq_net network:

docker compose -f deploy/rocketmq/docker-compose.yml up -d

Confirm it is healthy with docker compose -f deploy/rocketmq/docker-compose.yml ps. Studio reaches the cluster at nameserver:9876 over the shared network (the backend default).

RocketMQ ports: NameServer 9876, Broker 10911, Proxy Remoting 8080, Proxy gRPC 8081

Screenshots

Dashboard · AI chat — a single entry point that switches between AI chat, cluster diagnosis, resource management, and message query, with model selection and MCP tool calls.

Consumer group management — the group list shows subscription mode, online clients, total lag, and consumption delay; expanding a row reveals per-Topic subscription consistency and filter expressions, alongside offset reset and config import/export.

Message query — search messages by Topic / Message Key / Message ID within a time range, then inspect details, trace, verification, or download a single message.

Features

Module	Capabilities
Dashboard	Global statistics for clusters, brokers, topics, and consumer groups with TPS trends
Instances	Multi-instance access (Proxy / Direct mode), instance CRUD
Clusters	Cluster details, Broker / NameServer / Proxy node operations, hot config updates, NameServer configuration drift detection
K8s Certs	Studio-local TLS / mTLS / ServiceAccount certificate configuration
Topics	Topic CRUD, route viewer, consumer list, multi-type support (Normal / FIFO / Delay / Transaction / Lite)
Consumer Groups	Consumer group CRUD, consumption progress, subscription details, offset reset, config import/export
ACL	ACL rules and user management, v1 / v2 dual version support
Messages	Query by Topic / MsgId / Key / time range, message trace visualization
Dead Letter Queue	DLQ message viewing and batch resend
Clients	Producer / Consumer online connection list, protocol and language version stats
Alert Rules	Multi-dimensional alert rules (disk / lag / TPS / node offline), DingTalk / email / SMS notifications
System Alerts	System-level alert viewing, acknowledgment, and cleanup
Audit Logs	Operation audit log query, filter by type / time / result, history cleanup
AI Assistant	Hosted-agent chat over SSE with server-side conversation history, visible chain of thought, and RocketMQ tool calls through the rmqctl MCP bridge; query / diagnose / manage / general modes
Settings	General preferences, LLM config, datasource management

AI Assistant

Studio hosts a general-purpose agent CLI — Claude Code or Qoder, plus a plain OpenAI-compatible HTTP engine — rather than implementing its own tool-calling loop. RocketMQ capabilities reach the agent through rmqctl, the Go CLI in this repository, running as an MCP stdio server that calls back into Studio's own MCP endpoint. The same signed, instance-scoped, risk-gated tool surface therefore serves the hosted agent, a developer typing rmqctl topic list, and any external agent pointed at the output of rmqctl mcp config. See docs/ai-agent-architecture.md for the design and its trade-offs.

• Conversations persist server-side and are browsable from the history drawer. Reloading or reconnecting replays exactly what the live stream rendered, because both paths reduce to the same block model.
• Chain of thought is displayed, with model reasoning kept separate from the optional prompt-enhancement rewrite.
• Tool calls render as cards showing arguments, output, duration and risk level. L2/L3 mutations go through preview → confirm token → apply; L3 tools stay disabled unless STUDIO_AI_ALLOW_L3_TOOLS=true.
• Multi-turn context uses the agent CLI's own session resume, so tool state and reasoning survive across turns.
• One button sends and stops. It is a send arrow while idle and a stop square while generating; stopping terminates the agent process and its rmqctl child rather than merely dropping the connection.
• Degrades to plain chat when rmqctl is missing or STUDIO_AI_RMQCTL_ENABLED=false, and says so in the transcript instead of failing silently.

Generation is decoupled from the HTTP connection: closing the tab does not kill a run, and reopening the conversation re-attaches to it. All AI-related environment variables are documented in deploy/.env.example.

Tech Stack

• Frontend — React 18 + TypeScript + Vite + Ant Design + Tailwind CSS
• Backend — Java 21 + Spring Boot 4.1 + Spring AI MCP 2.0 + MyBatis-Plus + Hexagonal Architecture (ArchUnit enforced)
• CLI — Go 1.27 (rmqctl), both the MCP bridge the hosted agent uses and a standalone signed client for the same tool surface
• Deployment — Docker multi-stage builds (JDK runtime plus a Go stage that compiles rmqctl into the image), Nginx reverse proxy, Docker Compose or deploy.sh for remote deployment

Development Guidelines

• Branches — rocketmq-studio is the development trunk: base your branches and pull requests on it. master_archive keeps the legacy dashboard history and is not used for development. See CONTRIBUTING.md for the full workflow
• Code Style — ESLint + Prettier for frontend, Husky pre-commit hook for auto-check
• Commit Format — Conventional Commits (feat: / fix: / refactor: / chore: / docs: / perf:)
• Architecture Tests — mvn test runs ArchUnit hexagonal architecture constraint checks
• i18n — New frontend text must include both Chinese and English translations (web/src/i18n/)
• Table Width — Tables must not show a horizontal scrollbar by default (only allowed when the window/container is manually narrowed); use tableScrollX(columns) from web/src/utils/table.ts to compute scroll.x from declared column widths instead of hardcoded magic numbers; when a modal contains a wide table, adjust the modal width dynamically per active tab (e.g., Group detail: Overview 800 / Progress 1080) so that container width ≥ table width; long-text columns (e.g., long Topic names) should use ellipsis: true + title for hover-to-see-full-name truncation (no wrapping)
• Action Column Width — Button-bearing action columns must be sized as "measured button row width + cell padding + right margin"; never shrink them by guesswork: ant-flex is a block-level container that stretches to fill the cell, so an undersized column pushes buttons against (or past) the table's right edge, causing flush edges or horizontal scrollbars; measure the actual button row width in DevTools before changing, and update the guarding test accordingly (e.g., TopicPage.test.tsx "keeps the action column wide enough")

License

Apache License 2.0