服务器故障分析（Server Fault Analysis）

概述

本技能用于服务器系统软硬件故障的端到端分析：解析主流服务器厂商的带外（BMC）日志与操作系统硬件状态/日志，按统一故障分类体系归类故障、定级并给出根因与解决方法，自动生成标准化故障分析报告，并按故障类型查询备件 PN 码与数量。

覆盖厂商：Dell（iDRAC）、HPE（iLO）、Lenovo（XCC）、华为（iBMC）、浪潮、新华三（HDM）、曙光，以及通用 IPMI/BMC 日志与主流 Linux 发行版（RHEL/CentOS/Rocky/AlmaLinux/openEuler/Kylin/Ubuntu/SLES）。

时间窗口原则（需求 5）：默认只对分析窗口内（近 90 天，约 3 个月，可经 --within-days / --ref-date 调整）的报错进行诊断与给出解决方法；超过窗口的报错只在故障描述（第 1.4 节）中记录并标注时间，不做诊断、不给出解决方法（避免用陈年旧账误导当前处置）。无法判定时间的条目默认纳入窗口内分析。支持 Unix epoch 时间戳（浪潮等 BMC 的 SEL 直接使用 epoch 秒）。

硬件资产清单（需求 6）：分析过程中（采集阶段）一并记录所有硬件的型号、产品号（PN）、微码/固件版本，以及 BMC、BIOS 版本，保存至报告「附录 C 硬件资产与版本清单」；任意字段查不到时标记「（空）」，禁止凭记忆编造。在此基础上，能力 5 进一步对 BMC/BIOS 版本做健康分析（官网缺陷核实 + 最新版本确认 + 升级建议），结果写入报告 6.3 章 与 Excel「固件版本健康分析」工作表。

RAID 卡内部事件日志（重要）：浪潮/华为/新华三等厂商的一键诊断包内常含 bmcOnekeyLog/raid*.tar → raid4.log，为 LSI/MegaRAID/AVAGO SAS 控制器的内部事件日志。该日志是存储故障的关键证据源，含物理盘级介质错误、坏块穿刺、重建失败、电池故障等 BMC SEL 中完全看不到的细节，必须解析。脚本已内置解析与 LSI 官方事件码表映射。

使用决策（先执行这一步）

多能力组合时按 1/2 → 5 → 3 → 4 顺序执行：先分析，再做版本健康分析，再出报告，报告末附备件清单。

通用原则（所有能力适用）

1. 不编造。厂商事件码精确含义、备件 PN、硬件型号/PN/版本无法确认时，在输出中明确标注"待查证 / 待核实 / （空）"，并给出查证路径；禁止凭记忆填写具体编码或部件号。
2. 每条故障结论必须附日志证据（原始条目摘录，含时间与严重度）。
3. 根因按可能性从高到低排序并说明判断依据；证据不足时给出概率性判断并标注置信度。
4. 涉及数据安全或宕机风险的操作（换盘、拔电源、升级固件、更换主板等）必须在输出中给出风险提示。
5. 脚本输出的规则匹配结果是初筛，最终分类与根因表述由 agent 结合 references/fault-taxonomy.md 完善，不得原样照搬。
6. 时间窗口纪律：仅对分析窗口内（默认近 90 天，约 3 个月）的报错做诊断与解决；超窗口报错只在第 1.4 节记录并标注时间，不得据此给出处置建议。
7. 资产清单纪律：报告必须包含附录 C 硬件资产与版本清单（型号/PN/微码/BMC/BIOS 版本）；缺失字段标「（空）」。

能力 1：带外（BMC）日志分析

