---
title: "一键集群巡检 - 敏捷诊断工具 V3.2.0 | OceanBase 文档中心"
description: 一键集群巡检 本文适用于独立部署 obdiag 的场景，使用 obdiag check run 命令可帮助 OceanBase 数据库集群相关状态巡检，目前支持从系统内核参数、内部表等方式对 OceanBase 集群进行分析，发现已存在或可能会导致集群出现异常问题的原因分析并提供运维建议。 check 命令组 总览 …
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*5ZXST55u540AAAAAAAAAAAAADiGDAQ/original) 敏捷诊断工具V 3.2.0

# 一键集群巡检

更新时间：2026-04-13 17:11:14

[编辑](https://github.com/oceanbase/odt-doc/edit/V3.2.0/zh-CN/360.cluster-monitor/370.use-obiag-check-patrol-oceanbase-database-cluster.md)  

本文适用于独立部署 obdiag 的场景，使用 `obdiag check run` 命令可帮助 OceanBase 数据库集群相关状态巡检，目前支持从系统内核参数、内部表等方式对 OceanBase 集群进行分析，发现已存在或可能会导致集群出现异常问题的原因分析并提供运维建议。

## check 命令组

### 总览

```shell
# 列出所有巡检套餐
obdiag check list

# 全量巡检 (最常用)
obdiag check run

# 列存POC检查
obdiag check run --cases=column_storage_poc

# obproxy 版本检查
obdiag check run --obproxy_cases=proxy

# 部署环境检查
obdiag check run --cases=build_before

# 执行 sysbench 时的巡检任务集合
obdiag check run --cases=sysbench_run

# 执行 sysbench 前的巡检任务集合
obdiag check run --cases=sysbench_free

```

### 语法

```shell
obdiag check run [options]

```

options 说明：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| --cases | 否 | string | `` | 需要执行的 OceanBase 数据库巡检项目的集合名。当未赋值时执行所有的 tasks。 |
| --obproxy_cases | 否 | string | `` | 需要执行的 OBProxy 巡检项目的集合名。当未赋值时执行所有的 tasks。 |
| -c | 否 | string | `~/.obdiag/config.yml` | 配置文件路径。 |
| --report_type | 否 | string | table | 巡检报告的输出格式，目前支持 table、json、xml、yaml、html。 |
| --inner_config | 否 | string | 默认为空 | obdiag 自用的配置。 |
| --config | 否 | string | 默认为空 | 需被 obdiag 诊断的集群的配置，固定样式：--config key1=value1 --config key2=value2。   #### 说明    支持通过该选项配置的参数可参见 [obdiag 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000002488183)。 |

## 使用示例

### 方式一：无配置文件使用（开箱即用）

- 全量巡检（最常用）

  ```shell
  obdiag check run \
      --config db_host=xx.xx.xx.xx \
      --config db_port=xxxx \
      --config tenant_sys.user=root@sys \
      --config tenant_sys.password=*** \
      --config obcluster.servers.global.ssh_username=test \
      --config obcluster.servers.global.ssh_password=****** \
      --config obcluster.servers.global.home_path=/home/admin/oceanbase
      --config obcluster.servers.nodes[1].data_dir=/home/admin/oceanbase/store
      --config obcluster.servers.nodes[1].redo_dir=/home/admin/oceanbase/store
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```
 - 列存POC检查

  ```shell
  obdiag check run --cases=column_storage_poc \
      --config db_host=xx.xx.xx.xx \
      --config db_port=xxxx \
      --config tenant_sys.user=root@sys \
      --config tenant_sys.password=*** \
      --config obcluster.servers.global.ssh_username=test \
      --config obcluster.servers.global.ssh_password=****** \
      --config obcluster.servers.global.home_path=/home/admin/oceanbase
      --config obcluster.servers.nodes[1].data_dir=/home/admin/oceanbase/store
      --config obcluster.servers.nodes[1].redo_dir=/home/admin/oceanbase/store
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```
 - OBProxy 版本检查

  ```shell
  obdiag check run --obproxy_cases=proxy \
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```
 - 部署环境检查

  ```shell
  obdiag check run --cases=build_before \
      --config db_host=xx.xx.xx.xx \
      --config db_port=xxxx \
      --config tenant_sys.user=root@sys \
      --config tenant_sys.password=*** \
      --config obcluster.servers.global.ssh_username=test \
      --config obcluster.servers.global.ssh_password=****** \
      --config obcluster.servers.global.home_path=/home/admin/oceanbase
      --config obcluster.servers.nodes[1].data_dir=/home/admin/oceanbase/store
      --config obcluster.servers.nodes[1].redo_dir=/home/admin/oceanbase/store
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```
 - 执行 sysbench 时的巡检任务集合

  ```shell
  obdiag check run --cases=sysbench_run \
      --config db_host=xx.xx.xx.xx \
      --config db_port=xxxx \
      --config tenant_sys.user=root@sys \
      --config tenant_sys.password=*** \
      --config obcluster.servers.global.ssh_username=test \
      --config obcluster.servers.global.ssh_password=****** \
      --config obcluster.servers.global.home_path=/home/admin/oceanbase
      --config obcluster.servers.nodes[1].data_dir=/home/admin/oceanbase/store
      --config obcluster.servers.nodes[1].redo_dir=/home/admin/oceanbase/store
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```
 - 执行 sysbench 前的巡检任务集合

  ```shell
  obdiag check run --cases=sysbench_free \
      --config db_host=xx.xx.xx.xx \
      --config db_port=xxxx \
      --config tenant_sys.user=root@sys \
      --config tenant_sys.password=*** \
      --config obcluster.servers.global.ssh_username=test \
      --config obcluster.servers.global.ssh_password=****** \
      --config obcluster.servers.global.home_path=/home/admin/oceanbase
      --config obproxy.servers.nodes[0].ip=xx.xx.xx.1 \
      --config obproxy.servers.nodes[1].ip=xx.xx.xx.2 \
      --config obproxy.servers.global.ssh_username=test \
      --config obproxy.servers.global.ssh_password=****** \
      --config obproxy.servers.global.home_path=/home/admin/obproxy

  ```

### 方式二：有配置文件使用

#### 说明

需要确保已经在 obdiag 配置文件 `config.yml` 中配置好需要收集节点的登录信息。相关的详细配置介绍，参见 [obdiag 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000002488183)。

示例如下：

```shell
obdiag check run

'cat ./check_report/check_report_2023-10-30-16:15:52.table', export type is table
For more details, please run cmd 'cat ./check_report/check_report_2023-10-30-16:15:52.table'
If you want to view detailed obdiag logs, please run:'obdiag display-trace --trace_id a7674ecb-0d99-36fe-b584-3b707b4647bc'

```

指定配置文件：

```shell
obdiag check run -c /path/xxx_config.yml

```

## task 编写教程

task 是一个独立的巡检场景，可以理解为一个专业的，用 yaml 编写的，用 obdiag 识别的脚本文件。

task 会包含一些用于巡检的前置声明，用于实现对 OceanBase 进行更为专业的巡检。

### 开始编写前

在编写 `test.yaml` 文件前，需要先确认 `test.yaml` 文件的存放位置。

`test.yaml` 文件必须存放在 `config.yml` 文件中设置的 `CHECK.tasks_base_path` 所标识的目录内，在该目录下，分析编写的巡检场景是否属于已有的大类，若没有则创建一个文件夹用于声明这个大类。

例：

```shell
#先进入${CHECK.tasks_base_path}/observer，然后创建一个文件夹 test，并创建示例文件 test.yaml
cd ~/.obdiag/check/tasks/observer
mkdir test
cd test
touch test.yaml

```

### 编写 task 脚本

task 的作用是声明巡检执行的步骤，其基础结构是一个 list，用于兼容不同版本可能导致步骤的出入或者该巡检项目无法使用。

task 文件的示例如下：

```yaml
info: testinfo
task:
  - version: "[3.1.0,3.2.4]"
    steps:
      {steps_object}
  - version: "[4.2.0.0,4.3.0.0]"
    steps:
      {steps_object}

```

参数说明：

| 参数名 | 是否必填 | 描述 |
| --- | --- | --- |
| info | 是 | 声明这个 yaml 使用的场景，方便维护。 |
| version | 否 | 表示适用的版本，用 Str 的形式表示范围，需要完整的数字的版本号。    OceanBase 数据库 V3.x 版本为三位，例如 [3.1.1,3.2.0]。    OceanBase 数据库 V4.x 版本为四位，例如：[4.1.0.0,4.2.0.0]。 |
| steps | 是 | 所执行步骤，为 list 结构。 |

#### steps 介绍

steps 也是一个 list，用来表示具体的多个执行流程。

steps 的一个元素的结构即单个流程，如下：

| 参数名 | 是否必填 | |
| --- | --- | --- |
| type | 是 | 表示适用的执行类型，目前支持 `get_system_parameter`/ `ssh`/`sql`。 |
| {parameter_name/ssh/sql} | 是 | 根据所选的类型提供的参数，这块比较依赖代码里的对执行类型的逻辑说明。 |
| result | 否 | 结构为一个单独的对象，用于对这个步骤结束后需要进行的操作进行解析，如校验结果逻辑，逻辑不通过时需要报错的文本信息进行说明等等。具体可参考 `result & verify 功能`。 |

各种类型示例如下，`step:` 仅为一个标记，无实际作用。

- get_system_parameter

  ```yaml
  steps:
  - type: get_system_parameter
    parameter: parameter
    result:
      set_value: servervm.max_map_count

  ```
 - ssh

  远程执行指令并获取对应的返回值。

  ```yaml
  steps:
  - type: ssh
    ssh: wc -l /proc/${task_OBServer_pid}/maps | awk '{print $1}'
    result:
      set_value: observerMaps

  ```
 - SQL

  执行 SQL 并获取对应的值。

  ```yaml
  steps:
  - type: sql
    sql: select tenant_name from oceanbase.table_name from where tenant_id=${taskTenantId};
    result:
      set_value: tenant_name

  ```

##### result & verify 功能

这个字段也是 verify 功能的主要依赖字段，用于对 task 获取结果的验证。

其格式如下：

```yaml
result:
      set_value: {set_value}
      verify_type: {verify_type}
      report_type: {report_type}
      verify: {verify}
      err_msg: {err_msg}

```

**参数说明：**

| 参数名 | 是否必填 | 描述 |
| --- | --- | --- |
| set_value | 否 | 将执行后的值赋值,作为一个适用于整个 task 的变量，例如 `set_value: max_map_count`。 |
| verify_type | 否 | 用于设置验证的方式，默认为 base，一般需要和 `verify` 联动，base 即为通过 `verify` 的表达式进行验证，输出结果为 `true` 或 `false`，同时提供了以下常见的判断类型，减少编写量。 |
| verify | 否 | 服务于 verify_type，用于验证执行结果是否符合预期，若不符合，会输出 `err_msg` 部分的信息。 |
| report_type | 否 | 用于设置本步骤若出现 `verify` 为 `false` 需要执行的告警级别，默认告警级别为 `critical`。 |
| err_msg | 否 | 用于非正常执行时答应的日志，支持配置全局变量，在 `verify` 为 `false` 的时候所输出的 msg 建议配置了 `verify`，就一定要配上 `err_msg`。 |

**`verify_type` 支持的类型**

目前 verify_type 支持的类型，除了 base 外的类型仅适用于 int 类型。

- `between`：判断 `set_value` 的值是否在 `verify` 提供的范围内。
 - `max`：判断 `set_value` 的值是否小于 `verify` 提供的值。
 - `min`：判断 `set_value` 的值是否大于 `verify` 提供的值。
 - `equal`：判断 `set_value` 的值是否等于 `verify` 提供的值。

**关于 base 的说明**

`verify` 表达式会用于替换如下 shell 式子中的 `new_expr` 内进行执行验证，在编写 verify 时可以手动在本地进行逻辑验证。

```shell
if ${new_expr}; then
    echo "true"
else
    echo "false"
fi

```

### 编写 package 脚本

package 脚本目前包含observer_check_pakage.yaml和obproxy_check_package.yaml，分别对应 observer 和 proxy 的巡检包。

package本身的结构是一个大的dict，结构如下

```shell
{case_name}:
  info_en: "" # 对这个package英文解释
  info_cn: "" # 对这个package中文解释
  tasks:
    {tasks_names} # 一个list结构，用于元素为一个或多个task的名称

```

package 脚本编写完成后可以通过 `obdiag check list` 命令查看当前可用的 case 列表。

## 关于 task 的手动更新

为了更好地提供更有效的检测项任务，我们会不定时更新 task 的数量和质量，用户可以在 [obdiag 的代码仓库](https://github.com/oceanbase/oceanbase-diagnostic-tool) 中复制 `${code_path}/handler/check/tasks` 文件夹来替换原有文件夹 `~/.obdiag/check/tasks`，同时需要的还有 *check_package.yaml(`~/.obdiag/check/*check_package.yaml`)，用于更新对应的巡检套餐。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线