案例：从零安装到执行第一条命令¶

场景背景¶

角色：后端开发工程师，第一次接触 dbskiter
目标：15 分钟内完成安装、配置、执行第一条命令
环境：Windows 10/11，已有 Python 3.10+
数据库：本地 MySQL 8.0，测试库 jump

生活化比喻：dbskiter 就像新买的电动螺丝刀。开箱 → 装电池（安装）→ 调档位（配置）→ 拧第一颗螺丝（执行命令）。本案例带你完整走一遍。

步骤 1：安装（2 分钟）¶

检查 Python 版本¶

python --version
# 预期输出: Python 3.10.x 或更高

# 如果版本低于 3.8，需要升级
# 下载地址: https://www.python.org/downloads/

安装 dbskiter¶

pip install dbskiter

预期输出：

Collecting dbskiter
  Downloading dbskiter-3.0.19-py3-none-any.whl
...
Successfully installed dbskiter-3.0.19

验证安装¶

dbskiter --version

预期输出：

dbskiter 3.0.19

如果提示 dbskiter 不是内部或外部命令，说明 Python Scripts 目录不在 PATH 中。

Windows 修复 PATH：

# 临时添加（当前终端有效）
$env:PATH += ";C:\Users\你的用户名\AppData\Local\Programs\Python\Python310\Scripts"

# 永久添加（添加到系统环境变量）
# 控制面板 → 系统 → 高级系统设置 → 环境变量 → Path → 添加 Python Scripts 路径

步骤 2：配置数据库（3 分钟）¶

方案 A：交互式向导（推荐新手）¶

dbskiter init

交互过程：

欢迎使用 dbskiter 配置向导！

? 数据库类型: (使用方向键选择)
  MySQL
> PostgreSQL
  Oracle
  SQL Server
  ClickHouse
  SQLite

? 主机地址: localhost
? 端口: 3306
? 用户名: root
? 密码: [输入时隐藏]
? 数据库名称: jump
? 配置名称: jump_local（用于 --database=jump_local 指定）
? 保存为默认配置? (Y/n) Y

配置已保存: ~/.dbskiter/config.yaml

方案 B：手动配置文件（适合多数据库环境）¶

创建配置文件 ~/.dbskiter/config.yaml：

databases:
  jump_local:
    type: mysql
    host: localhost
    port: 3306
    user: root
    password: your_password
    database: jump

  jump_prod:
    type: mysql
    host: 192.168.1.100
    port: 3306
    user: dbskiter_readonly
    password: your_password
    database: jump

  oracle_erp:
    type: oracle
    host: 192.168.1.200
    port: 1521
    user: erp_reader
    password: your_password
    database: ORCL

# 默认使用的数据库
default: jump_local

注意：配置文件中包含密码，切勿提交到 Git 仓库。建议在 .gitignore 中添加 ~/.dbskiter/。

方案 C：环境变量（CI/CD 场景）¶

创建 .env 文件（项目目录下）：

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=jump

或者在命令行直接指定：

dbskiter --host=localhost --port=3306 --user=root --password=your_password --database=jump monitor health

步骤 3：执行第一条命令（2 分钟）¶

健康检查¶

# 如果配置了 default，直接执行
dbskiter monitor health

# 如果配置了多个数据库，指定名称
dbskiter --database=jump_local monitor health

# 或者命令行传参数（无需配置文件）
dbskiter --host=localhost --port=3306 --user=root --password=your_password --database=jump monitor health

预期输出：

============================================================
数据库健康检查: jump
============================================================
数据采集时间: 2026-06-18 14:30:22

健康评分: 66.4/100

性能指标:
  [绿色] 连接数使用率: 2.6%   正常
  [绿色] 缓冲池命中率: 99.90%  优秀
  [黄色] 临时表磁盘使用率: 61.96% 警告
  [黄色] 行锁等待次数: 147 警告

配置检查:
  [绿色] 配置检查: 18 项通过
  [黄色] 慢查询阈值: 10.0s 警告

安全状态:
  [绿色] 无空密码用户
  [黄色] SUPER 权限用户: 4 个

恭喜！你的第一条命令执行成功了。绿色 = 正常，黄色 = 警告，红色 = 严重。

步骤 4：快速体验其他命令（5 分钟）¶

2. 巡检报告¶

