Fusion DNS 文档

功能使用说明 · 部署手册 · 最佳实践与常见问题——内容与控制台现役版本一致。

架构总览#

整体架构

Fusion DNS 统一 DNS 管理平台 数据平面 边缘部署 · 按需横向扩展 · 全部 DNS 流量在此终结 客户端 内网终端 公网递归 · 拨测 下游从属(AXFR) :53 fusion-dns-proxy × N 多 worker · 贴核 · 心跳即注册(35s 判离线)· 本地缓存自持 权威解析 视图分流 递归缓存 域名拦截 ACL 准入 DNSSEC 预签 ECS 透传 区传 AXFR 九类型 RRset · 通配/CNAME 追逐 · LRU+TTL+负缓存 三策略调度 · 主动探活摘除/回归 · UDP→TCP 升级 快照本地自持 —— 控制面停机不影响解析 实测:2 核 权威 UDP 9.7k QPS · p99 19ms · 内存 16.4MiB 非本地区域按转发规则送上游 上游 DNS 公共递归 ×2 · 探活互备 控制平面 内网 / 云主机 · 不在解析流量路径上 管理员 HTTPS · MFA 管理操作 fusion-dns-web · 控制台 nginx 静态 + /api 反代 · 严格密文登录 /api/v1 fusion-dns-service :8210 快照编译(SOA serial = 版本号)· 长轮询下发 · 版本链/回滚 管理 API · RBAC MFA · 防爆破 审计 · 登录日志 告警巡检 ×4 观测聚合 HMAC 快照签名 MySQL 配置/版本/审计 每日备份 Redis 锁/缓存/限速 分钟桶聚合 Prometheus :9091 回环 remote_write · 30d 控制通道(proxy ⇄ service) 心跳上报(35s)· 查询日志批量入库 · 统计指标随心跳捎带 数据面 proxy 快照拉取(长轮询感知变更 · 约 1.4s 生效)· HMAC-SHA256 验签 · 失败自持 控制面 service 生产基线:发布→生效 1.4s · 单节点 2 核 UDP 9.7k QPS / p99 19ms · DNSSEC delv fully validated · MySQL 每日备份

双平面架构:控制面(service + web,内网)负责区域/记录/策略管理与版本化分发;数据面(proxy ×N,边缘部署)承载全部 DNS 查询流量。配置变更编译为全量快照(SOA serial = 版本号),经长轮询秒级下发(实测约 1.4s),proxy 本地缓存自持——控制面停机不影响解析。

组件职责端口
fusion-dns-service管理 API、快照编译、版本链、审计/告警/观测聚合8210
fusion-dns-proxy权威解析 + 递归转发 + 缓存 + 拦截 + ACL + DNSSEC 预签名应答53(UDP/TCP)
fusion-dns-web控制台(nginx 静态 + API 反代)80/443

节点与网关

proxy 部署后心跳即注册(35s 判离线),无需手工登记。网关是节点的逻辑分组容器;区域绑定网关后仅对该组节点可见——同一套控制面可服务多组解析拓扑。节点也可不绑网关(空配置模式:全局策略生效、无区域)。

每个 proxy 支持多 worker(SO_REUSEPORT 贴核),实测单节点 2 核权威 UDP 9.7k QPS、p99 19ms。

登录控制台

