# DBCheck

**Repository Path**: limtno/DBCheck

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据库巡检工具 - DBCheck

>支持对 **MySQL**、**PostgreSQL**、**Oracle**、**SQL Server**、**达梦 DM8** 和 **TiDB** 六种主流关系型数据库进行自动化健康巡检，生成格式规范的 Microsoft Word 报告，帮助 DBA 和运维人员快速掌握数据库运行状况、发现潜在风险。


[![Version](https://img.shields.io/badge/version-2.3.3-blue.svg)]()
[![MySQL](https://img.shields.io/badge/database-MySQL-blue.svg)]()
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-gray.svg)]()
[![Oracle](https://img.shields.io/badge/Oracle-red.svg)]()
[![SQL Server](https://img.shields.io/badge/SQL%20Server-orange.svg)]()
[![DM](https://img.shields.io/badge/DM-yellow.svg)]()
[![TiDB](https://img.shields.io/badge/TiDB-green.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)]()

> Language: [English](./README.md) | [中文](./README_zh.md)

## 🌍 多语言支持

DBCheck 支持**中文（默认）**和**英文**两种语言，界面文本随语言切换自动更新。

### 命令行语言切换

```bash
python main.py                    # 默认中文
python main.py --lang en         # 切换为英文
python main.py --lang zh         # 切换为中文（显式指定）
```

> Web UI 右上角也有 🌐 切换按钮，点击即可中英文切换，切换结果自动保存。

### 语言说明

| 参数 | 语言 | 说明 |
|------|------|------|
| `--lang zh` | 中文 | 默认语言 |
| `--lang en` | English | 英文界面 |
| 不指定 | 中文 | 默认使用上一次保存的语言，无保存记录时默认为中文 |

> **注意**：`--lang` 参数仅在当前会话临时生效，不会覆盖已保存的语言设置。Web UI 中切换语言会持久化到 `dbc_config.json`，下次启动 Web UI 时自动加载。

### 手动修改默认语言

如需在不启动程序的情况下修改默认语言，可直接编辑配置文件：

```json
// dbc_config.json
{
    "language": "zh"   // "zh" = 中文, "en" = English
}
```

配置文件位于 `main.py` 同级目录下。

## AI 辅助 · 问题发现即处理

### 🤖 AI 智能诊断

调用本地 **Ollama**（完全离线），基于当次巡检的指标数据（连接数、缓存命中率、慢查询数、安全风险等），自动生成结构化的优化建议。报告独立成章，Markdown 格式内容自动渲染为 Word 样式（加粗、代码块、列表、标题序号），方便直接转发给团队或领导审阅。

| 后端 | 特点 | 适用场景 |
|------|------|---------|
| `ollama` | 本地运行，零成本，无网络依赖 | 内网环境、数据安全要求高 |
| `disabled` | 不调用 AI（默认） | 离线环境 / 无需 AI |

> ⚠️ **安全说明**：AI 诊断功能仅支持本地 Ollama（localhost:11434），巡检数据不会发送到任何第三方服务。代码层已做硬性限制，即使配置文件被篡改为远程地址也会自动降级为禁用状态。

### 🔍 风险与建议

每条风险对应一张卡片，包含：**风险等级（高/中/低）→ 问题描述 → 修复 SQL（可直接复制执行）→ 优先级与负责人**。报告自动汇总，一眼看清全部待处理项。

| 维度 | MySQL | PostgreSQL | Oracle | SQL Server | DM8 | TiDB |
|------|:-----:|:----------:|:-----------:|:-----------:|:----:|:----:|
| 连接资源 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 缓存性能 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 查询效率 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 日志告警 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 安全审计 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 复制/DG | ✅ | ✅ | — | — | — | ✅ |
| 配置优化 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 表空间 | — | — | ✅ | ✅ | ✅ | — |
| SGA/PGA 内存 | — | — | ✅ | — | ✅ | — |
| Redo 日志 | — | — | ✅ | — | ✅ | — |
| 备份与归档 | — | — | ✅ | ✅ | ✅ | — |
| RAC 集群 | — | — | ✅ | — | — | — |
| ASM 磁盘组 | — | — | ✅ | — | — | — |
| Undo 管理 | — | — | ✅ | — | ✅ | — |
| Data Guard | — | — | ✅ | — | — | — |
| 等待事件 | — | — | ✅ | ✅ | ✅ | — |
| 锁与阻塞 | — | — | — | ✅ | — | — |
| DM8 特有视图 | — | — | — | — | ✅ | — |
| 调度与亲和性 | — | — | — | — | — | ✅ |

---

## 四大核心能力

| 能力 | 说明 |
|------|------|
| 📊 历史趋势分析 | 同一数据库多次巡检数据自动汇聚，生成指标趋势折线图，与上次对比发现变化 |
| 🤖 AI 智能诊断 | 基于巡检指标调用本地 Ollama，生成个性化优化建议 |
| 🔍 130+ 条增强规则 | 覆盖六种数据库全维度风险检测（MySQL 35+条 / PG 27+条 / Oracle 20+条 / SQL Server 15+条 / DM8 16+条 / TiDB 18+条）——含新增 28 条慢查询深度分析规则 |
| 🔒 脱敏导出报告 | 导出 Word 报告时自动掩码 IP、端口、用户名、服务名等敏感信息，防止信息泄露 |

---

## 四种使用方式

| 方式 | 说明 |
|------|------|
| 🖥️ 命令行 | `python main.py`，终端交互，适合熟悉命令行的用户 |
| 🌐 Web UI | `python web_ui.py`，浏览器图形界面，支持趋势图和 AI 诊断配置 |
| 🤖 OpenClaw Skill | 告诉 AI 助手"帮我巡检 XX 库"，零操作自动完成 |
| 📦 打包部署 | PyInstaller 打包成分发版，给团队成员使用 |

---

## 功能特性

### 数据库巡检

| 维度 | MySQL | PostgreSQL | Oracle | SQL Server | DM8 | TiDB |
|------|:-----:|:----------:|:-----------:|:-----------:|:----:|:----:|
| 基本信息（版本/实例/数据库） | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 会话与连接状态 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 内存与缓存配置 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 表空间使用情况 | — | — | ✅ | ✅ | ✅ | — |
| SGA / PGA 内存分析 | — | — | ✅ | — | ✅ | — |
| Redo 日志与状态 | — | — | ✅ | — | ✅ | — |
| 归档与备份检查 | — | — | ✅ | ✅ | ✅ | — |
| 关键参数配置 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 无效对象检测 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 用户安全审计 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Top SQL / 慢查询 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 主从复制 / Data Guard | ✅ | ✅ | — | — | — | ✅ |
| RAC 集群信息 | — | — | ✅ | — | — | — |
| ASM 磁盘组 | — | — | ✅ | — | — | — |
| Undo 表空间管理 | — | — | ✅ | — | ✅ | — |
| 回收站 / 闪回恢复区 | — | — | ✅ | — | ✅ | — |
| Profile 密码策略 | — | — | ✅ | — | — | — |
| 等待事件 TOP | — | — | ✅ | ✅ | ✅ | — |
| 锁与阻塞检测 | — | — | — | ✅ | — | — |
| 统计信息陈旧检测 | — | — | ✅ | ✅ | ✅ | ✅ |
| 分区表信息 | — | — | ✅ | ✅ | ✅ | ✅ |
| 数据文件状态 | — | — | ✅ | ✅ | ✅ | — |
| DM8 缓冲池详情 | — | — | — | — | ✅ | — |
| 调度与亲和性策略 | — | — | — | — | — | ✅ |

### 系统资源监控

- **CPU**：使用率、核心数、频率
- **内存**：总量、使用量、可用量、使用率
- **磁盘**：各挂载点容量及使用率
- **采集方式**：本地直采或 SSH 远程采集（支持密码/密钥认证，默认端口 22）；达梦 DM8 支持 SSH 采集（失败时自动降级为本地采集器）

### 智能风险分析

自动检测数据库潜在风险，**每条风险附可执行的修复 SQL**，可直接复制到数据库执行：

#### MySQL（18+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 连接数 | 使用率 >90% 高危 / >80% 中危 |
| 内存 | InnoDB 缓冲池偏小（<数据总量 60%）|
| 磁盘 | 使用率 >85% 警告 / >95% 高危 |
| 查询 | 长时间运行 SQL（>60s）、慢查询日志未开启 |
| 锁 | 锁等待比例偏高 |
| 安全 | 用户空密码、root@% 暴露、字符集非 UTF8 |
| 复制 | 主从延迟 >30s、复制状态异常 |
| 其他 | binlog 未开启、查询缓存残留、异常中止连接过多 |

#### PostgreSQL（16+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 连接 | 连接数接近上限、超级用户过多 |
| 缓存 | 缓存命中率偏低（<80%）、shared_buffers 偏小 |
| 性能 | dead tuples 大量累积、长时间运行 SQL |
| 安全 | 公开 schema 权限过宽 |
| 归档 | 归档模式未开启 |
| 其他 | 磁盘/内存/CPU 资源告警 |

#### Oracle（20+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 表空间 | 使用率 >90%（含自动扩展计算）|
| TEMP | 临时表空间使用率偏高 |
| 会话 | 数接近上限 / 进程超限 / 锁阻塞 |
| 内存 | SGA 占物理内存比例过高 |
| Redo | Redo 日志组异常 / 切换频繁 |
| 备份 | 归档模式未开启 / RMAN 备份缺失 |
| DG | MRP 未运行 / 保护模式偏低 |
| ASM | 磁盘组空间不足 / 离线磁盘 |
| FRA | 闪回恢复区使用率偏高 |
| 对象 | 无效对象过多 / 统计信息陈旧 |
| 安全 | Profile 密码策略宽松 / 审计未开启 |
| 其他 | open_cursors 偏小 / 回收站占用 / 数据文件脱机 |

#### DM8（16+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 表空间 | 使用率 >90%（含自动扩展计算）|
| 内存 | 各缓冲池（KEEP/RECYCLE/FAST/NORMAL/ROLL）配置异常 |
| 会话 | 连接数接近上限 / 长时间运行会话 |
| 事务 | 阻塞事务检测 / 事务等待 |
| 备份 | 备份集缺失 / 备份超时 |
| 参数 | 关键参数（INSTANCE_MODE, COMPATIBLE_VERSION 等）配置检查 |
| 安全 | 用户空密码 / 权限过宽 / 审计未开启 |
| 对象 | 无效对象 / 统计信息陈旧 / 分区表信息 |
| 归档 | 归档模式未开启 / 归档日志堆积 |

#### SQL Server（15+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 连接数 | 当前连接数接近最大连接数上限 |
| 会话 | 活动会话数异常 / 长时间运行会话 |
| 等待 | 等待统计 TOP10 / 等待类型分析 |
| 锁 | 当前锁信息 / 锁等待与阻塞链 |
| 死锁 | 死锁历史检测 / 阻塞进程分析 |
| 备份 | 最近备份缺失 / 备份类型检查 |
| 数据库 | 数据库状态 / 恢复模式 / 文件大小 |
| 内存 | 内存 clerk 使用 / 缓冲池命中率 |
| 性能 | Top SQL 按 CPU/IO/执行时间排序 |

#### TiDB（18+ 条规则）

| 维度 | 规则示例 |
|------|---------|
| 连接数 | 使用率 >90% 高危 / >80% 中危 |
| 内存 | TiDB 内存配置异常 |
| 磁盘 | 使用率 >85% 警告 / >95% 高危 |
| 查询 | 长时间运行 SQL（>60s）、慢查询日志未开启 |
| 锁 | 锁等待事件 / 死锁检测 |
| 安全 | 用户空密码、root@% 暴露、字符集非 UTF8 |
| 复制 | TiCDC/PD 心跳异常 / Follower 延迟 |
| 调度 | Placement Rules 配置异常 / 亲和性策略 |
| 统计 | 统计信息陈旧 / 自动分析未开启 |
| 其他 | binlog 未开启、异常中止连接过多、系统 CPU/内存压力 |

### 历史趋势分析 📊

> 多次巡检同一个数据库，自动汇聚指标数据，生成趋势图，发现悄然发生的变化。

- 每次巡检后，关键指标（内存使用率、连接数、QPS、CPU 等）自动写入本地 **SQLite 数据库**（`db_history.db`），进程重启后历史记录不丢失
- 同一数据库（IP + 端口 + 类型）多次巡检数据聚合保留，每个实例最多 30 条历史快照
- SQLite 存储封装在 `SQLiteHistoryManager` 中；原有 `HistoryManager` API 完全保留，调用方无需任何改动
- 自动降级：SQLite 不可用时（权限、文件锁定等）自动回退到内存模式，不阻塞巡检流程
- Web UI 提供**趋势分析页面**，绘制指标折线图，带警戒线标注
- 与上次巡检逐项对比：变化量带颜色箭头（↑ 变差 / ↓ 好转）

### AI 智能诊断 🤖

> 基于巡检数据，调用本地 Ollama 大模型生成个性化优化建议，从"发现问题"升级到"解决问题"。

AI 诊断与智能分析的关系：

| | 智能分析 | AI 诊断 |
|---|---|---|
| 原理 | 固定规则，离线判断 | 本地大模型推理，个性化输出 |
| 速度 | 毫秒级 | 取决于模型响应时间 |
| 结果 | 确定性结论 + 修复 SQL | 自然语言优化建议，Markdown 自动渲染为 Word 格式 |
| 调用 | 每次巡检自动执行 | 按需调用（可关闭） |

**AI 后端配置（Web UI 可视化设置）：**

| 参数 | 说明 |
|------|------|
| 后端类型 | `ollama` 或 `disabled` |
| API 地址 | 默认 `http://localhost:11434`（仅允许 localhost）|
| 模型名称 | 如 `qwen3:30b`、`qwen3:8b`、`llama3` 等 |
| 超时时间 | 默认 600 秒（大模型冷启动较慢）|

> ⚠️ 出于安全考虑，非 localhost 的 API 地址会被代码自动拒绝，防止敏感数据外传。

### 慢查询深度分析 🔍

> 不仅检测慢查询，DBCheck 还从执行计划、I/O 模式、锁等待、临时表使用等多个维度进行深度剖析，并将结果注入 AI 诊断，生成精准的根因分析优化建议。

#### 功能概述

当数据库出现慢查询症状时，DBCheck 会跨多个性能维度采集 Top N 最差性能语句，执行自动化风险规则分析，然后调用 AI advisor 生成针对性的优化建议。

#### 各数据库采集维度

每种数据库都有针对其性能模型优化的查询语句：

| 数据库 | 数据来源 | 采集维度 |
|--------|----------|----------|
| **MySQL** | `performance_schema.events_statements_summary_by_digest` | 执行延迟、全表扫描、锁等待、临时表、排序操作 |
| **PostgreSQL** | `pg_stat_statements` | 总时间、平均时间、I/O 时间、临时块、当前长查询 |
| **Oracle** | `v$sql` | Buffer Gets、Disk Reads、Elapsed Time（解析时间+执行时间）|
| **SQL Server** | `sys.dm_exec_query_stats` | CPU 使用率、逻辑读、Elapsed Time、物理读 |
| **DM8** | `V$SQL` | 执行时间、磁盘读 |
| **TiDB** | `information_schema.cluster_slow_query` | 查询时间、内存使用量、扫描行数、Coprocessor 任务数 |

#### 与巡检流程的集成

```
checkdb() 执行顺序：
1. getData() → 执行 SQL 巡检查询
2. checkdb() → 智能风险分析
3. 慢查询深度分析 ← 新增（AI 诊断之后自动执行）
4. context['slow_query_result'] → smart_analyze_* 执行风险规则评估
5. AI Advisor → 注入 slow_query_top3 + slow_query_count 指标
```

`SlowQueryResult` 标准化容器统一了各数据库分析器的输出格式，确保下游处理逻辑与数据库类型无关。

#### 增强的风险规则

巡检引擎新增了针对慢查询的数据库特定规则：

**MySQL（新增规则 17+ 条）：**
- `performance_schema` 未开启检测
- 全表扫描语句检测
- 锁等待比例阈值检测
- AI 诊断注入慢查询发现结果

**PostgreSQL（新增规则 11+ 条）：**
- `pg_stat_statements` 扩展未开启检测
- 高延迟语句检测
- 高 I/O 语句检测
- 长查询阈值检测
- AI 诊断注入慢查询发现结果

#### AI 诊断增强

`build_slow_query_ai_prompt()` 函数生成专项诊断 Prompt，AI advisor 接收到：

- **slow_query_top3**：影响最大的三条慢查询（按延迟/I/O/执行频率排序）
- **slow_query_count**：采集到的慢查询总数

使 AI 能够提供精确到单条语句的优化建议，而非泛泛而谈。

#### 报告中的呈现

慢查询分析结果以风险卡片形式出现在报告的风险建议章节，每条风险标注严重等级（🔴 高危 / 🟡 中危 / 🟢 低危），并附带可直接执行的修复 SQL。

---

## 环境要求

- **操作系统**：Linux / macOS / Windows
- **Python**：3.6 及以上
- **通用依赖**：pymysql、psycopg2-binary、python-docx、docxtpl、paramiko、psutil、openpyxl、pandas、flask、flask_socketio
- **Oracle 依赖**：`oracledb`（推荐）或 `cx_Oracle`（需要 Oracle Instant Client）
- **DM8 依赖**：`dmpython`（pip install dmpython）
- **SQL Server 依赖**：`pyodbc` + ODBC Driver 17（Windows/Linux 均支持）
- **MySQL 权限**：查询 information_schema、performance_schema、mysql 库的只读权限
- **PostgreSQL 权限**：查询 pg_stat_* 系列系统视图及 pg_roles 的只读权限
- **Oracle 权限**：查询 v$* 视图 / dba_* 视图的只读权限；支持 SYSDBA 特权连接（Web UI 复选框一键启用）
- **SQL Server 权限**：查询 sys.databases、sys.master_files、sys.dm_* 系列动态管理视图的只读权限
- **DM8 权限**：查询 V$* 系统视图 / DBA_* 管理视图的只读权限；默认端口 5236；连接用户即 Schema（无需 database 参数）
- **TiDB 依赖**：`pymysql`（与 MySQL 相同——TiDB 使用 MySQL 协议；默认端口 **4000**）
- **TiDB 权限**：查询 information_schema、performance_schema、mysql 库的只读权限（与 MySQL 完全一致）
- **SSH（可选）**：用于远程采集系统资源（MySQL / PostgreSQL / Oracle / DM8）；默认端口 22；DM8 SSH 采集失败时自动降级为本地采集器

### 安装依赖

```bash
pip install -r requirements.txt
```

> 💡 **数据库驱动说明：**
>
> - **Oracle**：`oracledb`（推荐，纯 Python 实现，无需 Instant Client）
> - **DM8**：`dmpython`（达梦官方驱动）
> - **SQL Server**：需额外安装 [ODBC Driver 17](https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server)

---

## 快速开始

```bash
python main.py
```

主入口菜单提供八个选项：

```
==================================================
  🗄️  数据库自动化巡检工具  v2.3  统一入口
==================================================
    🐬  1 │ MySQL           MySQL 数据库健康巡检与报告生成
    🐘  2 │ PostgreSQL      PostgreSQL 数据库健康巡检与报告生成
    🔴  3 │ Oracle          Oracle 数据库深度健康巡检（20+ 巡检项）
    🟠  4 │ SQL Server      SQL Server 数据库健康巡检与报告生成
    🟡  5 │ DM8             达梦 DM8 数据库健康巡检与报告生成
    🐬  6 │ TiDB            TiDB 数据库健康巡检与报告生成（MySQL 8.0+ 兼容）

    🌐  7 │ 启动 Web UI     浏览器可视化操作界面
    📋  8 │ 批量生成巡检模板  生成批量巡检 Excel 模板
    ❌  0 │ 退出
==================================================
```

1. 输入 **1~5**，进入对应数据库类型的巡检功能菜单
2. 输入 **6**，进入 TiDB 巡检功能菜单
3. 输入 **7**，启动 Web UI 服务
4. 输入 **8**，选择要生成的模板类型（MySQL / PostgreSQL / Oracle / SQL Server / DM8 / TiDB）
5. 输入 **0** 退出工具

#### 单机巡检流程（以 Oracle 全面巡检为例）

1. 选择 **3** 进入 Oracle 巡检菜单
2. 选择 **1** 进行单机巡检
3. 根据提示填写：
   - 巡检名称
   - 数据库 IP / 端口（默认 1521）/ 服务名或 SID
   - 用户名（支持 SYSDBA 身份，Web UI 提供复选框，CLI 支持 `sys as sysdba` 语法）/ 密码
   - SSH 信息（可选，默认端口 22，用于采集系统资源）
4. 工具自动执行 42 项 SQL 检查 → 采集系统信息 → 智能风险分析 → AI 诊断（可选）
5. 生成 Word 巡检报告

#### 批量巡检

1. 先通过选项 **4** 生成对应的 Excel 批量巡检模板
2. 在模板中填写多个数据库实例的连接信息
3. 选择 **2** 批量巡检，程序自动依次巡检所有实例

### Web UI（可视化界面）

启动 Web 服务后，在浏览器访问 **http://localhost:5003** 即可通过图形界面完成所有巡检操作。

```bash
python web_ui.py
```

**Web UI 操作步骤：**

| 步骤 | 功能 |
|:---:|------|
| 1 | 选择数据库类型（🐬 MySQL / 🐘 PostgreSQL / 🔴 Oracle / 🟠 SQL Server / 🟡 DM8 / 🐬 TiDB）|
| 2 | 填写连接信息，Oracle 需额外填写服务名/SID，DM8 无需填写 database 名 |
| 3 | 支持在线测试数据库连接（含 SYSDBA 特权验证，Web UI 复选框一键启用）|
| 4 | 配置 SSH 采集系统资源（可选，默认端口 22；DM8 支持 SSH 采集，失败时自动降级）|
| 5 | 填写巡检人员姓名（默认为 dbcheck），如需脱敏导出可勾选「🔒 脱敏导出报告」选项 |
| 6 | 确认信息后一键执行，实时查看日志进度（SSE 推送）|
| 7 | 巡检完成，在线预览智能分析 + AI 诊断结果 |
| 8 | 📊 历史趋势分析：查看同一数据库多次巡检的指标趋势 |
| 9 | 🤖 AI 诊断设置：配置本地 Ollama 参数（地址/模型/超时）|
| 10 | 下载 Word 报告，随时查阅历史报告 |

### OpenClaw Skill（AI 助手直连）

本项目已发布为 [ClawHub](https://clawhub.ai/skills/dbcheck) 上的 OpenClaw Skill，接入 AI 助手后可通过自然语言直接触发巡检，无需手动操作命令行或 Web UI。

#### 安装方式

在 OpenClaw 客户端执行：

```bash
clawhub install dbcheck
```

#### 使用方式

安装后，直接告诉 AI 助手你想做的事，例如：

> "帮我巡检一下 Oracle 生产库，IP 是 localhost，用户名 sys as sysdba"

AI 助手会自动加载 Skill，按步骤询问缺少的信息（端口、服务名、巡检人员姓名等），然后调用巡检脚本生成 Word 报告。

#### 支持的指令

| 指令示例 | 说明 |
|---------|------|
| 帮我巡检一下 MySQL 库 | 单机 MySQL 巡检 |
| 帮我巡检一下 PostgreSQL 库 | 单机 PG 巡检 |
| 帮我巡检一下 Oracle 库 | 单机 Oracle 巡检 |
| 巡检 localhost 的 Oracle | 指定 IP 的快速巡检 |
| 生成一份数据库巡检报告 | 触发完整巡检流程 |

#### Skill 文件结构

```
dbcheck/skill/dbcheck/
├── SKILL.md           # Skill 说明
├── security.md        # 安全说明
└── scripts/
    ├── run_inspection.py   # 非交互式入口
    ├── main_mysql.py       # MySQL 巡检逻辑
    ├── main_pg.py         # PostgreSQL 巡检逻辑
    ├── main_oracle_full.py # Oracle 巡检逻辑（20+ 巡检项）
    ├── main_sqlserver.py   # SQL Server 巡检逻辑
    ├── main_dm.py         # 达梦 DM8 巡检逻辑
    ├── main_tidb.py        # TiDB 巡检逻辑
    ├── analyzer.py        # 智能风险分析引擎
    ├── slow_query_analyzer.py  # 慢查询深度分析引擎（MySQL/PG/Oracle/SQLServer/DM8）
    └── main.py             # 统一菜单入口
```

> ⚠️ **安全提示**：Skill 凭据仅用于建立本地连接，不会发送到任何第三方。AI 诊断仅使用本地 Ollama。

---

## 打包部署

使用 PyInstaller 配置文件 `dbcheck.spec` 进行打包，将所有依赖、模板文件、项目模块全部打入单个 exe 文件：

```bash
cd D:\DBCheck

# 清理旧构建（Windows）
rd /s /q build dist __pycache__ 2>nul

# 打包
pyinstaller dbcheck.spec
```

> Linux/macOS 上请使用 `rm -rf build dist __pycache__` 清理。

打包后执行：

```bash
cd dist
dbcheck.exe         # Windows
./dbcheck           # Linux/macOS
```

双击即可运行完整版程序，包含所有数据库驱动、Word 模板、Web UI 页面模板，无需安装 Python 环境。

---

## 报告结构

生成的 Word 报告包含以下章节（Oracle 巡检报告示例）：

| 章节 | 内容（Oracle 巡检）|
|------|------|
| 封面 | 数据库名称、服务器地址、版本、主机名、启动时间、巡检人员、平台、报告时间 |
| 第1章 | OS 主机信息（CPU/内存/磁盘）|
| 第2章 | 数据库基本信息（版本/实例名/数据库名）|
| 第3章 | 表空间（永久 + 临时，含自动扩展）|
| 第4章 | SGA / PGA 内存分析 |
| 第5章 | 关键参数配置 |
| 第6章 | Undo 表空间管理 |
| 第7章 | 重做日志（Redo）|
| 第8章 | 归档与备份 |
| 第9章 | Data Guard 状态 |
| 第10章 | RAC 集群信息 |
| 第11章 | ASM 磁盘组 |
| 第12章 | 会话与连接（含等待事件 TOP5）|
| 第13章 | 性能指标（含 AWR 快照分析）|
| 第14章 | Alert 日志分析 |
| 第15章 | 用户与安全 |
| 第16章 | 无效对象与统计信息 |
| 第17章 | 分区表信息 |
| 第18章 | FRA 闪回恢复区 |
| 第19章 | 回收站 |
| 第20章 | 风险与建议（智能分析问题明细 + 修复 SQL 速查表）|
| 第21章 | AI 诊断建议（Markdown 自动渲染为 Word 格式，含序号标题、代码块、列表）|
| 第22章 | 报告说明 |

> 不同数据库类型的报告结构略有差异，但均包含封面、基本信息、性能分析、风险建议、AI 诊断、报告说明六大模块。

---

## 常见问题

### 通用问题

1. **部分内容为空或缺失**
   模板渲染出现兼容性问题时，程序会自动切换至备用渲染模式，仍可生成包含所有关键数据的完整报告，不影响使用。

2. **连接失败**
   检查数据库是否允许远程访问、用户权限是否充足、防火墙是否放行对应端口。

3. **SSH 采集失败**
   确认 SSH 服务正常运行（默认端口 22）、认证信息正确。部分精简版 Linux 可能缺少 `lscpu` 等命令，导致部分 CPU 信息显示为"未获取"，属正常现象。

4. **AI 诊断不生效**
   - 确认已在 Web UI「AI 诊断设置」中保存了有效配置
   - 确保 Ollama 已启动：`ollama serve`
   - 确保模型已下载：`ollama pull qwen3:30b`（建议大模型，冷启动慢）

5. **风险建议仅供参考**
   内置阈值基于通用最佳实践，实际场景中请结合业务负载综合评估。

### Oracle 专项

6. **ORA-01017 用户名/口令无效**
   - 如果使用 SYSDBA 身份，Web UI 请勾选「SYSDBA」复选框；CLI 请输入 `sys as sysdba`（完整格式），工具会自动解析并使用正确的特权模式连接
   - 确认密码正确（注意大小写）

7. **ORA-00904 / ORA-00942 标识符无效**
   部分高级视图/列在不同 Oracle 版本中可能不存在（如 11g vs 19c）。工具已做兼容处理，少数不兼容的项目会标记为⚠跳过，不影响整体巡检。

8. **需要安装 Oracle 客户端吗？**
   - 使用 `oracledb` 驱动（推荐）：不需要，纯 Python 实现
   - 使用 `cx_Oracle` 驱动：需要下载 [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client.html)

9. **Oracle 版本支持**
   支持 **11g R2、12c、19c、21c** 及以上版本。SQL 模板已做跨版本兼容处理。

### DM8 专项

10. **连接失败（returned a result with an exception set）**
    - dmPython 为惰性连接，连接对象创建成功不代表真正连通，需通过游标执行探测 SQL 才能确认
    - 工具已内置自动探测逻辑，如仍失败请检查：端口是否正确（默认 5236）、用户密码是否正确、服务器是否允许该 IP 访问

11. **提示"无效的列名"**
    - DM8 的 V$ 视图列名与 Oracle 有较大差异，工具已针对 DM8 实测列名做过适配，如仍有报错请截图发给我们补充

12. **SSH 采集功能不可用**
    - 受限于达梦服务器 OpenSSH 版本（端口 2022），SSH 采集暂时禁用。系统资源信息将使用本地采集器，本地与达梦服务器信息不一致属正常现象。

13. **报告中的"服务器主机名/平台"是本机信息**
    - SSH 采集禁用后的已知限制，达梦服务器系统信息采集依赖 SSH 通道，后续版本将尝试修复

### SQL Server 专项

14. **连接失败**
    - 确认 SQL Server 服务允许远程连接（SQL Server Configuration Manager → Network Configuration → TCP/IP 已启用）
    - 确认防火墙已放行 1433 端口（或自定义端口）
    - 确认使用了正确的认证方式（Windows 认证或 SQL Server 混合认证）

15. **pyodbc 安装成功但连接失败**
    - 需要安装 ODBC Driver 17：`curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -` 后安装对应版本的 mssql-server
    - Linux 上可能需要：`curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | tee /etc/apt/sources.list.d/mssql-release.list`

16. **SQL Server 版本支持**
    - 支持 **SQL Server 2012、2014、2016、2017、2019、2022** 及以上版本

---

## 界面截图

![首页](snapshot/webui0.png)

![步骤一：选择数据库类型](snapshot/webui1.png)
*图 1：选择数据库类型（MySQL 🐬 / PostgreSQL 🐘 / Oracle 🔴 / SQL Server 🟠 / DM8 🟡 / TiDB 🐬）*

![步骤二：填写连接信息](snapshot/webui2.png)
*图 2：填写数据库连接信息*

![步骤三：在线连接测试数据库连接](snapshot/webui3.png)
*图 3：在线连接测试数据库连接*

![步骤四：SSH 连接配置](snapshot/webui5.png)
*图 4：SSH 连接配置（可选，默认端口 22）*

![步骤五：巡检人员](snapshot/webui6.png)
*图 5：巡检人员配置（默认为 dbcheck）*

![步骤六：确认巡检信息](snapshot/webui7.png)
*图 6：确认巡检信息*

![步骤七：执行巡检](snapshot/webui8.png)
*图 7：一键巡检，实时预览巡检进度*

![报告下载](snapshot/webui9.png)
*图 8：巡检完成后直接下载 Word 报告*

![历史报告](snapshot/webui10.png)
*图 9：历史报告列表页，支持按名称、大小、时间浏览*

![历史趋势分析](snapshot/webui12.png)
*图 10：历史趋势分析*

![AI 诊断配置](snapshot/webui13.png)
*图 11：AI 诊断配置，可完全本地运行，无需 API Key，数据不出本机。*

![Clawhub dbcheck skill](snapshot/skill0.png)
*图 12：dbcheck 已发布到 Clawhub*

![QClaw](snapshot/skill1.png)
*图 13：在 QClaw 等支持 OpenClaw Skills 的软件中使用 dbcheck。*

![Reports](snapshot/report.png)
*图 14：AI 诊断报告（Markdown 自动渲染为 Word 格式）。*
---
## 鸣谢

> 本项目参考了以下项目，感谢原项目作者的付出：

* [Zhh9126/MySQLDBCHECK](https://github.com/Zhh9126/MySQLDBCHECK.git)
* [Zhh9126/SQL-SERVER-CHECK](https://github.com/Zhh9126/SQL-SERVER-CHECK.git)

部分功能仍在快速迭代中，将来会增加更多的数据库类型，也会增强自身功能，欢迎共同参与功能开发以及反馈问题与建议。

---

## 捐赠支持

DBCheck 从初版到功能完善，历经了大量版本迭代和实测打磨。如果这个工具对你的工作有帮助，欢迎通过以下方式支持项目持续迭代：

<img src="snapshot/pay.png" alt="PayPal 捐赠二维码" width="500" />

> 捐赠时备注你的名字或昵称，让我们知道谁在支持这个项目 ❤️
>
> 联系邮箱：sdfiyon@gmail.com