dbcheck

name	dbcheck
description	执行 MySQL、PostgreSQL、Oracle、SQL Server、DM8、TiDB 数据库健康巡检，内置 130+ 条增强风险分析规则 + 慢查询深度分析引擎 + 本地 Ollama AI 大模型诊断建议，一键生成专业 Word 巡检报告。适用于 DBA 和运维人员快速掌握数据库运行状况、排查风险。项目地址：https://github.com/fiyo/DBCheck.git
license	MIT
metadata	{"openclaw":{"emoji":"🔍"}}

DBCheck — 数据库自动化巡检工具

安全声明（必读）

本 Skill 的数据流向完全可控，如下所示：

用户凭据 → [本地 Python 脚本] → 数据库服务器 → 巡检结果 → [本地 Word 报告]
                                          ↘
                                           → [本地 Ollama] → AI 建议（可选）

• ✅ 数据库凭据：仅用于建立连接，不会写入磁盘持久文件，不会发送到任何第三方
• ✅ AI 诊断：仅支持本地部署的 Ollama（地址必须为 localhost / 127.0.0.1），代码层面强制校验，不支持 OpenAI / DeepSeek 等任何远程 API
• ✅ SSH 连接：使用 AutoAddPolicy 自动接受主机密钥（适用于内网可信环境），连接仅用于采集系统资源指标
• ✅ 本地文件写入：巡检结果以 Word 报告形式保存在本地 reports/ 目录；history.json 存储历史趋势数据（纯数值指标）；autoDoc.log 为运行日志。所有文件均在本地，不含敏感凭据
• ⚠️ 限制：本 Skill 仅用于合法授权的数据库巡检，请勿用于未授权访问

核心能力

能力	说明
📊 130+ 条增强风险规则	覆盖 MySQL 35+ / PostgreSQL 27+ / Oracle 20+ / SQL Server 15+ / DM8 16+ / TiDB 18+ 全维度，含 28 条慢查询深度分析专项规则，每条附修复 SQL
🔍 慢查询深度分析引擎	跨 6 种数据库多维度采集 Top SQL（延迟/I/O/锁等待/临时表），自动注入 AI 诊断生成根因优化建议
🤖 AI 智能诊断（仅本地 Ollama）	调用本地部署的大模型（需安装 Ollama）生成个性化优化建议，API 地址强制校验为 localhost，数据绝不外传
📈 历史趋势分析	多次巡检数据聚合，生成指标趋势折线图（存储在本地 SQLite / history.json）
🔒 脱敏报告导出	导出 Word 时自动掩码 IP、端口、用户名、服务名，防止信息泄露
📐 配置基线检查	MySQL/PostgreSQL 20+ 项核心配置参数与推荐值对比，生成配置差距报告，支持自动根据数据库规模计算推荐值
🔎 索引健康分析	MySQL/PostgreSQL 缺失索引/冗余索引/未使用索引识别，给出优化建议
📑 PDF 导出	支持将 DOCX 巡检报告转换为 PDF（需 LibreOffice 或 docx2pdf）

安全架构详解

数据不外传的保障机制

1. 代码层硬限制：AIAdvisor 类在初始化时检查 backend 值，openai/deepseek/custom 等非 ollama 值会被强制降级为 disabled
2. URL 地址校验：Ollama 的 API URL 必须是 localhost 或 127.0.0.1，非本地地址会导致 AI 诊断自动禁用
3. Web API 校验：/api/ai_config 接口保存配置时同时校验 backend 和 URL，双重保险
4. 无远程 API 代码：已移除 _call_openai() 等所有远程调用方法，仅保留 _call_ollama()

本地文件说明

