offline-disk-fault-diagnosis

name	offline-disk-fault-diagnosis
description	通过分析服务器离线日志（iBMC、OS Messages、InfoCollect）诊断离线磁盘硬件、RAID 控制器及存储链路故障并定位物理级根因。当用户提供日志并询问磁盘坏道（Bad Sector）、RAID 掉盘/降级（Offline/Degraded）、I/O 超时（Timeout/Blocked）、磁盘巡检错误（Predictive Failure/SMART Error）、SAS/SATA/NVMe 链路不稳定、物理槽位异常，以及当文件系统因底层存储故障自动切换为只读（Read-only）需要进行底层根因溯源时，调用本技能。
platforms	["linux"]

离线磁盘故障诊断

本技能通过分析从服务器收集的标准日志文件，重点诊断离线磁盘及存储子系统物理/链路级故障。

技能目录结构

本技能的目录结构如下，包含诊断脚本、参考资料和文档：

offline-disk-fault-diagnosis/
├── SKILL.md                          # 本技能的主文档
├── scripts/                          # 诊断脚本目录
│   ├── diagnose_summary.py           # Step 0: 故障日志采集脚本
│   ├── diagnose_ibmc.py              # Step 2: iBMC日志分析脚本
│   ├── diagnose_infocollect.py       # Step 2: InfoCollect/磁盘专项分析脚本
│   └── diagnose_messages.py          # Step 2: OS消息日志分析脚本
└── references/                       # 参考资料目录
    ├── DISK_fault_scenarios.md       # 磁盘故障场景分类表
    ├── DISK_scenario_analysis.md     # 磁盘故障场景专项分析指南
    ├── infocollect_guide.md          # InfoCollect诊断指南
    ├── messages.md                   # OS消息日志分析指南
    ├── huawei_ibmc.md                # 华为iBMC分析指南
    ├── h3c_ibmc.md                   # H3C iBMC分析指南
    └── Inspur_ibmc.md                # Inspur iBMC分析指南

输入日志目录结构与对应诊断脚本

以 /path/to/logs/xxxx 为例，标准的服务器日志收集包通常具有以下层级结构。本技能提供了针对性的脚本来分析不同层级的日志。

注意：在实际场景中，用户提供的日志包可能不完整，可能仅包含以下三种目录中的一种或多种。请根据实际存在的日志类型灵活选择对应的分析脚本。

<日志根目录> (例如: 10.120.6.76)
├── ibmc_logs/                  # iBMC 硬件带外管理日志
│   └── (磁盘在位/热插拔/错误事件) -> 使用 scripts/diagnose_ibmc.py
├── infocollect_logs/           # 系统信息收集工具生成的分类日志
│   └── (SMART信息/RAID卡日志/性能数据) -> 使用 scripts/diagnose_infocollect.py
└── messages/                   # 操作系统层面的系统日志
    └── (dmesg, syslog, messages) -> 使用 scripts/diagnose_messages.py

⚠️ 强制执行流程

必须严格按以下顺序执行，禁止跳过或乱序：

Step 0 (故障日志采集) → Step 1 (场景分类) → Step 2 (深入分析) → Step 3 (根因校验) → Step 4 (界面输出分析报告)

执行规则：

1. 顺序强制：必须完成当前步骤并验证通过后，才能进入下一步
2. 场景分支：Step 1 输出场景标签后，Step 2 必须针对性收集相关证据
3. 数据校验：Step 3 必须通过证据矩阵校验后才能得出最终结论
4. 文件适配：日志文件不全时自动降级分析策略，但必须至少有一个日志文件
5. 专注存储：分析过程应锁定存储链路及介质，排查文件系统只读等现象的底层诱因。

每步完成标志：

• Step 0：输出日志文件时间范围、文件统计、错误关键词概览
• Step 1：确定故障场景（如 DISK_HARDWARE_FAILURE 等）
• Step 2：输出物理级精准定位、传导链及初步根因
• Step 3：输出根因证据校验表、原生日志证据及置信度定性
• Step 4：在界面上按固定结构输出最终的分析报告（严禁生成独立文件）

---

分析流程总览

