This is an automated email from the ASF dual-hosted git repository. lizhimins pushed a commit to branch rocketmq-studio in repository https://gitbox.apache.org/repos/asf/rocketmq-dashboard.git
commit ef1596d0f15d45583dca9969155b095cc2104633 Author: lizhimins <[email protected]> AuthorDate: Wed Jul 8 10:12:00 2026 +0800 docs: add deployment config and bilingual README - Add Docker Compose deployment setup - Add Nginx reverse proxy configuration - Add deployment scripts and env templates - Add API specification document - Write bilingual README (English + Chinese) - Add project overview, architecture, and quick start guide --- README.md | 56 ++ README_zh.md | 56 ++ deploy/.env.example | 8 + deploy/README.md | 28 + deploy/deploy.sh | 185 +++++ deploy/docker-compose.yml | 24 + deploy/nginx.conf | 20 + docs/api-spec.md | 1696 +++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 2073 insertions(+) diff --git a/README.md b/README.md new file mode 100644 index 0000000..b4260eb --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# RocketMQ Studio + +**English** | [中文](README_zh.md) + +> Cross-cluster · Cross-architecture · Cross-cloud unified RocketMQ management platform + +RocketMQ Studio is a unified management platform for RocketMQ, supporting multi-cluster, multi-architecture, and multi-cloud 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. + +## Quick Start + +```bash +cd deploy && docker compose up -d --build +``` + +Visit **http://127.0.0.1:6789** after startup. + +**Studio ports:** Frontend 6789 (Nginx), Backend 8888 (Spring Boot) + +**RocketMQ ports:** NameServer 9876, Broker 10911, Proxy Remoting 8080, Proxy gRPC 8081 + +## 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 | +| **K8s Certs** | TLS / mTLS / ServiceAccount certificate management and renewal | +| **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** | SSE streaming chat, supports query / diagnose / manage / general modes, MCP tool integration | +| **Settings** | General preferences, LLM config, datasource management | + +## Tech Stack + +- **Frontend** — React 18 + TypeScript + Vite + Ant Design + Tailwind CSS +- **Backend** — Java 21 + Spring Boot 3.5 + Hexagonal Architecture (ArchUnit enforced) +- **Deployment** — Docker multi-stage builds, Nginx reverse proxy, Docker Compose or `deploy.sh` for remote deployment + +## Development Guidelines + +- **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/`) + +## License + +[Apache License 2.0](LICENSE) diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..a2a9319 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,56 @@ +# RocketMQ Studio + +[English](README.md) | **中文** + +> 跨集群 · 跨架构 · 跨云的 RocketMQ 统一管控平台 + +RocketMQ Studio 是一个面向多集群、多架构、多云环境的 RocketMQ 管控平台，提供实例管理、集群运维、Topic / 消费组 CRUD、ACL 权限管控、消息查询与轨迹追踪、死信队列处理、监控告警、审计日志以及 AI 智能助手等一站式能力。 + +## 一键构建 & 运行 + +```bash +cd deploy && docker compose up -d --build +``` + +启动后访问 **http://127.0.0.1:6789** 即可使用。 + +**Studio 服务端口：** 前端 6789（Nginx）、后端 8888（Spring Boot） + +**RocketMQ 服务端端口：** NameServer 9876、Broker 10911、Proxy Remoting 8080、Proxy gRPC 8081 + +## 功能概览 + +| 模块 | 能力 | +|------|------| +| **监控面板** | 集群/ Broker / Topic / 消费组全局统计，TPS 趋势图 | +| **实例管理** | 多实例接入（Proxy / Direct 模式），实例 CRUD | +| **集群管理** | 集群详情、Broker / NameServer / Proxy 节点运维、集群配置热更新 | +| **K8s 证书** | TLS / mTLS / ServiceAccount 证书管理与续期 | +| **Topic 管理** | Topic CRUD、路由查看、消费者列表、多类型支持（Normal / FIFO / Delay / Transaction / Lite） | +| **消费组管理** | 消费组 CRUD、消费进度、订阅详情、位点重置、配置导入导出 | +| **ACL 权限** | ACL 规则与用户管理，支持 v1 / v2 双版本 | +| **消息查询** | 按 Topic / MsgId / Key / 时间范围查询，消息轨迹可视化 | +| **死信队列** | DLQ 消息查看与批量重发 | +| **客户端连接** | Producer / Consumer 在线连接列表，协议与语言版本统计 | +| **告警规则** | 多维度告警规则配置（磁盘 / 堆积 / TPS / 节点离线），支持钉钉 / 邮件 / 短信通知 | +| **系统告警** | 系统级告警查看、确认与清理 | +| **审计日志** | 操作审计日志查询、按类型 / 时间 / 结果过滤、历史清理 | +| **AI 助手** | SSE 流式对话，支持查询 / 诊断 / 管控 / 通用多模式，MCP 工具集成 | +| **系统设置** | 通用偏好设置、LLM 配置、数据源管理 | + +## 技术栈 + +- **前端** — React 18 + TypeScript + Vite + Ant Design + Tailwind CSS +- **后端** — Java 21 + Spring Boot 3.5 + 六边形架构（ArchUnit 约束） +- **部署** — Docker 多阶段构建，Nginx 反向代理，支持 Docker Compose 本地运行或 `deploy.sh` 远程部署 + +## 开发规范 + +- **代码风格** — 前端通过 ESLint + Prettier 统一格式，Husky pre-commit hook 自动检查 +- **Commit 格式** — 遵循 Conventional Commits（`feat:` / `fix:` / `refactor:` / `chore:` / `docs:` / `perf:`） +- **架构测试** — 后端 `mvn test` 自动运行 ArchUnit 六边形架构约束检查 +- **国际化** — 新增前端文案需同时提供中英文翻译（`web/src/i18n/`） + +## License + +[Apache License 2.0](LICENSE) diff --git a/deploy/.env.example b/deploy/.env.example new file mode 100644 index 0000000..16b8e6e --- /dev/null +++ b/deploy/.env.example @@ -0,0 +1,8 @@ +# RocketMQ Studio Docker Environment +# Remote deployment target +REMOTE_HOST=101.37.235.82 +REMOTE_USER=root +REMOTE_PATH=/opt/rocketmq-studio + +# Frontend public port +PUBLIC_PORT=6789 diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..c02c26a --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,28 @@ +# 部署 + +## 一键部署 + +```bash +./deploy/deploy.sh # 部署 server + web +./deploy/deploy.sh server # 仅部署后端 +./deploy/deploy.sh web # 仅部署前端 +``` + +脚本自动完成：本地构建 → 导出镜像 → SCP 传输 → 远程加载 → 重启容器 → 验证 + +## 配置 + +编辑 `deploy/.env` 修改部署目标： + +```env +REMOTE_HOST=101.37.235.82 +REMOTE_USER=root +REMOTE_PATH=/opt/rocketmq-studio +PUBLIC_PORT=8080 +``` + +## 前置条件 + +- 本地安装 Docker +- 远程机器可通过 SSH 免密登录 +- 远程机器已安装 Podman（Alibaba Cloud Linux 3 默认提供） diff --git a/deploy/deploy.sh b/deploy/deploy.sh new file mode 100755 index 0000000..a67c810 --- /dev/null +++ b/deploy/deploy.sh @@ -0,0 +1,185 @@ +#!/usr/bin/env bash +set -euo pipefail + +# ─── RocketMQ Studio 一键部署脚本 ─── +# 用法: +# ./deploy/deploy.sh # 部署 server + web +# ./deploy/deploy.sh server # 仅部署 server +# ./deploy/deploy.sh web # 仅部署 web + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" + +# 加载配置 +if [[ -f "$SCRIPT_DIR/.env" ]]; then + set -a + # shellcheck disable=SC1091 + source "$SCRIPT_DIR/.env" + set +a +fi + +[[ -n "${REMOTE_HOST:-}" ]] || err "REMOTE_HOST 未配置，请在 deploy/.env 中设置" +REMOTE="${REMOTE_USER:-root}@$REMOTE_HOST" +REMOTE_PATH="${REMOTE_PATH:-/opt/rocketmq-studio}" +NETWORK="${PODMAN_NETWORK:-rocketmq-studio}" +TMP_DIR="/tmp/rocketmq-studio-deploy" + +TARGET="${1:-all}" # all | server | web + +# ─── 颜色输出 ─── +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +CYAN='\033[0;36m' +NC='\033[0m' + +log() { echo -e "${GREEN}[✓]${NC} $*"; } +info() { echo -e "${CYAN}[→]${NC} $*"; } +warn() { echo -e "${YELLOW}[!]${NC} $*"; } +err() { echo -e "${RED}[✗]${NC} $*"; exit 1; } + +# ─── 前置检查 ─── +check_prereqs() { + info "检查前置条件..." + command -v docker >/dev/null 2>&1 || err "docker 未安装" + command -v ssh >/dev/null 2>&1 || err "ssh 未安装" + command -v scp >/dev/null 2>&1 || err "scp 未安装" + ssh -o ConnectTimeout=5 -o BatchMode=yes "$REMOTE" "echo ok" >/dev/null 2>&1 \ + || err "无法 SSH 连接到 $REMOTE（请确认免密登录已配置）" + log "前置条件通过" +} + +# ─── 构建镜像 ─── +build_server() { + info "构建 rocketmq-server 镜像..." + docker build -t rocketmq-server:latest "$PROJECT_DIR/server" + log "rocketmq-server 镜像构建完成" +} + +build_web() { + info "构建 rocketmq-web 镜像..." + docker build -t rocketmq-web:latest "$PROJECT_DIR/web" + log "rocketmq-web 镜像构建完成" +} + +# ─── 导出 & 传输 ─── +transfer_images() { + mkdir -p "$TMP_DIR" + local images=() + + if [[ "$TARGET" == "all" || "$TARGET" == "server" ]]; then + images+=("rocketmq-server:latest") + fi + if [[ "$TARGET" == "all" || "$TARGET" == "web" ]]; then + images+=("rocketmq-web:latest") + fi + + local tarball="$TMP_DIR/rocketmq-studio-images.tar.gz" + info "导出镜像: ${images[*]}" + docker save "${images[@]}" | gzip > "$tarball" + log "镜像导出完成 ($(du -h "$tarball" | cut -f1))" + + info "传输到 $REMOTE:$REMOTE_PATH ..." + ssh "$REMOTE" "mkdir -p $REMOTE_PATH" + scp "$tarball" "$REMOTE:$REMOTE_PATH/" + log "传输完成" + + # 同步部署配置文件 + info "同步部署配置..." + scp "$SCRIPT_DIR/docker-compose.yml" "$REMOTE:$REMOTE_PATH/" + scp "$SCRIPT_DIR/nginx.conf" "$REMOTE:$REMOTE_PATH/" + log "配置同步完成" +} + +# ─── 远程加载 & 启动 ─── +deploy_remote() { + local tarball="$REMOTE_PATH/rocketmq-studio-images.tar.gz" + + info "远程加载镜像..." + ssh "$REMOTE" "gunzip -c $tarball | podman load" + log "镜像加载完成" + + # 确保网络存在 + ssh "$REMOTE" "podman network exists $NETWORK 2>/dev/null || podman network create $NETWORK" + + if [[ "$TARGET" == "all" || "$TARGET" == "server" ]]; then + info "重启 rocketmq-server..." + ssh "$REMOTE" " + podman rm -f rocketmq-server 2>/dev/null || true + podman run -d \ + --name rocketmq-server \ + --network $NETWORK \ + --restart unless-stopped \ + -p 8888:8888 \ + rocketmq-server:latest + " + log "rocketmq-server 已启动" + fi + + if [[ "$TARGET" == "all" || "$TARGET" == "web" ]]; then + info "重启 rocketmq-web..." + ssh "$REMOTE" " + podman rm -f rocketmq-web 2>/dev/null || true + podman run -d \ + --name rocketmq-web \ + --network $NETWORK \ + --restart unless-stopped \ + -p ${PUBLIC_PORT:-6789}:80 \ + rocketmq-web:latest + " + log "rocketmq-web 已启动" + fi +} + +# ─── 验证 ─── +verify() { + info "验证部署..." + sleep 3 + + local status + status=$(ssh "$REMOTE" "podman ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'" 2>&1) + echo "$status" + + echo "" + local http_code + http_code=$(ssh "$REMOTE" "curl -sf -o /dev/null -w '%{http_code}' --max-time 5 http://localhost:${PUBLIC_PORT:-6789}"; 2>/dev/null || echo "000") + if [[ "$http_code" == "200" ]]; then + log "前端响应正常 (HTTP $http_code)" + else + warn "前端返回 HTTP $http_code" + fi + + echo "" + log "部署完成 → http://${REMOTE_HOST}:${PUBLIC_PORT:-6789}"; +} + +# ─── 清理临时文件 ─── +cleanup() { + rm -rf "$TMP_DIR" +} + +# ─── 主流程 ─── +main() { + echo "═══════════════════════════════════════════" + echo " RocketMQ Studio 部署" + echo " 目标: $TARGET | 远程: $REMOTE:$REMOTE_PATH" + echo "═══════════════════════════════════════════" + echo "" + + check_prereqs + + case "$TARGET" in + server) build_server ;; + web) build_web ;; + all) build_server && build_web ;; + *) err "用法: $0 [all|server|web]" ;; + esac + + transfer_images + deploy_remote + verify + cleanup +} + +trap cleanup EXIT +main diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml new file mode 100644 index 0000000..1fe68bd --- /dev/null +++ b/deploy/docker-compose.yml @@ -0,0 +1,24 @@ +name: rocketmq-studio + +services: + rocketmq-server: + build: + context: ../server + dockerfile: Dockerfile + image: rocketmq-server:latest + container_name: rocketmq-server + restart: unless-stopped + expose: + - "8888" + + rocketmq-web: + build: + context: ../web + dockerfile: Dockerfile + image: rocketmq-web:latest + container_name: rocketmq-web + restart: unless-stopped + ports: + - "6789:80" + depends_on: + - rocketmq-server diff --git a/deploy/nginx.conf b/deploy/nginx.conf new file mode 100644 index 0000000..165c0f9 --- /dev/null +++ b/deploy/nginx.conf @@ -0,0 +1,20 @@ +server { + listen 80; + server_name _; + + location / { + root /usr/share/nginx/html; + index index.html; + try_files $uri $uri/ /index.html; + } + + location /api/ { + resolver 10.89.0.1 valid=10s; + set $backend http://rocketmq-server:8888; + proxy_pass $backend; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} diff --git a/docs/api-spec.md b/docs/api-spec.md new file mode 100644 index 0000000..581e8d0 --- /dev/null +++ b/docs/api-spec.md @@ -0,0 +1,1696 @@ +<!-- +请更新 docs/api-spec.md 接口文档，基于以下数据源： +1. 读取 web/src/mock/ 下所有 .ts 文件，提取每个文件的 interface/type 定义和 mock 数据的字段、类型、示例值 +2. 读取 web/src/pages/ 下所有页面组件，提取： + - Table columns 定义（title、dataIndex、render 函数） + - 表单字段（Form.Item 的 name、label、component、validation） + - 过滤/搜索参数 + - CRUD 操作（按钮、modal、调用逻辑） + - 分页配置（pageSize、showSizeChanger） +3. 读取 web/src/api/ 下所有 API 客户端文件，提取已有的 endpoint URL 和参数 +4. 读取 web/src/constants/ 下的枚举映射（如 TOPIC_TYPE_MAP、STATUS_MAP） +5. 将以上信息整合为 GET+POST 风格 API 文档，每个接口包含： + - HTTP Method + Path + - Query Parameters / Path Parameters / Request Body（字段、类型、必填、说明） + - Response data 字段定义（字段、类型、说明、示例值） + - 枚举值在附录 A 统一列出 +6. 保持接口速查表与实际接口数量一致 +7. 如果前端新增了页面或 mock 数据，在对应模块章节下新增接口 +8. 如果前端删除了页面或字段，同步移除对应接口或字段 +--> + +# RocketMQ Studio API 接口规范 + +> 本文档基于前端页面所需展示的全部数据和格式编写，用于指导后端 Java 代码开发。 +> +> Base URL: `/api` +> Content-Type: `application/json` +> 认证方式: `Authorization: Bearer <token>` + +## 接口设计风格 + +本项目采用 **GET + POST** 风格（非完整 RESTful），具体规则如下： + +- **GET** 用于所有查询/读取操作 +- **POST** 用于所有写入/操作类接口（创建、更新、删除、重启等） +- URL 路径使用动词标识操作类型：`/create`、`/update`、`/delete`、`/toggle`、`/restart`、`/cleanup` 等 +- POST 操作如需定位特定资源，在 **Request Body** 中传递 `id` 或 `name`（不放在 URL 路径中） +- GET 操作仍使用 Path Params 标识资源（如 `GET /api/topics/:name/routes`） + +## 接口速查 + +| # | Method | Path | 说明 | +|---|--------|------|------| +| 1 | POST | `/api/auth/login` | 登录 | +| 2 | POST | `/api/auth/logout` | 登出 | +| 3 | GET | `/api/dashboard` | 面板数据（统计 + 集群概览） | +| 4 | GET | `/api/instances` | 实例列表 | +| 5 | POST | `/api/instances/create` | 创建实例 | +| 6 | POST | `/api/instances/update` | 更新实例 | +| 7 | POST | `/api/instances/delete` | 删除实例 | +| 8 | GET | `/api/clusters` | 集群列表 | +| 9 | GET | `/api/clusters/:id` | 集群详情 | +| 10 | POST | `/api/clusters/config/update` | 更新集群配置 | +| 11 | POST | `/api/clusters/:clusterId/brokers/:name/restart` | 重启 Broker | +| 12 | POST | `/api/nameservers/create` | 创建 NameServer | +| 13 | POST | `/api/nameservers/update` | 更新 NameServer | +| 14 | POST | `/api/nameservers/restart` | 重启 NameServer | +| 15 | POST | `/api/nameservers/upgrade` | 升级 NameServer | +| 16 | POST | `/api/nameservers/delete` | 删除 NameServer | +| 17 | POST | `/api/proxies/restart` | 重启 Proxy | +| 18 | GET | `/api/k8s-certs` | K8s 证书列表 | +| 19 | POST | `/api/k8s-certs/create` | 添加证书 | +| 20 | POST | `/api/k8s-certs/update` | 更新证书 | +| 21 | POST | `/api/k8s-certs/renew` | 续期证书 | +| 22 | POST | `/api/k8s-certs/delete` | 删除证书 | +| 23 | GET | `/api/topics` | Topic 列表 | +| 24 | POST | `/api/topics/create` | 创建 Topic | +| 25 | POST | `/api/topics/update` | 更新 Topic | +| 26 | POST | `/api/topics/delete` | 删除 Topic | +| 27 | GET | `/api/topics/:name/routes` | Topic 路由 | +| 28 | GET | `/api/topics/:name/consumers` | Topic 消费者 | +| 29 | POST | `/api/topics/send` | 发送消息到 Topic | +| 30 | GET | `/api/groups` | 消费组列表 | +| 31 | GET | `/api/groups/:name` | 消费组详情 | +| 32 | GET | `/api/groups/:name/progress` | 消费进度 | +| 33 | GET | `/api/groups/:name/subscriptions` | 订阅详情 | +| 34 | POST | `/api/groups/create` | 创建消费组 | +| 35 | POST | `/api/groups/delete` | 删除消费组 | +| 36 | POST | `/api/groups/reset-offset` | 重置位点 | +| 37 | POST | `/api/groups/import` | 导入配置 | +| 38 | GET | `/api/groups/export` | 导出配置 | +| 39 | GET | `/api/acl/rules` | ACL 规则列表 | +| 40 | POST | `/api/acl/rules/create` | 创建 ACL 规则 | +| 41 | POST | `/api/acl/rules/delete` | 删除 ACL 规则 | +| 42 | GET | `/api/acl/users` | ACL 用户列表 | +| 43 | POST | `/api/acl/users/create` | 创建 ACL 用户 | +| 44 | POST | `/api/acl/users/delete` | 删除 ACL 用户 | +| 45 | GET | `/api/messages` | 消息查询 | +| 46 | GET | `/api/messages/:msgId/trace` | 消息轨迹 | +| 47 | GET | `/api/dlq` | 死信队列列表 | +| 48 | POST | `/api/dlq/resend` | 重发死信 | +| 49 | GET | `/api/clients` | 客户端连接列表 | +| 50 | GET | `/api/alert-rules` | 告警规则列表 | +| 51 | POST | `/api/alert-rules/create` | 创建告警规则 | +| 52 | POST | `/api/alert-rules/update` | 更新告警规则 | +| 53 | POST | `/api/alert-rules/toggle` | 切换启用状态 | +| 54 | POST | `/api/alert-rules/delete` | 删除告警规则 | +| 55 | GET | `/api/system-alerts` | 系统告警列表 | +| 56 | POST | `/api/system-alerts/acknowledge` | 确认告警 | +| 57 | POST | `/api/system-alerts/clear-acknowledged` | 清除已确认告警 | +| 58 | GET | `/api/audit-logs` | 审计日志列表 | +| 59 | POST | `/api/audit-logs/cleanup` | 清理审计日志 | +| 60 | GET | `/api/settings/general` | 获取通用设置 | +| 61 | POST | `/api/settings/general/save` | 保存通用设置 | +| 62 | GET | `/api/settings/datasources` | 数据源列表 | +| 63 | POST | `/api/settings/datasources/create` | 创建数据源 | +| 64 | POST | `/api/settings/datasources/update` | 更新数据源 | +| 65 | POST | `/api/settings/datasources/delete` | 删除数据源 | +| 66 | POST | `/api/settings/datasources/test` | 测试数据源连接 | +| 67 | POST | `/api/ai/chat` | AI 对话（SSE） | +| 68 | POST | `/api/ai/execute` | 执行 AI 指令 | +| 69 | GET | `/api/ai/tools` | 可用工具列表 | +| 70 | POST | `/api/metrics/query` | 查询监控指标数据 | + +## 通用响应格式 + +所有接口统一返回以下 JSON 结构： + +```json +{ + "code": 200, + "message": "success", + "data": {} +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `code` | `int` | 200 表示成功，与 HTTP 状态码对齐 | +| `message` | `string` | 提示信息 | +| `data` | `any` | 响应数据 | + +**错误码规范：** + +| 错误码 | 含义 | 场景 | +|--------|------|------| +| `200` | 成功 | 正常响应 | +| `400` | 参数错误 | 请求参数缺失或格式错误 | +| `401` | 未认证 | Token 过期或缺失 | +| `403` | 无权限 | 无权访问该资源 | +| `404` | 不存在 | 资源未找到 | +| `500` | 服务器异常 | 未预期的内部错误 | + +--- + +## 1. 认证 Auth + +### 1.1 登录 + +``` +POST /api/auth/login +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `username` | `string` | 是 | 用户名 | +| `password` | `string` | 是 | 密码 | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `token` | `string` | JWT Token | +| `expiresIn` | `number` | 过期时间（秒） | +| `user` | `object` | 用户信息 | +| `user.username` | `string` | 用户名 | +| `user.admin` | `boolean` | 是否管理员 | + +### 1.2 登出 + +``` +POST /api/auth/logout +``` + +**Response `data`:** `null` + +--- + +## 2. 监控面板 Dashboard + +### 2.1 获取面板数据（统计 + 集群概览） + +``` +GET /api/dashboard +``` + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `stats` | `DashboardStats` | 面板统计数据 | +| `clusters` | `ClusterOverview[]` | 集群概览列表 | + +**DashboardStats 字段：** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `totalClusters` | `number` | 集群总数 | +| `healthyClusters` | `number` | 健康集群数 | +| `totalBrokers` | `number` | Broker 总数（≥ 0） | +| `totalProxies` | `number` | Proxy 总数（≥ 0） | +| `totalNameServers` | `number` | NameServer 总数（≥ 0） | +| `totalTopics` | `number` | Topic 总数 | +| `totalConsumerGroups` | `number` | 消费组总数 | +| `totalMessagesToday` | `number` | 今日消息总量 | +| `messagesPerSecond` | `number` | 每秒消息数 | +| `tpsIn` | `number` | 入站 TPS | +| `tpsOut` | `number` | 出站 TPS | + +**ClusterOverview 字段：** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 集群 ID | +| `name` | `string` | 集群名称 | +| `type` | `string` | 集群类型，枚举: `V4_DIRECT` / `V5_PROXY_LOCAL` / `V5_PROXY_CLUSTER` | +| `status` | `string` | 状态: `healthy` / `warning` / `error` / `offline` | +| `brokers` | `number` | Broker 数量（≥ 0） | +| `proxies` | `number` | Proxy 数量（≥ 0，不会为负数） | +| `topics` | `number` | Topic 数量 | +| `groups` | `number` | 消费组数量 | +| `tpsIn` | `number` | 入站 TPS | +| `tpsOut` | `number` | 出站 TPS | +| `version` | `string` | RocketMQ 版本号 | +| `throughput` | `number[]` | TPS 趋势数据（12 个采样点） | + +**示例：** + +```json +{ + "stats": { + "totalClusters": 2, + "healthyClusters": 2, + "totalBrokers": 12, + "totalProxies": 5, + "totalNameServers": 5, + "totalTopics": 304, + "totalConsumerGroups": 152, + "totalMessagesToday": 18420000, + "messagesPerSecond": 85800, + "tpsIn": 85800, + "tpsOut": 222400 + }, + "clusters": [ + { + "id": "cluster-prod", + "name": "rocketmq-prod", + "type": "V5_PROXY_CLUSTER", + "status": "healthy", + "brokers": 8, + "proxies": 3, + "topics": 256, + "groups": 128, + "tpsIn": 78000, + "tpsOut": 203600, + "version": "5.2.0", + "throughput": [62000, 68000, 74000, 71000, 78000, 82000, 79000, 85000, 81000, 78000, 76000, 80000] + } + ] +} +``` + +--- + +### 3.1 获取实例列表 + +``` +GET /api/instances?type={type}&search={keyword} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `type` | `string` | 否 | 按类型过滤: `PROXY` / `DIRECT` | +| `search` | `string` | 否 | 按名称或地址搜索 | + +**Response `data`:** `Instance[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 实例 ID | +| `name` | `string` | 实例名称 | +| `remark` | `string` | 备注 | +| `type` | `string` | 接入类型: `PROXY` / `DIRECT` | +| `endpoint` | `string` | 接入地址 | +| `topicCount` | `number` | Topic 数量 | +| `consumerGroupCount` | `number` | 消费组数量 | +| `createdAt` | `string` | 创建时间 | +| `updatedAt` | `string` | 更新时间 | + +### 3.2 创建实例 + +``` +POST /api/instances/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 实例名称 | +| `type` | `string` | 是 | `PROXY` / `DIRECT` | +| `endpoint` | `string` | 是 | 接入地址 | + +**Response `data`:** `Instance` + +### 3.3 更新实例 + +``` +POST /api/instances/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 实例 ID | +| `name` | `string` | 是 | 实例名称 | +| `type` | `string` | 是 | `PROXY` / `DIRECT` | +| `endpoint` | `string` | 是 | 接入地址 | + +**Response `data`:** `Instance` + +### 3.4 删除实例 + +``` +POST /api/instances/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 实例 ID | + +**Response `data`:** `null` + +--- + +## 4. 集群管理 Cluster / NameServer / Proxy + +> 前端在同一个页面展示，因此 API 合并在此章节。 + +### 4.1 获取集群列表 + +``` +GET /api/clusters +``` + +**Response `data`:** `ClusterInfo[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 集群 ID | +| `name` | `string` | 集群名称 | +| `nsClusterName` | `string` | NameServer 集群名 | +| `type` | `string` | 集群类型，枚举: `V5_PROXY_CLUSTER` | +| `endpoint` | `string` | NameServer 地址，如 `10.101.2.1:9876` | +| `status` | `string` | 状态: `healthy` / `warning` / `error` / `offline` | +| `version` | `string` | 版本号 | +| `brokers` | `BrokerInfo[]` | Broker 节点列表 | +| `proxies` | `ProxyInfo[]` | Proxy 节点列表 | +| `nameServers` | `NameServerInfo[]` | NameServer 节点列表 | +| `config` | `ClusterConfig` | 集群配置 | +| `topicCount` | `number` | Topic 数量 | +| `groupCount` | `number` | 消费组数量 | +| `tpsHistory` | `number[]` | TPS 历史数据 | + +#### BrokerInfo + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `string` | Broker 名称 | +| `addr` | `string` | 地址，如 `10.101.2.11:10911` | +| `version` | `string` | 版本号 | +| `status` | `string` | 状态: `running` / `readonly` / `maintenance` | +| `diskUsage` | `number` | 磁盘使用率（0-100） | +| `tpsIn` | `number` | 入站 TPS | +| `tpsOut` | `number` | 出站 TPS | + +#### ProxyInfo + +| 字段 | 类型 | 说明 | +|------|------|------| +| `addr` | `string` | 地址 | +| `status` | `string` | 状态: `healthy` / `warning` / `error` / `offline` | +| `connections` | `number` | 当前连接数 | +| `grpcPort` | `number` | gRPC 端口 | +| `remotingPort` | `number` | Remoting 端口 | + +#### NameServerInfo + +| 字段 | 类型 | 说明 | +|------|------|------| +| `addr` | `string` | 地址，如 `10.101.2.1:9876` | +| `status` | `string` | 状态: `healthy` / `warning` / `error` / `offline` | + +#### ClusterConfig + +| 字段 | 类型 | 说明 | +|------|------|------| +| `writeQueueNums` | `number` | 写队列数 | +| `readQueueNums` | `number` | 读队列数 | +| `maxMessageSize` | `number` | 最大消息大小（字节） | +| `msgTraceTopicName` | `string` | 消息轨迹 Topic 名 | +| `autoCreateTopicEnable` | `boolean` | 是否自动创建 Topic | +| `autoCreateSubscriptionGroup` | `boolean` | 是否自动创建订阅组 | +| `deleteWhen` | `string` | 删除时间，如 `"04"` | +| `fileReservedTime` | `number` | 文件保留时间（小时） | +| `flushDiskType` | `string` | 刷盘方式: `ASYNC_FLUSH` / `SYNC_FLUSH` | +| `brokerPermission` | `number` | Broker 权限值（6 = 读写） | + +### 4.2 获取集群详情 + +``` +GET /api/clusters/:id +``` + +**Response `data`:** `ClusterInfo`（同 4.1 的单条记录） + +### 4.3 更新集群配置 + +``` +POST /api/clusters/config/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 集群 ID | +| `flushDiskType` | `string` | 是 | `ASYNC_FLUSH` / `SYNC_FLUSH` | +| `autoCreateTopicEnable` | `boolean` | 是 | 自动创建 Topic | +| `autoCreateSubscriptionGroup` | `boolean` | 是 | 自动创建订阅组 | +| `maxMessageSize` | `number` | 是 | 最大消息大小（字节） | +| `fileReservedTime` | `number` | 是 | 文件保留时间（小时，1-720） | +| `writeQueueNums` | `number` | 是 | 写队列数（1-256） | +| `readQueueNums` | `number` | 是 | 读队列数（1-256） | +| `brokerPermission` | `number` | 是 | Broker 权限（0-7） | + +**Response `data`:** `null` + +### 4.4 重启 Broker + +``` +POST /api/clusters/:clusterId/brokers/:name/restart +``` + +**Path Parameters:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `clusterId` | `string` | 集群 ID | +| `name` | `string` | Broker 名称 | + +**Response `data`:** `{ success: boolean, message: string }` + +### 4.5 创建 NameServer + +``` +POST /api/nameservers/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 是 | 所属集群 ID | +| `addr` | `string` | 是 | NameServer 地址，如 `10.0.1.1:9876` | + +**Response `data`:** `NameServerInfo` + +### 4.6 更新 NameServer + +``` +POST /api/nameservers/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 是 | 所属集群 ID | +| `addr` | `string` | 是 | 原地址 | +| `newAddr` | `string` | 否 | 新地址（不传则不修改） | + +**Response `data`:** `NameServerInfo` + +### 4.7 重启 NameServer + +``` +POST /api/nameservers/restart +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `addr` | `string` | 是 | NameServer 地址 | + +**Response `data`:** `{ success: boolean }` + +### 4.8 升级 NameServer + +``` +POST /api/nameservers/upgrade +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `addr` | `string` | 是 | NameServer 地址 | + +**Response `data`:** `{ success: boolean }` + +### 4.9 删除 NameServer + +``` +POST /api/nameservers/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `addr` | `string` | 是 | NameServer 地址 | + +**Response `data`:** `{ success: boolean }` + +### 4.10 重启 Proxy + +``` +POST /api/proxies/restart +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `addr` | `string` | 是 | Proxy 地址 | + +**Response `data`:** `{ success: boolean }` + +### 4.11 获取 K8s 证书列表 + +``` +GET /api/k8s-certs +``` + +**Response `data`:** `K8sCertInfo[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 证书 ID | +| `name` | `string` | 证书名称 | +| `namespace` | `string` | K8s 命名空间 | +| `cluster` | `string` | 所属集群名称 | +| `type` | `string` | 证书类型: `TLS` / `mTLS` / `ServiceAccount` | +| `issuer` | `string` | 签发者 | +| `notBefore` | `string` | 生效时间 (ISO 8601) | +| `notAfter` | `string` | 过期时间 (ISO 8601) | +| `status` | `string` | 状态: `valid` / `expiring` / `expired` | +| `daysRemaining` | `number` | 剩余天数 | +| `san` | `string[]` | Subject Alternative Name 列表 | + +### 4.12 添加 K8s 证书 + +``` +POST /api/k8s-certs/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 证书名称 | +| `namespace` | `string` | 是 | K8s 命名空间 | +| `cluster` | `string` | 是 | 所属集群 | +| `type` | `string` | 是 | 证书类型: `TLS` / `mTLS` / `ServiceAccount` | +| `issuer` | `string` | 否 | 签发者 | + +**Response `data`:** `K8sCertInfo` + +### 4.13 更新 K8s 证书 + +``` +POST /api/k8s-certs/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 证书 ID | +| `name` | `string` | 否 | 证书名称 | +| `namespace` | `string` | 否 | K8s 命名空间 | +| `cluster` | `string` | 否 | 所属集群 | +| `type` | `string` | 否 | 证书类型 | +| `issuer` | `string` | 否 | 签发者 | + +**Response `data`:** `K8sCertInfo` + +### 4.14 续期 K8s 证书 + +``` +POST /api/k8s-certs/renew +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 证书 ID | + +**Response `data`:** `K8sCertInfo` + +### 4.15 删除 K8s 证书 + +``` +POST /api/k8s-certs/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 证书 ID | + +**Response `data`:** `null` + +--- + +## 5. Topic 管理 + +### 5.1 获取 Topic 列表 + +``` +GET /api/topics?clusterId={clusterId}&type={type}&search={keyword} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 否 | 按集群过滤 | +| `type` | `string` | 否 | 按类型过滤: `NORMAL` / `FIFO` / `DELAY` / `TRANSACTION` / `LITE` | +| `search` | `string` | 否 | 按名称搜索 | + +**Response `data`:** `Topic[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `string` | Topic 名称 | +| `namespace` | `string` | 命名空间 | +| `type` | `string` | 类型: `NORMAL` / `FIFO` / `DELAY` / `TRANSACTION` / `LITE` | +| `clusterId` | `string` | 所属集群 ID | +| `writeQueues` | `number` | 写队列数 | +| `readQueues` | `number` | 读队列数 | +| `perm` | `string` | 权限: `RW` / `RO` / `WO` | +| `messageCount` | `number` | 消息总量 | +| `tps` | `number` | 当前 TPS | +| `consumerGroupCount` | `number` | 订阅消费组数 | +| `remark` | `string` | 备注 | +| `createdAt` | `string` | 创建时间 (ISO 8601) | +| `updatedAt` | `string` | 更新时间 (ISO 8601) | + +### 5.2 创建 Topic + +``` +POST /api/topics/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | Topic 名称 | +| `namespace` | `string` | 否 | 命名空间 | +| `type` | `string` | 是 | 类型 | +| `clusterId` | `string` | 是 | 所属集群 | +| `writeQueues` | `number` | 是 | 写队列数 | +| `readQueues` | `number` | 是 | 读队列数 | +| `perm` | `string` | 否 | 权限，默认 `RW` | +| `remark` | `string` | 否 | 备注 | + +**Response `data`:** `Topic` + +### 5.3 更新 Topic + +``` +POST /api/topics/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | Topic 名称（不可修改） | +| `namespace` | `string` | 否 | 命名空间 | +| `type` | `string` | 是 | 类型 | +| `clusterId` | `string` | 是 | 所属集群 | +| `writeQueues` | `number` | 是 | 写队列数 | +| `readQueues` | `number` | 是 | 读队列数 | +| `perm` | `string` | 否 | 权限，默认 `RW` | +| `remark` | `string` | 否 | 备注 | + +**Response `data`:** `Topic` + +### 5.4 删除 Topic + +``` +POST /api/topics/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | Topic 名称 | + +**Response `data`:** `null` + +### 5.5 获取 Topic 路由信息 + +``` +GET /api/topics/:name/routes +``` + +**Response `data`:** `BrokerRoute[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `brokerName` | `string` | Broker 名称 | +| `brokerAddr` | `string` | Broker 地址 | +| `writeQueues` | `number` | 写队列数 | +| `readQueues` | `number` | 读队列数 | +| `perm` | `string` | 权限 | + +### 5.6 获取 Topic 消费者列表 + +``` +GET /api/topics/:name/consumers +``` + +**Response `data`:** `TopicConsumerInfo[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `group` | `string` | 消费组名称 | +| `consumeType` | `string` | 消费类型: `CLUSTERING` / `BROADCASTING` | +| `messageModel` | `string` | 消费模式描述 | +| `consumeTps` | `number` | 消费 TPS | +| `diffTotal` | `number` | 堆积消息数 | + +### 5.7 发送消息到 Topic + +``` +POST /api/topics/send +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `topic` | `string` | 是 | Topic 名称 | +| `tag` | `string` | 否 | 消息 Tag | +| `key` | `string` | 否 | 消息 Key（用于消息查询） | +| `body` | `string` | 是 | 消息体内容 | +| `properties` | `Record<string, string>` | 否 | 消息自定义属性键值对 | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `msgId` | `string` | 消息 ID | +| `sendTime` | `string` | 发送时间 (ISO 8601) | +| `offsetMsgId` | `string` | 含偏移量的消息 ID | + +**示例：** + +```json +// Request +{ + "topic": "order-create", + "tag": "order", + "key": "ORDER-20260708-001", + "body": "{\"orderId\":\"20260708001\",\"amount\":299.00,\"status\":\"CREATED\"}", + "properties": { + "source": "rocketmq-studio", + "env": "test" + } +} + +// Response +{ + "msgId": "7F000001234567890000", + "sendTime": "2026-07-08T10:30:45.123Z", + "offsetMsgId": "7F000001234567890000-0:0:0:0" +} +``` + +--- + +## 6. 消费组管理 Consumer Group + +### 6.1 获取消费组列表 + +``` +GET /api/groups?clusterId={clusterId}&search={keyword} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 否 | 按集群过滤 | +| `search` | `string` | 否 | 按名称搜索 | + +**Response `data`:** `ConsumerGroup[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `string` | 消费组名称 | +| `namespace` | `string` | 命名空间 | +| `clusterId` | `string` | 所属集群 ID | +| `subscriptionMode` | `string` | 订阅模式: `Push` / `Pop` | +| `consumeType` | `string` | 消费类型: `CLUSTERING` / `BROADCASTING` | +| `onlineInstances` | `number` | 在线实例数 | +| `totalLag` | `number` | 总堆积消息数 | +| `subscribedTopics` | `string[]` | 订阅的 Topic 列表 | +| `subscriptionDataType` | `string` | 订阅数据类型: `NORMAL` / `FIFO` / `DELAY` / `TRANSACTION` | +| `deliveryOrderType` | `string?` | 顺序类型（FIFO 时）: `PARTITON_ORDER` / `MESSAGES_ORDER` | +| `retryMaxTimes` | `number` | 最大重试次数 | +| `delaySeconds` | `number` | 延迟秒数 | +| `createdAt` | `string` | 创建时间 | +| `updatedAt` | `string` | 更新时间 | + +### 6.2 获取消费组详情 + +``` +GET /api/groups/:name +``` + +**Response `data`:** `ConsumerGroup`（含 `instances` 字段） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `instances` | `ConsumerInstance[]` | 消费者实例列表 | + +#### ConsumerInstance + +| 字段 | 类型 | 说明 | +|------|------|------| +| `clientId` | `string` | 客户端 ID | +| `protocol` | `string` | 协议: `REMOTING` / `GRPC` | +| `address` | `string` | 客户端地址 | +| `subscribedTopics` | `string[]` | 订阅的 Topic | +| `lastHeartbeat` | `string` | 最后心跳时间 | +| `topicLag` | `Record<string, number>` | 各 Topic 堆积数 `{ "topic-name": lag_count }` | + +### 6.3 获取消费进度 + +``` +GET /api/groups/:name/progress +``` + +**Response `data`:** `QueueProgress[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `broker` | `string` | Broker 名称 | +| `queueId` | `number` | 队列 ID | +| `brokerOffset` | `number` | Broker 端 offset | +| `consumerOffset` | `number` | 消费端 offset | +| `diffTotal` | `number` | 堆积差值 | + +### 6.4 获取订阅详情 + +``` +GET /api/groups/:name/subscriptions +``` + +**Response `data`:** `SubscriptionEntry[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `topic` | `string` | Topic 名称 | +| `expression` | `string` | 过滤表达式 | +| `type` | `string` | 数据类型: `NORMAL` / `FIFO` / `DELAY` / `TRANSACTION` | +| `filterMode` | `string` | 过滤模式: `Tag 过滤` / `SQL92 过滤` / `全量` | +| `consistency` | `string` | 一致性: `一致` / `不一致` | + +### 6.5 创建消费组 + +``` +POST /api/groups/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 消费组名称 | +| `namespace` | `string` | 否 | 命名空间 | +| `clusterId` | `string` | 是 | 所属集群 | +| `subscriptionMode` | `string` | 是 | `Push` / `Pop` | +| `consumeType` | `string` | 是 | `CLUSTERING` / `BROADCASTING` | +| `subscribedTopics` | `string[]` | 否 | 订阅 Topic | +| `retryMaxTimes` | `number` | 否 | 最大重试次数 | + +**Response `data`:** `ConsumerGroup` + +### 6.6 删除消费组 + +``` +POST /api/groups/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 消费组名称 | + +**Response `data`:** `null` + +### 6.7 重置消费位点 + +``` +POST /api/groups/reset-offset +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 消费组名称 | +| `timestamp` | `string` | 是 | 重置到指定时间 (ISO 8601) | +| `topic` | `string` | 否 | 指定 Topic，不传则全部重置 | + +**Response `data`:** `null` + +### 6.8 导入消费组配置 + +``` +POST /api/groups/import +``` + +**Request Body:** `multipart/form-data` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `file` | `File` | JSON 配置文件 | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `imported` | `number` | 成功导入数量 | +| `failed` | `number` | 失败数量 | +| `errors` | `string[]` | 错误信息列表 | + +### 6.9 导出消费组配置 + +``` +GET /api/groups/export?names={name1,name2} +``` + +**Response:** `Content-Type: application/json`, `Content-Disposition: attachment` + +--- + +## 7. ACL 管理 + +### 7.1 获取 ACL 规则列表 + +``` +GET /api/acl/rules?clusterId={clusterId}&principal={principal} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 否 | 按集群过滤 | +| `principal` | `string` | 否 | 按用户过滤 | + +**Response `data`:** `AclRule[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 规则 ID | +| `principal` | `string` | 主体用户名 | +| `resource` | `string` | 资源名称/模式 | +| `resourceType` | `string` | 资源类型: `Topic` / `Group` / `Cluster` | +| `resourcePattern` | `string` | 匹配模式: `LITERAL` / `PREFIX` | +| `actions` | `string[]` | 操作列表: `PUB` / `SUB` / `ALL` | +| `decision` | `string` | 决策: `ALLOW` / `DENY` | +| `scope` | `string` | 作用域: `cluster` / `namespace` | +| `aclVersion` | `string` | ACL 版本: `1.0` / `2.0` | +| `createdAt` | `string` | 创建时间 (ISO 8601) | + +### 7.2 创建 ACL 规则 + +``` +POST /api/acl/rules/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `principal` | `string` | 是 | 主体 | +| `resource` | `string` | 是 | 资源 | +| `resourceType` | `string` | 是 | 资源类型 | +| `resourcePattern` | `string` | 是 | 匹配模式 | +| `actions` | `string[]` | 是 | 操作列表 | +| `decision` | `string` | 是 | ALLOW / DENY | +| `scope` | `string` | 否 | 作用域 | + +**Response `data`:** `AclRule` + +### 7.3 删除 ACL 规则 + +``` +POST /api/acl/rules/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 规则 ID | + +**Response `data`:** `null` + +### 7.4 获取 ACL 用户列表 + +``` +GET /api/acl/users +``` + +**Response `data`:** `AclUser[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 用户 ID | +| `username` | `string` | 用户名 | +| `accessKey` | `string` | AccessKey（脱敏显示） | +| `secretKey` | `string` | SecretKey（脱敏显示） | +| `admin` | `boolean` | 是否管理员 | +| `clusters` | `string[]` | 授权集群列表 | +| `createdAt` | `string` | 创建时间 | + +### 7.5 创建 ACL 用户 + +``` +POST /api/acl/users/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `username` | `string` | 是 | 用户名 | +| `admin` | `boolean` | 否 | 是否管理员 | +| `clusters` | `string[]` | 否 | 授权集群 | + +**Response `data`:** `AclUser`（含生成的 accessKey/secretKey） + +### 7.6 删除 ACL 用户 + +``` +POST /api/acl/users/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 用户 ID | + +**Response `data`:** `null` + +--- + +## 8. 消息查询 Message + +### 8.1 查询消息列表 + +``` +GET /api/messages?topic={topic}&msgId={msgId}&key={key}&startTime={startTime}&endTime={endTime} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `topic` | `string` | 否 | Topic 名称 | +| `msgId` | `string` | 否 | 消息 ID（精确查询） | +| `key` | `string` | 否 | 消息 Key | +| `startTime` | `string` | 否 | 开始时间 (ISO 8601) | +| `endTime` | `string` | 否 | 结束时间 (ISO 8601) | + +**Response `data`:** `MessageRecord[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `msgId` | `string` | 消息 ID | +| `topic` | `string` | Topic 名称 | +| `tag` | `string` | 消息 Tag | +| `key` | `string` | 消息 Key | +| `body` | `string` | 消息体（JSON 字符串） | +| `storeTime` | `string` | 存储时间 (ISO 8601) | +| `bornHost` | `string` | 发送方地址 | +| `storeHost` | `string` | 存储 Broker 地址 | +| `properties` | `Record<string, string>` | 消息属性键值对 | +| `size` | `number` | 消息大小（字节） | + +### 8.2 获取消息轨迹 + +``` +GET /api/messages/:msgId/trace +``` + +**Response `data`:** `TraceRecord` + +```json +{ + "nodes": [ + { + "title": "Producer 发送", + "timestamp": "2026-07-01T10:23:45.100Z", + "status": "finish", + "costTime": 3, + "description": "order-service (10.0.1.12:54321) → broker-hz-01" + }, + { + "title": "Broker 存储", + "timestamp": "2026-07-01T10:23:45.115Z", + "status": "finish", + "costTime": 8, + "description": "broker-hz-01 (10.0.2.3:10911) CommitLog 写入成功" + }, + { + "title": "Consumer 消费", + "timestamp": "2026-07-01T10:23:45.230Z", + "status": "finish", + "costTime": 107, + "description": "cg-order-processor → 消费成功 (23ms)" + } + ], + "consumerStatus": [ + { + "group": "cg-order-processor", + "deliveryStatus": "success", + "consumeTime": "2026-07-01T10:23:45.230Z", + "retryCount": 0 + } + ] +} +``` + +#### TraceNode + +| 字段 | 类型 | 说明 | +|------|------|------| +| `title` | `string` | 节点标题: `Producer 发送` / `Broker 存储` / `Consumer 消费` | +| `timestamp` | `string` | 时间戳 (ISO 8601) | +| `status` | `string` | 状态: `finish` / `process` / `wait` | +| `costTime` | `number` | 耗时（毫秒） | +| `description` | `string` | 详细描述 | + +#### ConsumerStatus + +| 字段 | 类型 | 说明 | +|------|------|------| +| `group` | `string` | 消费组名称 | +| `deliveryStatus` | `string` | 投递状态: `success` / `failed` / `pending` | +| `consumeTime` | `string` | 消费时间（`-` 表示未消费） | +| `retryCount` | `number` | 重试次数 | + +--- + +## 9. 死信队列 Dead Letter Queue + +### 9.1 获取 DLQ 列表 + +``` +GET /api/dlq?clusterId={clusterId} +``` + +**Response `data`:** `DLQGroup[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `groupName` | `string` | 消费组名称 | +| `dlqTopic` | `string` | 死信 Topic 名称（格式: `%DLQ%{groupName}`） | +| `messageCount` | `number` | 死信消息数量 | +| `lastEnqueueTime` | `string` | 最后入队时间 (ISO 8601) | +| `retryCount` | `number` | 已重试次数 | +| `status` | `string` | 状态: `active` / `empty` | + +### 9.2 重发死信消息 + +``` +POST /api/dlq/resend +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `groupName` | `string` | 是 | 消费组名称 | +| `startTime` | `string` | 是 | 重投时间范围起始 (ISO 8601) | +| `endTime` | `string` | 是 | 重投时间范围结束 (ISO 8601) | +| `targetTopic` | `string` | 否 | 目标 Topic，不传则重投回原 Topic | + +**Response `data`:** `null` + +--- + +## 10. 客户端连接 Clients + +### 10.1 获取客户端连接列表 + +``` +GET /api/clients?clusterId={clusterId}&type={type} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `clusterId` | `string` | 否 | 按集群过滤 | +| `type` | `string` | 否 | 按类型过滤: `Producer` / `Consumer` | + +**Response `data`:** `ClientConnection[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `clientId` | `string` | 客户端 ID | +| `type` | `string` | 类型: `Producer` / `Consumer` | +| `groupOrTopic` | `string` | 消费组名或 Topic 名 | +| `protocol` | `string` | 协议: `gRPC` / `Remoting` | +| `address` | `string` | 客户端地址 | +| `language` | `string` | 客户端语言: `Java` / `Go` / `Python` / `Rust` / `C++` / `C#` / `Node.js` / `PHP` | +| `version` | `string` | SDK 版本号 | +| `connectedAt` | `string` | 连接时间 | +| `clusterName` | `string` | 所属集群名称（显示在第一列） | + +--- + +## 11. 告警规则 Alert Rules + +### 11.1 获取告警规则列表 + +``` +GET /api/alert-rules +``` + +**Response `data`:** `AlertRule[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 规则 ID | +| `name` | `string` | 规则名称 | +| `metric` | `string` | 监控指标: `磁盘使用率` / `消费堆积量` / `TPS 异常` / `Broker 离线` / `Proxy 连接数` | +| `operator` | `string` | 比较运算符: `>` / `<` / `>=` / `<=` | +| `threshold` | `number` | 阈值 | +| `thresholdUnit` | `string` | 单位: `%` / `条` / `TPS` / `个` | +| `duration` | `string` | 持续时间: `1分钟` / `5分钟` / `15分钟` / `30分钟` | +| `channels` | `string[]` | 通知渠道: `dingtalk` / `email` / `sms` | +| `enabled` | `boolean` | 是否启用 | +| `lastTriggered` | `string \| null` | 最后触发时间，null 表示未触发 | +| `description` | `string` | 规则描述 | + +### 11.2 创建告警规则 + +``` +POST /api/alert-rules/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 规则名称 | +| `metric` | `string` | 是 | 监控指标 | +| `operator` | `string` | 是 | 运算符 | +| `threshold` | `number` | 是 | 阈值 | +| `duration` | `string` | 是 | 持续时间 | +| `channels` | `string[]` | 是 | 通知渠道 | +| `description` | `string` | 否 | 描述 | + +**Response `data`:** `AlertRule` + +### 11.3 更新告警规则 + +``` +POST /api/alert-rules/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 规则 ID | +| `name` | `string` | 是 | 规则名称 | +| `metric` | `string` | 是 | 监控指标 | +| `operator` | `string` | 是 | 运算符 | +| `threshold` | `number` | 是 | 阈值 | +| `duration` | `string` | 是 | 持续时间 | +| `channels` | `string[]` | 是 | 通知渠道 | +| `description` | `string` | 否 | 描述 | + +**Response `data`:** `AlertRule` + +### 11.4 切换告警规则启用状态 + +``` +POST /api/alert-rules/toggle +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 规则 ID | +| `enabled` | `boolean` | 是 | 启用/禁用 | + +**Response `data`:** `AlertRule` + +### 11.5 删除告警规则 + +``` +POST /api/alert-rules/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 规则 ID | + +**Response `data`:** `null` + +--- + +## 12. 系统告警 System Alerts + +### 12.1 获取系统告警列表 + +``` +GET /api/system-alerts?level={level} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `level` | `string` | 否 | 按级别过滤: `error` / `warning` / `info` | + +**Response `data`:** `SystemAlert[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 告警 ID | +| `level` | `string` | 级别: `error`（严重） / `warning`（警告） / `info`（信息） | +| `title` | `string` | 告警标题 | +| `description` | `string` | 告警详情 | +| `time` | `string` | 时间（短格式: `HH:mm`） | +| `acknowledged` | `boolean` | 是否已确认 | + +### 12.2 确认告警 + +``` +POST /api/system-alerts/acknowledge +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `string` | 是 | 告警 ID | + +**Response `data`:** `SystemAlert` + +### 12.3 清除已确认告警 + +``` +POST /api/system-alerts/clear-acknowledged +``` + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `cleared` | `number` | 清除数量 | + +--- + +## 13. 审计日志 Audit + +### 13.1 获取审计日志列表 + +``` +GET /api/audit-logs?page={page}&pageSize={pageSize}&search={search}&operationType={type}&startDate={start}&endDate={end}&result={result} +``` + +**Query Parameters:** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `page` | `number` | 否 | 页码，默认 1 | +| `pageSize` | `number` | 否 | 每页条数，默认 20 | +| `search` | `string` | 否 | 搜索（匹配 operator / target） | +| `operationType` | `string` | 否 | 操作类型过滤 | +| `startDate` | `string` | 否 | 开始日期 (YYYY-MM-DD) | +| `endDate` | `string` | 否 | 结束日期 (YYYY-MM-DD) | +| `result` | `string` | 否 | 结果过滤: `success` / `failure` | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `records` | `AuditRecord[]` | 记录列表 | +| `total` | `number` | 总条数 | + +#### AuditRecord + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 记录 ID | +| `timestamp` | `string` | 操作时间（`YYYY-MM-DD HH:mm:ss`） | +| `operator` | `string` | 操作人（如 `admin`, `ops-zhang`, `system`） | +| `operationType` | `string` | 操作类型: `创建Topic` / `删除Topic` / `修改配置` / `重置位点` / `ACL变更` / `重启Broker` / `删除消费组` | +| `target` | `string` | 操作对象 | +| `detail` | `string` | 详细描述 | +| `ipAddress` | `string` | 操作 IP 地址 | +| `result` | `string` | 结果: `success` / `failure` | + +### 13.2 清理审计日志 + +``` +POST /api/audit-logs/cleanup +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `beforeDays` | `number` | 是 | 清理多少天之前的日志（1-365） | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `deleted` | `number` | 清理数量 | + +--- + +## 14. 系统设置 Settings + +### 14.1 获取通用设置 + +``` +GET /api/settings/general +``` + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `theme` | `string` | 主题: `light` / `dark` / `system` | +| `compact` | `boolean` | 紧凑模式 | +| `desktopNotify` | `boolean` | 桌面通知 | +| `notifySound` | `boolean` | 通知声音 | +| `sessionTimeout` | `number` | 会话超时（分钟，5-1440） | +| `requireLogin` | `boolean` | 是否需要登录 | +| `llmProvider` | `string` | LLM 提供商: `openai` / `azure` / `ollama` / `qwen` | +| `apiKey` | `string` | API Key | +| `model` | `string` | 模型名称 | +| `baseUrl` | `string` | Base URL | + +### 14.2 保存通用设置 + +``` +POST /api/settings/general/save +``` + +**Request Body:** 同 14.1 响应格式 + +**Response `data`:** `null` + +### 14.3 获取数据源列表 + +``` +GET /api/settings/datasources +``` + +**Response `data`:** `DataSource[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `key` | `string` | 数据源 ID | +| `name` | `string` | 名称 | +| `type` | `string` | 类型: `Prometheus` / `VictoriaMetrics` / `Thanos` | +| `url` | `string` | 连接 URL | +| `auth` | `string` | 认证方式: `None` / `Basic Auth` / `Bearer Token` | +| `status` | `string` | 状态: `healthy` / `error` | + +### 14.4 创建数据源 + +``` +POST /api/settings/datasources/create +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | `string` | 是 | 名称 | +| `type` | `string` | 是 | 类型 | +| `url` | `string` | 是 | URL | +| `auth` | `string` | 否 | 认证方式，默认 `None` | + +**Response `data`:** `DataSource` + +### 14.5 更新数据源 + +``` +POST /api/settings/datasources/update +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `key` | `string` | 是 | 数据源 ID | +| `name` | `string` | 是 | 名称 | +| `type` | `string` | 是 | 类型 | +| `url` | `string` | 是 | URL | +| `auth` | `string` | 否 | 认证方式，默认 `None` | + +**Response `data`:** `DataSource` + +### 14.6 删除数据源 + +``` +POST /api/settings/datasources/delete +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `key` | `string` | 是 | 数据源 ID | + +**Response `data`:** `null` + +### 14.7 测试数据源连接 + +``` +POST /api/settings/datasources/test +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `url` | `string` | 是 | 连接 URL | +| `type` | `string` | 是 | 类型 | +| `auth` | `string` | 否 | 认证方式 | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `success` | `boolean` | 是否连接成功 | +| `message` | `string?` | 错误信息 | + +--- + +## 15. AI 交互 + +### 15.1 发送 AI 消息 + +``` +POST /api/ai/chat +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `message` | `string` | 是 | 用户消息 | +| `mode` | `string` | 否 | 模式: `query` / `diagnose` / `manage` / `chat` | +| `model` | `string` | 否 | 模型名称 | +| `conversationId` | `string` | 否 | 会话 ID（续接对话） | + +**Response:** `text/event-stream`（SSE 流式返回） + +### 15.2 执行 AI 指令 + +``` +POST /api/ai/execute +``` + +**Request Body:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `command` | `string` | AI 生成的可执行指令 | + +**Response `data`:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `success` | `boolean` | 执行结果 | +| `result` | `string` | 执行输出 | + +### 15.3 获取可用工具列表 + +``` +GET /api/ai/tools +``` + +**Response `data`:** `Tool[]` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `string` | 工具名称 | +| `description` | `string` | 工具描述 | +| `parameters` | `object` | 参数 Schema | + +--- + +## 16. 监控指标 Metrics + +### 16.1 查询监控指标数据 + +``` +POST /api/metrics/query +``` + +**Request Body:** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `metric` | `string` | 是 | 指标名称（如 `tps_in`、`tps_out`、`message_count`、`disk_usage`） | +| `start` | `number` | 是 | 起始时间（Unix 时间戳，秒） | +| `end` | `number` | 是 | 结束时间（Unix 时间戳，秒） | +| `step` | `string` | 否 | 采样步长（如 `"60s"`、`"5m"`、`"1h"`） | + +**Response `data`:** `MetricsResult` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `metric` | `string` | 指标名称 | +| `values` | `[number, number][]` | 数据点数组，每项为 `[timestamp, value]` | + +--- + +## 附录 A：枚举值速查 + +| 枚举 | 值 | +|------|---| +| **集群状态** | `healthy`, `warning`, `error`, `offline` | +| **Broker 状态** | `running`, `readonly`, `maintenance` | +| **节点状态** | `healthy`, `warning`, `error`, `offline` | +| **Topic 类型** | `NORMAL`, `FIFO`, `DELAY`, `TRANSACTION`, `LITE` | +| **Topic 权限** | `RW`, `RO`, `WO` | +| **消费类型** | `CLUSTERING`, `BROADCASTING` | +| **订阅模式** | `Push`, `Pop` | +| **协议** | `gRPC`, `Remoting` | +| **客户端语言** | `Java`, `Go`, `Python`, `Rust`, `C++`, `C#`, `Node.js`, `PHP` | +| **ACL 资源类型** | `Topic`, `Group`, `Cluster` | +| **ACL 匹配模式** | `LITERAL`, `PREFIX` | +| **ACL 操作** | `PUB`, `SUB`, `ALL` | +| **ACL 决策** | `ALLOW`, `DENY` | +| **告警级别** | `error`, `warning`, `info` | +| **审计结果** | `success`, `failure` | +| **投递状态** | `success`, `failed`, `pending` | +| **证书状态** | `valid`, `expiring`, `expired` | +| **证书类型** | `TLS`, `mTLS`, `ServiceAccount` | +| **刷盘方式** | `ASYNC_FLUSH`, `SYNC_FLUSH` | +| **集群类型** | `V4_DIRECT`, `V5_PROXY_LOCAL`, `V5_PROXY_CLUSTER` | +| **顺序类型** | `PARTITON_ORDER`, `MESSAGES_ORDER` | +| **通知渠道** | `dingtalk`, `email`, `sms` | +| **LLM 提供商** | `openai`, `azure`, `ollama`, `qwen` | +| **数据源类型** | `Prometheus`, `VictoriaMetrics`, `Thanos` |