dbskiter --database=jump_local inspector report --output jump_report.html

然后打开 jump_report.html，你会看到： - 健康评分大图 - 雷达图（5 维度评分） - 详细检查项列表 - 优化建议

3. 慢查询分析¶

dbskiter --database=jump_local diagnose slow-queries

4. 安全审计¶

dbskiter --database=jump_local security audit

5. 查看所有命令¶

dbskiter --help

步骤 5：无数据库体验（Demo 模式）¶

如果你暂时没有数据库，可以用内置 Mock 数据体验：

# 演示模式，无需配置数据库
dbskiter --demo monitor health
dbskiter --demo diagnose slow-queries
dbskiter --demo inspector run

Mock 数据模拟了一个有问题的数据库，你可以看到各种警告和严重问题，学习排查思路。

常见问题（FAQ）¶

Q1：安装失败，`pip install dbskiter` 报错¶

ERROR: Could not find a version that satisfies the requirement dbskiter

解决： - 升级 pip：pip install --upgrade pip - 检查 Python 版本：python --version（需 >= 3.8） - 使用国内镜像：pip install dbskiter -i https://pypi.tuna.tsinghua.edu.cn/simple

Q2：连接失败，`Access denied for user`¶

ConfigError: 数据库连接失败: (1045, "Access denied for user 'root'@'localhost'")

解决： - 检查密码是否正确 - 检查用户是否有权限：GRANT ALL ON jump.* TO 'root'@'localhost'; - 检查 MySQL 是否允许本地连接

Q3：命令找不到，`dbskiter 不是内部命令`¶

解决： - Windows：添加 Python Scripts 目录到 PATH（见步骤 1） - Linux/macOS：export PATH="$PATH:$(python -m site --user-base)/bin"

Q4：连接远程数据库失败¶

ConfigError: 数据库连接失败: (2003, "Can't connect to MySQL server")

解决： - 检查网络连通性：ping 192.168.1.100 - 检查 MySQL 端口：telnet 192.168.1.100 3306 - 检查 MySQL 是否允许远程连接：bind-address 不是 127.0.0.1 - 检查防火墙：云服务器安全组是否开放 3306 端口

Q5：如何查看配置文件路径？¶

dbskiter --config-path
# 输出: ~/.dbskiter/config.yaml

下一步学习路径¶

你的需求	推荐案例
业务变慢，查原因	业务卡顿查慢查询
磁盘快满了	磁盘空间告警
接口超时	接口超时查锁等待
每月巡检	月度巡检实战
安全合规	安全审计排查

命令速查卡¶

# 健康检查
dbskiter monitor health

# 巡检报告
dbskiter inspector report --output report.html

# 慢查询
dbskiter diagnose slow-queries

# 安全审计
dbskiter security audit

# 锁分析
dbskiter lock analyze

# 容量预测
dbskiter monitor capacity --resource=disk

# 所有命令帮助
dbskiter --help
dbskiter monitor --help
dbskiter diagnose --help

恭喜完成新手教程！你已经可以独立使用 dbskiter 进行数据库运维了。

案例：从零安装到执行第一条命令¶

场景背景¶

步骤 1：安装（2 分钟）¶

检查 Python 版本¶

安装 dbskiter¶

验证安装¶

步骤 2：配置数据库（3 分钟）¶

方案 A：交互式向导（推荐新手）¶

方案 B：手动配置文件（适合多数据库环境）¶

方案 C：环境变量（CI/CD 场景）¶

步骤 3：执行第一条命令（2 分钟）¶

健康检查¶

步骤 4：快速体验其他命令（5 分钟）¶

2. 巡检报告¶

3. 慢查询分析¶

4. 安全审计¶

5. 查看所有命令¶

步骤 5：无数据库体验（Demo 模式）¶

常见问题（FAQ）¶

Q1：安装失败，pip install dbskiter 报错¶

Q2：连接失败，Access denied for user¶

Q3：命令找不到，dbskiter 不是内部命令¶

Q4：连接远程数据库失败¶

Q5：如何查看配置文件路径？¶

下一步学习路径¶

命令速查卡¶

Q1：安装失败，`pip install dbskiter` 报错¶

Q2：连接失败，`Access denied for user`¶

Q3：命令找不到，`dbskiter 不是内部命令`¶