robin/waf-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
5d0b7c7e91120ba219a2d922c283ab46f3d94112
waf-platform/EdgeHttpDNS/HTTPDNS后端开发计划.md
robin 150799f41d 管理端全部功能跑通
2026-02-27 10:35:22 +08:00

9.9 KiB
Raw Blame History

HTTPDNS后端开发计划（V1.0）

0. 文档信息

  • 目标文件：EdgeHttpDNS/HTTPDNS后端开发计划.md
  • 交付范围：EdgeAdmin + EdgeAPI + EdgeHttpDNS + SDK对接接口
  • 交付策略：一次性全量交付（非分阶段）
  • 核心约束：
    • 仅新协议
    • 无 /bootstrap
    • /resolve 使用 GET 参数
    • 线路匹配仅基于客户端 IP 归属
    • 独立 edgeHTTPDNS* 数据表
    • 新增独立节点角色 NodeRoleHTTPDNS
    • 访问日志 MySQL + ClickHouse 双写（查询优先 ClickHouse）
    • 不复用智能DNS（EdgeDNS/NS）模块的 DAO/Service/Store，HTTPDNS 独立实现（可参考并复制所需能力）

1. 目标与成功标准

  1. 将 HTTPDNS 从当前 Admin 侧 mock/store 方案落地为真实后端能力。
  2. 打通“配置 -> 下发 -> 解析 -> 日志 -> 查询”闭环。
  3. 与当前前端设计严格对齐：
    • 菜单：集群管理、应用管理、访问日志、运行日志、解析测试
    • SNI 固定为“隐匿 SNI”
    • 自定义解析不含 SDNS 参数
  4. 成功标准：
    • 管理页面均通过 RPC 读取真实数据，无本地 mock 依赖
    • /resolve 可按应用/域名/线路返回解析结果
    • 访问日志与运行日志可查询、可筛选、可分页
    • 节点配置与状态可下发和回传
    • 主备集群服务域名可在应用设置中配置并生效
    • EdgeHttpDNS 支持 SNI 与 Host 解耦路由，并可执行 WAF 动态验签与隐匿 SNI 转发

2. 架构与边界

2.1 服务边界

  1. EdgeAdmin：仅负责页面动作与 RPC 编排，不存业务状态。
  2. EdgeAPI：负责数据存储、策略匹配、接口服务、日志汇聚。
  3. EdgeHttpDNS（HTTPDNS节点）：负责执行解析、上报运行日志/访问日志、接收任务。
  4. SDK：手动配置应用关联主备服务域名，调用 /resolve 获取结果。

2.2 不做项

  1. 不做 /bootstrap 接口。
  2. 不做 ECH / SNI 分级策略。
  3. 不做 SDNS 参数匹配。
  4. 不做第三方 DNS 依赖复用。

3. 公开接口与契约（需新增/调整）

3.1 HTTP 解析接口

  1. GET /resolve
  2. 请求参数：
    • appId（必填）
    • dn（必填）
    • qtype（可选，A/AAAA，默认 A）
    • cip（可选）
    • sid、sdk_version、os（可选，用于日志）
    • nonce、exp、sign（可选，验签开启时必需）
  3. 响应结构（统一）：
    • code、message、requestId
    • data：
      • domain
      • qtype
      • ttl
      • records[]（type,ip,weight?,line?,region?）
      • client（ip,region,carrier,country）
      • summary（命中规则摘要）
  4. 错误码最低集合：
    • app 无效/禁用
    • 域名未绑定
    • 验签失败
    • 无可用解析记录
    • 内部解析失败/超时

3.2 管理 RPC（EdgeAdmin -> EdgeAPI）

  1. 新增服务：
    • HTTPDNSClusterService
    • HTTPDNSNodeService
    • HTTPDNSAppService
    • HTTPDNSDomainService
    • HTTPDNSRuleService
    • HTTPDNSAccessLogService
    • HTTPDNSRuntimeLogService
    • HTTPDNSSandboxService
  2. 最小方法集：
    • 集群：增删改查、设置默认集群、TLS证书绑定、节点列表/状态
    • 应用：增删改查、主备集群设置、启停、验签开关、密钥重置
    • 域名：绑定/解绑/列表
    • 自定义解析：规则增删改查、启停、排序
    • 日志：访问日志分页查询、运行日志分页查询
    • 测试：在线解析测试调用（入参包含 appId、clusterId、domain、qtype、clientIp）

