# EasyDBA

**Repository Path**: fengstyle/EasyDBA

## Basic Information

- **Project Name**: EasyDBA
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyDBA

> 一个基于 **.NET 10** 的数据库健康检查与运维平台，覆盖 **21 种数据库 + 19 大子系统 1080+ 条唯一巡检规则 + RAG 知识库 + 多通道通知 + 进阶监控 + 多格式报告导出**。

EasyDBA 支持对**关系型 / 国产 / NoSQL / 列存 / HTAP** 等多种数据库进行**自动化健康巡检**，并生成符合审阅标准的 **Word / PDF / HTML / Markdown 报告**。它集成了 **RAG 知识库**、**多通道通知**（邮件 / 飞书 / 钉钉 / 企微）、**进阶监控**（容量预测 / 异常检测 / 阻塞链 / Top SQL）与 **AI 智能诊断**，适合 DBA、运维与平台工程师在日常托管、上线前检查、周期性巡检等场景中使用。

---

## ✨ 特性

### 数据库支持（21 种）

| 类别 | 数据库 |
|------|--------|
| 关系型主流 | SQL Server、MySQL、MariaDB、PostgreSQL、Oracle、SQLite |
| 国产数据库 | DM8（达梦）、YashanDB（崖山）、GBase 8s、OceanBase、openGauss、IvorySQL、KingbaseES、TiDB |
| 经典商用 | DB2、Informix |
| NoSQL / 文档 | MongoDB、Redis、Elasticsearch |
| 列存 / HTAP | ClickHouse、Cassandra |

**协议族复用**：MariaDB/TiDB/OceanBase → MySQL；IvorySQL/KingbaseES/openGauss → PostgreSQL；DM8/YashanDB → Oracle；GBase 8s/Informix → Informix。规则集与监控指标自动复用。

![输入图片说明](DemoImage/00.png)

![输入图片说明](DemoImage/0.png)

![输入图片说明](DemoImage/1.png)

![输入图片说明](DemoImage/2.png)

![输入图片说明](DemoImage/4.png)

![输入图片说明](DemoImage/5.png)

![输入图片说明](DemoImage/6.png)

![输入图片说明](DemoImage/7.png)

### 19 大子系统

| # | 子系统 | 说明 |
|---|--------|------|
| 1 | **巡检引擎** | 788 条唯一规则（按数据源有效统计累计 1080+），覆盖 21 种数据库，含健康评分、风险等级、手工检查提醒 |
| 2 | **配置基线** | 关键参数当前值 vs 推荐值（DM8/YashanDB/GBase 8s/Oracle/SQLite/MySQL/PG/SQL Server） |
| 3 | **fix_sql 一键修复** | 每项风险带可执行修复脚本，危险操作标记 RiskLevel |
| 4 | **报告导出** | Word (.docx) + PDF + HTML（自包含、可邮件发送）+ Markdown，状态色编码、修复脚本盒、手工检查提醒区块、知识引用章节 |
| 5 | **REST API** | Key + Cookie 双鉴权中间件，25 个 Controller / 约 140 个端点 |
| 6 | **RBAC 用户权限** | admin / operator / viewer 三角色，PBKDF2-SHA256 密码哈希，API Key 自动签发 |
| 7 | **AI 智能诊断** | 基于 Microsoft Agent Framework + Ollama，本地大模型分析巡检结果 |
| 8 | **AI 对话面板** | Web 右下角浮动 FAB 聊天小组件，多轮对话 + SSE 流式响应，会话归属隔离 |
| 9 | **RAG 知识库** | 三段式范式（Catalog 注册表 → Seeder 落库 → 用户 CRUD），6 个 Catalog 内置 30 篇种子，文档上传（txt/md/docx）+ 混合检索（BM25 + 向量 RRF 融合） |
| 10 | **历史趋势分析** | 报告总数 / 平均分 / 各健康等级计数等统计卡片 + 表格化趋势列表，按数据源维度展示 |
| 11 | **巡检章节配置化** | InspectionProfile 配置驱动，章节可启用/禁用/排序，规则白名单 |
| 12 | **定时任务调度** | Hosted Service + Cron 解析（5 段式），巡检/备份/清理三类作业 |
| 13 | **多通道通知** | 4 通道独立开关（email/feishu/dingtalk/wecom），全局默认 + 每数据源覆盖，SMTP 多账户，备份规则级通道白名单 |
| 14 | **容灾备份** | MySQL/PG/SQLite/SQLServer/Mongo 自动调用 dump 工具，保留策略，A-B 拓扑（本地 / SSH 远程 / 共享存储）配置下沉到备份规则 |
| 15 | **SQL 编辑器** | Web 内置编辑器（CodeMirror 方言高亮），`Ctrl+Enter` 执行、最近 20 条历史（localStorage）、危险 SQL（DROP/DELETE/TRUNCATE）二次确认 |
| 16 | **实时监控** | 连接延迟 / 多指标采集，ECharts 仪表盘与折线图，可配置刷新间隔（5/10/30s/关闭），自适应网格布局可拖拽调宽 |
| 17 | **进阶监控面板** | 容量预测（线性回归）/ 异常检测（基线检测）/ 多实例对比 / 阻塞链根因 / Top SQL（performance_schema digest），BaseChart + CSS 变量主题自适应 |
| 18 | **时序指标分级保留** | 原始样本 7d + 5m 聚合 30d + 1h 聚合 365d，MetricRollupService 自动 rollup，QueryRange 智能路由（按 span 选 rollup 层级，无数据回退原始表） |
| 19 | **多语言 i18n** | 中英文切换，`data-i18n` 自动翻译 |
| — | **共享链接** | 免登录报告分享（`/s/:token`），过期/访问次数控制 |
| — | **远程终端 SSH** | 基于 SSH.NET，密码认证，多会话管理（预览版） |
| — | **AWR 报告分析** | Oracle AWR HTML 解析，Top SQL/事件/段（基于 HtmlAgilityPack） |
| — | **DM8 离线扫描** | 8KB 分页扫描，坏块启发式检测 |
| — | **指标告警规则** | 指标阈值规则 CRUD + 定时扫描 + 告警历史 |
| — | **插件系统** | PluginManifest + IPlugin 接口，反射加载；市场目录为**预览版**（`install` 当前仅注册清单，不实际加载 / 执行 DLL） |

