内容
# DBPilot 数据库自治诊断平台
自托管的 SQL Server 诊断系统，对标阿里云 DAS：持续采集性能数据，在浏览器中完成性能趋势、性能洞察、SQL 分析、索引诊断、锁与阻塞、慢日志、执行计划等日常 DBA 工作。
## 为什么选 DBPilot
- **单进程部署** —— 一个 .NET 进程 + 一个平台库（SQL Server 自动建库建表），开箱即用
- **广泛兼容** —— 被监控实例支持 SQL Server 2008 ~ 2022
- **极低开销** —— 常规运行对被监控实例 <1% CPU，只读 DMV / 扩展事件，零侵入
- **AI 就绪** —— 内置只读 MCP Server，一条命令接入 Claude Code / Codex，用自然语言做诊断
## 功能一览
| 模块 | 能力 |
|---|---|
| 性能趋势 | CPU / 内存 / PLE / QPS·TPS / IO / 磁盘，10s 采集、秒级粒度，长区间自动降采样 |
| 性能洞察 | 平均活跃会话（AAS）拆解 CPU / 锁 / IO / 等待，可下钻单条 SQL 贡献 |
| Top SQL | 实时榜 + 历史趋势，指纹合并、噪音一键排除 |
| 执行计划 | 计划版本留存、变更事件、计划树对比 |
| 索引诊断 | 缺失索引推荐 / 使用率 / 碎片扫描，附维护脚本 |
| 锁与阻塞 | 实时阻塞树 + 历史统计，死锁自动捕获与图形化展示 |
| 慢日志 | 超阈值 SQL 自动留档，完整文本与 IO 明细 |
## 仓库结构
```
DBPilot.App/
├── app/ # 发布产物：exe + 依赖 + 前端资源 + 脱敏配置
├── scripts/ # 启动脚本（run.bat）
├── DBPilot.McpConsole/ # 命令行 AI 诊断对话台（OpenAI 兼容端点 + MCP，需先构建：dotnet build）
├── DBPilot.Scenarios/ # 遗留系统故障演练工程（造负载数据供 AI 定位演练，需先构建）
├── McpServer-src/ # MCP Server 实现源码参考副本（只读，不可独立构建）
└── README.md
```
## 快速开始
| 依赖 | 版本 |
|---|---|
| .NET Runtime | 10.0+ |
| SQL Server | 2008 ~ 2022（平台库 + 被监控实例） |
1. 编辑 `app\appsettings.json`，填入 `DBPilot:ConnectionString`（平台库连接串，库和表结构启动时自动创建）
2. 双击 `scripts\run.bat` 启动 → 打开 `http://localhost:5200`
3. 默认账号 `admin` / `dbpilot@2026`，**首次登录后立即改密码**：
双击 `scripts\hash-password.bat`（或 `app\DBPilot.Host.exe --hash <新密码>`），
把输出的哈希写入 `app\appsettings.json` 的 `DBPilot:Auth:PasswordHash` 后重启
4. 页面「实例管理」接入被监控实例（地址 + 账号密码，凭据加密存储）→ 连接测试 → 启用
5. 采集自动运行：实时类页面立即可用，历史类数据随运行时间积累
## AI 诊断（MCP Server）
内置只读 MCP Server（`/mcp`，Streamable HTTP + API Key），把指标 / 慢SQL / 死锁 / 阻塞 / 索引证据以 11 个只读工具交给 AI agent。
开启（`app\appsettings.json`）：
```json
"DBPilot": {
"Modules": {
"Mcp": { "Enabled": true, "ApiKey": "换成一个足够随机的 key" }
}
}
```
接入 Claude Code：
```bash
claude mcp add --transport http dbpilot http://localhost:5200/mcp --header "X-Api-Key: <你的key>"
```
接入 Codex CLI（`~/.codex/config.toml`）：
```toml
[mcp_servers.dbpilot]
url = "http://localhost:5200/mcp"
[mcp_servers.dbpilot.http_headers]
X-Api-Key = "<你的key>"
```
## 对被监控实例的性能影响
常规运行 <1% CPU、零磁盘压力。采集只读 SQL Server 内存里的元数据视图（DMV）和扩展事件文件——不扫业务表、不产生物理 IO、不对用户对象加锁。秒级 DMV 轮询是业界标准做法（SQL Server 自带 `system_health`、阿里云 DAS、AWS Performance Insights 同款路径）。
可自证：跑一天后在被监控实例执行，监控账号的累计 CPU 秒即真实开销——
```sql
SELECT login_name, SUM(cpu_time)/1000 AS cpu_seconds_total
FROM sys.dm_exec_sessions
WHERE host_process_id IS NOT NULL
GROUP BY login_name;
```
## 安全说明
- 本仓库的 `app\appsettings.json` 与两个工程（`DBPilot.McpConsole` / `DBPilot.Scenarios`）的 `appsettings.json` 均为**脱敏模板**，不含任何真实凭据
- `DBPilot.McpConsole` / `DBPilot.Scenarios` 的真实凭据放各自目录的 **`appsettings.Local.json`**（已被 .gitignore 排除，程序优先读取，模板文件保持占位符不用改）
- `app\appsettings.json` 为标准 ASP.NET 配置：本地填入真实连接串后 `git status` 会显示已修改——**请勿提交**，防止凭据外泄
- 被监控实例的连接信息在页面「实例管理」维护，加密存储于平台库，不在配置文件里
- 建议设置环境变量 `DBPILOT_MASTER_KEY`（凭据加密密钥），否则重启后需重新登录
## 常见问题
| 现象 | 处理 |
|---|---|
| 启动告警 `平台库结构初始化失败` | 检查 `DBPilot:ConnectionString` 与 SQL Server 可达性 |
| 打不开 5200 端口 | 确认 `scripts\run.bat` 中 `ASPNETCORE_URLS` 端口未被占用 |
| 登录后重启就掉线 | 未设置 `DBPILOT_MASTER_KEY`（预期行为） |
| 性能洞察无数据 | 确认实例已启用且采集正常，采样满 1 分钟后生成 |
| 死锁/慢SQL 事件看不到 | 事件落盘有约 1 分钟缓冲延迟，稍等后刷新 |
| 想多进程部署（采集与 Web 分开） | 配置 `DBPilot:Roles`（`Web`/`Collector`，默认双开）；只允许一个 Collector 连同一平台库，Web 可多实例 |
---
源码与开发指南见源码仓库。本仓库仅分发可运行的发布产物（Release 构建产物 + 脱敏配置 + 启动脚本）。
MCP 市场