跳到主要内容

routerctl doctor — 运行时健康诊断

routerctl doctor 执行一组只读检查，回报当前 routerd 是否作为家庭网关正常工作。 不会变更主机状态。面向运维人员、CI、监控代理与下游工具（Prometheus exporter、 Web Console、LLM 辅助诊断等）。

使用方式​

# 全部 area（默认）
routerctl doctor

# 单一 area
routerctl doctor dns

# 不执行主机命令（仅基于资源 status）
routerctl doctor --no-host

# 机器可读输出
routerctl doctor -o json
routerctl doctor -o yaml

选项与 diagnose 一致: --config, --state-file, --no-host / --host, -o / --output, --timeout。

Areas​

Area检查内容
wanEgressRoutePolicy 与 HealthCheck 的资源 status；IPv4 / IPv6 默认路由（ip -4/-6 route show default）。
dnsDNSResolver 的资源 status；通过 dig @127.0.0.1 进行 A 记录探测。
dsliteDSLiteTunnel 的资源 status；AFTR FQDN 的 AAAA 探测；tunnel device 存在性（ip link show）。
dhcpv6-pdDHCPv6PrefixDelegation 的 status（Bound、委派前缀）。PD 未取得时按设计为 WARN（不在 LAN 上广告损坏的 IPv6）。
natNAT44Rule 的资源 status；nft list table ip routerd_nat 存在。
firewallFirewallZone / FirewallPolicy 的 status；nft list table inet routerd_filter 存在且 input 链 policy drop（否则视为 permissive）。
rollback至少存在一个已保存世代，使 routerctl rollback --to 可用。
disk/var/lib/routerd 与 /run/routerd 的容量。≥90% 或 <256 MiB 时 WARN，≥98% 或 <64 MiB 时 FAIL。
mgmt管理接口的存在性（从 ManagementAccess 或 FirewallZone role=mgmt 推断）；WebConsole 的 bind（0.0.0.0 / :: 为 WARN/FAIL）。

每个检查返回 pass、warn、fail、skip（资源或信号不存在）之一。

JSON 输出契约​

routerctl doctor -o json 是稳定的机器可读接口。形式：

{
  "summary": {
    "overall": "pass",      // "pass" | "warn" | "fail" | "skip"
    "pass": 7,
    "warn": 1,
    "fail": 0,
    "skip": 2
  },
  "checks": [
    {
      "area":   "dns",                          // 见上方 Areas 表
      "name":   "DNSResolver/lan-resolver",     // 人类可读对象名
      "status": "warn",                         // "pass" | "warn" | "fail" | "skip"
      "detail": "phase=Degraded,waiting=...",   // 可选
      "remedy": "wait for or repair dependency wan-pd" // 可选
    }
    // ...
  ]
}

保证：

  • summary.overall 取 checks[].status 的最差值（fail > warn > unknown/skip > pass）。
  • summary.pass/warn/fail/skip 为整数计数，其和等于 len(checks)。
  • checks[].status 仅取 pass、warn、fail、skip（不会出现其他值）。
  • checks[].area 取自 Areas 表中的稳定标识符集合。
  • checks[].name 为人类可读，请勿对其精确形式做模式匹配。
  • detail / remedy 为可选自由文本，面向运维人员。

退出码​

  • 0 — 没有 fail 检查（pass、warn、skip 均不视为失败）。
  • 非 0 — 至少一个 fail。可写为 routerctl doctor || alert。

warn 不会让退出码变为非 0（例如开机后 DHCPv6-PD 尚未 Bound 这类信息性情况）。 若要更严的门禁，请明确选择 area（如 routerctl doctor wan 仅在 wan fail 时非 0）。

稳定性​

JSON 形式、area 标识符与 status 枚举是 v1alpha1 的运维契约。后续版本可能新增 area 或可选字段， 但已有的 area 名称与 status 取值在 v1alpha1 的 minor 版本之间不会改名或改义。

参见​