跳到主要内容

故障排查

从 routerctl get status 和 dry-run intent 到 OS state、daemon socket、event、DHCP/DNS/conntrack check 的 routerd troubleshooting order

排查 routerd 问题时，请先区分 routerd 的意图 与 主机的实际状态。 确认 routerd 意图达成什么之后，再与 OS 的实际状态进行比对。

服务或状态命令失败时​

在 Ubuntu 上先检查服务，不要反复尝试 live apply：

sudo systemctl status routerd.service --no-pager
sudo journalctl -u routerd.service -n 50 --no-pager
sudo routerd validate --config /usr/local/etc/routerd/router.yaml
  • 缺少配置或验证失败：返回第一台实验路由器，启动前先修正文件。
  • socket 不存在或连接被拒绝：routerctl 需要运行中的 daemon。routerd apply --once 会退出，不会留下控制 socket。
  • 权限不足：先用 sudo routerctl get status。免 sudo 只读访问需要管理员把用户加入 routerd 组，并重新登录。
  • 服务 active 但客户端无法访问：按客户端检查依次检查 WAN 租约、LAN 地址和网关、DNS。

不要在现有服务旁另开 routerd serve 或 live one-shot apply。排查网络变更失败时保持控制台可用。

基本排查顺序​

  1. sudo routerctl get status — 总览全局
  2. sudo routerctl describe <kind>/<name> — 深入查看目标资源
  3. sudo routerctl plan — 确认下次应用将会发生什么变更
  4. OS 命令（ip、nft、ss、journalctl）— 确认实际状态
  5. 对应守护进程的 /v1/status 与事件日志

DHCPv6-PD​

curl --unix-socket /run/routerd/dhcpv6-client/wan-pd.sock http://unix/v1/status
tail -n 20 /var/lib/routerd/dhcpv6-client/wan-pd/events.jsonl

确认以下项目：

  • phase 是否为 Bound；未过期的租约在 Renew/Rebind 交换期间对外仍保持 Bound
  • observed.leaseState 是否显示详细交换状态（renewing 或 rebinding），且租约仍可用时 LeaseReady condition 是否为 true
  • currentPrefix 是否已填入
  • renewAt 是否为未来时刻
  • 事件日志中是否记录了 Reply 或 Renew

若非 Bound 状态，或 LeaseReady 变为 false，LAN 侧的 IPv6 RA、AAAA 记录和 DHCPv6 应停止 运作。routerd 的安全约定是在更新期间维持尚未过期的前缀，但在该前缀不再可用后停止下发。

DHCPv4​

curl --unix-socket /run/routerd/dhcpv4-client/wan.sock http://unix/v1/status

确认 DHCPv4Client 是否处于 Bound 状态。 若需要立即更新，可通过 POST /v1/commands/renew 发出请求。

dnsmasq​

当前的 routerd 中，dnsmasq 专责 DHCPv4、DHCPv6、DHCP 中继及 Router Advertisement。 DNS 响应与转发由 routerd-dns-resolver 负责。

请确认生成的 dnsmasq 配置是否符合以下条件：

  • 包含预期的 dhcp-range
  • 配置为 port=0（禁用 DNS 功能；DNS 是 routerd-dns-resolver 的职责）
  • 包含 dhcp-script=/usr/local/libexec/routerd/dhcp-event-relay（将租约变更通知 routerd 的路径）
  • 按需加入 enable-ra

DNS resolver​

sudo curl --unix-socket /run/routerd/dns-resolver/<resource>.sock http://unix/v1/healthz
dig @<lan-ip> router.lan.example.org A
dig @<lan-ip> example.com A

依次确认以下项目：

  • 监听地址与端口是否符合预期（ss -lnup）
  • 本地权威区域是否正常响应（DNSZone 的手动记录与 DHCP 生成的记录）
  • 条件式转发是否送达指定的上游（dig @<lan-ip> <forwarded-domain>）
  • 默认上游是以 DoH / DoT / TCP / 明文 UDP 哪种方式响应（查看解析器 status 及上游 health）

DS-Lite​

ip -6 tunnel show
ip route show default
nft list table ip routerd_nat

若 AFTR 的 FQDN 无法解析，请确认 DNSResolver 的 forward source 配置。 特定接入网络的 AFTR 记录，通常无法通过公开 DNS 解析。

conntrack​

依环境不同，/proc/net/nf_conntrack 可能不存在。 此时 routerd 会退回使用 sysctl 来源的汇总统计。 即使详细流量清单为空，也不一定代表 NAT 已损坏。请查看 routerctl get connections 的摘要。

排查时应避免的事项​

  • 请勿在生产环境的 WAN 上，同时运行旧有的 DHCP 客户端或手动测试用守护进程与 routerd 并行。从同一接口同时发出多个 DHCPv6-PD 客户端，可能会破坏上游的租约状态。
  • 更换路由时，请勿 flush nf_conntrack。routerd 刻意不进行 flush，强制 flush 会中断已建立的连接会话。
  • 请勿在同一主机上编辑 /usr/local/etc/routerd/router.yaml 的同时，在其他位置放置临时的 YAML 覆盖文件。每台主机保持单一配置文件，可维持调和（reconcile）的可预测性。

相关参考​