自动化故障排除

使用此页面解决调度器和传递问题（cron + heartbeat）。

命令阶梯

bash
mayros status
mayros gateway status
mayros logs --follow
mayros doctor
mayros channels status --probe

然后运行自动化检查：

bash
mayros cron status
mayros cron list
mayros system heartbeat last

Cron 未触发

bash
mayros cron status
mayros cron list
mayros cron runs --id <jobId> --limit 20
mayros logs --follow

良好的输出如下所示：

  • cron status 报告已启用和将来的 nextWakeAtMs。
  • 作业已启用并具有有效的计划/时区。
  • cron runs 显示 ok 或明确的跳过原因。

常见特征：

  • cron: scheduler disabled; jobs will not run automatically → cron 在配置/env 中禁用。
  • cron: timer tick failed → 调度器 tick 崩溃；检查周围的堆栈/日志上下文。
  • 运行输出中的 reason: not-due → 在没有 --force 的情况下调用手动运行，作业尚未到期。

Cron 触发但没有传递

bash
mayros cron runs --id <jobId> --limit 20
mayros cron list
mayros channels status --probe
mayros logs --follow

良好的输出如下所示：

  • 运行状态为 ok。
  • 为隔离作业设置传递模式/目标。
  • 渠道探测报告目标渠道已连接。

常见特征：

  • 运行成功但传递模式为 none → 不期望外部消息。
  • 传递目标缺失/无效（channel/to）→ 运行可能在内部成功但跳过出站。
  • 渠道身份验证错误（unauthorized、missing_scope、Forbidden）→ 渠道凭据/权限阻止传递。

Heartbeat 被抑制或跳过

bash
mayros system heartbeat last
mayros logs --follow
mayros config get agents.defaults.heartbeat
mayros channels status --probe

良好的输出如下所示：

  • Heartbeat 已启用，间隔非零。
  • 最后一次 heartbeat 结果是 ran（或跳过原因已理解）。

常见特征：

  • 带有 reason=quiet-hours 的 heartbeat skipped → 在 activeHours 之外。
  • requests-in-flight → 主通道繁忙；heartbeat 延迟。
  • empty-heartbeat-file → 跳过间隔 heartbeat，因为 HEARTBEAT.md 没有可操作的内容并且没有排队的标记 cron 事件。
  • alerts-disabled → 可见性设置抑制出站 heartbeat 消息。

时区和 activeHours 陷阱

bash
mayros config get agents.defaults.heartbeat.activeHours
mayros config get agents.defaults.heartbeat.activeHours.timezone
mayros config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
mayros cron list
mayros logs --follow

快速规则：

  • Config path not found: agents.defaults.userTimezone 表示该键未设置；heartbeat 回退到主机时区（或如果设置则为 activeHours.timezone）。
  • 没有 --tz 的 Cron 使用网关主机时区。
  • Heartbeat activeHours 使用配置的时区解析（user、local 或显式 IANA tz）。
  • 没有时区的 ISO 时间戳对于 cron at 计划被视为 UTC。

常见特征：

  • 主机时区更改后，作业在错误的挂钟时间运行。
  • Heartbeat 总是在您的白天被跳过，因为 activeHours.timezone 错误。

相关：