步骤	阶段目标	主要工具/方法
Step 0 故障日志采集	全量/定点扫描日志目录并识别关键报错	diagnose_summary.py <log_dir> [-k/-d/-s]
Step 1 场景分类	判定现象并确定故障场景类型	根据 Step 0 采集结果进行场景匹配
Step 2 深入分析	构建起止 T0 的传导链并执行诊断	使用 diagnose_ibmc.py/diagnose_infocollect.py/diagnose_messages.py 获取多维证据
Step 3 根因校验	交叉质询证据链，执行证据双向校验	对比 iBMC/内核/系统日志的一致性，防止结论发散
Step 4 界面输出分析报告	汇总证据链与确认根因，在界面直接输出报告内容	结构化输出：结论 + 故障链条 + 修复建议

---

Step 0：故障日志采集

全量扫描（宏观分析）

目标：快速扫描所有日志文件，识别磁盘及存储子系统的异常，建立故障全景视图。当存在特定报错或时间范围时，利用参数进行第一轮初步精确定位。

执行命令（根据场景选择）：

# 场景 1：无明确过滤条件（默认全量扫描）
python3 scripts/diagnose_summary.py <log_dir>

# 场景 2：用户提供故障关键词时
python3 scripts/diagnose_summary.py <log_dir> -k "disk_fail" "slot0"

# 场景 3：用户提供故障发生时间/日期时
python3 scripts/diagnose_summary.py <log_dir> -d "Mar 16"
python3 scripts/diagnose_summary.py <log_dir> -s "2026-03-10 08:00:00" -e "2026-03-10 12:00:00"

精细定位（微观分析）

目标：在优先使用上述带有参数的扫描命令锁定范围的基础上，结合全量扫描结果，辅以 grep / less 等文件操作命令查看更细节的原始日志上下文。

注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。

---

Step 1：场景分类

根据 Step 0 采集的日志概览，分析故障现象并确定故障场景类型。

场景分类概述

根据 Step 0 采集的日志概览，分析故障现象并从以下标准场景中确定故障场景类型。

📖 参考详见：磁盘故障场景分类

场景标签	中文描述	主要特征
DISK_HARDWARE_FAILURE	磁盘硬件故障	SMART 阈值超限、UNC/UF 坏道 (MEDIUM ERROR)、WP 写保护报错、磁盘离线
DISK_IO_PERFORMANCE	I/O 性能问题	I/O 延迟高、落盘缓慢 (Await 激增)、块请求堆积、SCSI 指令超时
DISK_RAID_ERROR	RAID/控制器故障	RAID 掉盘、控制器 Cache 故障、电池/超级电容告警、阵列降级
DISK_LINK_ISSUE	链路/背板故障	频繁 SAS 链路重置 (PHY Reset)、ICRC/ABRT 接口错误、链路及背板供电不稳定
STORAGE_INDUCED_FS_ERROR	存储诱发的文件系统故障	底层 I/O 错误引发文件系统 Remount Read-only（注：纯逻辑 FS 损坏属文件系统技能范畴）
DISK_SYSTEM_CONFIG	系统/配置与兼容性限制	盘符漂移 (Drift)、磁盘不支持特定指令 (Illegal Request)、磁盘挂载数量过载

场景辅助分析与根因假设

确定场景标签后，必须参考专项分析指南进行候选根因的初步验证：

🔍 专项分析指南：磁盘故障场景专项分析指南

场景标签	候选根因假设（需在 Step 2 中验证）
DISK_HARDWARE_FAILURE	① 磁盘物理损坏引发大量坏道 ② 磁盘固件 Bug 导致逻辑死锁/写保护 ③ No Medium/介质丢失
DISK_IO_PERFORMANCE	① 磁盘老化导致写缓存落盘缓慢 ② 业务压力超过 IOPS 限制 ③ RAID 背景扫描任务
DISK_RAID_ERROR	① RAID 卡缓存校验错误 ② 电池能量耗尽导致写策略回退
DISK_LINK_ISSUE	① SAS 线缆接触不良触发 PHY Reset ② 磁盘背板电气特性不稳定 ③ HBA 接口 CRC 错误
STORAGE_INDUCED_FS_ERROR	① 底层介质/链路持续 I/O 错误触发内核安全机制 ② 存储日志写入失败导致日志提交异常
DISK_SYSTEM_CONFIG	① 挂载未采用 UUID 导致漂移 ② 下发指令与磁盘固件不兼容 ③ 数量超过 HBA/内核上限

