架构总览#
整体架构
双平面架构:控制面(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(签名密钥,仅展示一次)。每次请求带两个签名头:
| 请求头 | 说明 |
|---|---|
Authorization | FDNS-HMAC-SHA256 Credential=<AK>, Signature=<签名> |
X-FD-Timestamp | unix 秒时间戳(±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 从属同步不受影响。