中国域名 DNS 配置¶

问题背景¶

当系统使用的 DNS 服务器无法正确解析中国域名时，本项目的部分服务会连接失败：

服务	域名	影响范围
DeepSeek API	api.deepseek.com	Hermes / OpenClaw 默认模型
智谱 GLM API	open.bigmodel.cn	Hermes 各 profile 备用模型（zai / glm-5.3-flash）
钉钉 Stream	api.dingtalk.com, wss-open-connection.dingtalk.com	Hermes / OpenClaw 钉钉机器人
飞书 WebSocket	open.feishu.cn, msg-frontier.feishu.cn	Hermes 飞书机器人
Moonshot API	api.moonshot.cn	OpenClaw 备用模型
小米 MiMo API	api.xiaomimimo.com	虾酱 TTS 语音回复（各 agent 主模型已切 `deepseek-flash`）
QQ 邮箱	imap.qq.com, smtp.qq.com	himalaya 邮件客户端
WorkBuddy	workbuddy.cn	外部服务依赖
GitCode	gitcode.com	代码托管

典型表现：日志中出现 ENOTFOUND、NameResolutionError、getaddrinfo failed 等错误。

解决方案¶

macOS 支持 /etc/resolver/ 机制，可以按域名指定 DNS 服务器。脚本会自动探测一个可用的国内 DNS：优先沿用现有 /etc/resolver/ 配置，其次 223.5.5.5 → 119.29.29.29 → 180.76.76.76，最后回退到本机默认网关（路由器 DNS）。全部不可用时报错退出，绝不把不可用的 DNS 写进 /etc/resolver/。Docker 容器通过宿主 DNS 转发自动受益，无需额外配置。

⚠️ 不要写死 DNS 地址：223.5.5.5 在部分网络（校园网、部分运营商）会被拦截 53 端口，写死后解析会整体失效。2026-08-14 与 2026-09-10 两次事故都源于此。

一键配置¶

./scripts/setup-dns.sh

脚本会自动： 1. 探测可用 DNS（--dry-run 只演练选择过程，不写文件、不需要 sudo） 2. 在 /etc/resolver/ 创建域名级别的 DNS 路由规则（需 sudo，写入前自动备份到 ~/resolver-backup-<时间戳>.tgz） 3. 在 /etc/hosts 写入备份条目（IP 过期时可再次运行刷新） 4. 验证所有域名解析正常

手动配置¶

如果需要手动配置，创建以下文件：

# /etc/resolver/ 下的每个文件对应一个域名及其子域名
# 文件名 = 域名，内容 = nameserver 指令

DOMAINS="alibabadns.com aliyunddos1022.com bigmodel.cn bytedns1.com cdnbuild.net cdngslb.com deepseek.com dingtalk.com eo.dnse1.com eo.dnse5.com feishu.cn gitcode.com gtm-a4b8.com kunluncan.com moonshot.cn open.bigmodel.cn qq.com queniuiq.com queniurc.com queniuyk.com queniuck.com xiaomimimo.com xiaomi.com workbuddy.cn yundunwaf3.com zhipu.ai"

# 先确认该 DNS 在当前网络可用（校园网/部分运营商会拦 53 端口）
DNS=223.5.5.5          # 或路由器地址，如 192.168.3.1
dig +short +time=2 @$DNS www.qq.com    # 有输出才可用

for domain in $DOMAINS; do
  echo "nameserver $DNS" | sudo tee /etc/resolver/$domain
done

# 刷新 DNS 缓存
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

⚠️ 脚本只增/改，不删：/etc/resolver/ 里可能残留脚本不再管理的域名（历史配置或手工加的），脚本每次只创建/更新上面这份名单（26 个），不会清理其它文件。2026-09-28 实测宿主机有 28 个，多出的 4 个是 bilibili.com、bilicdn1.com、huaweicloudwaf.com、queniuyk.co —— 仓库里没有任何配置引用它们。其中 queniuyk.co 疑为 queniuyk.com 的笔误（两者同时存在，内容相同）。确认无用后手工清理：sudo rm /etc/resolver/<域名>。

反向的坑更隐蔽：磁盘上有、仓库里没有的域，换机器时会静默丢失。cdnbuild.net 和 kunluncan.com 曾经就是这种状态（只存在于这台机器的 /etc/resolver/，飞书文件链接依赖它们）， 2026-09-28 已收编进 RESOLVER_DOMAINS。

关键细节¶

CNAME 链问题¶

