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

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

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

# 一键集群巡检

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

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

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

## 前提条件

请确保已经安装 obdiag，详细信息，请参见 [安装 obdiag](https://www.oceanbase.com/docs/common-obdiag-cn-1000000000441301) 。

## check 命令组

### 语法

```shell
obdiag check [options]

```

options 说明：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| --cases | 否 | string | `` | 需要执行的observer巡检项目的集合名。当未赋值时执行所有的 tasks。 |
| --obproxy_cases | 否 | string | `` | 需要执行的obproxy巡检项目的集合名。当未赋值时执行所有的 tasks。 |
| -c | 否 | string | `~/.obdiag/config.yml` | 配置文件路径 |

示例如下：

```shell
obdiag check --cases=test

'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'

```

## 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/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_name: 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

```

## 关于 task 的手动更新

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