⚠️ 强制要求：在进入 Step 2 深入分析前，应先通过 DISK_scenario_analysis.md 了解对应场景的分析路径与关键证据点。分析结束后，必须对上述候选根因方案逐一标注：✅ 已证实 / ❌ 已排除 / ❓ 证据不足。

Step 1 完成标志：

1. ✅ 确定主要故障场景标签（从上述类型中选择）
2. ✅ 记录故障现象与关键证据
3. ✅ 为 Step 2 深入分析提供明确的故障场景方向

---

Step 2：深入分析

根据 Step 1 的场景分类结果，必须首先完成时序关联与故障传导链重建，然后再通过多源脚本收集证据，最终给出精确的物理坐标定位。

2.1 时序关联与传导链重建 (核心理论框架)

目标：通过多源日志的时间戳对齐，重建故障发生的完整时间轴，厘清事件的先后顺序与因果链，为根因定位提供时序证据。

2.1.1 确定磁盘故障零点 (T0)

故障零点（T0）是时序分析的基准锚点，定义为最早可观测到异常的时间戳。确定优先级（由高到低）：

优先级	来源	说明
P1	硬件错误日志（iBMC / SEL）	底层致命报错（如 Drive Fault, Hot Plug Removal），时间点最准确。
P2	内核感知层（dmesg / messages）	最早出现的 SCSI Error、I/O Error 或 Device Reset。
P3	系统调度层（syslog / messages）	系统级重试、文件系统切只读或 OOM 相关 IO 阻塞。
P4	应用感知层	业务响应超时、数据库写入失败等应用级异常，通常滞后较大。

⚠️ 时钟偏差处理：多节点场景下，需留意 iBMC 时间与 OS 时间（NTP）是否存在时钟偏移。多源对齐时需留意并修正该偏差量。

2.1.2 多维日志对齐与时间轴矩阵

以 T0 为基准，将 iBMC 传感器告警、dmesg 报错、RAID 卡日志和 OS 系统日志统一映射到绝对时间轴上，构建事件序列矩阵。 示例：因底板/背板供电异常导致磁盘掉盘与文件系统只读的时间轴

T0-5m   ├─ [iBMC SEL]    检测到背板（Backplane）供电电压出现瞬间短幅跌落告警。
T0-1m   ├─ [OS dmesg]    `mpt3sas_cm0: log_info(0x31110d01): originator(PL)...` (频繁出现 SAS 链路重置)。
T0-30s  ├─ [OS iostat]   底层块设备 I/O await 严重阻塞，请求大量堆积，应用层感知死锁。
T0      ├─ [iBMC SEL]    记录 `Drive 8 Fault` 拔出或离线错误 → 标定为致命故障节点 T0。
T0+1m   ├─ [OS messages] 存储写入失败重试达到内核阈值，文件系统触发内核安全保护并触发 `Remount read-only`。

2.1.3 磁盘故障传导链推断 (示例)

结合对齐的时间轴矩阵，运用以下规则推导故障传导链方向：

• 规则一：层级自下而上（硬件损坏主导）
  • 传导链：磁盘物理损坏 (T0) → 触发底层报错 (SMI/NMI) → 操作系统驱动报错 (I/O Error) → 文件系统切只读。
• 规则二：环境向硬件传导（链路/压力主导）
  • 传导链：业务高负载 (T0) → 触发链路重置 (SAS Reset) → RAID 卡性能下降 → 最终应用超时。

⚠️ 精确定位强制要求：在磁盘诊断中，严禁仅使用“磁盘故障”这类含糊结论。 必须通过证据追踪到细粒度的三维物理坐标定位，例如：

• ✅ 正确结论：Slot 4 (Disk Index: 8) -> Media Error -> Reallocated Sectors Exceeded。
• ❌ 错误结论：发生 I/O 错误 或仅仅说是 磁盘 sdb 损坏。

2.1.4 存储数据流拓扑梳理

在推断故障传导链的同时，必须梳理受影响的存储数据拓扑网络（即从用户业务层直达物理磁盘层的映射关系），以便确认底层硬件异常最终影响的业务定损边界。明确逆向映射：