浏览器打开控制台地址(如 https://admin.fusion-dns.com)。登录采用严格密文传输:每次登录现取一次性 RSA 公钥加密密码(用后即焚),密码明文不出浏览器。首次登录强制改密。

开启 MFA 的账号在密码通过后需输入验证器 App 的 6 位动态码(TOTP);首次开启会引导扫码绑定。

首个区域解析#

创建区域与记录

解析配置 → 权威区域 → 新建:填写区域名(如 example.com.)、分组与网关(必填),保存后进入区域详情添加记录。记录支持 A / AAAA / CNAME / MX / TXT / NS / SRV / PTR / CAA 九类型;同名称同类型多行构成 RRset(轮询应答)。TTL 为 0 时继承区域默认值。

验证生效

保存后配置自动发布新版本,节点 5s 内同步。在任意客户端验证:

dig @<节点地址> www.example.com A +short

控制台 域名防护 → 查询日志 可看到该查询的来源、视图、应答与解析结果(应答 RR 全文)。

回滚

系统 → 配置版本 列出每次变更的全量快照,支持「快照 JSON / 变更对比 / 一键回滚」。回滚以历史快照重发新版本(版本号只增不减,SOA serial 天然合法),秒级生效。

视图(内外网分流)#

多视图解析

视图按客户端来源 CIDR 拆分解析结果:同一域名可为内网/外网(或不同机房)返回不同地址。优先级小者优先,客户端按序匹配首个命中的视图;未命中任何视图走默认(视图 0)。

记录编辑时选择所属视图即可。验证:控制台 解析配置 → 解析测试 支持模拟客户端子网(ECS),免真实客户端分流验证。

EDNS Client Subnet

递归转发场景支持 ECS 透传:客户端子网传给上游(精准调度),缓存按子网隔离。开启 view_by_ecs 后,带 ECS 的查询以子网地址匹配视图(ACL 准入仍按真实来源 IP)。

转发与上游#

转发规则

非本地区域的查询按转发规则(后缀匹配,最长优先)送往对应上游组;. 为全局兜底。典型用法:内网域走内部 DNS,其余走公共递归。

上游组与探活

上游组支持三种调度:加权轮询 / 随机 / 并发竞速。内置主动探活(周期域名探测 + 失败摘除 + 恢复回归)与被动健康(错误率)。控制台上游组列表展示实时健康状态与节点明细。

递归缓存(LRU + TTL + 负缓存)命中时直接应答,实测重复查询 57ms → 3ms;支持内存水位与按域名软配额防单域挤占。

域名防护#

域名拦截

按精确 / 后缀匹配域名,动作返回 NXDOMAIN 或自定义 IP(广告/跟踪域名秒答)。命中记录在查询日志中 source=block,流量观测的「域名拦截趋势」图表按域名拆分展示。

访问控制(ACL)

客户端 CIDR 准入:允许/拒绝 + 优先级(小者优先)+ 条目化默认策略(最低优先级可插入「拒绝所有」兜底,防 open-resolver 滥用)。拒绝的查询立即 REFUSED,不达转发层。

DNSSEC 与区传#

DNSSEC 签名

区域详情 → DNSSEC 一键启用:KSK/ZSK(ECDSA P-256)由控制面生成并 master_key GCM 加密存储,RRSIG/NSEC3 在发布时编译期预签名进快照——数据面零私钥零签名开销。delv 全链验证通过(fully validated)。

DS 记录在启用后导出,需在父区/注册商上传完成信任链。ZSK 自动续签(90 天);KSK 轮换走 RFC 6781 双签法(start 双签 → 父区换 DS → finish 晋级),钥龄超阈值自动告警提醒。

AXFR / IXFR 区传

给下游 DNS 做从属源:TCP + 节点 axfr_enabled + ACL 显式放行三卡准入;AXFR 按 RFC5936 分批多消息,IXFR(RFC 1995)按 8 版历史环计算差量。dig 实测差量正确删旧增新。

观测 · 告警 · 审计#

流量观测与查询日志

流量观测七张图——查询量 / 平均耗时 / 缓存命中率 / 应答分布(NXDOMAIN·SERVFAIL·REFUSED)/ 域名拦截趋势 / 上游耗时(全部上游整体均值)。点击放大:逐域名 Top20 多线 + 合计线(上游耗时放大为按上游组分组多线),悬停显示主体名与数值。分钟桶 Redis 预聚合,1 小时窗口毫秒级响应。

查询日志保留 7 天,含客户端、视图、来源、上游、耗时与解析结果全文(点击「查看」弹窗逐条显示应答 RR);列表支持列设置(隐藏不需要的列)与横向滚动。高流量环境可在节点 node.yaml 关闭采集。

告警与通知渠道

四场景状态机(60s 巡检):节点离线 / 上游全摘 / SERVFAIL 突增 / KSK 钥龄超阈。通知为渠道制(gateway 同构):渠道(邮件/飞书/企微/钉钉/webhook)× 模板 × 规则三实体,触发与恢复各一条,发送记录可查。邮件渠道支持自定义 From 显示名(RFC5322)——收件人看到「Fusion DNS 告警 <[email protected]>」而非邮箱前缀。

审计与登录日志

全部写操作留痕 180 天(操作人/对象/明细 before-after/来源 IP),登录成功失败全量 90 天。支持按时间段、动作类型、关键字检索。

账号与安全#

RBAC 权限

15 模块 × 读/写权限码;用户可直授多角色(权限并集),用户组绑角色成员继承。系统预置「系统管理员 / 只读」两角色。前端权限感知:无权限的菜单/按钮自动隐藏。

区域 ACL(数据级授权)

权限码之外的数据级控制:每个权威区域可单独配置「查看 ACL」与「管理 ACL」——

ACL控制范围留空语义
查看区域列表/详情/记录/变更历史/导出/DNSSEC 状态所有人可见
管理区域编辑与删除/记录增删改/DNSSEC 操作有权限码即可管

授权主体三类混合:用户(指定账号)、角色(如「区域运维」)、用户组(组成员共享)——任一命中即通过;「系统管理员」(* 权限)始终旁路。仅控制台层生效,不影响数据面解析。典型用法:给运维团队的角色授权生产区域,其余区域不可见。

MFA 两步登录

用户管理中为账号开启 MFA 后,该账号下次登录强制扫码绑定验证器(Google/Microsoft Authenticator 等),此后每次登录需 6 位动态码。验证码错 5 次 token 作废需重新密码登录。换机/丢失由管理员「重置MFA」解绑。

防爆破与会话

用户名 + IP 双维度计数锁定(阈值/时长/JWT 有效期运行时可调);密码错误次数过多临时锁定;改密即吊销全部现有会话;JWT epoch 机制支持服务端即时吊销。

自动化接入(MCP / API)#

两种接入方式

平台全部管理能力对自动化开放,两种方式共用同一套平台权限(可用范围同你的账号角色,角色变更即时生效;每次写操作落操作审计):

方式适合入口
MCP 协议Cursor / Claude Code 等 AI IDE——对话式管理,「看一下区域」「给 www 加条 A 记录」POST /api/v1/mcp(Streamable HTTP)
REST API脚本 / 程序 / CI-CD——AK/SK 签名直调全部 /api/v1/* 接口(与控制台同路径同权限)任意业务端点 + 签名头

令牌管理:控制台顶栏头像菜单 → 「令牌管理」(/tokens 页,API 密钥与 MCP 令牌两个页签,支持搜索 / 分页 / 批量启停删除)。明文仅创建时展示一次;可设过期时间;支持停用(临时失效可恢复)/ 启用 / 删除。系统设置 → MCP服务 可整体停用 MCP(所有令牌即刻失效)。

安全防护:身份频控(MCP 120 次/分、API 300 次/分,超限 429)+ 认证失败 IP 锁定(30 次 / 10 分钟锁 10 分钟)+ 凭证配额(每类 20 个/用户)。

MCP 接入(Cursor / Claude Code)

MCP 令牌创建后,二选一接入:

Claude Code(终端执行,替换 <令牌>):

claude mcp add --transport http fusion-dns https://admin.fusion-dns.com/api/v1/mcp --header "Authorization: Bearer <令牌>"

Cursor:Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "fusion-dns": {
      "url": "https://admin.fusion-dns.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer <令牌>" }
    }
  }
}

接入后对话即用(工具自动选择,70+ 工具与平台 API 一一对应)。示例:「列出所有区域」「给 example.com 的 www 加一条 A 记录指向 1.2.3.4」「回滚到上一版配置」——区域 / 记录变更经工具调用即时发布(节点约 1.4s 拉取生效),可用工具随账号权限实时过滤。

API 接入(AK/SK 签名)

API 密钥创建后得到 AK(ak_ 前缀,公开标识)与 SK(签名密钥,仅展示一次)。每次请求带两个签名头:

请求头说明
AuthorizationFDNS-HMAC-SHA256 Credential=<AK>, Signature=<签名>
X-FD-Timestampunix 秒时间戳(±300s 窗口,防重放)

签名串(四行,\n 分隔,路径含 /api/v1 前缀与 query 原始顺序;GET/DELETE 空 body 记空串):METHOD + 路径?query + hex(SHA256(body)) + timestamp;Signature = hex(HMAC-SHA256(SK, 签名串))。请求体参与签名(与部分云 API 不同,改 body 必须重签)。

curl 示例(列区域):

AK="ak_xxxx"; SK="sk_yyyy"; TS=$(date +%s)
BH=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')   # 空 body 哈希
SIG=$(printf 'GET
/api/v1/zones?page_size=10
%s
%s' "$BH" "$TS" \
      | openssl dgst -sha256 -hmac "$SK" -hex | awk '{print $NF}')
curl -H "Authorization: FDNS-HMAC-SHA256 Credential=$AK, Signature=$SIG" \
     -H "X-FD-Timestamp: $TS" "https://admin.fusion-dns.com/api/v1/zones?page_size=10"

Python 示例(通用签名函数,读写同规则):

import hashlib, hmac, json, time, urllib.request

AK, SK = "ak_xxxx", "sk_yyyy"
BASE = "https://admin.fusion-dns.com"

def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else b""
    ts = str(int(time.time()))
    bh = hashlib.sha256(data).hexdigest()
    sig = hmac.new(SK.encode(), "\n".join([method, path, bh, ts]).encode(),
                   hashlib.sha256).hexdigest()
    req = urllib.request.Request(BASE + path, data=data or None, method=method)
    req.add_header("Authorization", f"FDNS-HMAC-SHA256 Credential={AK}, Signature={sig}")
    req.add_header("X-FD-Timestamp", ts)
    if data:
        req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

# 读:平台总览 / 查区域
call("GET", "/api/v1/dashboard")
call("GET", "/api/v1/zones?q=example&page=1&page_size=20")
# 写:建区 → 加 A 记录(即时发布,落审计)
zone = call("POST", "/api/v1/zones", {"name": "api-demo.example.com", "ttl": 600,
    "group_id": "分组ID", "gateway_ids": ["网关ID"], "tag_ids": []})
call("POST", "/api/v1/records", {"zone_id": zone["data"]["id"], "name": "www",
    "type": "A", "value": "203.0.113.10", "ttl": 60})
# 批量:部分成功语义(被引用的跳过并说明)
call("POST", "/api/v1/zones/batch-delete", {"ids": ["id1", "id2"]})

错误语义:401=签名 / 时间窗 / 密钥停用(带原因,落安全审计);403=权限不足(模块:读写);429=频控或 IP 锁定(带 Retry-After)。响应信封 {code, message, success, data},雪花 ID 一律字符串;写操作自动触发配置发布。完整接口清单见仓库文档 docs/dns-service-design.md。

上线检查单#

先收 ACL 再开 53

对公网提供解析前,访问控制必须配置为白名单 + 拒绝兜底:放行目标客户端网段,最低优先级加「拒绝所有」条目——否则沦为 open-resolver 被扫描滥用(生产实测公网 53 数小时内即出现随机域名探测)。

视图拆分建议

内外网内容一致的记录无需建两份——默认视图兜底,只为确实不同的名称建视图记录。视图优先级留间隔(如 10/20)便于后续插入。

上游与缓存

公共递归至少配两家(如 223.5.5.5 + 119.29.29.29)探活互备;内网专用域用独立转发规则指向内部 DNS,避免出网绕行。高流量场景开启缓存内存水位(cache_max_mb)与按域名软配额。

备份

MySQL 每日自动备份(mysqldump 全库 + 配置 tar);DNSSEC 私钥由 master_key 加密——master_key 与备份分开存放,两者齐失才不可恢复。回滚应急优先用配置版本页(秒级),DB 恢复为最后手段。

部署拓扑#

典型拓扑

控制面(service/web/MySQL/Redis)部署于内网或云主机;proxy 部署于各解析出口(机房/POP),53 端口对客户端可达。proxy 通过 service_addr 回连控制面(心跳/拉配置/上报日志),方向单一、无需反向打通。

共享机器注意端口:web 用 5015(纯 HTTP,TLS 由前置网关终结);Prometheus 专用实例 9091(仅回环 + remote_write receiver)。

节点接入

proxy 以 node.yaml 自举(node_id / service_addr / service_token / dns_listen 等),容器化部署后心跳即注册。多 worker 配 workers: N;解析地址(advertise_addr)用于区传与展示。配置挂载于宿主 /data/apps/fusion-dns-proxy/configs——镜像更新不覆盖手工配置。

TLS 与域名

生产控制台走前置网关(gateway-proxy 终结 TLS,按域名转发 5015);也可独立部署时启用 web 内置 TLS(自签或正式证书运行时挂载,80 一律 301)。严格密文登录要求 HTTPS 环境(WebCrypto 需安全上下文)。

常见问题#

公网 53 开放后出现陌生域名查询?

正常现象——互联网扫描器持续探测开放解析器。确认 ACL 已按「上线检查单」配置白名单 + 拒绝兜底即可:扫描流量会被 REFUSED(查询日志 source=deny),不消耗上游配额。

改了记录不生效?

按序排查:① 节点管理看节点「配置同步」是否 synced(lagged/failed 会有状态与错误信息);② 客户端本地 DNS 缓存(TTL 内旧值);③ 视图是否命中(解析测试带 ECS 模拟客户端子网验证);④ 查询日志确认该查询实际命中的视图与来源。

MFA 验证器丢了怎么登录?

由另一名管理员在「用户管理 → 更多 → 重置MFA」解绑,之后重新登录走扫码绑定。单管理员场景请务必保管好验证器(或为关键账号配备第二管理员)。

为什么第一次慢、后面快?

递归缓存:首次查询走上游(真实往返耗时),命中缓存后本地直接应答(毫秒级)。缓存随配置发布清空(保证一致性),TTL 到期自动失效。流量观测「缓存命中率」与节点列表「缓存命中」可监控。

回滚会丢掉之后的修改吗?

不会——回滚是把历史快照重发为新版本(版本号续增),之后的修改仍留在版本链里可再回滚。SOA serial 严格单调,从属 DNS 的 IXFR 不会混乱。

如何扩容?

解析层无状态:新节点部署 proxy 即自动注册,绑到目标网关即刻服务(配置自动拉取)。控制面单点足够(不在查询路径);MySQL/Redis 已外置化,可独立扩容。

为什么有的账号看不到某些区域?

该区域配置了「查看 ACL」且当前账号身份(用户/角色/用户组)不在授权列表——列表直接过滤不可见(非报错)。系统管理员(* 权限)始终可见全部。需要访问请联系区域管理员将你的账号/角色/用户组加入查看 ACL。

版本号 20261008v3 是什么含义?

展示版号 = 发布日期 + 当日第 N 版(如 20261008v3 = 10 月 8 日第 3 次变更)。它是纯展示形态——底层快照 ID(雪花)仍是 SOA serial,严格单调递增,IXFR 从属同步不受影响。