3.3 节点日志上报 RPC（EdgeHttpDNS -> EdgeAPI）

  1. CreateHTTPDNSAccessLogs（批量）
  2. CreateHTTPDNSRuntimeLogs（批量）
  3. 幂等键：requestId + nodeId
  4. 支持高吞吐批量提交和失败重试

3.4 节点路由与 WAF 策略下发契约（EdgeAPI -> EdgeHttpDNS）

  1. 下发内容最小集合：
    • appId/domain/serviceDomain
    • sniMode（固定为隐匿 SNI）
    • hostRouteMode（SNI 与 Host 解耦）
    • wafVerifyEnabled
    • wafVerifyPolicy（验签字段、时效窗口、失败动作）
  2. 节点执行口径：
    • 入站按 serviceDomain 接入，按 Host/业务域名做路由匹配
    • TLS 握手与业务 Host 解耦，避免真实业务域名暴露在 SNI
    • 命中需要验签的应用时，先执行 WAF 动态验签，再继续解析链路
  3. 失败处置：
    • 验签失败按策略拒绝并记录运行日志、访问日志错误码
    • 路由未命中返回统一错误码并上报审计日志

4. 数据模型设计（独立 HTTPDNS 表）

  1. edgeHTTPDNSClusters
    • id,name,isOn,isDefault,serviceDomain,defaultTTL,fallbackTimeoutMs,installDir,tlsPolicyJSON,createdAt,updatedAt
  2. edgeHTTPDNSNodes
    • id,clusterId,name,isOn,isUp,isInstalled,isActive,statusJSON,installStatusJSON,installDir,uniqueId,secret,createdAt,updatedAt
  3. edgeHTTPDNSApps
    • id,name,appId,isOn,primaryClusterId,backupClusterId,sniMode(fixed_hide),createdAt,updatedAt
  4. edgeHTTPDNSAppSecrets
    • id,appId,signEnabled,signSecretEnc,signUpdatedAt,updatedAt
  5. edgeHTTPDNSDomains
    • id,appId,domain,isOn,createdAt,updatedAt
  6. edgeHTTPDNSCustomRules
    • id,appId,domainId,ruleName,lineScope,lineCarrier,lineRegion,lineProvince,lineContinent,lineCountry,ttl,isOn,priority,updatedAt
  7. edgeHTTPDNSCustomRuleRecords
    • id,ruleId,recordType,recordValue,weight,sort
  8. edgeHTTPDNSAccessLogs
    • id,requestId,clusterId,nodeId,appId,domain,qtype,clientIP,clientRegion,carrier,sdkVersion,os,resultIPs,status,errorCode,costMs,createdAt,day
  9. edgeHTTPDNSRuntimeLogs
    • id,clusterId,nodeId,level,type,tag,description,count,createdAt,day

4.1 索引与唯一约束

  1. 唯一：edgeHTTPDNSApps.appId
  2. 唯一：edgeHTTPDNSDomains(appId,domain)
  3. 唯一：edgeHTTPDNSAccessLogs(requestId,nodeId)
  4. 索引：
    • 访问日志：day,clusterId,nodeId,domain,status,createdAt
    • 规则匹配：domainId,isOn,priority,lineScope,...
    • 应用查询：name,appId,isOn

5. 解析引擎实现（EdgeAPI）

  1. 输入校验：appId/dn/qtype
  2. 应用与域名校验：
    • app 存在且启用
    • 域名已绑定到 app
  3. 线路归属：
    • cip 优先，其次 remote IP
    • 映射字段：运营商/大区/省份/洲/国家
  4. 规则匹配：
    • 精确匹配 > 半精确 > 默认
    • 同级按 priority 从小到大
  5. 记录返回：
    • 权重关闭：返回全部记录
    • 权重开启：按权重算法返回单条或子集（固定口径）
  6. TTL 取值：
    • 命中规则取规则 TTL
    • 未命中规则取集群默认 TTL
  7. 验签：
    • signEnabled=true 时必须通过签名校验
    • signEnabled=false 时跳过签名校验
  8. 访问日志：
    • 解析结束异步写日志
    • 双写 MySQL/ClickHouse

