beacon

<div align="center"> <img src="docs/assets/images/beacon-mark.svg" width="82" alt="Beacon" /> # Beacon **为 AI 时代打造的数据库监控平台** 语义警报、跨数据库编排和受控的 MCP 服务器 — 让您的团队 *和* AI 助手可以安全地监视、查询和移动数据。 [](https://moberghr.github.io/beacon) [](https://www.nuget.org/) [](LICENSING.md) [](https://dotnet.microsoft.com/) [](https://moberghr.github.io/beacon/features/mcp-server/) [文档](https://moberghr.github.io/beacon) · [快速开始](#-快速开始) · [MCP 服务器](#-mcp-服务器-您的-ai-的可靠助手) · [通过 NuGet 嵌入](#-在您的应用中嵌入-beacon) · [许可证](LICENSING.md) <br/> <img src="docs/assets/images/screenshots/home-dark.png" alt="Beacon 首页仪表盘（深色主题）" width="100%" /> _{显示的数据来自 Beacon 内置的模拟模式（`npm run dev:mock`）。} </div> --- ## 什么是 Beacon？ Beacon 是一个 **.NET 10 平台，用于语义数据库监控、警报和数据编排**。将它指向您的数据库 — PostgreSQL、SQL Server、MySQL、BigQuery、Snowflake、Databricks、Azure Synapse、AWS CloudWatch 或任何 REST API — 它就成为了这些数据库之上的运维层： - **监视** — 定时 SQL 检查捕获数据质量问题、业务规则问题和不健康的数据库，在用户发现之前。 - **警报** — 结果传递给电子邮件、Microsoft Teams、Slack、Jira 或 webhook，附带完整的数据集。 - **移动** — 可审计的 ETL 作业（插入 / 更新 / 清除 / 同步）在不同的数据库引擎之间。 - **服务 AI** — 内置的、生产级别的 **MCP 服务器** 为 Claude、Cursor 和任何 MCP 客户端提供只读的、具有 PII 意识的、完全审计的访问权限。 它以两种形式提供：一个 **可自行托管的应用程序**（克隆并运行）和 **NuGet 包**，您可以将这些包嵌入到自己的 ASP.NET Core 应用程序中。 ## 为什么团队选择 Beacon | | 您获得的内容 | |---|---| | **AI 级 SQL 准确性** | 自然语言问题变成 SQL，基于 **M-Schema 上下文** 和 **真实样本值**，通过 **多方言 AST 解析器** 验证，并通过 **预运行修复循环** 自我纠正 — 而不是天真的提示到 SQL 管道。 | | **自我改进的 MCP 服务器** | 每个 MCP 查询都会记录一个使用信号 — 意图、生成的 SQL、路由、结果、时间。**学习循环** 将这些信号转化为批准的模式澄清和文档补丁，因此答案随着使用而变得更好。 | | **安全作为默认值，而不是附加项** | AES-256-GCM 加密连接字符串，SHA256 哈希作用域 API 密钥仅显示一次，在连接器级别强制执行只读，PII 检测和掩蔽，登录速率限制，防伪，OIDC/SSO 和 MCP 客户端的 JWT。 | | **跨数据库查询** | 跨引擎链接查询步骤并在内存中 SQLite 中连接结果（`@@result1`，`@@result2`）— 无需数据仓库。 | | **可嵌入** | `AddBeaconServices()` 将整个平台 — UI、API、MCP 服务器、调度器 — 放入您现有的 ASP.NET Core 主机。您的应用、您的身份验证、您的领域。 | | **运行时可更换的 LLM** | OpenAI、Anthropic Claude、Azure OpenAI 或 AWS Bedrock — 在管理员设置中热交换，无需重启，在具有使用跟踪的并发限制请求队列后面。 | ## 看看它 <table> <tr> <td width="50%"> <img src="docs/assets/images/screenshots/control-tower-dark.png" alt="控制中心 — 实时订阅健康状况" /> <p align="center"><b>控制中心</b> — 实时健康状况，自动刷新。</p> </td> <td width="50%"> <img src="docs/assets/images/screenshots/mcp-learning-dark.png" alt="MCP 学习 — 服务器从使用情况中学习" /> <p align="center"><b>MCP 学习</b> — 审查学习的模式和文档补丁，批准或拒绝。</p> </td> </tr> <tr> <td width="50%"> <img src="docs/assets/images/screenshots/query-editor-light.png" alt="具有数据库浏览器的多步骤查询编辑器" /> <p align="center"><b>查询编辑器</b> — Monaco SQL 编辑器，实时数据库浏览器，类型参数，飞行前检查。</p> </td> <td width="50%"> <img src="docs/assets/images/screenshots/mcp-playground-dark.png" alt="MCP 游乐场 — 在将客户端指向它们之前测试工具" /> <p align="center"><b>MCP 游乐场</b> — 在将客户端指向它们之前交互式测试工具。</p> </td> </tr> </table> ## 🚀 快速开始 **先决条件：**.NET 10 SDK、Node.js 18+ 和 PostgreSQL 数据库。在 `src/Beacon.SampleProject/appsettings.json`（或用户密钥 / 环境变量）中设置连接字符串和 32 个字符的加密密钥： ```json { "ConnectionStrings": { "BeaconContext": "Host=localhost;Database=beacon;Username=postgres;Password=yourpassword" }, "Beacon": { "EncryptionKey": "your-secure-32-character-key-here" } } ``` ```bash # 1. 启动 API 主机（Kestrel）— http://localhost:5296 / https://localhost:7187 dotnet run --project Beacon.SampleProject --no-launch-profile # 2. 在另一个终端中，启动 React 开发服务器（Vite）— http://localhost:5173 npm run dev --prefix src/Beacon.UI/web ``` 打开 **http://localhost:5173**。在第一次运行 Beacon 时，它会应用 EF Core 迁移，并引导您完成 **首次运行管理员设置** — 没有硬编码的凭证。 > **没有后端？** `npm run dev:mock --prefix src/Beacon.UI/web` 在浏览器中运行完整的 UI，对抗现实的内存模拟数据（MSW）— 与上面的截图相同的模式。 | URL | 内容 | |---|---| | `/` | React UI | | `/beacon/api/health` | 健康检查 | | `/openapi/v1.json` | OpenAPI 文档（驱动类型化的 TS 客户端） | | `/beacon/mcp` | MCP 服务器（Streamable HTTP，需要身份验证） | | `/beacon/api/hub` | SignalR 中心（实时事件） | 📚 [详细快速入门指南 →](https://moberghr.github.io/beacon/getting-started/quick-start/) ## 🔌 MCP 服务器：您 AI 的可靠助手 Beacon 随附一个 **模型上下文协议** 服务器，通过 Streamable HTTP 在 `/beacon/mcp` 提供。它公开了五个工具 — | 工具 | 它执行的操作 | |---|---| | `get_context` | 项目概述：数据源、模式、表、质量分数、文档状态 | | `ask` | 自然语言问题 → 意图分类 → 数据源路由 → 接地 SQL → 受保护的执行 | | `query` | 直接 SQL（仅限 SELECT，受强制执行）针对特定数据源 | | `search` | 跨模式和文档的全文搜索 | | `get_documentation` | 项目 / 数据源 / 表级别的 AI 生成文档 | — 并且每个调用都经过相同的防护栏堆栈： ``` 自然语言问题 │ ▼ M-Schema 接地 ──── 模式 + 列类型 + LLM 上下文中的真实样本值 │ ▼ AST 只读验证 ── SQL 按方言解析；DML/DDL，堆叠查询， │ 在执行前拒绝隐藏的写入 ▼ 预运行修复循环 ──── 失败的 SQL 重试并刷新模式； │ 截断修复被拒绝 ▼ 行限制 + PII 掩蔽 ── 可配置的上限；电子邮件，SSN，令牌，信用 │ 卡掩蔽（`a***z`），支持自定义模式 ▼ 审计 + 使用信号 ──── 每个调用都记录（用户，SQL，时间，行， 结果）并馈送到学习循环中 ``` 身份验证永远不是匿名的：cookie 会话，**作用域 API 密钥**，或 **JWT 持有者**（OIDC）。 📚 [MCP 服务器文档 →](https://moberghr.github.io/beacon/features/mcp-server/) ## 🏗️ 架构 Beacon 遵循 CQRS（MediatR）核心，其中所有项目引用都集中在 `Beacon.Core`： ```mermaid graph TB subgraph UI["表示层"] React[React SPA<br/>Vite + TypeScript + Tailwind] end subgraph Edge["主机边缘 — Beacon.SampleProject"] RestApi[REST API<br/>/beacon/api/*] ~~~ Mcp[MCP 服务器<br/>/beacon/mcp] ~~~ Hub[SignalR 中心<br/>/beacon/api/hub] end subgraph Core["应用程序核心（MediatR / CQRS）"] QuerySvc[查询服务] ~~~ SubSvc[订阅服务] ~~~ MigSvc[迁移服务] NotifSvc[通知服务] ~~~ DataSrcSvc[数据源服务] ~~~ AiSvc[AI 服务] end subgraph Adapters["通知适配器"] EmailAdapter[电子邮件] ~~~ TeamsAdapter[Teams] ~~~ SlackAdapter[Slack] ~~~ JiraAdapter[Jira] end subgraph Data["数据访问"] EFCore[EF Core 10<br/>BeaconContext] ~~~ Dapper[Dapper<br/>热路径] end subgraph Infrastructure["基础设施"] Meta[(元数据 DB<br/>PostgreSQL / SQL Server)] ~~~ Sources[(9 数据源<br/>连接器)] Scheduler[IBeaconScheduler<br/>可插入调度器] ~~~ SQLiteVM[内存 SQLite<br/>跨 DB 连接] end React --> Edge Edge --> Core Core --> Adapters Core --> Data Data --> Infrastructure Core --> Infrastructure Adapters --> Infrastructure style UI fill:#e9e4fc,stroke:#430cda style Edge fill:#ece7fd,stroke:#5a30ee style Core fill:#eef0fa,stroke:#6c48ff style Adapters fill:#f4f6fa,stroke:#717a80 style Data fill:#eaf5ee,stroke:#16a34a style Infrastructure fill:#f4f6fa,stroke:#545454 ``` ### 查询执行：多步骤，跨数据库 ```mermaid sequenceDiagram participant User participant Scheduler as Beacon 调度器 participant QueryOrchestrator participant VirtualTableManager participant PostgreSQL participant SQLServer participant NotificationService participant Adapter User->>Scheduler: 创建订阅（Cron） Scheduler->>QueryOrchestrator: 执行查询（定时） QueryOrchestrator->>PostgreSQL: 执行步骤 1 PostgreSQL-->>QueryOrchestrator: 结果集 1 QueryOrchestrator->>VirtualTableManager: 存储 @@result1 QueryOrchestrator->>SQLServer: 执行步骤 2（带有 @@result1） SQLServer-->>QueryOrchestrator: 结果集 2 QueryOrchestrator->>VirtualTableManager: 存储 @@result2 QueryOrchestrator->>VirtualTableManager: 执行最终查询<br/>（连接 @@result1 和 @@result2） VirtualTableManager->>VirtualTableManager: 创建内存 SQLite 表 VirtualTableManager-->>QueryOrchestrator: 组合结果 QueryOrchestrator->>NotificationService: 发送结果 NotificationService->>Adapter: 分发（电子邮件/Teams/Slack/Jira） Adapter-->>User: 通知已交付 ``` ## ✨ 功能游览 ### 🔍 语义查询监控 - 多步骤查询，具有结果链接（`@@result1`，`@@result2`，…）和跨引擎连接 - 类型参数（`{startDate}`，`{userId}`）具有自动检测和验证 - 具有实时数据库浏览器的 Monaco SQL 编辑器；具有完整历史记录的查询版本控制 - 每次运行的执行历史记录和审计跟踪 ### ⏱️ 调度和自动化 - 通过可插入的 `IBeaconScheduler` 接口进行 Cron 调度；带来您自己的作业运行器；[Moberg Warp](https://moberghr.github.io/warp/) 是一个很好的选择，示例主机提供了一个可用的参考实现 - 通过 SignalR（`JobStatusChanged`，`NotificationCreated`，`ApprovalUpdated`）实时显示作业状态 ### 🔔 多通道通知 - **电子邮件**，带有 HTML 表格 + CSV/Excel 附件（完整数据集，无行限制） - **Microsoft Teams** 自适应卡片，**Slack** 丰富表格块，**Jira** 问题创建，**webhooks** - 具有每个订阅路由的收件人管理 ### 📋 警报任务和异常检测 - 订阅可以在检查发现问题时自动打开 **任务**；在后续运行返回干净时自动解决 - 统计异常检测：**Z-score（标准偏差）**，**IQR**，和 **百分比变化**，具有基线学习和每指标灵敏度 - 趋势图，注释，相关任务发现，手动解析带有注释 ### 🔄 数据迁移（ETL） - 四种模式：**插入**，**更新插入**，**截断加载**，**同步**（完美镜像） - 通过 `EFCore.BulkExtensions` 进行批量操作，具有行级错误跟踪 - 具有回滚、执行指标和完整历史的原子事务 ### 🤖 AI 功能（实验性） - **自动文档**: AI 分析您的模式并编写文档 — 以 Markdown、带有 ERD 图的 HTML 或 PDF 导出 - **自然语言警报**: 用英语描述检查，获取有效查询 - **AI 代理**: LLM 驱动的监控代理，其计划在执行前通过人为 **审批流程** - 运行时可更换的提供商（OpenAI / Anthropic / Azure OpenAI / AWS Bedrock），具有速率限制的队列和预算跟踪 > ⚠️ AI 功能为实验性。在依赖 AI 生成的内容之前，请审查它。 ### 🔐 安全性和治理 | 层 | 机制 | |---|---| | 静态机密 | 连接字符串使用 **AES-256-GCM** （经过身份验证，每个值都有_nonce）加密；强制 `Beacon:EncryptionKey` | | API 密钥 | **SHA256 哈希**，作用域（`读取` / `执行` / `管理员`），可选的每个项目限制，过期 — 原始密钥仅显示一次 | | 会话 | `HttpOnly`，`SameSite` cookie；状态更改请求的防伪令牌；登录速率限制 | | SSO | OIDC（任何兼容的提供商），具有可配置的角色映射；MCP 客户端的 JWT 持有者 | | MCP 执行 | 在连接器 **和** AST 级别强制执行只读；PII 检测和掩蔽；行限制；完整审计跟踪 | | 部署 | 可选的转发头支持，带有反向代理设置的代理白名单 | ### 💻 开发体验 - React 18 + Vite + TypeScript + Tailwind UI，具有类型化的 OpenAPI 客户端（`npm run codegen`，NSwag） - **模拟模式**（`npm run dev:mock`）— 完整的 UI，无需后端，由 MSW 提供支持 - 每个 REST 端点一个 MediatR 处理程序，OpenAPI 合同在 CI 中测试 - 150+ 后端测试（NUnit），包括 EF Core → SQL 翻译测试；Vitest + RTL + MSW 在前端 ## 📦 在您自己的应用中嵌入 Beacon 您想在现有的 ASP.NET Core 主机中集成 Beacon 吗？安装您需要的包： | 包 | 目的 | |---|---| | `Beacon.Core` | 核心域，CQRS 处理程序，EF 模型（必需） | | `Beacon.Core.PostgreSql` / `Beacon.Core.SqlServer` | EF Core 提供程序 + Beacon 元数据 DB 的迁移 | | `Beacon.UI` | React SPA 作为 Razor 类库提供（在 `/` 处提供服务） | | `Beacon.Api` | REST 最小 API 端点 + OpenAPI | | `Beacon.MCP` | MCP 服务器（工具 + 资源） | | `Beacon.AI` | LLM 集成，自动文档，异常检测（可选） | | `Beacon.Connector.*` | 每个引擎一个：`PostgreSql`，`SqlServer`，`MySql`，`BigQuery`，`Snowflake`，`Databricks`，`AzureSynapse`，`CloudWatch`，`Api` | ```bash dotnet add package Beacon.Core.PostgreSql dotnet add package Beacon.UI dotnet add package Beacon.Connector.PostgreSql ``` ```csharp using Beacon.Core; using Beacon.Core.PostgreSql; using Beacon.Connector.PostgreSql; using Beacon.UI; var builder = WebApplication.CreateBuilder(args); // 1. 核心服务 + 数据库提供程序 + 连接器 builder.Services.AddBeaconServices(builder.Configuration, options => { options.AddBeaconScheduler<YourScheduler>(); // 您的 IBeaconScheduler 实现 options.BaseUrl = "https://your-domain.com"; // 用于通知深链接 options.UseAI = true; // 可选（实验性） options.Authorization.Enabled = true; options.Authentication.EnableLoginForm = true; options.AddAuthenticationProvider<DatabaseAuthenticationProvider>(); }) .AddPostgreSqlConnector() // .AddSqlServerConnector().AddMySqlConnector().AddBigQueryConnector() ... .UsePostgreSql(builder.Configuration.GetConnectionString("BeaconContext")!, "beacon"); // 2. 身份验证（根目录的 React shell 的 cookie 方案） builder.Services.AddBeaconCookieAuthentication("/"); // builder.Services.AddBeaconOidcAuthentication(builder.Configuration); // 可选的 SSO // 3. AI + MCP + OpenAPI（可选层） builder.Services.AddBeaconAI(builder.Configuration); builder.Services.AddBeaconMcp(); builder.Services.AddOpenApi(); var app = builder.Build(); app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseAuthentication(); app.UseAuthorization(); app.MapOpenApi(); // /openapi/v1.json app.MapBeaconApi(); // /beacon/api/* app.MapMcp("/beacon/mcp").RequireAuthorization(); // MCP 服务器 app.MapBeaconUi(); // 根目录的 React SPA app.Run(); ``` > `src/Beacon.SampleProject/Program.cs` 是规范的、完整的参考（调度器连接、SignalR、OIDC、MCP 的 JWT、速率限制、防伪和负载轴承中间件顺序）。从它开始嵌入。调度通过 `IBeaconScheduler` 抽象 — 使用您选择的作业运行器实现它，例如 [Moberg Warp](https://moberghr.github.io/warp/)。 **生成安全加密密钥：** ```bash openssl rand -base64 32 ``` 📚 [安装指南 →](https://moberghr.github.io/beacon/getting-started/installation/) · [配置参考 →](https://moberghr.github.io/beacon/getting-started/configuration/) ## 🧱 项目布局 | 项目 | 角色 | |---|---| | `Beacon.Core` | 领域，CQRS 处理程序，服务，EF 模型 — 所有内容都指向这里 | | `Beacon.Core.PostgreSql` / `Beacon.Core.SqlServer` | 特定于提供程序的 `BeaconContext` + EF 迁移 | | `Beacon.AI` | LLM 集成，自动文档生成，异常检测，NL → SQL | | `Beacon.MCP` | MCP 服务器：工具，资源，防护措施，学习循环 | | `Beacon.Api` | REST 最小-API 端点 + OpenAPI，用于 React 外壳 | | `Beacon.UI` | React 单页应用 (`web/`)，作为 Razor 类库交付，在 `/` 处提供服务 | | `Beacon.SampleProject` | 主机 / 组合根（Kestrel，DI 接线，调度器，中间件，身份验证） | | `Beacon.Connector.*` | 9 种支持的引擎的数据源连接器 | | `Beacon.Tests` | NUnit 4 + Moq + FluentAssertions；通过 `NpgsqlTestContext` 进行 EF 转换测试 | ## 🛠️ 技术栈 **运行时** — .NET 10 / C# 14 / ASP.NET Core (Kestrel, 自托管) · **UI** — React 18, Vite, TypeScript, Tailwind CSS, Radix UI, TanStack Query/Table, Monaco, SignalR · **数据** — EF Core 10 (双提供程序迁移)，Dapper 热路径，EFCore.BulkExtensions · **作业** — 通过 `IBeaconScheduler` 可插拔（将其与 [Moberg Warp](https://moberghr.github.io/warp/) 结合使用） · **AI** — OpenAI / Anthropic / Azure OpenAI / AWS Bedrock，通过可交换的提供程序抽象 · **文档** — QuestPDF, Markdig, Mermaid ERDs, ClosedXML, CsvHelper · **集成** — Jira (Atlassian.SDK), Teams 自适应卡片, Slack ## 🔧 需求 - **.NET 10 SDK** 和 **Node.js 18+** （用于构建 React UI） - **PostgreSQL 12+** 或 **SQL Server 2019+** 作为 Beacon 的元数据数据库 - **32 个字符的加密密钥** (`Beacon:EncryptionKey`) — 必需 - *(可选)* AI 功能的 LLM API 密钥 · 用于电子邮件通知的 SMTP 提供程序 ## 🤝 支持与贡献 - **问题** — [报告错误或请求功能](https://github.com/moberghr/beacon/issues) - **讨论** — [提问和分享想法](https://github.com/moberghr/beacon/discussions) - **贡献** — 贡献需要签署 [CLA](CLA.md) ## 📄 许可证 Beacon 是 **双重许可** 的：免费 [GNU AGPL v3.0](LICENSE) **或** 付费商业许可证。 在 AGPLv3 下使用它 — 包括其 §13 网络/SaaS 源代码披露要求 — 无需付费，或 [联系我们获取商业许可证](LICENSING.md) 以在没有共用许可义务的情况下使用 Beacon。有关完整比较，请参见 [LICENSING.md](LICENSING.md)。 --- <div align="center"> _{A <b>Moberg</b> product · <i>严谨的工程，无限的可能性。</i>} <br/> _{2026 Moberg d.o.o. · <a href="https://moberghr.github.io/beacon">文档</a> · <a href="LICENSING.md">许可</a>} </div>