中国服务的域名通常使用 CDN/GSLB，解析时经过多级 CNAME 跳转。CNAME 链中的某些中间域名不在服务主域名下，如果系统 DNS 无法解析这些外域，整个链路就会失败。

服务	CNAME 链经过的外域	说明
钉钉 api.dingtalk.com	`gds.alibabadns.com`	阿里云 GSLB
DeepSeek api.deepseek.com	`eo.dnse1.com`	火山引擎 CDN
WorkBuddy workbuddy.cn	`eo.dnse5.com`	腾讯 EdgeOne CDN（与 DeepSeek 的 dnse1 是两条独立链）
飞书 open.feishu.cn	`bytedns1.com` → `cdngslb.com` → `queniuyk.com`	字节 CDN → GSLB → 金山云 CNAME 终端
飞书 accounts/www.feishu.cn	`bytedns1.com` → `cdngslb.com` → `queniurc.com`	登录页与官网的终端域（2026-09-28 补配）
飞书 help/passport/okr.feishu.cn	`cdngslb.com` → `queniuiq.com`	另一支终端域（与 `queniurc.com` 不同，2026-09-28 补配）
飞书文件链接 `*.feishu.cn`	`bytedns1.com` → `kunluncan.com`（部分地理为 `cdnbuild.net`）	文件 CDN 终端（通配），如 `drive.feishu.cn`
飞书 msg-frontier.feishu.cn	`queniuck.com`	飞书长连接 CNAME 终端
小米 MiMo api.xiaomimimo.com	`xiaomi.com`	`mimo-pri-alisgp.alb.xiaomi.com`
Moonshot api.moonshot.cn	`aliyunddos1022.com`	阿里云 DDoS 防护
智谱 open.bigmodel.cn	`yundunwaf3.com` → `gtm-a4b8.com`	阿里云 WAF → GTM

以钉钉为例：

api.dingtalk.com → v6-cname.dingtalk.com → region-cname.dingtalk.com
→ region-cname.dingtalk.com.gds.alibabadns.com → ... → 最终 IP

CNAME 链经过了 gds.alibabadns.com（阿里云 GSLB 内部域），它不在 dingtalk.com 域下，因此需要单独配置 /etc/resolver/alibabadns.com。如果不配这个，即使 dingtalk.com 的 resolver 正确，api.dingtalk.com 仍然会解析失败。

setup-dns.sh 已包含所有已知的外域 resolver，新发现的 CNAME 外域也需加入。

/etc/hosts 备份作用¶

/etc/hosts 中的条目优先级高于 DNS 查询，作为额外的安全网。但其中的 IP 来自 CDN，会随时间变化，需要定期更新。运行 ./scripts/setup-dns.sh 即可刷新。

⚠️ 死 IP 会「遮蔽」可用 DNS：hosts 优先级高于 DNS，一旦其中的 IP 失效（换网络、CDN 轮换），即使 /etc/resolver/ 解析完全正常，应用也只会连到那个死 IP 上 —— 而且症状具有迷惑性（2026-09-10：open.feishu.cn 被 hosts 里的旧 IP 挡住，飞书推送全挂，但同一台机器上 msg-frontier.feishu.cn 收发正常）。排查：dscacheutil -q host -a name <域名>（看是不是 hosts 抢答）对比 dig @<DNS> <域名>。因此 hosts 只保留少数确实需要兜底的域名，不要往里加 CDN 域名。

当前写入的备份条目（共 8 条，与 scripts/setup-dns.sh 的 HOSTS_DOMAINS 一致）：

open.bigmodel.cn                    # 智谱 GLM API
mcp.dingtalk.com                    # 钉钉 MCP
wss-open-connection.dingtalk.com    # 钉钉 Stream 长连接
imap.qq.com / smtp.qq.com           # QQ 邮箱
api.xiaomimimo.com                  # 小米 MiMo API
workbuddy.cn / www.workbuddy.cn     # WorkBuddy

Docker 容器 DNS 链路¶

容器应用 → Docker DNS (127.0.0.11) → 宿主 DNS → /etc/resolver/ → <选定的可用 DNS>

Docker Desktop for Mac 的内嵌 DNS 服务器会将查询转发到宿主，宿主按 /etc/resolver/ 规则路由到指定 DNS。因此只需在宿主配置 resolver，所有容器自动生效，不需要在 docker-compose.yml 中用 extra_hosts 硬编码 IP。

代理工具设置¶

如果使用网络代理工具，需确保中国 IP 地址走直连（不经过代理隧道），否则即使 DNS 解析正确，TCP 连接也可能超时或被拦截。通常的配置方式是在代理工具中启用"中国网站直连"或"分流规则"。