time-sync-diagnosis

name	time-sync-diagnosis
description	面向 Linux 时间同步故障的结构化诊断技能。适用于时间漂移、同步失败、ntpq 查询异常、UDP 123 连通性异常、计时源不稳定、False Ticker、Panic 阈值触发等场景；当用户提到时间不同步、时钟漂移、NTP/chronyd 故障、时钟源或 Stratum 异常时应触发。

Time Sync Diagnosis

目标

在最短路径内给出可复现、可验证的时间同步故障结论，并输出清晰的时间链与根因链。

总流程（四阶段）

1. 第一阶段：全量信息收集与指纹归类
2. 第二阶段：按场景深度下钻
3. 第三阶段：反思与交叉验证
4. 第四阶段：输出根因分析结论

---

第一阶段：全量信息收集与指纹归类

执行

运行：

bash ./scripts/time_master_diag.sh

目标

• 一次性抓取服务状态、端口占用、配置、网络可达性、内核计时源、协议日志
• 生成“故障指纹”，并映射到单一主场景（A/B/C/D/E）

指纹到场景映射

识别指纹（Step 1 关键输出）	归属场景	诊断方法论
多个时间服务同时 active；UDP 123 被非目标服务占用；启动失败且配置可疑	A 控制平面	服务唯一性原则（同类守护进程冲突优先）
进程存在但 ntpq refused；本地查询失败；ACL 可疑	B 管理通道	监听边界 + 访问控制审计（重点 loopback）
域名解析失败；TIMEOUT；reach=0；上游不可达	C 链路通断	端到端剥离（DNS -> 网络 -> 对端）
steal time 高；hpet/低性能时钟源；时钟中断抖动	D 内核与交付	计时源稳定性与调度干预分析
False Ticker；Panic/Step 触发；可连但不被信任	E 协议逻辑与安全	一致性与置信度校验

第一阶段产出要求

• 主场景（A/B/C/D/E）+ 备选场景（最多 2 个）
• 触发该判断的证据清单（命令输出片段 + 指标）
• 下一阶段要执行的下钻脚本

---

第二阶段：按场景深度下钻

原则：先验证“是否成立”，再解释“为什么成立”，最后界定“影响范围”。

场景 A：控制平面

• 脚本：bash ./scripts/drill_down_control.sh
• 方法论：依赖 -> 冲突 -> 配置
  • 依赖：网卡、服务单元、权限、文件可读
  • 冲突：chronyd/ntpd/timesyncd 是否并存并抢占 UDP 123
  • 配置：Try-run、语法与权限错误定位
• 判定标准：
  • 存在双服务并发或端口冲突即可判为高置信问题

场景 B：管理通道

• 脚本：bash ./scripts/drill_down_mgmt.sh
• 方法论：监听边界 -> ACL -> 工具路径
  • 服务是否绑定 127.0.0.1 / ::1
  • restrict/allow 是否允许本地查询
  • 区分“能同步时间”与“无权查询状态”
• 判定标准：
  • 同步正常但管理查询被策略拒绝，属于管理面故障而非同步面故障

场景 C：链路通断

• 脚本：bash ./scripts/drill_down_network.sh
• 方法论：DNS -> UDP123 -> 上游
  • 先排除解析问题
  • 使用 nc/探测手段验证 UDP 123
  • 网络通但 reach=0 时检查上游 stratum 与可用性
• 判定标准：
  • 本机协议栈正常但链路/上游异常，归因网络或外部源

场景 D：内核与交付

• 脚本：bash ./scripts/drill_down_kernel.sh
• 方法论：clocksource -> steal -> 调度影响
  • 审计当前 clocksource（如 TSC/HPET）
  • 关注云环境 steal time
  • 判断抖动来自系统算法还是底层调度
• 判定标准：
  • 计时源不稳或 steal 异常导致授时不收敛

场景 E：协议逻辑与安全

• 脚本：bash ./scripts/drill_down_protocol.sh
• 方法论：一致性比对 -> 离散度分析 -> 阈值保护
  • 多源 offset 对比识别 False Ticker
  • 分析 jitter/offset 离散度
  • 检查 Panic/Step 阈值触发条件
• 判定标准：
  • 连通正常但置信机制拒绝选源，归因协议层自保护

第二阶段产出要求

• 每个已验证假设的状态：成立 / 不成立 / 待证实
• 每条假设至少一个“支持证据”与“反证证据”
• 更新主场景置信度（高/中/低）

---

第三阶段：反思与交叉验证

目标：防止“单证据误判”，确保结论经得起反事实挑战。

3.1 反思方法论

• 区分“症状、机制、根因”三层，不将症状直接定为根因。
• 优先质疑当前主假设，主动寻找最强反证，避免单路径确认偏误。
• 当证据不足时保留不确定性，用“待补证据”替代过度结论。

3.2 交叉验证方法论

• 至少从服务、网络、时间三个维度做一致性校验。
• 同一结论需由独立证据源支持（命令输出、日志、监控/指标）。
• 若结论依赖单一证据，应显式降级置信度并补充验证建议。

---

第四阶段：输出根因分析结论

按以下模板输出最终结论，缺失项要显式标注“待补证据”。

## 时间同步故障根因分析结论

### 1) 基本信息
- 故障时间：<YYYY-MM-DD HH:MM:SS 时区>
- 发现时间：<...>
- 影响范围：<主机/集群/业务>
- 影响表现：<时钟漂移/同步失败/查询失败/...>

### 2) 故障事件时间链（Time Chain，按故障演进而非诊断步骤）
- T0 <时间>：<变更/触发事件，如升级、配置发布、网络策略变更>
- T1 <时间>：<首次异常出现，如 offset 突增、同步中断、告警触发>
- T2 <时间>：<故障扩大或稳定化表现，如 reach 持续为 0、业务受影响>
- T3 <时间>：<关键转折事件，如切源失败、服务重启无效、冲突加剧>
- T4 <时间>：<处置动作与恢复信号，如冲突解除后指标回归>

### 3) 故障根因链（Causal Chain）
- 直接原因：<例如 UDP 123 被 timesyncd 占用，chronyd 无法有效工作>
- 中间机制：<例如 进程冲突 -> 选源失败 -> reach 持续为 0>
- 深层原因：<例如 变更未执行服务唯一性校验>
- 触发条件：<例如 升级后默认启用 timesyncd>

### 4) 证据清单（支持 / 反证）
- 支持证据：
  - <命令/日志/指标 1>
  - <命令/日志/指标 2>
- 反证与排除：
  - <被排除候选根因 1 + 理由>

### 5) 结论置信度
- 置信等级：<高/中/低>
- 置信依据：<跨服务/网络/时间三维一致性说明>

### 6) 修复与预防
- 即时修复：<已执行动作>
- 长期治理：<配置基线、巡检项、监控项、变更门禁>
- 验证结果：<恢复指标与观察窗口>

---