Layout.WatchDog.NET.Storages.PostgreSql 1.5.0-beta.6

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 存在已知依赖安全隐患，请勿继续使用。

主要功能

1.5.0-beta.6 发布准备：基于 beta.5 重构 Dashboard，重新组织日志工作区、资源图表、主题导航与 AI 抽屉；修复六后端存储与迁移，新增可选 OpenTelemetry 指标导出。安装示例已切换到候选版本；包尚未正式发布，上架前请使用本地候选包源。见详细发布说明、发布评估、Dashboard 图文导览、Storage 专题和OpenTelemetry 专题。

• 实时 HTTP 监控：记录所有请求和响应的详细信息。
• 异常捕获：自动捕获并记录应用程序运行时的异常。
• 代码内日志：支持在业务代码中手动记录消息和事件。
• 重构版 Dashboard：响应式日志工作区、资源雷达与趋势图，支持深浅主题、中英文、侧栏收起及 AI 右侧抽屉；显式启用后通过 /watchdog 访问。
• 多种数据库支持：内置 LiteDB，支持一键切换至主流关系型数据库、MongoDB 与 SQLite。
• 日志自动清理：支持配置定时自动清理旧日志。
• AI 辅助分析（可选）：装上附加包并在看板打开开关后，页面右下角出现悬浮助手，可直接用自然语言追问日志与异常；同一套数据也以 MCP 工具形式暴露给 Claude Desktop / Cursor 等外部客户端。核心包不引任何 AI 依赖，不装附加包时行为与之前完全一致。

重构版 Dashboard 页面导览

以下为 beta.6 当前 Dashboard 的真实界面截图，使用固定演示日志与资源数据，不包含真实业务信息、模型凭据或实际 AI 回答。各页面的使用场景、功能边界与英文图片见 Dashboard 图文导览。新版需显式开启，配置见下方快速开始。

登录：独立的看板入口

登录后进入统一导航的日志工作区；使用宿主配置的账号和密码。

请求日志：列表与详情一起查看

按路径、方法和状态筛选，选中请求后在下方查看元信息，切换请求头、响应头、请求体与响应体；详情栏随宽度调整，内容以淡主题色区分。

异常日志：堆栈与请求上下文并排

左侧快速切换异常，右侧展示异常类型、来源、路径、堆栈和请求体，减少来回打开详情的操作。

代码日志：关联事件与调用位置

按日志级别筛选，查看事件 ID、消息、源文件行号和调用方法；选中后保留列表上下文。

资源监控：节点与进程分区展示

资源雷达、CPU/内存趋势、磁盘容量、网络速率及进程 GC/线程集中展示。浏览器保留最近两分钟趋势，不是服务端历史数据库。

深色主题：图表、卡片和导航一起切换

同一套资源数据支持深浅主题，中英文与主题偏好可在顶部切换。

AI 助手：在日志页面打开右侧抽屉

通过悬浮机器人进入日志问答，支持拖动与贴边收起。图中为待发送问题，没有调用模型；需安装并配置可选 Agent 包后使用。

会话记录：继续排查、重命名与导出

在助手内管理会话，支持打开历史、重命名、导出、删除和多选导出；图中会话为演示数据。

模型配置：提供商、接口与模型集中管理

在助手内配置提供商、Endpoint、API Key 与模型列表，按需测试连接或保存配置。图中未填写凭据、未执行连接测试。

<details> <summary>查看窄屏布局：请求详情上下排列</summary>

窄屏中详情由左右分栏切换为上下排列，工具栏自动换行。下图为 780px 宽的演示。

</details>

安装

方式一：.NET CLI

安装 Layout.WatchDog.NET 核心包：

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

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

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

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

可用 Storage 包：

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

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

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

如需持续采集资源指标并通过标准 OTLP 对外发送 Metrics，可安装独立扩展包：

dotnet add package Layout.WatchDog.NET.OpenTelemetry --version 1.5.0-beta.6

接入方式、指标口径和后续 GreptimeDB 配置见 OpenTelemetry 指南。该包不增加历史数据库或 OTLP 接收端。

方式二：NuGet 包管理器

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

快速开始

1. 注册服务

在 Program.cs 中注册 WatchDog 服务。

using WatchDog;

// 在 Program.cs 中（本包目标框架为 .NET 8 / .NET 10）
builder.Services.AddWatchDog(wd => wd
    .WithAuth("admin", "your-password")
    .WithDashboard(d =>
    {
        d.Enabled = true;
        d.DefaultLocale = "zh-Hans";
        d.Features.Metrics = true; // 显示资源监控页
    }));

2. 配置中间件

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

var app = builder.Build();

app.UseWatchDog();

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

3. 查看日志

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

上述示例显式启用了新版 Dashboard。未开启 Dashboard.Enabled 时仍使用旧版 WatchPage；新版默认保留 /watchdog-legacy 作为兼容入口。AI 助手还需 Features.Agent、Agent 包和端点配置，见 Agent 接入指南。

记录日志

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

using WatchDog;

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

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

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

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

// .NET 8 / .NET 10 在 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.OpenTelemetry/：持续采集资源指标并通过 OTLP 导出的可选扩展包（Layout.WatchDog.NET.OpenTelemetry），不含历史存储。
• 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 许可证。