1. 确认日志来源。用户未提供日志时，按 references/oob-log-guide.md 指引其从 iDRAC / iLO / XCC / iBMC / ipmitool 导出。
2. 解析：运行 scripts/parse_oob_log.py，输入日志文件，输出 JSON + Markdown 摘要。
   - 自动识别厂商与日志格式；识别失败时退化为通用逐行解析并提示人工确认。
   - 每条输出：时间、严重度、事件内容、故障类别、状态（未恢复 / 已恢复）。
   - 时间窗口：默认 --within-days 90（约 3 个月，可用 --ref-date 指定基准日）。窗口内条目进入 faults（诊断/解决用）；超窗口条目进入 historical（仅记录，不分析），并随结果带出 analysis_window 元数据。支持 Unix epoch 时间戳（浪潮 BMC SEL 第二列即为 epoch 秒）。
   - 浪潮/华为等一键诊断包：先解压外层 .tar.gz，再重点解析 bmc/sel_elist.txt、bmc/restful/health_summary、bmc/restful/raid_controller_*、bmc/restful/asset_*、bmc/restful/version_summary，以及嵌套的 bmc/restful/bmcOnekeyLog-*.tar 内的 raid4.log（RAID 卡事件）、err.log/warning.log、sel.log、sysmonitor.log。
   - 华为 iBMC 的 SEL 常为 SQLite（sel.db），须先用脚本/Python 导出为文本或自行解析后再喂入本脚本。
3. 归类与诊断：对聚合出的每个故障类别，按 references/fault-taxonomy.md 完成：
   - 定级（紧急 / 重要 / 提示）
   - 根因分析（按概率排序，附证据与置信度）
   - 解决方法（分应急处理与彻底解决）
   - 风险提示
4. 事件码精确定义：用 WebSearch 查厂商官方事件码文档（如 Dell Event Message Reference、HPE IML、Lenovo XCC Events）；查不到时标注"待查证"，只用事件文本本身支持结论。
5. 将 JSON 结果传递给能力 3 / 4。

能力 2：操作系统硬件状态与日志分析

> 安全提示：采集脚本以 root 运行，仅在你授权的目标机、处于变更窗口内执行；脚本仅只读采集，不修改系统配置。

1. 采集：在目标 Linux 服务器上以 root 运行 scripts/collect_os_hw.sh，或按 references/os-hardware-diagnostics.md 的命令清单手工采集。采集脚本已内置硬件资产信息收集（dmidecode 机型/主板/BIOS/CPU/内存、ipmitool fru/mc、microcode、smartctl、nvme、RAID、网卡固件），这些信息用于报告附录 C。
2. 分析：运行 scripts/analyze_os_hw.py 处理采集文件，输出 JSON + Markdown 摘要。同样支持 --within-days / --ref-date 时间窗口（带时间戳的条目按窗口判定，无时间戳的当前快照默认纳入窗口内）。
3. 归类与诊断：同能力 1 第 3 步。OS 层异常须与带外事件互相印证（如 dmesg 的 I/O error 对应 SEL 的磁盘事件）。
4. 将 JSON 结果传递给能力 3 / 4。

能力 3：自动生成故障分析报告（DSH 四件套交付物）

> 交付物标准（经 5 台不同厂商设备实测确定）：最终产物必须是四件套——
> 报告名.docx + 报告名_附件_硬件清单与备件.xlsx + 报告名.md + 报告名.json，
> 版式对齐参照 assets/report-template.md（7 章结构、深蓝表头、严重级别配色）；演示样例报告
> 服务器软硬件故障分析报告_演示环境-Dell R740_20261021-120000.docx 不随本包发布，仅作版式说明。
> 不要只交 Markdown，也不要临时用 workbuddy-docx 把
> Markdown 转 Word（会丢失表格分页、加粗、命令块等版式，且无法承载结构化诊断内容）。

标准流程（推荐，可复现）：用技能自带的 assets/renderer/ 管线。

1. 写数据模块 data_xxx.js：按 assets/renderer/data_schema.md 契约，把分析结论、证据、
   根因排序、备件、硬件清单、时间线等填入（可复制 assets/renderer/example-data.js 改写）。
   - 该文件是唯一事实源；厂商叙事（关键结论、时间线）必须显式提供，渲染器不内置任何厂商故事。
2. 运行生成器：
   bash node assets/renderer/generate_report.mjs ./data_xxx.js <输出目录>
   流程：data_xxx.js → content.js（内容块，与渲染器无关）→ docx.js / markdown.js / xlsx.js
   三套渲染器 → 四件套。Word / Markdown / Excel 内容严格同源（同一份 blocks）。
