Layout.WatchDog.NET 1.5.0-beta.5

WatchDog

简介

WatchDog 是一个专为 ASP.NET Core Web 应用程序和 API 设计的实时消息、事件、HTTP（请求和响应）和异常记录器和查看器。它允许开发人员记录和查看消息、事件、对其 Web 应用程序的 HTTP 请求以及在运行时捕获的异常，全部实时显示。

WatchDog 利用 SignalR 实现实时通信，默认使用轻量级数据库 LiteDB（无需配置），同时支持扩展至外部数据库（MSSQL, MySQL, PostgreSQL, MongoDB, SQLite）。

本仓库以 Layout.WatchDog.NET 为包 ID 持续维护。上游 WatchDog.NET 的最新公开版本 1.4.12 存在已知依赖安全隐患，请勿继续使用。

主要功能

• 实时 HTTP 监控：记录所有请求和响应的详细信息。
• 异常捕获：自动捕获并记录应用程序运行时的异常。
• 代码内日志：支持在业务代码中手动记录消息和事件。
• 实时仪表盘：提供 Web 界面 (/watchdog) 查看日志，支持搜索和过滤。
• 多种数据库支持：内置 LiteDB，支持一键切换至主流关系型数据库、MongoDB 与 SQLite。
• 日志自动清理：支持配置定时自动清理旧日志。
• AI 辅助分析（可选）：装上附加包并在看板打开开关后，页面右下角出现悬浮助手，可直接用自然语言追问日志与异常；同一套数据也以 MCP 工具形式暴露给 Claude Desktop / Cursor 等外部客户端。核心包不引任何 AI 依赖，不装附加包时行为与之前完全一致。

截图预览

• 登录页面

• 请求与响应查看器

• 异常日志示例

安装

方式一：.NET CLI

安装 Layout.WatchDog.NET 核心包：

dotnet add package Layout.WatchDog.NET --version 1.5.0-beta.5

当前为预发布版，必须显式指定版本号（或加 --prerelease），否则默认只会装到稳定版。

如需使用外部数据库（MSSQL / MySQL / PostgreSQL / SQLite / MongoDB），额外安装对应的 Storage 扩展包：

# 例如使用 PostgreSQL
dotnet add package Layout.WatchDog.NET.Storages.PostgreSql --version 1.5.0-beta.5

可用 Storage 包：

默认 LiteDB 后端内置于核心包，无需额外安装。

如需 AI 能力，再按需安装两个可选包：

dotnet add package Layout.WatchDog.NET.Mcp   --version 1.5.0-beta.5   # 5 个只读日志查询工具（MCP）
dotnet add package Layout.WatchDog.NET.Agent --version 1.5.0-beta.5   # 巡检报告 + 看板内对话

方式二：NuGet 包管理器

Install-Package Layout.WatchDog.NET --version 1.5.0-beta.5
# 如需外部数据库，例如 PostgreSQL：
Install-Package Layout.WatchDog.NET.Storages.PostgreSql --version 1.5.0-beta.5

快速开始

1. 注册服务

在 Program.cs 中注册 WatchDog 服务。

using WatchDog;

// 在 Program.cs 中 (适用于 .NET 6+)
builder.Services.AddWatchDog(wd => wd
    .WithAuth("admin", "Qwerty@123"));

2. 配置中间件

在 HTTP 请求管道中启用 WatchDog 中间件。建议在 UseRouting, UseAuthentication, UseAuthorization 之后添加。

var app = builder.Build();

app.UseWatchDog();

异常日志中间件已由 UseWatchDog() 内部自动挂载，无需手动调用。

3. 查看日志

启动你的应用程序，访问 /watchdog 路径（例如：https://localhost:5000/watchdog），使用配置的用户名和密码登录即可查看实时日志。

记录日志

在代码的任何位置调用 WatchLogger：

using WatchDog;

// 记录普通信息
WatchLogger.Log("用户登录成功");

// 记录警告
WatchLogger.LogWarning("请求频率过高");

// 记录错误
WatchLogger.LogError("处理订单失败", eventId: "Order_001");

也可以把标准的 ILogger 日志汇总到 WatchDog：

// .NET 6+ 在 Program.cs 中配置
builder.Logging.AddWatchDogLogger();