文件/目录	用途	是否含敏感信息
reports/*.docx	巡检 Word 报告	含数据库结构和配置（不含密码）
history.json	历史趋势数据	仅含数值指标（CPU/内存/连接数等）
autoDoc.log	运行日志	含执行过程信息（不含密码）

支持的数据库

数据库	驱动	默认端口	SSH 系统采集	特有巡检项
🐬 MySQL	pymysql	3306	✅ 支持	主从复制、binlog、查询缓存
🐘 PostgreSQL	psycopg2	5432	✅ 支持	归档模式、缓存命中率、dead tuples
🔴 Oracle	oracledb / cx_Oracle	1521	✅ 支持	表空间、SGA/PGA、RAC、ASM、Data Guard、Redo、备份
🟠 SQL Server	pyodbc (ODBC Driver 17)	1433	❌ 不支持	等待统计、锁与阻塞、备份检查
🟡 DM8	dmpython	5236	✅ 支持	表空间、SGA/PGA、DM8 缓冲池、备份、DM8 特有视图
🐬 TiDB	pymysql	4000	✅ 支持	Placement Rules、亲和性策略、TiCDC/PD 心跳、Follower 延迟

DM8 SSH 说明：通过 SSH 采集达梦服务器的主机级系统信息（CPU/内存/磁盘）。连接失败时自动降级为本地采集器。

TiDB 说明：TiDB 使用 MySQL 协议，连接参数与 MySQL 相同（默认端口 4000）。

触发条件

当用户请求以下任意一项时，加载本 Skill 并执行：

• 对数据库做健康检查 / 健康巡检 / 体检
• 检查 MySQL / PostgreSQL / Oracle / SQL Server / DM8 / TiDB 的运行状态、连接数、缓存命中率等
• 生成数据库巡检报告 / 健康报告
• 数据库风险排查 / 巡检
• "帮我巡检一下 XX 数据库"
• "生成一份 MySQL/PostgreSQL/Oracle/SQL Server/DM8/TiDB 巡检报告"

前置准备

必需信息

开始巡检前，必须向用户收集以下信息（缺少任何一项都要询问，不要自行猜测）：

参数	说明	默认值
db_type	数据库类型	需用户确认：mysql / pg / oracle / sqlserver / dm / tidb
host	数据库主机 IP 或域名	需用户确认
port	数据库端口	MySQL 默认 3306，PG 默认 5432，Oracle 默认 1521，SQL Server 默认 1433，DM8 默认 5236，TiDB 默认 4000
user	数据库用户名	需用户确认
password	数据库密码	需用户确认
label	数据库标签（用于报告命名）	需用户确认，如 "生产库-MySQL"
inspector	巡检人员姓名	需用户确认

Oracle 专用参数

参数	说明
service_name 或 sid	Oracle 服务名或 SID（二选一，必填）
特权连接	用户名输入 sys as sysdba 可建立 SYSDBA 特权连接

DM8 注意事项

参数	说明
database	无需填写，DM8 连接用户即 Schema，无需指定 database 参数
驱动安装	需 pip install dmpython
连接特性	dmPython 为惰性连接，connect() 成功不代表真正连通，需通过游标执行探测 SQL 才能确认

可选信息

参数	说明
ssh_host	SSH 主机 IP（采集系统资源时需要，DM8 除外）
ssh_port	SSH 端口，默认 22
ssh_user	SSH 用户名
ssh_password	SSH 密码
ssh_key	SSH 私钥文件路径（与密码二选一）

安全提醒：

• 数据库/SSH 凭据仅用于建立连接，不写入持久文件，不发送到任何第三方
• AI 诊断（如启用）仅使用本地 Ollama（localhost），API 地址在代码和 API 层面均有校验
• 巡检结果（Word 报告）保存在本地 reports/ 目录，历史数据存储在本地 history.json
• SSH 连接使用 AutoAddPolicy（适合内网可信环境）

工具选择

使用 execute_command 工具执行 Python 脚本。不要使用 del /F 或 rm -rf 等危险命令。

脚本路径

DBCheck 工具位于 Agent 的 skills 目录中，通过 run_inspection.py 非交互式入口执行。

依赖检查

先检查依赖是否完整：

python -c "import pymysql, psycopg2, docxtpl, paramiko, psutil, openpyxl, docx" 2>&1

如有缺失，提示用户安装：

pip install pymysql psycopg2-binary paramiko openpyxl docxtpl python-docx pandas psutil flask oracledb dmpython pyodbc flask_socketio

执行巡检

MySQL 巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type mysql \
    --host <数据库IP> \
    --port 3306 \
    --user <用户名> \
    --password <密码> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

PostgreSQL 巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type pg \
    --host <数据库IP> \
    --port 5432 \
    --user <用户名> \
    --password <密码> \
    --database <数据库名，默认postgres> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

Oracle 巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type oracle \
    --host <数据库IP> \
    --port 1521 \
    --user <用户名> \
    --password <密码> \
    --service_name <服务名> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

Oracle 特权连接：用户名输入 sys as sysdba，工具自动识别并使用 SYSDBA 模式连接。

SQL Server 巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type sqlserver \
    --host <数据库IP> \
    --port 1433 \
    --user <用户名> \
    --password <密码> \
    --database <数据库名，默认master> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

SQL Server 注意：需要安装 ODBC Driver 17。无需填写 --service_name 参数。

DM8（达梦）巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type dm \
    --host <数据库IP> \
    --port 5236 \
    --user <用户名> \
    --password <密码> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

DM8 注意：无需填写 --database 参数，连接用户即 Schema。SSH 采集连接失败时自动降级为本地采集器。

TiDB 巡检

cd <skill_scripts_dir>
python run_inspection.py \
    --type tidb \
    --host <数据库IP> \
    --port 4000 \
    --user <用户名> \
    --password <密码> \
    --label "<数据库标签>" \
    --inspector "<巡检人员姓名>"

TiDB 注意：TiDB 使用 MySQL 协议（pymysql），默认端口 4000，权限配置与 MySQL 完全相同。

配置基线检查（MySQL / PostgreSQL 专用）

cd <skill_scripts_dir>

# MySQL 配置基线检查
python run_inspection.py \
    --type mysql \
    --host <数据库IP> \
    --port 3306 \
    --user <用户名> \
    --password <密码> \
    --check-config

# PostgreSQL 配置基线检查（输出 PDF）
python run_inspection.py \
    --type pg \
    --host <数据库IP> \
    --port 5432 \
    --user <用户名> \
    --password <密码> \
    --check-config \
    --output-format pdf

检查 20+ 项核心配置参数（innodb_buffer_pool_size、max_connections、shared_buffers 等）与推荐值的差距，输出当前值/推荐值/差距百分比。

索引健康分析（MySQL / PostgreSQL 专用）

cd <skill_scripts_dir>

# MySQL 索引健康分析（文本输出）
python run_inspection.py \
    --type mysql \
    --host <数据库IP> \
    --port 3306 \
    --user <用户名> \
    --password <密码> \
    --check-indexes

# PostgreSQL 索引健康分析（输出 PDF）
python run_inspection.py \
    --type pg \
    --host <数据库IP> \
    --port 5432 \
    --user <用户名> \
    --password <密码> \
    --check-indexes \
    --output-format pdf

分析缺失索引、冗余索引、未使用索引，给出优化建议。依赖 performance_schema（MySQL）或 pg_stat_user_indexes（PostgreSQL）。

PDF 导出

cd <skill_scripts_dir>
python run_inspection.py --to-pdf /path/to/report.docx

将已生成的 DOCX 巡检报告转换为 PDF。依赖 LibreOffice（跨平台）或 docx2pdf（Windows）。

带 SSH 系统资源采集（MySQL / PostgreSQL / Oracle）

python run_inspection.py \
    --type mysql \
    --host <IP> \
    --user <用户名> \
    --password <密码> \
    --label "<标签>" \
    --inspector "<姓名>" \
    --ssh-host <SSH主机IP> \
    --ssh-user <SSH用户名> \
    --ssh-password <SSH密码>

完整参数参考

--type           数据库类型: mysql / pg / oracle / sqlserver / dm / tidb（完整巡检必需）
--host           数据库主机 IP 或域名
--port           数据库端口（默认 MySQL 3306, TiDB 4000, PG 5432, Oracle 1521, SQL Server 1433, DM8 5236）
--user           数据库用户名
--password       数据库密码
--service_name   Oracle 服务名（Oracle 专用）
--sid            Oracle SID（Oracle 专用，与 service_name 二选一）
--database       数据库名（PG/SQL Server 专用，默认 postgres/master）
--label          数据库标签，用于报告命名
--inspector      巡检人员姓名
--ssh-host       SSH 主机 IP（可选，SQL Server/DM8 暂不支持）
--ssh-port       SSH 端口（默认 22）
--ssh-user       SSH 用户名（可选）
--ssh-password   SSH 密码（可选）
--ssh-key        SSH 私钥文件路径（可选，与密码二选一）

# ── 单项检查模式 ───────────────────────────────────────────────
--check-config   执行配置基线与合规检查（支持 MySQL/PostgreSQL）
--check-indexes 执行索引健康分析（支持 MySQL/PostgreSQL）
--output-format  输出格式: txt（默认）/ pdf

# ── PDF 转换模式 ───────────────────────────────────────────────
--to-pdf <PATH> 将 DOCX 报告转换为 PDF（单独使用）

报告输出

• 报告自动保存在 <scripts_dir>/reports/ 目录下
• 文件名格式：
  • MySQL：MySQL巡检报告_<标签>_<时间戳>.docx
  • PostgreSQL：PostgreSQL巡检报告_<标签>_<时间戳>.docx
  • Oracle：Oracle巡检报告_<标签>_<时间戳>.docx
  • SQL Server：SQLServer_<标签>_<时间戳>.docx
  • DM8：DM8巡检报告_<标签>_<时间戳>.docx
  • TiDB：TiDB巡检报告_<标签>_<时间戳>.docx
  • 配置基线：MySQL配置基线报告_<标签>_<时间戳>.txt/.pdf
  • 索引健康：MySQL索引健康分析_<标签>_<时间戳>.txt/.pdf
• 报告可用 Microsoft Word / WPS 打开（DOCX）；PDF 报告可用任意 PDF 阅读器打开

报告结构（各数据库通用）

生成的 Word 报告包含以下章节（各数据库结构略有差异）：

• 封面：数据库基本信息（名称/版本/实例/主机名/启动时间/巡检人员/平台/报告时间）
• 第1章：数据库基本信息（版本/实例名/服务器版本等）
• 第2章：巡检执行摘要（执行时间、耗时、异常项统计）
• 第3章：表空间使用情况（各数据库文件使用率）
• 第4章：会话与事务（活动会话列表 + 阻塞事务）
• 第5章：内存分析（SGA/PGA + 各缓冲池详情，DM8 含 DM8 特有缓冲池）
• 第6章：重做日志与归档
• 第7章：系统资源监控（CPU/内存/磁盘，SSH 采集或本地采集）
• 第8章：对象与用户安全
• 第9章：备份与归档（Oracle/DM8 含备份集检查）
• 第10章：风险与建议（130+ 条增强规则，含慢查询深度分析，每条附修复 SQL）
• 第11章：报告说明

Oracle 报告额外包含：RAC 集群信息、ASM 磁盘组、Data Guard 状态、Undo 表空间、Profile 密码策略等。 DM8 报告额外包含：DM8 缓冲池详情、DM8 特有视图等。 TiDB 报告额外包含：Placement Rules、亲和性策略、TiCDC/PD 心跳状态等。

常见错误处理

错误信息	原因	解决方案
pymysql: Access denied	用户名或密码错误	核对数据库账户信息（MySQL/TiDB 均适用）
Can't connect to MySQL server	防火墙阻止或端口不对	确认端口（MySQL 默认 3306，TiDB 默认 4000）、防火墙、安全组规则
psycopg2: connection refused	PG 端口不对或未监听该地址	检查 postgresql.conf 的 listen_addresses
ORA-01017 (Oracle)	用户名/口令无效	确认密码（注意大小写）；如用 SYSDBA 请输入完整格式 sys as sysdba
ORA-00904 (Oracle)	无效列名/标识符	部分高级视图在低版本 Oracle 中不存在，标记⚠跳过不影响整体巡检
Oracle 连接需要 Instant Client？	使用 oracledb 驱动则不需要	推荐使用 oracledb（纯 Python，无需 Instant Client）
dmPython returned a result with an exception set (DM8)	dmPython 为惰性连接，探测失败	检查端口（默认 5236）、用户名、密码、服务器访问权限
SSH 采集失败	SSH 认证失败或目标机器无相关命令	检查用户名密码或私钥路径；确认目标机器有 top/free/df/lscpu 命令
Permission denied（SSH）	SSH 认证失败	检查用户名密码或私钥路径
command not found: lscpu	精简版 Linux 缺少命令	报告该部分显示"N/A"，不影响数据库数据

结果展示

巡检完成后：

1. 告知用户报告文件完整路径
2. 使用 open_result_view 工具打开报告文件供用户查看
3. 简要汇报关键发现（如发现高风险项，单独列出）
4. 提示用户报告中风险建议仅供参考，需结合实际业务评估

限制与注意事项

• 本 Skill 仅用于合法授权的数据库巡检，请勿用于未授权访问
• SSH 采集依赖目标机器的 top、free、df、lscpu 命令（使用 AutoAddPolicy 接受主机密钥）
• 报告生成依赖 python-docx 和 docxtpl 库，务必确保已安装
• Oracle 支持 11g R2 / 12c / 19c / 21c 及以上版本，部分高级视图在不同版本间有差异，工具已做兼容处理
• DM8 巡检依赖 dmpython 驱动（pip install dmpython）；V$ 视图列名与 Oracle 有较大差异，工具已针对 DM8 实测列名做过适配
• SQL Server 巡检依赖 pyodbc（pip install pyodbc）和 ODBC Driver 17（需单独安装）
• TiDB 使用 MySQL 协议（pymysql），默认端口 4000；权限配置与 MySQL 完全相同
• 本地文件写入：巡检会在 reports/ 生成 Word 报告、在当前目录写入 history.json（纯数值指标）、autoDoc.log（运行日志），均在本地机器上
• AI 诊断限制：仅支持本地 Ollama，API 地址必须是 localhost/127.0.0.1；不支持任何远程 AI 服务
• 配置基线检查：仅支持 MySQL/PostgreSQL，依赖 performance_schema（MySQL）或 pg_stat_statements（PG）获取统计信息
• 索引健康分析：仅支持 MySQL/PostgreSQL，MySQL 依赖 performance_schema.table_statistics，PG 依赖 pg_stat_user_indexes
• PDF 导出：依赖 LibreOffice（跨平台，推荐）或 docx2pdf（Windows 专用）；如需 PDF 格式报告请安装：pip install reportlab（用于直接生成 PDF 报告）