3. 校验：用 zipfile 验证 docx/xlsx 的 testzip()、遍历各 part 能否被 XML 解析、确认 r:id
   引用与 pStyle 均已定义（详见 references/delivery-dsh-format.md 的"OOXML 合规"一节，
   三种常见导致 Word 报"文档损坏"的写法是实测踩过的坑）。
4. 报告结构（与 assets/report-template.md 一致）：1 执行摘要（含 1.1 关键结论 / 1.2 处理
   优先级 / 1.3 时间线）→ 2 故障描述（2.1 窗口内 / 2.2 超三个月历史 / 2.3 时间异常 / 2.4 排除项
   与正常项）→ 3 分析诊断（逐事件 + 全局证据 + 全局根因排序）→ 4 解决方法（应急 / 分事件 /
   要点 / 风险 / 验证 / 预防）→ 5 备件清单 → 6 硬件清单与版本 → 7 附录（文件 / 完整性 / 告警 /
   规则覆盖 / 待确认 / 操作风险 / 链路 / 查证说明）。
5. 时间窗口呈现：表头标注分析窗口（近 N 天 / 起点日期）；2.2 列出超窗口报错（仅记录+时间）；
   第 3/4 章仅覆盖窗口内。资产清单：第 6 章与 Excel"硬件清单"工作表记录全部硬件型号/PN/
   微码/BMC/BIOS 版本，缺失标「（空）」。待确认事项：7.6 列出所有未核实 PN / 事件码 /
   低置信度判断。

快速路径（仅要 Markdown 草稿）：scripts/generate_report.py 仍可生成 Markdown 初稿，
供内部流转；但最终交付仍以四件套为准。

严重级别术语：对外交付物统一渲染为 严重 / 重要 / 一般（对应内部 critical / major / minor，
warning 计为一般、info 仅记录）；与 fault-taxonomy.md 的 CRITICAL(紧急)/MAJOR(重要)/MINOR(提示)
为同一套定级，仅展示用词不同。

能力 4：备件 PN 码与数量查询

1. 运行 scripts/query_spare_parts.py，按故障类别（--category）、机型（--model）或故障描述（--fault）查询。
2. 数据来源：
   - assets/spare-parts/fault-part-mapping.csv：故障类别 → 备件类别、规格要求与数量逻辑（内置知识，可直接使用）
   - assets/spare-parts/parts-library.csv：PN 库（需按 references/spare-parts-guide.md 维护）
3. 库中无匹配 PN 时：输出备件类别、规格要求与查询指引（厂商 FRU 清单查询方法），明确标注"PN 待核实"，禁止编造 PN。
4. 维护：用户提供 PN 时用 --add 追加，默认 verified=no，核实后改为 yes。

能力 5：固件版本健康分析（BIOS / BMC 版本检核）

对已在能力 1/2 中采集到的 BIOS / BMC 当前版本，进一步到官网核实当前版本是否存在已知缺陷
（含安全漏洞），并确认官网当前最新版本，给出升级/保持建议与风险提示。本能力强调可溯源与不臆造。

1. 前置：已取得 parse_inventory.py 的 JSON（含 bios_version / bmc_version 与机型），
   或用户直接给出厂商/机型/版本。版本字段缺失时标「（空）」，不编造。
2. 生成骨架：运行 scripts/analyze_firmware_versions.py（详见 references/firmware-version-guide.md）：
   - 按厂商映射到官方支持/发布说明/安全公告入口，产出 firmware_analysis 骨架（当前版本 + 官方核实检索式 + 待核实字段）。
   - 输出 JSON（供报告 firmwareAnalysis[] 消费）与 Markdown 摘要。
3. 官网核实（agent 用 WebSearch 执行，本脚本不联网）：对每个组件（BIOS、BMC）分别核实
   - 当前版本是否有已知缺陷：以官方 Release Notes 的 Known Issues / Resolved Issues、安全公告、CVE 为准；当前版本低于某缺陷"修复于 X 版本"中的 X，即视为受影响。
   - 官网最新版本与发布日期：以厂商支持门户"驱动与下载"页为准。
   - 把结果回填骨架：latest_version / latest_release_date / known_issues / recommendation / confidence / source_urls / checked_at，每条必须附官方 URL。