• 挂载点，即用户入口（例如 /data/vols/vol13/phenix_data） → 文件系统类型（例如 ext4/xfs） → 对应的分区或 LVM 逻辑卷（例如直接分区块设备 或 /dev/mapper/xxx） → 发生告警/故障的真实底层物理磁盘设备（例如 /dev/sda）。

---

2.2 日志脚本分析执行 (执行工具动作)

2.2.1 通用分析流程

通用分析流程适用于所有磁盘故障场景，提供基础的日志提取与数据分析能力：

# iBMC 日志分析（硬件层）
python3 scripts/diagnose_ibmc.py <log_dir>

# InfoCollect 日志分析（系统信息层）
python3 scripts/diagnose_infocollect.py <log_dir>

# OS Messages 日志分析（操作系统层）
python3 scripts/diagnose_messages.py <log_dir>

注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。

2.2.2 按场景专项分析

当 Step 1 确定故障场景后，优先分析对应的关键指标：

1. 磁盘硬件故障：重点查看 SMART 中的 Reallocated_Sector_Ct 和 Standard_Health_Status。
2. I/O 性能问题：重点查看 iostat 中的 await 和 util%。
3. RAID故障：重点查看 sasraidlog 中的 Logical Drive Status 和 Battery/Capacitor 状态。

2.2.3 分析执行原则

1. 场景优先原则：当故障现象明确匹配某个场景时，优先针对该场景取证。
2. 组合使用原则：必须同时使用带外（iBMC）和带内（OS）脚本进行相互验证。
3. 逐步深入原则：从宏观概览开始，逐步根据时序对齐结果深入特定日志行。

Step 2 完成标志：

1. ✅ 输出故障零点 T0 的精确时间戳及其所依托的具体日志行。
2. ✅ 梳理出以 T0 为基准的结构化事件序列矩阵与至少 3 步的确定故障传导链。
3. ✅ 给出精确到物理部件（例如 Slot ID / Disk Index）的细粒度定位结果。
4. ✅ 收集脚本产出的相关原生日志片段作为强有力的支撑证据。
5. ✅ 成功梳理出底层设备故障直达业务挂载点的重点存储数据流拓扑映射关系。

---

Step 3：根因反思与证据双向校验 (Cross-Examination Rules)

目标：对 Step 2 输出的“初步传导链与定位结果”进行“交叉质询”，确保得出的最终结论 100% 由底层日志支撑。

3.1 交叉质询铁律 (Cross-Examination Rules)

1. 孤证不立原则：任何物理级磁盘故障（如磁盘坏道），绝对不能仅凭系统层的一个报错（如 I/O Error）就下断言。必须同时找到硬件层（如 SMART 或 iBMC SEL）的第二独立证据源支撑。
2. 逻辑闭环原则：从 T0 到最终业务故障结果，传导链不允许出现跳跃。例如：链路重启不能直接等同于驱动器彻底故障，除非伴随连续的硬件离线记录。
3. 互斥排异原则：如果判定故障是磁盘 A 损坏，则必须验证同背板/同通道的其他磁盘是否正常，以排除共性故障（如背板供电）。

3.2 强制：根因证据校验表 (Evidence Validation Matrix)

在确认最终结论前，强制要求进行证据校验：

校验维度	校验标准要求	强制证据格式（分析打样要求）
E1: 时序连续性	硬件告警时间是否早于或同步于系统层报错？	[✅/❌ 结果] + 时序对齐说明 + [绝对路径 : 行号/行号范围] + 原生日志片段
E2: 物理同一性	各级日志指控的逻辑盘符（sdX）与物理槽位（Slot Y）是否对应？	[✅/❌ 结果] + 盘符与槽位映射日志梳理 + [绝对路径 : 行号/行号范围] + 原生日志片段
E3: 现象排他性	是否排除了 RAID 重建或巡检等预定后台任务的干扰？	[✅/❌ 结果] + RAID 卡状态及任务日志排除说明 + [绝对路径 : 行号/行号范围] + 原生日志片段

3.3 结论防发散拦截机制 (Anti-Hallucination Mechanism)