更多文档

项目结构

整体分三层：宿主进程内的请求管道与终结点、可按需替换的存储层、以及可选的 AI 扩展包。所有能力都在宿主进程内运行——没有独立服务，也没有第二个进程。

flowchart TB
    Browser["浏览器：独立看板 / 原内嵌页面"]
    ExtClient["Claude Desktop / Cursor"]
    Model["外部模型：OpenAI / Anthropic / Ollama"]

    subgraph Process["宿主进程 · WatchDog 全部在进程内"]
        Pipe["请求管道<br/>异常记录 → 路由 → 请求/响应记录 → 终结点"]
        subgraph Endpoints["终结点"]
            Legacy["/watchdog-legacy 原内嵌页面"]
            Dash["/watchdog 独立看板"]
            Api["/watchdog-api/v1/* JSON API"]
            Hub["/wtchdlogger SignalR"]
            Mcp["/watchdog-mcp MCP 工具"]
            Ai["/watchdog-ai/v1/* AI 助手"]
        end
        Services["核心服务<br/>WatchDogOptions / SkipRegistry / SessionAuth / LogIdGenerator"]
        Ana["IWatchDogAnalytics<br/>DefaultAnalytics：聚合、时间窗口、按 id 查单条"]
    end

    subgraph Store["存储层 · IWatchDogStorage（可替换）"]
        Lite["LiteDB（内置，零配置）"]
        Ext["SQLite / SQL Server / MySQL / PostgreSQL / MongoDB"]
    end

    Browser --> Dash
    Browser --> Api
    Browser --> Hub
    ExtClient --> Mcp
    Model --> Ai
    Ai --> Mcp
    Pipe --> Legacy
    Pipe --> Dash
    Pipe --> Api
    Pipe --> Hub
    Pipe --> Mcp
    Pipe --> Ai
    Api --> Ana
    Mcp --> Ana
    Ai --> Ana
    Pipe -- 写日志 --> Store
    Ana -- 读时间窗口 --> Store
    Services -. 配置 / 跳过前缀 / 会话校验 .-> Pipe

各模块说明：

• src/WatchDog/：核心库源码（Layout.WatchDog.NET，内置 LiteDB 后端与看板嵌入资源宿主）。
  • Extensions/：AddWatchDog / UseWatchDog 入口与 Fluent Builder。
  • Validation/：启动期配置校验。
  • src/Controllers/：包含处理日志查看请求的控制器。
  • src/Storages/：默认 LiteDB 存储实现（IWatchDogStorage）。
  • src/Analytics/：可分析查询层（聚合、时间窗口、按 id 查单条）。
  • src/Helpers/：日志 ID 生成器、分页、节点指标采集等工具。
  • src/Hubs/：SignalR 集线器，用于实时推送日志。
  • src/Models/：数据模型定义与统一配置模型 WatchDogOptions。
  • src/Services/：后台自动清理服务等。
  • src/WatchPage/：内嵌前端页面（由 /WTCHDGstatics 提供）。
  • src/Dashboard/：Vue 看板构建产物（内嵌为资源）。
• src/WatchDog.Storages.SqlServer/、.MySql/、.PostgreSql/、.Sqlite/、.MongoDb/：外部数据库 Storage 扩展包，各自只依赖一个驱动。
• src/WatchDog.Mcp/：MCP Server 扩展包（Layout.WatchDog.NET.Mcp），同进程内嵌，暴露 5 个只读日志查询工具，不依赖任何模型。
• src/WatchDog.Agent/：单 Agent 宿主扩展包（Layout.WatchDog.NET.Agent），把 MCP 端点包成可出报告的巡检 Agent，并给看板提供悬浮助手。
• src/WatchDog.Dashboard/：独立看板前端源码（Vue 3 + Vite + Tailwind）。
• samples/：API / MVC / MCP / Agent 示例宿主。
• test/：单元测试工程（xunit.v3），运行方式见 test/README.md。

贡献

如果你发现了 Bug 或者希望增加新功能：

1. Fork 本仓库。
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 发起 Pull Request。

致谢

• Kelechi Onyekwere - GitHub | Twitter
• Israel Ulelu - GitHub | Twitter

许可证：本项目采用 MIT 许可证。