4. 状态判定（写入 current_status）：无已知缺陷 / 存在已知缺陷 / 建议升级（明显过旧）/ 保持（已最新）/ 待核实（无法确认）。查不到则标"待核实"，不臆造最新版本。
5. 报告落位：写入报告 6.3 固件版本健康分析（BIOS / BMC）（docx/md 同章节、xlsx 新增"固件版本健康分析"工作表，内容同源）。升级类风险并入 7.7 操作风险，待核实项并入 7.6 待确认事项。
6. 诚实性与风险纪律：
   - 仅第三方/论坛结果时置信度降档并注明；必须官方来源方可给确定结论。
   - 固件升级属高风险操作（失败可致使设备无法启动、管理平面失联），须变更窗口、备份、确认供电冗余与版本兼容、在保优先走厂商渠道；详见 references/firmware-version-guide.md 第 5 节。
   - 版本比较须同厂商、同机型、同组件维度，跨机型版本号不可直接比较。

Resources

scripts/

• fault_rules.py：共享分类规则（类别、严重度、状态、时间窗口判定），被各脚本引用
• parse_oob_log.py：带外日志解析与故障分类（支持 --within-days / --ref-date）
• analyze_os_hw.py：OS 硬件状态/日志异常检测（支持 --within-days / --ref-date）
• parse_inventory.py：硬件资产与版本清单解析（型号/PN/微码/BMC/BIOS 版本 → 报告附录 C）
• query_spare_parts.py：备件 PN / 数量查询与维护
• analyze_firmware_versions.py：固件版本健康分析脚手架（能力 5，输出 BIOS/BMC 版本核实骨架 + 官方入口 + 检索式；最新版本/缺陷由 agent 经 WebSearch 回填）
• generate_report.py：生成故障分析报告 Markdown 初稿（含 1.4 历史记录与附录 C）
• collect_os_hw.sh：目标 Linux 服务器采集脚本（root 运行，含资产信息采集）

assets/renderer/（四件套交付管线，实测可用）

• generate_report.mjs：四件套生成器，node generate_report.mjs <data模块.mjs> <输出目录>
• data_schema.md：数据模块契约（必读，写分析报告前先看）
• example-data.js：可运行范例（DELL R740xd），复制改写即可
• content.js：内容块生成器（唯一事实源，厂商无关）
• docx.js / markdown.js / xlsx.js：三套渲染器（消费同一份 blocks，内容同源）
• zip.js / util.js：OOXML ZIP 打包与通用工具
• 依赖：Node.js ≥ 18（用到顶层 await 与 node:url）

references/

• oob-log-guide.md：各厂商带外日志导出方法、已实测的厂商日志包结构（DELL TSR / 中兴一键包 / HP AHS / 华为 iBMC / 浪潮 tar.gz）、格式识别、事件码查证
• os-hardware-diagnostics.md：OS 硬件信息采集命令与异常判读规则
• fault-taxonomy.md：故障分类体系（症状 → 定级 → 根因 → 处理 → 风险）
• firmware-version-guide.md：固件版本健康分析指南（各厂商官方核实入口、Release Notes/安全公告/CVE 检索方法、版本时效性判读、升级风险与诚实性纪律）
• spare-parts-guide.md：备件库结构与维护规范
• delivery-dsh-format.md：DSH 四件套交付规范 —— 报告结构、内容块架构、Excel 15 张表、OOXML 合规三坑（颜色 XML 二次嵌套 / <w:pPr> 子元素顺序 / <w:tcPr> 底纹位置）

assets/

• report-template.md：故障分析报告模板（7 章 DSH 结构）
• spare-parts/fault-part-mapping.csv：故障 → 备件类别/数量映射
• spare-parts/parts-library.csv：备件 PN 库（用户维护；当前为空，PN 普遍待核实）