6. 节点与任务链路

  1. 在 EdgeCommon/pkg/nodeconfigs 增加 NodeRoleHTTPDNS。
  2. 在任务系统增加 HTTPDNS 任务类型：
    • 配置变更
    • 应用变更
    • 域名变更
    • 规则变更
    • 证书变更
    • 路由与 WAF 策略变更
  3. EdgeHttpDNS 增加 HTTPDNS 子服务：
    • 接收配置快照
    • 执行解析
    • 上报运行/访问日志
    • 执行 SNI/Host 解耦路由
    • 执行 WAF 动态验签
    • 执行隐匿 SNI 转发
  4. 复用现有安装升级框架，但节点角色、任务通道、日志 tag 独立。

7. EdgeAdmin 后端改造

  1. 将 internal/web/actions/default/httpdns/* 的 store/mock 读写改为 RPC。
  2. 删除/停用旧能力路由：
    • /httpdns/policies
    • /httpdns/guide
    • /httpdns/ech
  3. 保留必要跳转，避免旧链接 404。
  4. sandbox/test 改为调用真实解析服务（可保留测试开关）。
  5. 解析测试页面交互固定为：
    • 配置区标题“解析测试”
    • 所属集群使用下拉框
    • 解析域名使用下拉框并按目标应用联动

8. 安全与审计

  1. Secret 持久化使用加密存储（至少密文列），返回时脱敏。
  2. 操作审计记录：
    • 验签开关启停
    • Sign Secret 重置
    • 应用主备集群修改
  3. 验签失败日志保留 requestId,errorCode,sourceIP。
  4. 防滥用：
    • /resolve 增加基础限流与异常请求过滤（按 appId + IP 维度）。
  5. 节点侧安全执行：
    • WAF 动态验签失败必须留存审计日志（含 requestId/appId/sourceIP）
    • SNI/Host 解耦路由命中结果需可追踪（用于问题回溯）

9. 测试与验收

9.1 单元测试

  1. 规则匹配优先级与线路匹配
  2. 验签成功/失败路径
  3. 权重返回算法
  4. DAO CRUD 与唯一约束

9.2 集成测试

  1. EdgeAdmin -> RPC -> DB 全链路
  2. /resolve 各错误码分支
  3. 节点日志上报双写（MySQL+CH）
  4. CH 不可用时 MySQL 回退查询
  5. EdgeAPI 策略下发 -> EdgeHttpDNS 路由/WAF 执行 -> 日志落库全链路

9.3 回归测试

  1. 智能DNS功能不受影响
  2. 菜单与权限不串模块
  3. 旧入口跳转正确，无新增 404

9.4 验收用例

  1. 应用配置主备服务域名后，SDK可解析成功
  2. 主集群故障时可切备集群
  3. 自定义解析按线路返回预期 IP
  4. 访问日志筛选与概要展示正确
  5. 运行日志级别/字段与智能DNS一致
  6. EdgeHttpDNS 可在 SNI 与 Host 解耦场景下正确路由到目标应用
  7. 开启 WAF 动态验签后，合法请求通过、非法签名请求被拒绝且有审计日志

10. 发布与回滚

  1. 发布顺序：
    • DB migration
    • EdgeAPI（DAO+RPC+resolve）
    • EdgeHttpDNS（角色+上报）
    • EdgeAdmin（RPC切换）
  2. 开关控制：
    • httpdns.resolve.enabled
    • httpdns.log.clickhouse.enabled
  3. 回滚策略：
    • 关闭 resolve 新实现开关
    • 访问日志读取切回 MySQL
    • Admin 保留只读能力

11. 默认值与固定决策

  1. 无 /bootstrap，SDK手动配置主备服务域名。
  2. SNI 固定“隐匿 SNI”。
  3. 自定义解析无 SDNS 参数。
  4. 线路仅客户端 IP 归属。
  5. 日志双写，查询优先 ClickHouse。
  6. 节点角色独立：NodeRoleHTTPDNS。