mcpField
T
tailscale-subnet-router-debug

tailscale-subnet-router-debug

github.com/rshade云与 DevOps396 次安装2 周前更新
代码仓库

关于 tailscale-subnet-router-debug

tailscale-subnet-router-debug 是用于排查 Tailscale 子网路由器连接故障的技能，通过七项有序检查，追踪路由从通告、批准到转发和返回路径的完整过程。

主要功能

  1. 01七项有序连通性检查
  2. 02检查路由通告与批准
  3. 03检查客户端路由接受设置
  4. 04检查策略路由表 52
  5. 05验证转发与返回路径

适用场景

  1. 01排查客户端无法访问子网设备
  2. 02调查已批准路由未出现在路由表
  3. 03排查 Docker 子网路由通告
  4. 04查找响应流量未返回的原因

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rshade/agent-skills --skill tailscale-subnet-router-debug

安装后在 Claude Code 中输入/tailscale-subnet-router-debug确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
common-failures.md
policy-routing.md
route-lifecycle.md

详细介绍

Tailscale 子网路由器故障排查

诊断并修复 Tailscale 子网路由器连接故障。依次运行七项检查，覆盖从路由通告到返回路径验证的完整路由生命周期。

此技能的功能

  1. 验证子网路由器是否通告了该路由。
  2. 确认路由已获批准（通过管理控制台或 autoApprovers）。
  3. 检查客户端是否接受子网路由（--accept-routes）。
  4. 检查策略路由表 52 中是否已安装路由。
  5. 验证子网路由器是否已启用 IP 转发。
  6. 测试子网路由器能否直接访问目标。
  7. 验证响应流量的返回路径。

常见触发情况

  • 客户端可以 ping 通子网路由器，但无法访问通告子网上的设备
  • 管理控制台显示路由已获批准，但 ip route 输出为空
  • Docker 容器无法通过 TS_ROUTES 通告路由
  • 流量可以到达目标，但响应始终无法返回
  • “从路由器本身访问正常，但其他客户端不行”

诊断工作流

按顺序运行每一步。遇到首个失败时，先应用修复再继续——后续步骤依赖前面的步骤。

第 1 步 — 验证路由是否已通告
tailscale status --json | jq '.Self.AllowedIPs'

通过： AllowedIPs 中显示子网 CIDR（例如 10.100.0.0/24）。

失败： 仅显示 Tailscale IP。路由未通告。

修复： tailscale set --advertise-routes=<CIDR>。在 Docker 中，检查 TS_ROUTES 环境变量——如果首次启动时身份验证失败，它可能不会生效。 此时可在运行时改用 tailscale set。

第 2 步 — 验证路由是否已获批准

检查管理控制台，或在对等节点上运行：

tailscale status --json | jq '.Peer[] | select(.HostName=="<router>") | .AllowedIPs'

通过： 对等节点所见的路由器 AllowedIPs 中显示子网 CIDR。

失败： 从对等节点的视角仅显示 Tailscale IP。路由正等待批准。

修复： 在管理控制台中批准，或将 autoApprovers 添加到 ACL：

"autoApprovers": {
  "routes": { "10.100.0.0/24": ["tag:subnet"] }
}
第 3 步 — 验证客户端是否接受路由
tailscale debug prefs | grep -i route

失败： --accept-routes 为 false（默认值）。即使子网路由已获批准，客户端也会忽略通告的子网路由。

修复： tailscale set --accept-routes=true。在 Docker 中，将 --accept-routes 添加到 TS_EXTRA_ARGS。不要在 Docker 中使用 tailscale down——这会终止 containerboot。请改用 tailscale set。

第 4 步 — 验证策略路由表中的路由
ip route show table 52

通过： 显示指向子网 CIDR、经由 dev tailscale0 的路由。

失败： 表 52 为空，或缺少子网路由。

重要： ip route（不带表参数）只显示主路由表。Tailscale 使用策略路由表 52——路由不会出现在默认输出中。这是最常见的误报。

另请检查：

ip rule show

有关表 52 和 Tailscale 策略路由工作方式的详情，请参阅 references/policy-routing.md。

第 5 步 — 验证子网路由器上的 IP 转发
cat /proc/sys/net/ipv4/ip_forward

通过： 返回 1。

失败： 返回 0。内核会静默丢弃转发的数据包。

修复： sysctl -w net.ipv4.ip_forward=1。在 Docker Compose 中，设置 sysctls: [net.ipv4.ip_forward=1]。如需在 Linux 主机上持久生效， 请将其添加到 /etc/sysctl.d/。

第 6 步 — 验证从子网路由器到目标的网络路径

在子网路由器上运行：

ping <target-ip>
ip addr show

通过： 路由器可以访问目标，并且在通告的子网上有一个接口。

失败： 路由器无法访问目标。这是本地网络问题（防火墙、VLAN、路由）， 不是 Tailscale 问题。

第 7 步 — 验证返回路径

目标必须将响应路由回子网路由器。如果目标的默认网关不是子网路由器，返回流量会走不同的路径并被丢弃。

修复： 在目标（或其网关）上添加一条静态路由，将 100.64.0.0/10 指向子网路由器的内部 IP。或者启用伪装：

iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE

Tailscale 1.64+ 默认启用 --snat-subnet-routes，会自动处理此问题。

错误处理

不要默默跳过检查失败。报告具体的失败及修复方法，然后再继续。如果修复需要重启 Tailscale 或重新创建容器，请指导用户执行这些操作，并从第 1 步重新开始。

参考资料

  • references/route-lifecycle.md — 路由从通告到返回路径的完整 7 阶段生命周期
  • references/policy-routing.md — 表 52、ip rule、VRF 类比，以及 ip route 为什么无法显示 Tailscale 路由
  • references/common-failures.md — 按症状查找的表格，包含根本原因和修复方法

评论

支持 Markdown