dns-setup

name	dns-setup
description	广域发现 DNS 配置：设置 DNS 记录以支持跨网络的节点自动发现。当需要配置远程节点发现、设置 DNS SRV 记录或排查节点发现问题时使用此技能。
tools	gateway
metadata	{"category":"operations","emoji":"🌐","tree_id":"system/gateway","tree_group":"system","min_tier":"task_write","intent_priority":20,"intent_keywords":{"zh":["DNS配置","节点发现","广域网","DNS记录","SRV记录","TXT记录","节点自动发现","DNS设置","远程节点"],"en":["dns setup","node discovery","dns records","srv record","txt record","wide area discovery"]},"scene_hint":"配置广域DNS发现用此→节点列表查看用nodes工具→网络问题排查用doctor-diagnostics"}

DNS 广域发现技能

适用场景

用户需要配置 DNS 以支持跨网络的 Crab Claw 节点自动发现时触发。

选择原则

场景	工具/技能
配置广域 DNS 发现	本技能
本地网络发现 (mDNS/Bonjour)	自动工作，无需配置
节点管理	→ nodes 工具技能
系统配置	→ system-config

一、概述

Crab Claw 支持两种节点发现方式：

方式	范围	配置需求
mDNS/Bonjour	局域网	零配置，自动发现
DNS SRV/TXT	广域网	需要 DNS 记录配置

当节点分布在不同网络（如家庭 + 办公室 + 云服务器）时，需要 DNS 广域发现。

二、配置 DNS 发现

crabclaw dns setup [--apply]

参数：

• --apply: 实际应用配置（不加则为 dry-run 预览模式）

交互式向导，引导用户：

1. 选择 DNS 提供商（Cloudflare/Route53/手动）
2. 配置域名
3. 创建必要的 DNS 记录
4. 验证记录生效

三、DNS 记录要求

3.1 SRV 记录

<instance>._crabclaw-gw._tcp IN SRV 0 0 <port> <host>

示例：

mynode._crabclaw-gw._tcp IN SRV 0 0 19001 gateway.example.com

同时需要一条 PTR 记录：

_crabclaw-gw._tcp IN PTR mynode._crabclaw-gw._tcp

3.2 TXT 记录

<instance>._crabclaw-gw._tcp IN TXT "displayName=<name>" "role=gateway" "transport=gateway" "gatewayPort=<port>"

TXT 记录携带节点元数据：

• displayName: 节点显示名称
• role: 节点角色（gateway）
• transport: 传输类型（gateway）
• gatewayPort: Gateway 端口号

四、配置文件

DNS 发现配置存储在系统配置的 discovery.dns 字段中：

{
  "discovery": {
    "dns": {
      "enabled": true,
      "domain": "example.com",
      "provider": "cloudflare",
      "zoneId": "..."
    }
  }
}

可通过 system-config 技能中的 config.patch 修改。

五、验证与排查

5.1 验证 DNS 记录

dig SRV _crabclaw._tcp.example.com

5.2 测试节点发现

crabclaw status --deep

在 Discovery 部分查看是否通过 DNS 发现了远程节点。

5.3 常见问题

问题	原因	解决
未发现远程节点	DNS 记录未生效	等待 TTL 过期或手动刷新
连接被拒	防火墙阻止端口	开放 Gateway 端口
认证失败	Token 不匹配	检查 discovery token 配置

六、CLI 命令对照

CLI 命令	说明
crabclaw dns setup	DNS 发现配置（dry-run 预览）
crabclaw dns setup --apply	DNS 发现配置（实际应用）