### UI 设计（Diagnostic Atlas v2.0）

- **Diagnostic Atlas 设计系统**：朱红（crimson）/ 钢青（steel teal）/ 纸色（paper）令牌，暗色为默认主题
- 替代早期 NOC 风格（磷光薄荷绿 #00E5A0）
- **签名元素**：圆环式健康度仪表盘（conic-gradient + 内联 CSS 变量）
- 风险等级标记（Critical 脉冲动画）
- 待手工检查提醒区块（紫色高亮）
- 知识引用章节（靛蓝 #6366F1 主题色）
- 三态主题（light / dark / system）、响应式布局、`prefers-reduced-motion` 支持

### 生产风险防控

- `HealthRule` 增加 `RiskLevel` / `ManualCheckRequired` / `ManualCheckReason` / `ManualCheckGuide`
- 引擎跳过 `ManualCheckRequired=true` 的规则，汇总到报告末尾手工检查清单
- MongoDB / Informix / Cassandra 等数据库的部分高危巡检改为手工检查（全库共 81 项）
- 结果不计入健康评分

---

## 🧱 解决方案结构

```
EasyDBA.slnx
├── src/
│   ├── EasyDBA.Core/              # 引擎、规则、领域模型与本地存储
│   │   ├── Abstractions/          #   IDbProvider 抽象
│   │   ├── Configuration/         #   SectionConfig / InspectionProfile
│   │   ├── Engine/                #   InspectionEngine / RuleEvaluator / HealthScoring
│   │   ├── Models/                #   DataSource / HealthRule / InspectionReport /
│   │   │                          #   NotificationModels / KnowledgeModels 等
│   │   ├── Plugins/               #   PluginManifest / IPlugin 接口
│   │   ├── Rules/                 #   RuleCatalog + 各数据库规则集
│   │   │   └── Catalogs/          #     *Rules.cs（21 种数据库规则）
│   │   ├── Scheduling/            #   ScheduleJob / JobExecutionLog
│   │   └── Store/                 #   DataSourceStore / UserStore / ConfigStore /
│   │                              #   KnowledgeStore / ShareLinkStore / ScheduleStore /
│   │                              #   PluginStore / NotificationStore / MetricStore
│   ├── EasyDBA.Providers/         # 各数据库驱动实现
│   │   └── Providers/             #   SqlServer / MySql / PostgreSQL / Oracle / Sqlite /
│   │                              #   MongoDB / Redis / ClickHouse / Elasticsearch /
│   │                              #   Informix / Db2 / Cassandra
│   └── EasyDBA.Web/               # ASP.NET Core 宿主（托管 Vue3 SPA + REST API）
│       ├── Controllers/           #   25 个 Controller（约 140 端点）
│       ├── Pages/                 #   仅 3 个白名单 Razor 旧根（Account/Login、Account/Logout、Error）
│       │                          #   + 布局；其余 Razor 页已在 GA 收口删除（SPA 为唯一官方前端）
│       ├── ClientApp/             #   Vue3 SPA 前端源码（Vite 构建产物输出到 wwwroot/）
│       ├── Security/              #   ApiKeyMiddleware / AuthService / ApiRbac
│       ├── Services/              #   InspectionService / ReportRenderer / PdfReportRenderer /
│       │                          #   AiService / MetricsCollector / MetricRollupService /
│       │                          #   SchedulerService / NotificationService / BackupService /
│       │                          #   SshTerminalService / AwrAnalyzer / Dm8OfflineScanner /
│       │                          #   PluginLoader / I18nService / KnowledgeAugmenter /
│       │                          #   ReportKnowledgeResolver
│       └── wwwroot/               #   SPA 构建产物（index.html / assets/）+ css / i18n / favicon
└── tests/                         # 单元测试与集成测试
```

---

## 🚀 快速开始

### 环境要求

- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)（`global.json` 锁定 `10.0.300`）
- 如需巡检非 SQLite 数据库，目标库需可达且其端口/账号可用
- 如需 AI 智能诊断：本地 [Ollama](https://ollama.ai/) 运行 `qwen2.5:7b`（或任意 OpenAI 兼容端点）
- 如需 SSH 远程终端：目标主机开启 SSH 服务
- 如需备份功能：MySQL 安装 `mysqldump`、PG 安装 `pg_dump`、Mongo 安装 `mongodump`

### 运行

```bash
dotnet run --project src/EasyDBA.Web/EasyDBA.Web.csproj
```

默认监听 **http://localhost:5180**（首次启动自动创建 SQLite 元数据库与演示数据源）。

### 默认管理员

首次启动自动创建管理员账号（**强制改密门禁**：首次登录必须修改密码，否则路由守卫拦截到改密页）：

| 用户名 | 密码 | 角色 | 强制改密 |
|--------|------|------|----------|
| `admin` | `admin123` | admin | ✅ 是 |

**强烈建议登录后立即修改密码或在用户管理页创建新管理员并禁用默认账号。**

#### 种子开关（环境变量）

| 变量 | 作用 |
|------|------|
| `EASYDBA_NO_SEED_ADMIN` | 非空时跳过默认管理员种子（生产可裸账号启动，由外部编排创建账号） |
| `EASYDBA_ADMIN_USER` / `EASYDBA_ADMIN_PASSWORD` | 无用户时引导种子该管理员（仍标记强制改密）。例如 `EASYDBA_ADMIN_USER=root EASYDBA_ADMIN_PASSWORD='StrongPass!23'` |
| 二者均未设置 | 维持默认 `admin`/`admin123` 种子（带强制改密） |

> 改密接口：`POST /api/v1/auth/change-password`（`old_password` + `new_password`，需登录；新密码长度 ≥ 8）。

### 配置 AI（可选）

启动 Ollama：
```bash
ollama pull qwen2.5:7b
ollama serve
```

在 Web 控制台 → AI 配置 → 勾选 "启用 AI" → 保存。

---

## 📦 部署方式

EasyDBA 提供四种部署方式，按场景选择：

| 方式 | 适用场景 | 体积 | 说明 |
|------|----------|------|------|
| **源码运行** | 开发 / 调试 | 需 .NET 10 SDK + Node | `dotnet run` + `npm run dev` |
| **Docker** | 服务器 / 容器化部署 | ~200MB 镜像 | 一键 `docker compose up -d` |
| **桌面 EXE** | 个人 DBA 本地使用 | ~80MB（裁剪后） | 双击运行，自动开浏览器，无需装运行时 |
| **Windows 服务** | 常驻后台（定时巡检/备份） | 同桌面 EXE | 开机自启，同一 EXE 切换模式 |

### 方式一：Docker 快速部署（推荐服务器场景）

```bash
# 构建并后台启动
docker compose up -d

# 查看日志
docker compose logs -f

# 停止
docker compose down
```

- 访问：`http://<服务器IP>:5180`
- 数据持久化：Docker 卷 `easydba-data` 挂载到 `/app/data`（SQLite 元数据库、备份、AES 密钥、插件）
- 默认账号：`admin` / `admin123`（首次登录强制改密）
- 生产环境务必修改 `docker-compose.yml` 中的 `EASYDBA_ADMIN_PASSWORD`

### 方式二：桌面 EXE（双击运行）

```powershell
# 在项目根目录执行发布脚本
.\publish-desktop.ps1
```

产物输出到 `publish/` 目录，包含：
- `EasyDBA.Web.exe` —— 自包含单文件（含 .NET 运行时，目标机无需安装任何依赖）
- `wwwroot/` —— Vue3 SPA 静态资源
- `appsettings.json` / `appsettings.Production.json` —— 配置文件

**使用方式**：将 `publish/` 目录拷贝到目标 Windows 机器，双击 `EasyDBA.Web.exe`：
- 控制台窗口显示运行状态
- 自动打开默认浏览器访问 `http://localhost:5180`
- 数据存储在 EXE 同级 `data/` 目录
- 关闭控制台窗口即停止

**体积优化选项**：
```powershell
.\publish-desktop.ps1              # 默认：partial 裁剪（安全，移除未使用框架代码）
.\publish-desktop.ps1 -NoTrim       # 不裁剪（最大兼容性，体积约 +30%）
.\publish-desktop.ps1 -Runtime win-arm64  # ARM64 设备
```

### 方式三：Windows 服务（开机自启）

同一 EXE 可注册为 Windows 服务，实现定时巡检 / 备份 / 告警的开机自启：

```powershell
# 先按方式二发布到 publish/ 目录

# 注册服务（路径用绝对路径，binPath= 后有一个空格）
sc create EasyDBA binPath= "C:\EasyDBA\EasyDBA.Web.exe" start= auto
sc description EasyDBA "EasyDBA 数据库巡检平台（定时巡检/备份/告警）"

# 启动
sc start EasyDBA

# 停止 / 删除
sc stop EasyDBA
sc delete EasyDBA
```

服务模式下不自动弹窗（通过浏览器访问 `http://localhost:5180`），日志写入 Windows 事件查看器。

### 环境变量参考

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `EASYDBA_PORT` | `5180` | 监听端口（桌面模式绑定 localhost） |
| `ASPNETCORE_URLS` | — | 覆盖监听地址（Docker 设 `http://+:5180`） |
| `ASPNETCORE_ENVIRONMENT` | `Production` | 运行环境（开发用 `Development`） |
| `EASYDBA_ADMIN_USER` | `admin` | 首次启动种子管理员用户名 |
| `EASYDBA_ADMIN_PASSWORD` | `admin123` | 首次启动种子管理员密码（仍强制改密） |
| `EASYDBA_NO_SEED_ADMIN` | — | 非空时跳过种子管理员（外部编排创建账号） |
| `EASYDBA_NO_BROWSER` | `0` | 设 `1` 禁止桌面模式自动开浏览器 |
| `DOTNET_RUNNING_IN_CONTAINER` | — | Docker 内自动设为 `true`，跳过自动开浏览器 |

### 桌面版 vs Web 版设计说明

EasyDBA 选择 **自包含 ASP.NET Core EXE + 自动开浏览器** 而非 MAUI+WebView2 套壳：

- **MAUI+WebView2**：依赖 WebView2 运行时（目标机未必安装）、SDK 体积膨胀、裁剪不友好，且 SPA 已是成品，套壳无视觉增益
- **自包含 EXE**：纯 ASP.NET Core，完全可裁剪，双击即用 + 自动开浏览器，体积最小（裁剪后 ~80MB），同一二进制支持服务模式

---

## 🔍 巡检规则一览

> 规则数按各数据源 `RuleCatalog.Get()` 实际返回的有效规则统计（协议族复用：MariaDB 复用 MySQL、IvorySQL/openGauss/KingbaseES 复用 PostgreSQL、DM7 复用 DM8）。去重后全库唯一规则定义 **788 条**，按数据源累计 **1080+ 条**。

| 数据库 | 规则数 | 典型检查项 |
|--------|--------|------------|
| SQL Server | 72 | 安全配置审计（sa 启用/空密码/sysadmin 成员/xp_cmdshell 等）、配置基线、版本、连接、阻塞链、缺失索引、Top CPU/逻辑读、长事务、备份新鲜度、AlwaysOn、tempdb、复制、作业状态、死锁历史、内存压力、VLF 数量、页生命周期、系统层手工检查 |
| MySQL | 104 | 安全配置审计（空密码/root 远程/anonymous/SSL/secure_file_priv/弱插件）、配置基线、复制（GTID/半同步）、缓冲池命中率、慢查询 digest、冗余/未用索引、长事务、binlog 保留、死锁、临时表溢出、全表扫描比率、MyISAM 表、持久化（innodb_flush_log_at_trx_commit/sync_binlog）、系统层手工检查 |
| MariaDB | 118 | 复用 MySQL 通用规则 + Galera 集群规模/复制延迟/流控、ColumnStore、Aria 引擎、sys schema 兼容性等 MariaDB 专属 |
| PostgreSQL | 63 | 安全配置审计（trust 认证/无密码登录/superuser/SSL/密码加密）、配置基线、膨胀、Vacuum、WAL、慢查询、冗余/未用索引、长事务、复制延迟、复制槽、autovacuum、连接耗尽、临时文件、系统层手工检查 |
| openGauss | 63 | 复用 PostgreSQL 规则集（PG 协议兼容，pg_stat_*/pg_settings 通用） |
| IvorySQL | 63 | 复用 PostgreSQL 规则集（PG 协议兼容） |
| KingbaseES | 77 | 复用 PG 通用规则 + KSR 双机热备、审计状态、sysctl/sysview、DCI 兼容参数等金仓专属 |
| Oracle | 90 | 安全配置审计（默认开放账号/审计关闭/PUBLIC 系统权限/弱 profile/失败登录/过期锁定）、配置基线（8 参数）、AWR 负载画像、归档速率、FRA、闪回区、Data Guard、阻塞链、死锁、未用索引、失效约束/触发器、Top SQL、表空间、系统层手工检查 |
| DM8（达梦） | 37 | 安全配置审计、实例状态、表空间、会话、锁等待、长事务、归档模式、AWR Top SQL、缓冲池命中率、失效对象、备份新鲜度、配置基线（BUFFER/MAX_SESSIONS/REDO/CHECK_TIME）、系统层手工检查 |
| YashanDB（崖山） | 33 | 安全配置审计、实例状态、表空间、会话、锁等待、长事务、归档模式、Top SQL、缓冲池命中率、失效对象、备份新鲜度、HA 集群节点、配置基线、系统层手工检查 |
| SQLite | 28 | 配置基线（PRAGMA）、表无主键、冗余索引、无索引表、stat1 过期、integrity_check（手工）、外键检查（手工）、WAL 检查点、空闲页、文件权限、文件系统类型 |
| GBase 8s | 34 | 安全配置审计、实例版本、dbspace 使用率、会话、长连接、锁等待、长事务、死锁、逻辑日志、归档模式、检查点、缓冲池命中率、Top SQL、无索引大表、配置基线（BUFFERS/LOGFILES/LOGSIZE）、系统层手工检查 |
| Informix | 26 | 安全配置审计、dbspace、锁、检查点、长事务、缓冲池 |
| TiDB | 57 | MySQL 协议层通用子集（安全审计/连接/库大小/字符集/大表/无主键等 22 条）+ Region 健康/热点、TiKV 水位、PD 调度、GC、TSO 延迟、TiFlash 副本等分布式专属 |
| OceanBase | 4 | SQL 审计开关、租户/Unit 资源水位、合并/冻结、关键参数（display 型呈现，阈值告警由监控指标 MetricThresholds 承载） |
| MongoDB | 54 | 健康状态、连接、副本集、安全（含手工检查）、性能分析、存储空间、日志与文件系统（手工）、备份策略（手工） |
| Redis | 37 | 安全（protected-mode/requirepass/ACL/命令重命名）、内存、连接、持久化、慢日志、复制、键过期策略、最大内存策略 |
| Elasticsearch | 38 | 安全（传输/HTTP TLS/匿名）、集群健康、节点状态、分片、索引大小、线程池、缓存 |
| ClickHouse | 32 | 安全（匿名访问/TLS）、集群、副本、分区、合并、慢查询、磁盘 |
| Cassandra | 25 | 安全（匿名访问/TLS）、节点状态、压缩、流式传输、修复历史 |
| DB2 | 26 | 安全配置审计、表空间、缓冲池、锁、连接、日志 |

**总计 1080+ 条有效规则**（去重后唯一规则定义 788 条；协议族复用 MySQL / PostgreSQL / Oracle / Informix）。其中 **81 条**标记为 `ManualCheckRequired=true`，自动跳过执行，统一在报告末尾「手工待检查项提醒」区块展示完整原因与操作指引；部分规则施加 `MinVersion` 版本区间门控，兼容多版本数据库，优先最新版、尽力兼容老版。

---

## 🧩 健康评分算法

```
score = 100 - critical * 15 - warning * 6
score = clamp(score, 0, 100)
level = 优秀 (>=90) / 良好 (>=75) / 一般 (>=60) / 需关注 (<60)
```

每条规则结果状态：`通过 / 警告 / 严重 / 信息 / 待手工`。`待手工` 与 `信息` 不计入评分。

---

## 📚 RAG 知识库

三段式范式对齐 RuleCatalog 模式，确保内置知识可版本化升级且不覆盖用户修改：

| 阶段 | 说明 |
|------|------|
| **Catalog 注册表** | 6 个 Catalog（Common / MySql / Oracle / SqlServer / PostgreSQL / Dm8），每个含 5 篇内置种子，每篇含 BuiltinKey / BuiltinVersion / Category / DbTypes / RuleKeys / Tags / Content(Markdown) |
| **Seeder 落库** | 幂等播种：缺失则 InsertBuiltin；版本递增且 `UserModified=false` 则 UpgradeBuiltin；`UserModified=true` 跳过不覆盖 |
| **用户 CRUD** | 15 端点矩阵，支持上传 / 编辑 / 删除 / 重建索引 / 规则关联 / 告警关联 |

**混合检索**：BM25 关键词检索 + TF-IDF 向量检索，通过 RRF（Reciprocal Rank Fusion）融合排序，本地嵌入无外部依赖。

**报告知识引用**：导出报告时 `ReportKnowledgeResolver` 按报告命中规则 key 反查 `KnowledgeLinkStore` 关联知识，填充 `InspectionReport.KnowledgeRefs`，4 个渲染器（Word/PDF/HTML/Markdown）统一渲染「📚 依据知识 / 参考资料」章节，受 `KnowledgeSettings.ReportCitationEnabled` 开关控制。

**权限矩阵**：GET 端点 viewer 可读；写操作（upload / docs POST/PATCH/DELETE / reindex / links）限 operator；全量重建 rebuild + 设置 PUT + 污染扫描 scan-suspect 限 admin。

---

## 🔔 多通道通知

| 通道 | 说明 |
|------|------|
| **email** | SMTP 多账户管理，TLS/SSL 支持 |
| **feishu**（飞书） | 机器人 Webhook，markdown 格式，成功 green / 失败 red |
| **dingtalk**（钉钉） | 机器人 Webhook，markdown 格式 |
| **wecom**（企业微信） | 机器人 Webhook，markdown 格式，成功 info / 失败 warning |

**配置模型**：全局默认 `NotificationProfileGlobal` + 每数据源覆盖 `NotificationProfileDs`，4 通道独立开关。

**备份规则级通道白名单**：`notify_channels`（逗号分隔存 `ScheduleJob.parameters` JSON）—— 空 = 沿用通知设置全部启用通道；非空 = 仅发指定通道。`BackupNotificationContext` 透传至 `NotificationService.NotifyBackupAsync` 用 HashSet 做通道过滤。

**通知文案**：备份成功/失败含「数据源名称 + 数据库版本 + 日期」，数据库版本由 `BackupService.TryGetServerVersion` 自动获取。

---

## 📈 进阶监控与时序存储

**进阶监控面板**（`src/components/monitor/`，统一 BaseChart + CSS 变量 token 主题自适应）：

| 面板 | 能力 |
|------|------|
| CapacityForecastPanel | 容量预测（线性回归外推） |
| AnomalyDetectionPanel | 异常检测（基线 + 阈值偏差） |
| MultiSourceComparePanel | 多实例指标对比 |
| BlockingChainPanel | 阻塞链根因分析（仅 MySQL 协议族，MariaDB/OceanBase try/catch 兜底） |
| TopSqlPanel | Top SQL（`performance_schema.events_statements_summary_by_digest`，TopSqlSnapshotService 每 5 分钟采集） |

**视图布局**：`MetricTrendView` 含 4 标签页（趋势分析 / 容量预测 / 多实例对比 / 异常检测），`MonitorView` 含 3 标签页（实时快照 / 阻塞链 / Top SQL），新 tab 用 lazy 加载。

**时序指标分级保留**（仅 SQLite rollup 生效，TimescaleDB/InfluxDB/TDengine 走各自原生 continuous aggregates / downsampling）：

| 层级 | 保留期 | 生成时机 |
|------|--------|----------|
| 原始样本 | 7 天 | 实时采集 |
| 5 分钟聚合 | 30 天 | `MetricRollupService` 每 1h 生成 |
| 1 小时聚合 | 365 天 | `MetricRollupService` 每 1d 生成 |

`QueryRangeAsync` 智能路由：`bucket>=3600 & span>1d` → 1h rollup；`bucket>=300 & span>6h` → 5m rollup；桶须是 resolution 整数倍；rollup 无数据回退原始表。通过 `is SqliteMetricStore` 类型判断跳过 rollup 逻辑。

---

## 🔌 REST API

API 认证：`X-API-Key` 头或 `Authorization: Bearer <key>`（由登录接口签发）。**鉴权层级**：admin > operator > viewer；标注「公开」的端点无需密钥（匿名可调用）。

> 开发环境启动后访问 `http://localhost:5180/swagger` 查看交互式 Swagger 文档（仅 Development 暴露；生产环境关闭，避免端点清单泄露）。

### 核心端点（节选）

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/v1/health` | 公开 | 健康检查 |
| POST | `/api/v1/auth/login` | 公开 | 用户名/密码登录，签发 API Key |
| POST | `/api/v1/auth/change-password` | viewer | 修改当前用户密码 |
| GET | `/api/v1/auth/whoami` | viewer | 当前用户信息（含 `must_change_password`） |
| POST | `/api/v1/users` | admin | 创建用户 |
| GET/POST/PUT/DELETE | `/api/v1/datasources` | viewer/operator | 数据源 CRUD |
| POST | `/api/v1/datasources/{id}/inspect` | operator | 触发单库巡检 |
| POST | `/api/v1/datasources/inspect-all` | operator | 批量巡检全部数据源 |
| POST | `/api/v1/inspect` | operator | 执行巡检 |
| POST | `/api/v1/inspect-all` | operator | 批量巡检 |
| GET | `/api/v1/inspects` | viewer | 历史报告列表 |
| GET | `/api/v1/reports/{id}` | viewer | 报告详情 |
| GET | `/api/v1/reports/{id}/docx` | viewer | 下载 Word 报告 |
| GET | `/api/v1/reports/{id}/pdf` | viewer | 下载 PDF 报告 |
| GET | `/api/v1/reports/{id}/html` | viewer | 下载 HTML 报告（自包含） |
| GET | `/api/v1/reports/{id}/md` | viewer | 下载 Markdown 报告 |
| GET | `/api/v1/compare` | viewer | 配置参数对比（不支持返回 **501** + `UNSUPPORTED_DB_TYPE`） |
| GET | `/api/v1/sessions` | viewer | 活动会话（不支持返回 **501**） |
| POST | `/api/v1/sessions/kill` | operator | 批量 KILL 会话 |
| GET | `/api/v1/slow-query` | viewer | 慢查询日志（不支持返回 **501**） |

### 告警与指标告警

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET/POST | `/api/v1/alerts/rules` | viewer/operator | 告警规则列表 / 新增 |
| PUT/DELETE | `/api/v1/alerts/rules/{id}` | operator | 更新 / 删除告警规则 |
| POST | `/api/v1/alerts/scan` | operator | 立即扫描告警 |
| GET | `/api/v1/alerts/history` | viewer | 告警触发历史 |
| POST | `/api/v1/alerts/rules/seed-defaults` | admin | 种子默认告警规则 |

### 巡检配置 / SQL / 监控

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET/POST | `/api/v1/config/profiles` | viewer/admin | 巡检配置方案列表 / 新增 |
| DELETE | `/api/v1/config/profiles/{id}` | admin | 删除配置方案 |
| POST | `/api/v1/config/profiles/{id}/default` | admin | 设为默认方案 |
| POST | `/api/v1/sql/execute` | operator | SQL 编辑器执行 |
| GET | `/api/v1/monitor/snapshot` | viewer | 实时监控指标快照 |
| GET | `/api/v1/monitor/history` | viewer | 监控历史 |
| GET | `/api/v1/monitor/trend` | viewer | 趋势分析（智能路由 rollup） |
| GET | `/api/v1/monitor/capacity-forecast` | viewer | 容量预测 |
| GET | `/api/v1/monitor/anomaly-detection` | viewer | 异常检测 |
| GET | `/api/v1/monitor/blocking-chain` | viewer | 阻塞链（MySQL 协议族） |
| GET | `/api/v1/monitor/top-sql` | viewer | Top SQL（MySQL 协议族） |

### AI 诊断与对话（SSE 流式）

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/v1/ai/diagnose` | viewer | AI 诊断报告 |
| POST | `/api/v1/ai/chat` | viewer | AI 对话 |
| GET | `/api/v1/ai/chat/stream` | viewer | SSE 流式对话（会话归属校验） |
| GET | `/api/v1/ai/messages` | viewer | 对话历史 |
| DELETE | `/api/v1/ai/conversations/{id}` | viewer | 删除会话（归属校验） |
| POST | `/api/v1/ai/chat/clear` | viewer | 清空对话上下文 |
| GET | `/api/v1/ai/status` | viewer | AI 服务状态 |
| GET | `/api/v1/ai/models` | viewer | 可用模型列表 |
| POST | `/api/v1/ai/test` | viewer | 测试 AI 连接 |

### 知识库（15 端点）

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET/POST | `/api/v1/knowledge/docs` | viewer/operator | 文档列表 / 新建 |
| GET/DELETE/PATCH | `/api/v1/knowledge/docs/{id}` | viewer/operator | 详情 / 删除 / 更新 |
| POST | `/api/v1/knowledge/docs/{id}/reindex` | operator | 重建单篇索引 |
| POST | `/api/v1/knowledge/upload` | operator | 上传文档（txt/md/docx） |
| GET | `/api/v1/knowledge/search` | viewer | 混合检索（BM25 + 向量 RRF） |
| POST | `/api/v1/knowledge/rebuild` | admin | 全量重建索引 |
| GET | `/api/v1/knowledge/index/state` | viewer | 索引状态 |
| GET | `/api/v1/knowledge/coverage` | viewer | 覆盖度概览 |
| GET | `/api/v1/knowledge/stats/misses` | operator | 无结果查询 TOP |
| GET/PUT | `/api/v1/knowledge/settings` | viewer/admin | 检索 / 分块 / 融合 / 报告引用配置 |
| POST/DELETE | `/api/v1/knowledge/{id}/links/rules` | operator | 规则关联管理 |
| POST/DELETE | `/api/v1/knowledge/{id}/links/alerts` | operator | 告警关联管理 |
| POST | `/api/v1/knowledge/maintenance/scan-suspect` | admin | 污染扫描 |

### 通知（多通道）

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET/PUT | `/api/v1/notifications/profile` | viewer/operator | 全局通知配置 |
| GET/PUT/DELETE | `/api/v1/notifications/profile/ds/{dsId}` | viewer/operator | 数据源覆盖配置 |
| POST | `/api/v1/notifications/test-channel` | operator | 测试通道连通性 |
| GET/POST/PUT/DELETE | `/api/v1/notifications/smtp-accounts` | viewer/operator | SMTP 账户 CRUD |

### 备份 / 定时任务 / 共享 / SSH / 插件 / AWR / DM8

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/v1/backup/run` | operator | 触发备份 |
| GET | `/api/v1/backup/history` | viewer | 备份历史 |
| GET | `/api/v1/backup/download` | operator | 下载备份文件（路径白名单校验） |
| GET/POST | `/api/v1/schedule/jobs` | viewer/operator | 定时任务列表 / 新增 |
| DELETE | `/api/v1/schedule/jobs/{id}` | operator | 删除定时任务 |
| POST | `/api/v1/schedule/jobs/{id}/run` | operator | 立即运行任务 |
| GET | `/api/v1/schedule/jobs/{id}/logs` | viewer | 任务执行日志 |
| POST | `/api/v1/share` | operator | 创建分享链接 |
| GET | `/api/v1/share` | viewer | 分享链接列表 |
| DELETE | `/api/v1/share/{id}` | operator | 删除分享链接 |
| GET | `/api/v1/share/{token}` | 公开 | 免登录查看分享报告 |
| POST | `/api/v1/i18n/set` | 公开 | 设置界面语言 |
| GET | `/api/v1/i18n/status` | 公开 | 当前语言状态 |
| POST | `/api/v1/ssh/connect` | operator | 建立 SSH 会话 |
| POST | `/api/v1/ssh/execute` | operator | 执行远程命令 |
| POST | `/api/v1/ssh/disconnect` | operator | 断开 SSH 会话 |
| GET | `/api/v1/ssh/sessions` | viewer | SSH 会话列表 |
| POST | `/api/v1/dm8/scan` | admin | DM8 离线扫描 |
| POST | `/api/v1/awr/parse` | operator | 解析 Oracle AWR HTML |
| GET | `/api/v1/plugins` | viewer | 插件列表 |
| POST | `/api/v1/plugins/{id}/toggle` | operator | 启用/禁用插件 |
| DELETE | `/api/v1/plugins/{id}` | admin | 卸载插件 |
| POST | `/api/v1/plugins/install` | operator | 安装插件 |

共 **25 个 Controller**、约 **140 个端点**。完整交互式文档见开发环境的 `/swagger`（Swagger UI）。

---

## 🛠️ 技术栈

- **.NET 10** / ASP.NET Core（托管 Vue3 SPA + REST API）/ SQLite（元数据库，`Pooling=true` 处理 busy lock）
- **前端（唯一官方 UI）**：Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router + Vue I18n + ECharts
- **Razor Pages**：仅保留 3 个白名单旧根（`/Account/Login`、`/Account/Logout`、`/Error`）作 Cookie 登录/错误页，其余已在 GA 收口中删除
- **数据库驱动**：SqlClient、MySqlConnector、Npgsql、Oracle.ManagedDataAccess、MongoDB.Driver、StackExchange.Redis、System.Data.Odbc
- **报告导出**：DocumentFormat.OpenXml v3（Word）、QuestPDF 2025.1（PDF）、自包含 HTML（CSS+SVG+数据单文件，无外部依赖）、Markdown
- **AI 框架**：Microsoft Agent Framework 1.13 (`Microsoft.Agents.AI.OpenAI`) + OpenAI SDK 2.12，SSE 流式输出
- **RAG 知识库**：本地 TF-IDF 向量嵌入 + BM25 关键词检索 + RRF 融合，无外部向量服务依赖
- **SSH**：SSH.NET 2025
- **HTML 解析**：HtmlAgilityPack 1.11
- **认证**：Cookie 认证 + API Key 中间件，PBKDF2-SHA256 密码哈希，AES 应用层加密托管数据库密码

---

## 📊 与主流（含云厂商收费）工具对标

EasyDBA 定位为**自托管、多库统一、信创友好**的开源巡检平台，对标对象涵盖开源命令行工具、商业 GUI 与**云厂商收费数据库监控/自治服务**。下表从功能维度横向对比，帮助评估适用边界。

### 功能对标矩阵

| 工具 | 定位 / 计费 | 优势领域 | EasyDBA 对应能力 | 对标状态 |
|------|------------|----------|------------------|---------|
| **Percona PMM** | 开源免费 | MySQL/PG/Mongo 深度监控 + QAN 慢查询分析 | MySQL/PG/Mongo 巡检 + 慢查询 digest + 实时监控 + Top SQL | ⚠️ 接近（PMM 指标粒度更细、QAN 更强） |
| **Percona Toolkit**（pt-stalk / pt-query-digest / pt-index-usage） | 开源免费 | MySQL 命令行深度诊断 | MySQL 慢查询 digest / 冗余未用索引 / 死锁 / binlog 缓存 / 临时表 / 全表扫描比率 | ✅ 覆盖核心项 |
| **Oracle Enterprise Manager** | 商业收费 | Oracle 全栈（AWR/ASH/ADDM/集群/补丁） | AWR HTML 解析 + AWR 关键指标 + FRA + Data Guard + 阻塞链 + 实时监控 | ⚠️ 部分覆盖（缺 ASH/ADDM 自动诊断、补丁管理） |
| **Navicat / DBeaver** | 商业 / 开源 GUI | 多库 GUI + 基础检查 + SQL 编辑 | Web UI + 21 库巡检 + SQL 编辑器 + 报告导出 | ✅ 超越（报告 + RBAC + 定时 + 通知） |
| **pgBadger** | 开源免费 | PostgreSQL 慢日志深度聚合分析 | PG 慢查询 / 复制槽 / autovacuum / 膨胀 / 长事务 | ⚠️ 部分覆盖（日志文件解析尚未实现） |
| **AWS RDS Performance Insights** | 云收费（按实例） | 云端性能洞察、按 SQL 归因、CloudWatch 联动 | Top SQL / 慢查询 / 锁诊断 / 实时监控 / 历史趋势 / 容量预测 | ⚠️ 接近（缺云端联动、自动化调优建议） |
| **Aliyun DAS（数据库自治服务）** | 云收费 | 自动 SQL 优化、自动限流、自动索引、压测回归 | AI 诊断建议 + fix_sql 手工执行 + 指标告警规则 | ⚠️ 接近（缺自动限流/自动索引/压测回归） |
| **Tencent Cloud DBbrain** | 云收费 | 慢 SQL 优化、空间诊断、健康评分、大 Key 分析 | 健康评分 + 慢查询 + 空间统计 + Redis 大 Key（待补） | ⚠️ 部分覆盖（缺 AI SQL 改写建议、大 Key 检测） |
| **Huawei GaussDB Inspect / DAS** | 云收费 | GaussDB 专项巡检 + 容灾演练 | openGauss/GaussDB 复用 PG 规则集 + 备份容灾 | ⚠️ 部分覆盖（缺原生 GaussDB 专属规则与容灾演练） |
| **Azure SQL Insights / Database Watcher** | 云收费 | Azure SQL 全栈监控、智能洞察 | SQL Server 巡检 + 实时监控 + 趋势分析 | ⚠️ 部分覆盖（缺智能洞察引擎、Azure 联动） |
| **Datadog Database Monitoring** | SaaS 收费（按主机/实例） | 跨云统一监控、APM 关联、长周期留存、异常检测 | 多库监控 + 异常检测 + 容量预测 + 分级保留 | ⚠️ 接近（缺 APM 跨服务追踪、超长周期留存） |
| **SolarWinds DPA / VividCortex** | 商业收费 | 阻塞链分析、查询性能回溯、多云异构 | 阻塞链 + Top SQL + 历史趋势 + 多库异构 | ⚠️ 接近（缺查询性能回溯、无代理采集） |
| **MongoDB Cloud Manager / Atlas** | 云收费 | Mongo 副本集/分片监控 + 自动备份 + 告警 | Mongo 副本集/连接/安全/性能 + 备份 + 通知 | ⚠️ 部分覆盖（缺分片集群深度监控） |

### EasyDBA 相对云厂商收费工具的独特优势

- **自托管 / 数据主权**：所有巡检数据、知识库、AI 推理均在本地闭环，零外发遥测，满足金融 / 政府 / 信创场景的合规与数据出境要求
- **零按实例授权费**：云厂商监控多按「实例数 × 时长」计费，规模越大费用越高；EasyDBA 单实例部署即可纳管数百数据源，无边际许可成本
- **21 库统一平台（含国产）**：DM8 / YashanDB / GBase 8s / KingbaseES / openGauss / IvorySQL 专用规则集，云厂商监控通常只覆盖自有引擎，跨云跨国产支持稀缺
- **本地 LLM AI 诊断**：基于 Microsoft Agent Framework + Ollama，推理不出网；云厂商自治服务依赖云端 LLM，SQL 与采样数据需上云
- **一键离线巡检报告**：Word / PDF / HTML / Markdown 多格式自包含报告 + 知识引用章节，云厂商以 Dashboard 为主，离线交付报告能力弱
- **生产风险防控**：81 项高危巡检自动跳过并生成「手工检查提醒」区块，避免巡检拖垮在线业务；云厂商多为只读指标采集，较少考虑巡检 SQL 自身风险

### 当前不足与后续路线（相对云厂商收费工具）

- **实时 push 告警**：当前支持定时任务 + 通知 + 指标告警规则（pull 模式），未实现亚分钟级 push 实时告警与电话/短信升级；云厂商普遍具备秒级异常检测 + 多渠道升级
- **自动化自治能力**：AI 诊断仅提供优化建议，需人工确认后执行 fix_sql；DAS/DBbrain 已实现自动限流、自动索引、自动参数调优
- **日志深度分析**：MySQL / PostgreSQL 慢查询**日志文件**解析（pgBadger / pt-query-digest 风格的跨实例指纹聚合）尚未实现，当前依赖 `performance_schema` / `pg_stat_statements`
- **ML 异常检测**：当前异常检测基于基线 + 阈值偏差；云厂商多采用机器学习时序异常检测，对周期性 / 节假日模式更鲁棒
- **查询性能回溯**：缺 Top SQL 的执行计划回归检测与历史对比；DPA / DAS 支持查询计划版本回溯与 what-if 分析
- **APM 跨服务追踪**：缺应用层 trace 关联，无法定位「慢 SQL 由哪个服务 / 接口触发」；Datadog / 阿里 ARMS 已打通
- **平台自身高可用**：当前单节点部署，巡检平台自身无集群高可用；云厂商监控平台为托管高可用
- **长周期指标留存**：当前最长 365d（1h 聚合）；云厂商可留存数年并支持任意长周期对比
- **FinOps 成本归因**：未将性能指标与云资源成本关联；云厂商可输出「慢 SQL → 资源浪费 → 成本」链路
- **可视化图表**：报告以表格为主（实时监控 / 趋势页已用 ECharts），报告内嵌图表化为后续路线
- **NoSQL 深度覆盖**：MongoDB 分片集群、Redis 大 Key / 热 Key、ES 分片再平衡等专项检测较云厂商专用方案仍有差距

---

## 📄 许可

仅供学习与内部运维用途。原始项目版权归原作者所有。