tailscale-docker-debug

Tailscale Docker 调试

诊断并修复 Docker 容器内的 Tailscale 连接和 DNS 问题。依次运行 6 项检查，覆盖从容器运行模式到 MagicDNS 解析的完整调试链路。

此技能的作用

1. 检测容器运行于内核模式还是用户空间模式。
2. 验证 TUN 接口存在且具有 Tailscale IP。
3. 检查 DNS 解析器链，查找查询路由错误。
4. 确认 100.100.100.100 通过容器的 Tailscale 路由。
5. 检测主机与容器之间的多 tailnet 冲突。
6. 通过名称解析测试端到端验证 MagicDNS。

常见触发情形

• 客户报告 Docker/Podman 容器内“DNS 无法正常工作”
• 主机位于一个 tailnet，容器位于另一个 tailnet
• Compose 文件包含 NET_ADMIN 和 /dev/net/tun，但 Tailscale 仍以用户空间模式运行
• 从 docker run 迁移到 docker compose 后 TUN 无法正常工作

诊断工作流

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

步骤 1 — 检测容器运行模式

docker logs <container> 2>&1 | grep -iE "tun|userspace|netstack"

**通过：**日志显示 tun "tailscale0"——内核模式。继续步骤 2。

**失败：**日志显示 --tun=userspace-networking。无论功能权限如何，官方 tailscale/tailscale 镜像都默认通过 containerboot 使用用户空间模式。

**修复：**在环境变量中设置 TS_USERSPACE=false。为 /dev/net/tun 使用 devices:（而非 volumes:）。添加 cap_add: [NET_ADMIN, SYS_MODULE]。完整配置请参阅 references/compose-configuration-matrix.md。

步骤 2 — 验证 TUN 接口是否存在

docker exec <container> ip addr show tailscale0

**通过：**接口显示 100.x.y.z/32 地址。继续步骤 3。

**失败：**即使设置了 TS_USERSPACE=false，仍不存在 tailscale0 接口。

**修复：**在 compose 中将 /dev/net/tun 从 volumes: 改为 devices:。确认容器内存在主次设备号为 10, 200 的设备。确认已设置 cap_add: [NET_ADMIN, SYS_MODULE]。

步骤 3 — 检查 DNS 解析器链

docker exec <container> cat /etc/resolv.conf

检查以下三项：

• nameserver——预期为 127.0.0.11（Docker 内嵌 DNS）
• 外部服务器——应转发到 100.100.100.100
• search——应与容器的 tailnet 匹配，而非主机的 tailnet

失败指标：

• ExtServers: [host(127.0.0.53)]——Docker 将请求转发到主机的 systemd-resolved，而非 Tailscale
• 搜索域名属于另一个 tailnet

**修复：**在 compose 中为每个服务添加 dns: [100.100.100.100]。完整解析路径请参阅 references/dns-resolver-chain.md。

步骤 4 — 验证 100.100.100.100 的路由

docker exec <container> ip route get 100.100.100.100

**通过：**路由经由 tailscale0 或本地接口。

**失败：**路由经由 eth0 或 Docker 网关（例如 via 172.18.0.1）——DNS 查询会泄漏到主机。

docker exec <container> ss -ulnp | grep 100.100

**修复：**这是步骤 1（用户空间模式）或步骤 2（缺少 TUN）的症状。先修复这两项。

步骤 5 — 检测多 tailnet 冲突

docker exec <container> tailscale status | head -1
docker exec <container> grep search /etc/resolv.conf

将 tailscale status 中显示的 tailnet 与 resolv.conf 中的搜索域名进行比较。

**失败：**搜索域名（从主机继承）与容器的 tailnet 不匹配。例如：主机位于 tucuxi-lungfish.ts.net，容器位于 tail9a660c.ts.net。

**修复：**在 compose 中添加 dns_search: [<correct-tailnet>.ts.net]，或仅使用 FQDN。根本原因是 Docker 继承了主机 resolv.conf 中的搜索域名。

步骤 6 — 端到端验证 MagicDNS

docker exec <container> tailscale dns status | head -3

**通过：**显示 Tailscale DNS: enabled。

**失败：**显示 Tailscale DNS: disabled。

**修复：**在环境变量中设置 TS_ACCEPT_DNS=true。

最终验证：

docker exec <container> nslookup <peer>.<tailnet>.ts.net 100.100.100.100
docker exec <container> ping -c 1 <peer>.<tailnet>.ts.net

如果两项都成功，MagicDNS 就能在容器内正常工作。

错误处理

不要默默跳过检查失败。继续操作前，报告具体故障及修复方法。如果修复需要重启容器，请告知用户重新创建容器（docker compose up -d），并从步骤 1 重新运行工作流。

日志消息 getting OS base config is not supported 不会导致致命错误 ——Tailscale 无法直接读取容器的 DNS 配置。请改为通过 compose 文件修复 DNS。

参考资料

• references/compose-configuration-matrix.md — 使用 MagicDNS 的内核模式 Tailscale 所需的最低 compose 配置，逐项说明各项设置
• references/dns-resolver-chain.md — 通过 Docker 内置 DNS 的完整 DNS 解析路径，以及短名称与 FQDN 的冲突
• references/common-failures.md — 按症状分类的查找表，包含根本原因及修复方法