Layout.WatchDog.NET.Storages.Sqlite 1.5.0-beta.7

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.7 候选准备：日志改为直接等待 Storage 写入，完善依赖注入、取消和实时会话鉴权；修复 LLM 配置保存、MCP 资源释放及对话归档一致性，交互助手新增当前资源快照查询。九个包统一版本，包含接口和失败处理行为变更，升级前请阅读发布说明与验证记录。尚未执行 NuGet 发布；上架前请使用本地候选包源。下方界面导览沿用 beta.6 的演示截图。

• 实时 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.7

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

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

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

可用 Storage 包：

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

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

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

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

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

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

交互助手可显式启用 MCP 的 EnableResourceSnapshots，复用当前资源采样缓存回答 CPU、内存、磁盘容量等问题。 支持采样新鲜度、缺失值与指标口径说明，巡检报告仍保持日志分析范围，见 资源问答接入。

方式二：NuGet 包管理器

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

快速开始

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 接入指南。

宿主自行管理路由

原有 app.UseWatchDog() 保留组合注册方式及默认 MVC 路由行为。需要与宿主自己的 MVC、Minimal API 路由分别管理时，可使用分步入口：

app.UseWatchDogMiddleware();
app.MapWatchDog();             // 只映射 WatchDog 页面、API 与实时端点
app.MapControllers();         // 宿主继续决定自己的路由

AddWatchDog 不再修改宿主的 MvcOptions.EnableEndpointRouting，也不会提前构建一条随后丢弃的中间件管道。启用 WithOutputCache() 时会同时注册所需服务；缓存策略仍由宿主决定。

配置在 AddWatchDog 完成时校验并复制嵌套设置与数组，之后修改原 Builder 对象不会改变已注册配置。配置按启动期生效，不支持通过修改运行对象热更新。非法正则、空配置对象和未知枚举值会作为配置错误提前报告。

工程检查使用 global.json 中固定的 .NET 10 SDK，继续编译和测试 net8.0/net10.0。核心生成 XML 文档并在打包时检查跨框架 API 兼容性；历史文档和命名建议逐步治理，取消令牌遗漏、动态日志模板和可空错误会阻止新增回归。跨平台核心测试与 Linux 六数据库集成测试分别执行。

记录日志

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

using WatchDog;

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

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

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

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

// .NET 8 / .NET 10 在 Program.cs 中配置
builder.Logging.AddWatchDogLogger();

通过 DI 扩展

默认扩展契约通过 TryAdd 注册，宿主可以在 AddWatchDog / AddWatchDogAgent 前注册自己的实现，也可以在注册后覆盖。默认行为、HTTP 路由、数据格式与配置保持兼容。

核心契约位于 WatchDog.src.Interfaces，节点原始指标契约位于 WatchDog.src.Helpers.Metrics，Agent 契约位于 WatchDog.Agent、WatchDog.Agent.Chat 和 WatchDog.Agent.Ai。

using WatchDog.src.Interfaces;

builder.Services.AddSingleton<IWatchDogIdGenerator, ApplicationLogIdGenerator>();
builder.Services.AddWatchDog(wd => wd.WithAuth("admin", "your-password"));

Singleton 实现需要支持并发，不能捕获 Scoped 服务。采集实例由请求中间件恢复和释放，不得关闭业务流；脱敏仅修改日志副本。自定义会话策略应同时处理会话与实时连接，保留注销撤销连接及过期检查。投递诊断不能重新写入 WatchDog 日志，以免回环。

核心宿主适配器会启动、停止被选中的会话/投递实现（实现 IHostedService 时），无需再为这些实例调用 AddHostedService。默认日志直接等待 Storage 写入，成功后再广播，不使用内存 Channel、后台队列或持久化暂存。替换投递实现也不会跳过存储初始化。显式 UseSqlite / UseMySql 等仍选择对应后端。可选存储能力支持直接注册 IWatchDogAiSettingsStorage、IWatchDogChatSessionStorage、IWatchDogRetentionStorage、IWatchLogWindowReader，未注册时继续使用当前存储实现提供的能力。

IWatchDogLogPipeline.WriteAsync 现在返回 Task，同步 Write 与 IWatchDogLogWriter.Write 都等待实际入库；移除旧 TryWrite、入队成功布尔值及容量/字节预算/排空配置。写库失败向调用方传播，ILogger 可能由框架包装为 AggregateException；同步日志会承担数据库延迟。HTTP 响应已发送时无法撤回成功状态，业务异常的保存失败通过独立诊断及异常 Data["WatchDog.LoggingFailure"] 报告，原业务异常仍被保留。Storage 内部及其构造/迁移不能通过 WatchDog 记录自身诊断，应使用独立日志出口，避免递归依赖。详见直接写库语义。

宿主适配器与直接写入服务共享幂等存储初始化；停止时关闭新调用并等待正在执行的操作，不丢弃或额外取消调用方持有的写入。写入、Flush、清空与压缩通过操作门协调，滚动保留仍由 Storage 的事务/并发语义保障。会话 Registry 将 HTTP/SignalR 适配与租约索引分开管理，断连回调和发送在状态锁外执行；注销或过期会取消该租约正在进行的发送，推送不会延长空闲时间。

IWatchDogModelClientFactory 负责所有模型提供商，并区分聊天、报告和连接测试；原有 IWatchDogChatClientFactory 仍只处理 provider=custom。工具源工厂每次创建独立实例，报告与聊天各自缓存和释放连接。工厂返回的模型客户端由 Agent 在关闭时释放，连接测试用完即释放。

原有 WatchLogger.* 和 WatchDogSessionAuth 静态 API 保留。多个宿主共用进程时，请通过 ILogger / IWatchDogLogWriter 记录日志；静态 WatchLogger 仍使用最后一次 UseWatchDog 指定的宿主。

更多文档

项目结构

整体分三层：宿主进程内的请求管道与终结点、可按需替换的存储层、以及可选的 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 许可证。