zhaohai666 opened a new pull request, #420:
URL: https://github.com/apache/rocketmq-dashboard/pull/420
# PR Title
**[RIP-1 + RIP-3] Control Plane 5.0 Unified Implementation: Core
Architecture Refactor + LLM Native Integration (CLI / MCP / Embedded Chat)**
---
## Summary
This PR delivers the full end-to-end implementation of RocketMQ Control
Plane 5.0 within the `apache/rocketmq-dashboard` repository, integrating
**RIP-1 (Unified Control Plane Architecture)** and **RIP-3 (LLM Native
Integration)** as a cohesive delivery unit.
It rebuilds the control plane with a standard three-layer abstraction
architecture, achieving unified management across 4.0 direct, 5.0 Proxy
Local/Cluster and cloud-managed clusters. Built entirely on top of RIP-1's core
abstractions, RIP-3 extends the control plane into three programmable,
AI-native interaction forms — `rmqctl` CLI, standard MCP Server, and in-console
embedded LLM chat — with a single unified tool schema as the single source of
truth. No independent backend APIs are introduced for RIP-3; all capabilities
share the same metadata, auth and observability stack from RIP-1.
---
## 1. Background & Motivation
The existing `rocketmq-dashboard v2.1.0` faces structural limitations in the
cloud-native and AI-Native era:
1. **Architecture entanglement**: 4.0 and 5.0 code paths are deeply coupled,
lacking standardized abstraction layers, causing recurring compatibility
defects (#390, #401, #402, #403).
2. **Fragmented interaction modes**: Only Web UI is provided, with no
standardized CLI or API surface for scripting, automation and third-party
system integration.
3. **Zero AI agent accessibility**: No standard protocol for LLM agents /
IDE copilots to invoke RocketMQ O&M capabilities, forcing teams to build custom
wrappers.
4. **Inconsistent observability & auth**: No unified Prometheus integration;
ACL 1.0 and 2.0 adaptation is incomplete for multi-architecture clusters.
This PR resolves the above issues in one go: RIP-1 lays the solid underlying
architecture foundation, and RIP-3 extends the capability boundary to human +
AI dual-target interaction modes, fully reusing the underlying layer without
redundant construction.
---
## 2. Core Architecture & Design Principles
### 2.1 Three-Layer Abstraction (RIP-1 Foundation)
```
┌─────────────────────────────────────────────────────────────┐
│ Business Layer (RIP-1 Web UI + RIP-3 CLI / MCP / LLM Chat) │
│ Capability-driven dynamic rendering & multi-modal access │
└───────────────────────────┬─────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────┐
│ MetadataProvider Domain Layer (META-01) │
│ Namespace / Topic / Group / ACL / Client / LiteTopic │
│ Cloud vendor SPI extension point │
└───────────────────────────┬─────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────┐
│ AdminClient Protocol Layer (ARCH-01) │
│ Remoting / gRPC / Cloud OpenAPI multi-protocol support │
│ Standard auth hook injection (AUTH-01) │
└───────────────────────────┬─────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
4.0 NameSrv+Broker 5.0 Proxy Cluster Cloud Mgmt API
```
### 2.2 Key Design Principles
1. **Single source of truth**: All interaction forms (Web, CLI, MCP) share
the same `MetadataProvider`, `AdminClient` and tool schema — zero capability
drift.
2. **Capability-driven UI**: Menus, form fields and available tools are
dynamically rendered based on cluster capability set, avoiding "visible but
unusable" entries.
3. **Security by default**: Three-tier risk classification (L1/L2/L3)
applied consistently across Web, CLI and MCP; dry-run two-phase execution for
all mutation operations.
4. **Full backward compatibility**: 100% parity with v2.1.0 features; 4.0
clusters work out of the box with no configuration changes.
5. **Graceful degradation**: All advanced features (5.0-specific, LLM)
degrade smoothly on unsupported clusters or configurations.
---
## 3. Detailed Changes
### Part A: RIP-1 — Control Plane 5.0 Core Modules
Six fully delivered modules:
| Module ID | Module Name | Key Deliverables |
|-----------|-------------|------------------|
| **BASE-01** | Baseline Parity | Full migration of all 11 categories of
v2.1.0 capabilities; fixes for 7 critical defects (#380, #381, #390, #401,
#402, #403, #407) |
| **ARCH-01** | Multi-Architecture Support | `ClusterProvider`,
`AdminClient`, `MetadataProvider` SPI abstractions; implementations for
v4-namesrv / v5-proxy-local / v5-proxy-cluster / cloud modes; runtime
architecture switching |
| **META-01** | Metadata Management | Namespace CRUD & resource tree
navigation; strong-type management for 5 Topic types
(NORMAL/FIFO/DELAY/TRANSACTION/LITE); prefix-aggregated LiteTopic lifecycle
management; cloud vendor SPI extension point |
| **AUTH-01** | Full-Chain ACL | Dual adaptation for ACL 1.0 (Remoting) and
ACL 2.0 (gRPC); hybrid mode auto-detection; encrypted credential storage at
cluster granularity; hot-reload support; audit logging quadruplet |
| **CLIENT-01** | Dual-Protocol Clients | Protocol-agnostic unified client
view (Remoting + gRPC); client detail drawer with subscriptions, heartbeat
timeline and consumption progress; compatible with both transition view
(telemetry metrics) and RIP-2 final view |
| **METRICS-01** | Observability | Prometheus datasource integration; PromQL
proxy with auth & audit; 10+ built-in standard dashboards; Grafana JSON
one-click export; 20+ built-in alert rule templates |
### Part B: RIP-3 — LLM Native Integration (Built 100% on RIP-1 Abstractions)
> **No independent backend APIs are added.** All RIP-3 capabilities directly
reuse RIP-1's `MetadataProvider`, `AdminClient` and `AUTH-01` authentication
chain.
#### Phase 1: `rmqctl` CLI
- 30 tools across 9 resource groups (cluster, namespace, topic, group,
message, client, acl, broker, metrics)
- kubectl-style multi-cluster context management, config persisted at
`~/.rmqctl/config.yaml`
- Structured output: `table` / `json` / `yaml`; unified structured error
model `{code, message, hint}`
- Three-tier risk enforcement:
- L1 (read-only): silent execution
- L2 (controlled mutation): default dry-run preview, apply after
confirmation
- L3 (dangerous): blocked by default, requires `--yes --force` explicit
opt-in
- Local audit logging and encrypted credential storage
#### Phase 2: Standard MCP Server
- 1:1 tool mapping with CLI commands (`rmqctl topic create` →
`rmq.topic.create`), zero schema drift
- Dual transport support: `stdio` for local AI clients (Claude Desktop,
Cursor, etc.) and `SSE` for web scenarios
- `rmq.capabilities` capability detection tool — LLM perceives cluster
feature boundaries to avoid hallucination
- Built-in SecurityGate enforcing L1/L2/L3 rules and dry-run/apply two-phase
execution
- Reuses RIP-1 AUTH-01 auth chain for all tool calls
#### Phase 3: Console Embedded LLM Chat
- 3 entry points: homepage full-width command bar, global `Cmd/Ctrl+K`
shortcut overlay, detail-page sidebar chat with auto context injection
- Backend MCP Bridge: all LLM calls go through backend proxy, API keys are
never exposed to frontend
- Structured result rendering with native UI components and deep links to
corresponding resource detail pages
- Consistent safety guardrails with CLI/MCP: L1 silent, L2 dry-run
confirmation, L3 rejected with manual page guidance
- Graceful degradation: falls back to global search when no LLM provider is
configured
- 6 supported providers: OpenAI, Azure OpenAI, AWS Bedrock, DeepSeek, Tongyi
(Qwen), Ollama (local)
---
## 4. Cross-RIP Synergy Highlights
1. **Unified auth**: CLI, MCP and Web Console all share the same AUTH-01
credential system and permission model.
2. **Unified capability model**: All interaction forms follow the same
cluster capability set — 4.0 clusters automatically hide 5.0-only tools and
menus.
3. **Unified observability**: `rmqctl metrics query`, MCP
`rmq.metrics.query` and Web dashboards all reuse METRICS-01 PromQL proxy.
4. **Unified client view**: Client query capabilities in CLI and MCP
directly reuse CLIENT-01 aggregation logic.
5. **Unified audit**: All write operations from Web/CLI/MCP generate
standardized audit logs with source marking.
---
## 5. Repository Structure (rocketmq-dashboard)
```
rocketmq-dashboard/
├── src/main/java/.../architecture/ # RIP-1 ARCH-01: SPI
abstractions
│ └── impl/ # RIP-1 ARCH-01: V4/V5/Cloud
implementations
├── src/main/java/.../service/ # RIP-1: Core service layer (6
modules)
├── src/main/java/.../controller/ # RIP-1: REST controllers
├── rocketmq-dashboard-app/ # Main Spring Boot application
(Web Console)
├── rocketmq-dashboard-cli/ # RIP-3 P1: rmqctl CLI module
├── rocketmq-dashboard-mcp/ # RIP-3 P2: MCP Server module
├── rocketmq-dashboard-llm/ # RIP-3 P3: LLM Bridge & MCP
Bridge
├── frontend-new/
│ ├── src/components/llm/ # RIP-3 P3: Chat UI components
│ └── src/pages/LlmSettings/ # RIP-3 P3: LLM provider config
page
└── docs/rip/
├── rip-1-control-plane-5.0.md
└── rip-3-llm-native-integration.md
```
---
## 6. Testing & Verification
| Module | Test Coverage | Status |
|--------|---------------|--------|
| RIP-1 Core (ARCH/META/AUTH/CLIENT/METRICS) | 40 test files, all interfaces
and core logic verified | ✅ All passed |
| RIP-3 CLI (rmqctl) | 161 tests, ~80% instruction coverage | ✅ All passed |
| RIP-3 MCP Server | 101 tests, ~81% instruction coverage | ✅ All passed |
| RIP-3 Console LLM Backend | 98 tests, all REST endpoints + filters +
providers verified | ✅ All passed |
| End-to-end integration | Full workflow verification on 4.0 / 5.0-Local /
5.0-Cluster clusters | ✅ All passed |
---
## 7. Compatibility & Upgrade Notes
1. **Full backward compatibility**: All v2.1.0 REST APIs and features remain
available; existing users can upgrade without business impact.
2. **Multi-architecture auto-adaptation**: Automatically detects cluster
type and dynamically adjusts available features.
3. **Optional features**: CLI, MCP and LLM chat are all optional modules
that can be disabled via configuration for compliance-sensitive environments.
4. **Smooth RIP-2 transition**: CLIENT-01 works with telemetry metrics
today, and will seamlessly switch to RIP-2 Proxy Admin final view once RIP-2 is
released.
---
## 8. Acceptance Checklist
### RIP-1
- [x] ARCH-01: Three-layer SPI abstractions + V4/V5/Cloud implementations +
runtime switching
- [x] BASE-01: 100% v2.1.0 feature parity + 7 defect fixes
- [x] META-01: Namespace, 5 topic types, LiteTopic management, Cloud SPI
- [x] AUTH-01: ACL 1.0 + 2.0 dual adaptation, encrypted credentials,
hot-reload
- [x] CLIENT-01: Remoting + gRPC unified client view, detail drawer
- [x] METRICS-01: Prometheus integration, 10+ dashboards, alert rules
### RIP-3
- [x] CLI: 30 tools, multi-cluster context, structured output, dry-run safety
- [x] MCP Server: stdio/SSE dual transport, capability detection,
SecurityGate
- [x] Console LLM: 3 entry points, MCP Bridge, structured results, safety
guardrails
- [x] 100% reuse of RIP-1 abstractions, no duplicate backend logic
- [x] Graceful degradation for unconfigured LLM and 4.0 clusters
---
### Related Work
- **RIP-2 (Proxy Admin API)**: Companion implementation in `apache/rocketmq`
main repository. This PR's CLIENT-01 is compatible with both current transition
view and upcoming RIP-2 final view.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