• 断链阻断：若无法从日志中找到证明因果传导的片段，强制触发流程拦截，回溯重新收集。
• 降级处分：若确实缺乏某一层关键日志（如无 iBMC），必须在报告中声明为**“疑似故障 (Suspected)”**并标注证据断层位置。
• 严禁用词限制：在证据链未能满足完全闭环标准前，严禁使用“肯定”、“必然”、“磁盘绝对已坏”等决定性断言。

Step 3 完成标志：

1. ✅ 结构化地产出《根因证据校验表》中每一项的自查结论。
2. ✅ 每个通过项均附带 Trace 日志中的 Timestamp、Text 以及其明确的 [绝对路径 : 行号/行号范围]。
3. ✅ 输出与之等位置信度（已证实 / 高度疑似 / 多重原因交织）的严谨研判方向。

---

Step 4：界面输出分析报告

汇总 Step 0～3 的所有分析结果，直接在当前对话界面输出结构化的诊断结论。禁止生成任何额外的文档或报告文件。

报告结构：

1. Executive Summary（故障摘要） — 严禁使用笼统回答，必须包含以下三要素：
   • 具体设备及物理槽位信息（例如：明确指出具体的 Slot 号、盘符及硬件型号）。
   • 具体的根因故障（例如：具体的“基于 SMART 阈值超限的物理坏道”或“明确的 SAS 链路重置”，而非宽泛的“硬件故障”）。
   • 业务后果概述（例如：该底层故障引发的上层业务异常表现，如“引发 I/O 长期阻塞并导致文件系统自动挂载为只读”）。
2. Storage Data Flow（存储数据流拓扑） — 必须呈现从业务感知层到底层故障部件的数据流向映射关系：
   • 必须按层级包含以下上下游映射关系及路径节点名：挂载点（用户入口，如 /data/vols/vol13/phenix_data） → 文件系统（如 ext4/xfs） → 分区/LVM逻辑卷 → 真实故障物理磁盘设备（如 /dev/sda）。
3. Fault Chains（故障链条分析） — 必须包含以下两级链条：
   • 故障时间链 (Fault Time Chain)：列出带关键节点的事件序列，每个节点必须包含准确的时间戳及对应的出处 [绝对路径 : 行号/行号范围]。
   • 故障传播链 (Fault Propagation Chain)：清晰描绘导致系统表现的物理/外部因果传导路径（例如：硬盘物理损坏 -> I/O 请求严重堆积 -> 内核触发 Device Reset -> 文件系统被动切为 Read Only）。
4. Technical Analysis & Root Cause（技术分析与根因） — 基于 Step 2 的传导链底层回溯与 Step 3 的交叉质询得出的物理级或配置级根因，并提供多源证据链（E1/E2/E3）支撑。🔴 强制约束：针对提供证明此根因或结论对应的原生日志片段，必须强制标明其确切证据出处，格式统一为 [绝对路径 : 行号/行号范围]。溯源路径必须是从系统中可查找的完整绝对路径，严禁截断。
   • ✅ 正确示例：[/path/to/logs/ibmc_logs/maintenance/sel.log : 1024]
   • ❌ 错误示例：[sel.log : 1024]（丢失路径）或 [maintenance/sel.log : 1024]（路径不完整）
5. Recommendations（修复建议） — 立即操作、备件更换建议及预防性检查

诊断分析完成性拦截检查（不满足条件时强行熔断回溯，严禁盲目输出报告）：

在得出结论前，核心系统（作为自我审查器）必须强制执行以下内部清单确认拦截：

• ⚠️ 关键校验 1：报告中是否已经完整包含并格式化输出了直探底部物理硬件的挂载存储数据流映射关系结构？
• ⚠️ 关键校验 2：所有关键证据或者日志引用的出处，是否都已经无遗漏地指明了它的完整绝对路径（而非仅文件名或相对路径）与精准行号/行号范围？
• 是否给出了精确的物理槽位号（Slot ID）？
• Step 1 场景假设矩阵是否已完成 ✅/❌ 标注？
• 是否排除了硬件以外的软件或链路干扰因素？
• 故障时间链中的每一个节点是否都有准确的时间和对应的溯源出处 [绝对路径 : 行号/行号范围]？
• 是否清晰勾勒并输出了故障传播链？

---

参考资料

• InfoCollect 诊断指南
• OS Messages 诊断指南
• Huawei iBMC 分析
• H3C iBMC 分析
• Inspur iBMC 分析

---