debdevops/servicehub

## 为什么选择 ServiceHub？ 生产环境在凌晨 2 点发生故障。Azure 门户显示 **死信队列中有 5,000 条消息** —— 但你只能看到数量，无法阅读内容。你只能逐条手动采样，耗费数小时完成本应几分钟的工作。 **ServiceHub 是一个自托管的 Web 应用程序，为工程师提供对 Azure Service Bus 的完整法医可见性 —— 就像一个调试器，但针对的是你的消息队列。** | 功能 | Azure 门户 | ServiceHub | |---|---|---| | 查看消息正文与内容 | ❌ 仅数量 | ✅ 完整正文 + 语法高亮 | | 跨消息内容搜索 | ❌ 不可用 | ✅ 实时全文搜索 | | 死信队列调查 | ❌ 一次一条 | ✅ 批量分析 + AI 模式 | | AI 模式检测 | ❌ 不可用 | ✅ 客户端侧聚类，零数据外传 | | 从死信队列重放 | ❌ 不可用 | ✅ 一键或自动重放规则 | | 多命名空间支持 | ❌ 仅门户 | ✅ 管理多个连接 | | 相关性 ID 追踪 | ❌ 不可用 | ✅ 跨所有队列追踪旅程 | | 定时消息管理 | ❌ 不可用 | ✅ 查看、重新调度与取消 | ## ✨ 功能特性 ### 🔌 30 秒连接 —— 零配置 输入一次连接字符串，即可立即浏览消息。支持 **仅读（读取）**、**发送** 和 **管理** 策略。连接字符串在存储时采用 **AES-GCM 加密** —— 绝不以明文形式保存任何秘密。  ### 📨 消息浏览器 —— 触手可及的数千条消息 并排浏览 **活跃（Active）** 与 **死信（Dead-Letter）** 队列消息。完整的消息预览、状态徽章、入队时间以及元数据，在虚拟化网格中流畅处理数千条记录。自动每 7 秒刷新一次，确保在事件处理期间视图保持实时。  ### 🔍 法医级消息检查 —— 每一字节可见 点击任意消息即可进行完整的法医分析： - **正文** —— 完整的 JSON/XML，支持语法高亮与一键复制 - **属性** —— 消息 ID、序列号、TTL、投递计数、入队时间 - **标头** —— 所有自定义应用属性和关联 ID - **AI 洞察** —— 模式上下文与修复建议，完全在浏览器内计算  ### 🤖 AI 分析结果 —— 检测数千条消息中的模式 点击 **AI 分析** 查看当前队列视图中检测到的错误模式聚类。引擎按错误类型对消息进行分组，计算置信度分数，并突出显示最具影响力的聚类 —— 让你清楚知道首先查看哪里。  ### 💀 死信队列调查 —— 从困惑到根因 选择 **死信（Dead-Letter）** 标签以完整检查失败的消息。每条 DLQ 消息显示： - **DLQ 原因** —— Azure 将消息移入死信队列的确切原因 - **DLQ 错误描述** —— 来自 Azure Service Bus 代理的完整错误文本 - **AI 评估** —— ServiceHub 的分类与解释 - **一键重放** —— 修复根因后重新发送到活跃队列  ### 📊 DLQ 智能 —— 持久化历史与 30 天趋势 DLQ 智能会自动扫描死信队列，并将每个发现存储在本地 SQLite 数据库中 —— 因此你可以追踪随时间变化的失败情况，而不仅限于当前会话。 - **30 天趋势图** —— 可视化 DLQ 峰值与解决曲线 - **自动分类** —— 5 种失败类型：瞬态、最大投递、已过期、数据质量、授权 - **重放安全评级** —— 知道哪些消息可以安全自动重放 - **导出** —— 下载完整历史记录为 CSV 或 JSON 用于事后分析  ### ⚡ 自动重放规则 —— 自动化恢复 定义规则以监控死信消息，并在匹配条件时自动重放。无需人工干预即可从常见故障中恢复。 - **AI 生成规则** —— 基于实际 DLQ 模式一键生成规则 - **模板库** —— 超时、限流错误、已过期消息的预构建规则 - **灵活匹配** —— 按 DLQ 原因、错误描述、实体、投递计数、正文内容或正则表达式匹配 - **安全控制** —— 速率限制与断路器防止压垮下游服务 - **实时统计** —— 每条规则的待处理 / 已重放 / 成功计数实时更新  ### 🔎 实时搜索 —— 秒级查找任意消息 在消息正文、属性和标头中即时搜索。快速将 1,000+ 条消息筛选至所需内容 —— 无需等待，无分页往返。  ### 🔗 相关性探索器 —— 追踪消息旅程 粘贴任意相关性 ID，即可在所有队列、主题和命名空间中即时追踪消息的完整旅程。在故障排查期间至关重要 —— 找出订单、支付或事件最终落在何处，以及它是否在活跃队列或死信中。  ### 🏢 多命名空间支持 —— 管理所有环境 同时连接到多个 Azure Service Bus 命名空间。在开发、测试和生产环境之间切换而无需断开连接。所有命名空间在侧边栏中可见，并带有实时的颜色编码消息计数。  ### 🕐 定时消息管理 —— 查看、重新调度与取消 查看跨命名空间的所有定时投递消息。直接从 UI 重新调度或取消单个消息 —— 无需 SDK 或脚本。  ### 💚 系统健康 —— 监控你的部署 ServiceHub API 本身的实时运行时指标：正常运行时间、内存使用、线程数、GC 代计数，以及包括 .NET 版本和环境名称在内的完整服务器信息。  ## 📸 截图 | 功能 | 预览 | |---|| | 连接页面 |  | | 消息浏览器 |  | | 消息详情（JSON 正文） |  | | DLQ 调查 |  | | AI 模式发现 |  | | DLQ 智能 |  | | 自动重放规则 |  | | 相关性探索器 |  | | 定时消息 |  | | 系统健康 |  | ## ⚡ 快速开始 ### 一键设置（推荐） ``` git clone https://github.com/debdevops/servicehub.git cd servicehub ./run.sh ``` 打开 **http://localhost:3000** —— 然后使用你的 Azure Service Bus 连接字符串进行连接。 脚本会自动安装 .NET 10 SDK 和 Node.js 18+（如果尚未存在）。 ### 先决条件 你需要提供： - Azure Service Bus 连接字符串（至少具备读取权限） 由 `run.sh` 自动安装： - .NET 10.0 SDK - Node.js 18+ ### 创建专用策略 用于仅读浏览（生产环境推荐）： ``` az servicebus namespace authorization-rule create \ --namespace-name \ --resource-group \ --name servicehub-readonly \ --rights Listen ``` 用于完全访问（发送、生成、重放）： ``` az servicebus namespace authorization-rule create \ --namespace-name \ --resource-group \ --name servicehub \ --rights Listen Send Manage ``` ### 服务地址 | 服务 | 地址 | |---|---| | **在线演示** | **https://app-servicehub-prod.azurewebsites.net/** | | UI（本地） | http://localhost:3000 | | API（本地） | http://localhost:5153 | | API 文档 — Scalar | http://localhost:5153/scalar/v1 | | API 文档 — Swagger UI | http://localhost:5153/swagger/index.html | | OpenAPI JSON | http://localhost:5153/openapi/v1.json | ## 🏗️ 架构设计 ``` Browser (React 19 SPA) └── TanStack Query hooks (useMessages, useQueues, useRules, …) └── Axios API client → Vite dev proxy └── ASP.NET Core 10 API (port 5153) ├── NamespacesController → AES-GCM encrypted connections ├── MessagesController → PeekMessagesAsync (read-only) ├── QueuesController → queue metadata + counts ├── TopicsController → topic + subscription metadata ├── DlqHistoryController → SQLite DLQ intelligence ├── RulesController → auto-replay rule engine ├── ScheduledMessagesController ├── CorrelationController → cross-queue message tracing └── HealthController → runtime health metrics └── Azure.Messaging.ServiceBus SDK ``` **项目结构：** ``` servicehub/ ├── apps/web/ # React 19 + TypeScript + Vite (port 3000) │ └── src/ │ ├── components/ # UI components (messages, DLQ, rules, FAB) │ ├── hooks/ # TanStack Query hooks for all API calls │ ├── lib/ # Axios client, AI engine, utilities │ └── pages/ # 10 page routes │ ├── services/api/ # ASP.NET Core 10 backend (port 5153) │ └── src/ │ ├── ServiceHub.Api/ # Controllers, middleware, auth │ ├── ServiceHub.Core/ # Domain entities, DTOs, interfaces │ ├── ServiceHub.Infrastructure/ # Azure SDK, SQLite, AES-GCM encryption │ └── ServiceHub.Shared/ # Result, Error, constants │ ├── scripts/ # Key generation + Azure setup scripts └── run.sh # One-command startup ``` **技术栈：** | 层级 | 技术 | |---|---| | 前端 | React 19, TypeScript 5, Tailwind CSS v4, TanStack Query v5 | | 后端 | ASP.NET Core 10, Azure.Messaging.ServiceBus SDK | | AI 分析 | 客户端启发式引擎（无外部 API 调用） | | 数据库 | SQLite（DLQ 智能历史），内存消息缓存 | | API 文档 | Scalar（OpenAPI）+ Swagger UI | | 安全 | AES-GCM 加密连接、HMAC SPA 令牌、默认只读 | 如需深入了解架构细节，请参阅 [services/api/ARCHITECTURE.md](services/api/ARCHITECTURE.md)。 ## 🔐 权限指南 | 权限级别 | 功能 | |---|---| | **仅读** | 浏览消息、检查 DLQ、搜索、AI 洞察、相关性探索器、系统健康 | | **读取 + 发送** | 以上全部 + 从 DLQ 重放 + 发送测试消息 | | **管理** | 以上全部 + 生成测试消息、定时消息、完整队列管理 | ## 💡 实际应用场景 ### 场景 1：凌晨 2 点的死信队列事件 **问题：** 5,000 个订单卡在死信队列中。Azure 门户仅显示数量。 **使用 ServiceHub：** 1. 在数秒内浏览全部 5,000 条 DLQ 消息 2. AI 检测到 3 个错误聚类：支付超时（40%）、无效地址（35%）、重复（25%） 3. 按相关性 ID 搜索以即时找到某个客户的订单 4. 创建自动重放规则，针对支付超时 → 自动重放 2,000 条消息 **节省时间：** 6 小时 → 45 分钟 ### 场景 2：排查丢失的订单 **问题：** 客户报告订单未处理。消息进入了哪个队列？ **使用 ServiceHub：** 1. 打开相关性探索器 2. 粘贴订单的相关性 ID 3. 在一次搜索中追踪消息在所有队列和命名空间中的完整旅程 **节省时间：** 30 分钟 → 30 秒 ### 场景 3：集成测试 **问题：** 需要 100 个真实的故障场景来测试错误处理。 **使用 ServiceHub：** 1. 打开消息生成器 → 选择支付网关场景 2. 生成 100 条消息，异常率为 30% 3. 验证 DLQ 行为与错误处理 4. 按 `ServiceHub-Generated` 标签筛选以清理测试数据 **节省时间：** 数小时的手动测试数据 → 2 分钟 ## 🛡️ 安全与可靠性 - **默认只读** —— 使用 `PeekMessagesAsync`；消息**不会被移除或消费** - **最小权限** —— 仅读取权限即可实现全部功能 - **AES-GCM 加密** —— 连接字符串在存储时加密；密钥保存在本地配置中 - **零外部调用** —— AI 分析完全在浏览器内执行；不发送任何消息数据到外部 - **无消息持久化** —— 消息仅在当前会话中内存显示 - **生产安全** —— 不会影响你活跃的消息消费者 ## 📖 API 文档 ServiceHub 提供完整的 REST API，并配备两种交互式文档界面： | 接口 | 地址 | |---|---| | **Scalar**（现代） | http://localhost:5153/scalar/v1 | | **Swagger UI** | http://localhost:5153/swagger/index.html | | OpenAPI JSON | http://localhost:5153/openapi/v1.json | **关键端点：** ``` GET /api/v1/namespaces List connected namespaces POST /api/v1/namespaces Add a namespace connection GET /api/v1/namespaces/{id}/queues List queues with counts GET /api/v1/namespaces/{id}/queues/{name}/messages Browse messages (peek only) POST /api/v1/namespaces/{id}/queues/{name}/messages Send a message GET /api/v1/namespaces/{id}/topics List topics + subscriptions GET /api/v1/dlq-history DLQ Intelligence records GET /api/v1/replay-rules Auto-replay rules POST /api/v1/replay-rules Create a replay rule GET /api/v1/health Runtime health metrics ``` ## ❓ 常见问题 **ServiceHub 会从队列中移除消息吗？** 不会。ServiceHub 仅使用 `PeekMessagesAsync`。你的消费者会照常处理消息，完全不受影响。 **在生产环境中使用安全吗？** 安全。读取模式完全只读。将 ServiceHub 部署在你的私有网络中以获得额外安全保障。 **没有 API 密钥，AI 分析如何工作？** ServiceHub 使用客户端侧启发式模式检测 —— 纯 JavaScript 运行在浏览器中。无 GPT、无外部服务、无数据外传。 **敏感消息内容如何处理？** 消息仅在当前浏览器会话中显示 —— 绝不会存入数据库或传输到任何地方。在本地部署以获得最高数据主权。 **可以在 Docker / Kubernetes / Azure App Service 中运行吗？** 可以。ServiceHub 是标准的 ASP.NET Core + React SPA。可部署到任何兼容 .NET 10 的主机。详见 [自托管指南](self-hosting/)。 **是否支持主题与订阅？** 是的。可独立浏览队列与主题订阅的消息。两者均显示活跃与死信标签页。 ## 🤝 贡献 欢迎提交错误修复、功能改进与文档更新。 1. 叉出仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 编写代码并添加测试（`cd apps/web && npm run test:coverage`） 4. 提交并推送 5. 发起 Pull Request ## 许可证 MIT 许可证 —— 详见 [LICENSE](LICENSE)。

**ServiceHub** —— 因为你的 Service Bus 消息在故障期间不应不可见。 为 DevOps、平台与 SRE 工程师而构建。 [在线演示](https://app-servicehub-prod.azurewebsites.net/) · [快速开始](#-quick-start) · [报告问题]()

标签：AI 检测, AI 模式检测, Azure Service Bus, Azure 监控, .NET 10, Portal 替代, React, Syscalls, TypeScript, Web 应用, 全文检索, 全栈, 威胁情报, 安全插件, 实时调试, 客户端分析, 幻觉缓解, 开发者工具, 批量分析, 服务总线, 模式识别, 死信队列, 浏览器调试, 消息体查看, 消息分析, 消息取证, 消息搜索, 消息查看, 消息监控, 消息重放, 消息队列, 生产排障, 自托管, 语法高亮, 零数据上传