04 ops-diagnose 主项目设计

项目定位

ops-diagnose 是一个面向私有云和基础组件排障的自助诊断工具。

第一版不要做大平台，只做小而完整的 CLI：

能检查常见基础组件。
能输出 Markdown / JSON 报告。
能沉淀配套 runbook。
后续能暴露 Prometheus 指标。
最终能接入 AI Runbook 知识库。

目录结构

ops-diagnose/
  README.md
  pyproject.toml
  ops_diagnose/
    cli.py
    checks/
      dns.py
      yum.py
      ntp.py
      syslog.py
      disk.py
      network.py
    report.py
  docs/
    runbooks/
      runbook-yum-repo-unavailable.md
      runbook-dns-resolution-failure.md
      runbook-chrony-time-offset.md
      runbook-rsyslog-not-forwarding.md
  examples/
    report-demo.md

CLI 命令

ops-diagnose check yum --url http://repo.example.com/os/
ops-diagnose check dns --domain repo.example.com
ops-diagnose check ntp
ops-diagnose check syslog
ops-diagnose check disk --threshold 85
ops-diagnose check network --host repo.example.com --port 80
ops-diagnose check all --format markdown
ops-diagnose check all --format json

检查结果结构

每个检查输出统一结构：

{
  "name": "yum",
  "status": "critical",
  "summary": "repo URL returned 404",
  "evidence": [
    "curl -I http://repo.example.com/os/ -> 404"
  ],
  "possible_causes": [
    "baseurl 配置错误",
    "源站目录不存在",
    "代理或网关改写路径"
  ],
  "next_steps": [
    "检查 /etc/yum.repos.d/*.repo",
    "确认源站目录和发行版版本是否匹配"
  ],
  "runbook": "docs/runbooks/runbook-yum-repo-unavailable.md"
}

第一阶段检查项

检查项	目标	输出
yum	repo 是否可访问，HTTP 状态码是否正常	状态码、DNS、baseurl 建议
dns	域名是否可解析	解析结果、nameserver、失败原因
ntp	chronyd/ntpd 是否正常，时间偏差是否过大	服务状态、offset、上游源
syslog	rsyslog 是否运行，端口和配置是否正常	服务状态、配置语法、端口
disk	磁盘使用率和 inode 是否异常	使用率、阈值、最大目录提示
network	目标主机和端口是否可达	延迟、端口状态、下一步命令

Prometheus 指标

第 5 周加入：

ops_dns_check_success
ops_yum_repo_up
ops_ntp_service_up
ops_ntp_offset_seconds
ops_syslog_service_up
ops_disk_usage_percent
ops_diagnose_last_success

简历表达

基于 Python 开发基础组件自助诊断 CLI，覆盖 DNS、yum repo、NTP、syslog、磁盘、网络连通性等场景，支持 Markdown/JSON 报告输出，并沉淀配套 runbook，降低重复答疑和人工排查成本。

加入监控后：

使用 Prometheus client_python 暴露诊断指标，并结合 blackbox exporter 构建 HTTP、DNS、TCP 可用性监控和告警规则。

加入 AI 知识库后：

将 runbook 和故障复盘接入 Dify/RAGFlow，构建 AI 运维知识库，支持基于引用来源的排障建议生成，并对高风险修复动作增加人工确认提示。

03 第一周马上开始 05 Runbook 与复盘模板