VTY 品牌域名防护体系 · 产品需求文档（PRD）

文档目录

一、需求背景

1.1 业务背景

VTY 对外有 品牌域名（如 winbet.com），用于广告、投放、口碑、线下物料等 品牌入口。
真正承载产品的是 站点域名池（play-*.com 等可轮换业务域），会因监管、投诉、DNS 污染、CDN 风控等原因失效。

当前架构矛盾：

• 品牌域若直接挂站点 → 爬虫/举报可抓到业务特征 → 品牌资产被污染或封禁。
• 站点域被封若入口写死 → 用户进不来、分享全失效。
• 后台 H5 域名池 与 App 域名池分开维护 → 切换不同步、探活重复、分享与 App 入口不一致。
• 技术反馈「产品方案无法落地」→ 缺少 接口何时返回域名、何时切换、谁负责什么 的可编码规格。

1.2 现状基线：vty.vip 品牌域（中国部分区域）

数据来源： 现网监测与运营反馈（2026-08～09）；口径为「用户点击品牌链 → 最终进入可交互首页」。

1.2.1 当前表现

1.2.2 75% 失败原因拆解（归因假设，上线后用埋点验证）

1.2.3 现状结论（为什么要换新方案）

1. vty.vip 作为品牌域长期承载跳转与内容暴露，在中国部分区域已出现 约 1/4 用户无法进入。
2. 失败 不是单点，而是「区域解析 + 单域跳转 + 举报/扫描」叠加。
3. 新方案目标不是「再换一个品牌域名字」，而是 Brand 干净、Gate 风控、Site 可轮换、客户端多域容错 的组合拳。

1.3 现状问题（方案层）

1.4 v2 新增诉求（本次定案）

1.5 目标与非目标

目标（Must）

1. 品牌域零内容：探测仅见 301 或规范空响应，无业务页/登录/钱包文案。
2. Gate 风控可落地：双检通过才 Resolve；爬虫见空页。
3. 站点域可轮换：探活摘除 + 客户端轮询 + 加密下发 3 域。
4. H5/App 池统一：一套配置、一套探活、一套主站决策。
5. 分享动态解析：与 Resolve 同一主站数据源。
6. 品牌来源可统计：hop_id + brand_domain 归因。
7. 职责清晰：运维/技术/测试各一章，可直接拆工单。

非目标

• 不实现充值/投注等业务功能。
• 不对抗国家级深度流量分析；目标是 降暴露 + 提可替换性。
• 不把短链平台做成完整 SaaS。

1.6 成功标准与 成功率目标（KPI）

1.6.1 安全与功能指标

1.6.2 用户成功进入率（核心 KPI · 相对 vty.vip 基线）

口径定义（统一，上线前后同口径对比）：
成功进入 = 用户发起访问后，在 30s 内 到达 Site 首页且 __health / 首屏关键接口至少 1 次成功（可交互）。
统计维度： 分省、分运营商（移动/联通/电信/广电）、分入口（品牌 H5 / App / 分享）。

1.6.3 分期达标（上线后）

1.6.4 未达标处置

1.6.5 监测实现（技术必须埋点）

二、PRD 总体方案

2.1 一页结论

品牌域（运维 301 零内容）
    → 【落地域 · 中间层】entry.xx.net（Gate 服务：双检 + resolve + probe 编排）
        ├─ 判定失败 → 地址栏仍是落地域，在落地域展示报错（空页/Loading/全屏）
        └─ 判定成功 → location 进入 【站点主域】play-a.com（域名池，可轮换）
            → 运行期故障 → 在主站域内 Toast / FAILOVER（不切回落地域）
App → bootstrap 版本关 → resolve → probe → 同上进入主站域

四段链路：

2.2 域名分层（五层 · 含落地中间层）

命名说明： 文档中的 Gate = 部署在 落地域 上的风控+引导 服务；entry.vty.net 为落地域 FQDN 示例（可与 go-gate.xx.net 并存热备，均属 Landing 角色）。

Brand ──301──→ Landing（落地中间层）──判定 OK──→ Site 主站域（池）
  │                 │                              │
  │                 ├─ 判定 FAIL：报错在落地域      ├─ 运行期 FAIL：报错在主站域
  │                 │   （不暴露 play-*.com）       │   （Toast / FAILOVER）
运维301         Gate双检+加密+probe编排          探活+轮询+业务

2.2.1 落地域 vs 主站域：判定归属与报错规则（产品定案）

核心规则：

1. 落地域 = 中间层判定域：双检、resolve、解密、PROBE_LIST 全程在落地域 hostname 下完成（浏览器地址栏为 entry.vty.net）。
2. 判定失败 → 当前域（落地域）报错：不跳主站、不在地址栏出现 play-*.com。
3. 判定成功 → 才 location.replace 进入站点主域：此后报错归属 主站域。
4. 站点主域 来自域名池 site_domain_pool，与落地域 证书/DNS/桶完全分离。

                    ┌──────────────────────────────────────┐
                    │  落地域 entry.vty.net（中间层）       │
                    │  ┌────────────────────────────────┐  │
  Brand 301 ───────→│  │ IP/fp 双检                      │  │
                    │  │ resolve → 解密 → probe 编排      │  │
                    │  │ FAIL → 本域报错（见 §4.10.5）   │  │
                    │  └───────────────┬────────────────┘  │
                    └──────────────────│ PASS ─────────────┘
                                       ▼
                    ┌──────────────────────────────────────┐
                    │  站点主域 play-a.com（池内 · 可轮换）  │
                    │  首页 / 登录 / 投注 · FAILOVER 在此域  │
                    └──────────────────────────────────────┘

与分享/直访差异：

2.2.2 落地域配置（运维 + 技术）

核心原则

1. 品牌域 永不 托管业务内容。
2. Site 可牺牲轮换；Brand 尽量不动。
3. 分享永远解析 当前 Site。
4. hop_id 第一跳签发、落地核销，防刷量。

2.3 全入口端到端流程（品牌 / 分享 / 主站直访 / App）

本章定位： 四条入口共用 域名池（主站域）+ 落地域判定 + FAILOVER；品牌 H5 必须经 落地中间层。实现见 §4.3～§4.6。

2.3.0 四条入口总览

Brand ─301─→ Landing 落地域（判定层 · 失败留本域报错）
                    │
                    │ PASS：location.replace
                    ▼
              Site 主站域 play-a/b/c（池 · 运行期故障在本域处理）

sequenceDiagram
  participant U as 用户浏览器
  participant B as Brand<br/>winbet.com
  participant L as 落地域<br/>entry.vty.net
  participant R as Resolve API
  participant P as 主站域名池
  participant S as 站点主域<br/>play-a.com

  U->>B: ① 点击品牌 URL
  B->>L: ② 301（零 Body）
  Note over U,L: 地址栏 = entry.vty.net（中间层）
  L->>L: ③ IP 检测
  L->>U: ④ bootstrap
  U->>U: ⑤ 采集 fp
  U->>L: ⑥ POST gate/resolve
  alt 判定失败（IP/fp/resolve/probe）
    L-->>U: 留在落地域报错（空页/Loading/全屏）
    Note over U: 地址栏仍为 entry.vty.net
  else 判定成功
    L->>P: ⑧ 查 healthy TOP3
    L-->>U: 加密 payload
    U->>U: 解密 + PROBE_LIST（仍在落地域 orchestrate）
    U->>S: ⑪ location.replace → play-a.com
    Note over U,S: 地址栏变为主站域 · 此后报错在主站
    alt 主站运行期故障
      U->>U: FAILOVER（Toast · 不切回落地域）
    end
  end

2.3.2 品牌 H5：阶段一（Brand → 落地域）

触发： 用户点击 https://winbet.com/。

原则： Brand 零 Body；301 Location 只能 是落地域 FQDN。

2.3.3 品牌 H5：阶段二（落地域 · 风控双检）

发生域： 地址栏 = entry.vty.net（落地中间层）。
Gate 服务收到 GET /r/{brandId} 后返回 bootstrap；判定失败不跳主站，在落地域处理。

判定失败 vs 成功的域归属

判断顺序（短路，任一 FAIL 即停）

1. brand_id 有效？          → 否：404
2. IP 硬拒绝 IP-H1~H5？     → 是：空页 40301
3. IP 白名单 IP-W1？        → 是：跳过 IP 打分（仅限流）
4. IP 评分 ip_score         → <60：空页 40301
5. 频率限流                  → 超限：429 或空页
6. （resolve 时）fp 硬拒绝   → 是：空页 40302
7. fp 评分 fp_score          → <60：空页 40302
8. 全部通过                  → 执行 Resolve 查池

Gate 全分支表

关键： G2～G8 绝不调用 Resolve；响应中 无 domains 明文、无跳转 Site。

2.3.4 品牌 H5：阶段三（域名池 · Resolve · 解密）

A. 服务端：域名从哪来

Resolve 不接受客户端指定域名；只从统一池 site_domain_pool 读取：

SELECT domain FROM site_domain_pool
WHERE status = 'active'
  AND health = 'ok'
  AND fail_streak < 3
  AND (channels @> ARRAY['all'] OR channels @> ARRAY['h5'])
ORDER BY is_primary DESC, weight DESC
LIMIT 3;

池维护（与 Resolve 联动）：

• 探活 Worker 每 30s HEAD 各 Site /__health；连续 3 败 → health=fail、status=disabled → 下次 Resolve 自动剔除。
• Admin 改 primary → 下次 Resolve 的 domains[0] 变化；H5/App/Share 同源。
• 人工 blocked → 立即剔除，不等待探活。

B. 客户端：如何请求 Resolve

Gate bootstrap 加载后，SDK 执行：

1. gate-fp-collect.js 采集 → fp_hash（≤3s，超时则 resolve 仍发但 fp 空 → 40302）
2. 生成 nonce(uuid)、ts、sig = HMAC(brand_id|ts|nonce|fp_hash)
3. POST /api/v1/gate/resolve  Body: { brand_id, channel:"h5", fp_hash, ts, nonce, sig }
4. 超时 5s；网络错误 → RETRY_RESOLVE（最多 3 轮，间隔 2s）

C. 客户端：如何解密

Response 示例：

{
  "code": 0,
  "data": {
    "key_id": "k2026-03",
    "expires_at": 1735689900,
    "ttl_sec": 300,
    "payload": "<BASE64(iv+ciphertext+tag)>"
  }
}

解密步骤（H5 / App 一致）：

1. 用 key_id 从本地密钥表取 AES-256 密钥 K（H5 bootstrap 内嵌混淆；App 内置可热更新）
2. BASE64 解码 payload → 拆 iv(12B) + ciphertext + tag(16B)
3. AES-256-GCM 解密(K, iv, ciphertext, tag) → UTF-8 JSON 明文
4. 校验 JSON：v=1，domains 为非空数组，hop_id 存在，expires_at 未过期
5. domain_list = domains（顺序即 probe 顺序）；写入 resolve_meta 到 sessionStorage

明文结构（解密后）：

{
  "v": 1,
  "domains": ["play-a.com", "play-b.com", "play-c.com"],
  "primary": "play-a.com",
  "hop_id": "hop_8f3k2j",
  "brand_id": "winbet"
}

2.3.5 品牌 H5：阶段四（探活 · 跳转主站域）

关键： PROBE_LIST 由落地域 bootstrap 发起，但 仅在 probe 成功 后执行 location.replace；此前地址栏 始终是落地域。

# 地址栏仍为 entry.vty.net
for domain in domain_list:
  probe(domain)   # HEAD https://play-x.com/__health
  if ok:
    location.replace("https://{domain}/?hop=...")  # 地址栏 → 主站域
    return
# 全失败：留在落地域，展示 E-RESOLVE-01（不暴露主站 URL 给用户点击）

进站后： 业务 API 基址 = https://{current_domain}；hop_id 随首屏请求上报核销。

2.3.6 共用：运行期故障（主站域内 · 不回退落地域）

适用： 用户地址栏 已是 play-*.com（主站域）。FAILOVER 在主站域之间切换，不跳回落地域（避免二次双检损耗）。

故障检测（任一触发 FAILOVER）

FAILOVER 流程

RUNNING 状态，current_domain = play-a.com

1. 标记 play-a.com 为 local_bad（本地 60s 内不再优先）
2. 从 domain_list 取下一未标记域 play-b.com
3. HEAD play-b.com/__health（3s）
   ├─ 成功 → 切换 API baseUrl 到 play-b
   │         Toast E-NET-01「网络异常，已为您切换至备用线路」
   │         上报 domain_switch(from=play-a, to=play-b)
   │         用户 **无刷新** 继续操作（SPA 重绑 baseUrl）
   └─ 失败 → 试 play-c.com
4. 列表内无可用域 → RETRY_RESOLVE（2 轮）
   ├─ 拿到新 domain_list → 再 PROBE_LIST
   └─ 仍失败 → 全屏 E-RESOLVE-01

运行期全分支

Brand 域不受影响： Site 全挂时 不改 Brand 301；用户刷新品牌链重新走 Gate 流程。

2.3.7 端到端分支 master 表（四入口速查）

2.3.8 分享链路（点击分享短链）

触发： 用户在 IM/社媒点击 https://s-xx.com/{code}（或带路径 /p/match/123）。

sequenceDiagram
  participant U as 用户浏览器
  participant Sh as Share 域<br/>s-xx.com
  participant P as 域名池 DB
  participant S as Site<br/>play-*.com

  U->>Sh: GET /{code}
  Sh->>Sh: ① IP 限流 + 可选 Bot 识别
  Sh->>Sh: ② 校验 code 有效 / 未过期
  alt code 无效
    Sh-->>U: 404 短链不存在
  else code 有效
    Sh->>P: ③ 查 is_primary + healthy 备份序
    alt 无 healthy 域
      Sh-->>U: 503 Share 维护页
    else 有可用域
      Sh->>Sh: ④ 选 target：primary 不通则次优 healthy
      Sh-->>U: 302 Location=Site 落地页
      U->>S: ⑤ 加载 Site SPA + SDK
      S->>S: entry_type=share；写 share_code/hop_id
      Note over U,S: 无 Gate 双检；运行期 FAILOVER 同 §2.3.6
    end
  end

逐步流程

分享 vs 品牌：关键差异

分享分支表

分享接口（与 Resolve 同源）

GET /api/v1/resolve/current-site
Authorization: Bearer {admin_or_share_service}
→ { "primary": "play-a.com", "healthy": ["play-a.com","play-b.com"], "version": 12 }

用户短链边缘逻辑等价于：读 current-site → 302 到 primary + 原始 path。

2.3.9 主站直访（点击/输入 Site 域名）

触发： 用户 收藏夹、短信老链接、手动输入 打开 https://play-a.com/（或 /login），不经过 Brand / Gate / Share。

sequenceDiagram
  participant U as 用户浏览器
  participant S as Site<br/>play-a.com
  participant G as Gate<br/>（仅兜底）
  participant B as Brand<br/>（官方入口）

  U->>S: GET https://play-a.com/
  S->>U: 加载 SPA + domain-shield SDK
  U->>S: HEAD /__health（3s）
  alt 当前域可用
    S->>S: entry_type=direct → RUNNING
  else 当前域不可用
    alt localStorage 有 resolve_meta
      U->>U: PROBE_LIST 缓存域 → FAILOVER
    else 无缓存
      U->>G: 可选：跳 Gate bootstrap
      U->>B: 或：跳 Brand 官方入口
      Note over U: 全屏「请从官方入口进入」
    end
  end

逐步流程

直访分支表

产品定案（直访）

1. 允许直访：不强制每次跳 Brand（否则收藏失效，体验差）。
2. 不直访下发域名池：无 Gate 双检时 不得 在 Site 页调用 gate/resolve 展示备选域列表（防爬虫撞库）。
3. 兜底顺序：本地缓存 FAILOVER → 跳 Brand 官方入口 → 跳 Gate → 全屏 E-RESOLVE-01。
4. 配置项：official_brand_url、gate_fallback_url 由配置中心下发，写入 Site SDK。

// Site SDK 直访 INIT 伪代码
async function initDirect() {
  const host = location.hostname;
  if (await probe(host)) {
    setEntryType('direct');
    return enterRunning(host);
  }
  const cached = loadResolveMeta();
  if (cached?.domains?.length) {
    return probeListAndFailover(cached.domains); // D-F1
  }
  const brand = config.official_brand_url;
  if (brand) return location.replace(brand);      // D-F2
  return location.replace(config.gate_fallback_url + '?from=direct'); // D-F3
}

2.3.10 App 链路（不经品牌域 · 含版本校验）

触发： App 冷启动、网络恢复、后台切前台、定时 5min、FAILOVER 需新列表。

与 H5 差异： App 必须先过版本关，再 resolve；旧版在切流日 强制更新，否则无法拿域名。

sequenceDiagram
  participant A as App
  participant C as Config/bootstrap API
  participant K as Keychain
  participant API as app/resolve
  participant P as 域名池
  participant S as Site

  A->>C: ① GET /app/bootstrap（X-App-Version）
  alt version < min_version 或 force_update
    C-->>A: force_update + store_url
    A->>A: 全屏强制更新（不可关闭）
  else 版本 OK
    A->>K: ② 读 current_domain + resolve_meta
    A->>S: ③ probe current（3s）
    alt probe OK 且 meta 未过期
      A->>A: 跳过 resolve，RUNNING
    else
      A->>API: ④ POST app/resolve（HMAC）
      alt 40310 force_update
        API-->>A: 强制更新
      else 403 无签名
        API-->>A: 拒绝
      else OK
        API->>P: 查池 TOP3（channel=app）
        API-->>A: 加密 payload
        A->>A: 解密 → PROBE_LIST → 写 Keychain
      end
    end
    A->>S: ⑤ 业务 API（X-App-Sign）
  end

App 版本分支表

App 与 H5 能力对照（版本相关）

2.3.11 四入口对照总表

2.7 大版本上线切流：品牌域调整 + 品牌皮肤改版 + App 强制更新（一次性）

产品定案： 新品牌域、新 Gate、新 品牌皮肤（UI 主题）、新 App 域名防护能力 同一窗口上线；旧 App 一律强制更新，不允许静默降级访问。

2.7.1 为什么要绑在一起

结论： 切流日 = 运维切 Brand + H5 Gate 上新 + 服务端抬高 min_version + App Store 仅保留新包。

2.7.2 上线包内容（Cutover Bundle 2026-brand-v2）

2.7.3 切流时间线（T 日 = 正式上线）

2.7.4 切流日各端行为

【旧 App <4.0.0 用户】
  打开 App → bootstrap → 40310 / force_update
  → 全屏「版本过低，请更新」（不可关闭、不可进首页）
  → 跳转 App Store / APK 官网

【新 App ≥4.0.0 用户】
  bootstrap OK → app/resolve → 新池 3 域 → probe → 新皮肤首页

【H5 用户】
  点击 winbet.com（新 Brand 物料）→ 301 Gate → 双检 → resolve
  （无强更；浏览器始终最新 bootstrap）

【分享 / 直访】
  Share 302 新 primary；直访逻辑不变（§2.3.8～2.3.9）

2.7.5 回滚原则

禁止： 切流后为救急 降低 min_version 让旧 App 带旧皮肤 + 旧 Brand 访问新 Gate（会造成双轨运营与举报风险）。

2.7.6 职责 RACI（切流专项）

2.4 关键场景

2.5 运维 × 技术协作

2.6 风险场景与应对（举报 · 机器扫描 · 区域不可用）

原则： 品牌域 永不承载可举报内容；机器/爬虫 看不到域名池；Site 被封 不影响 Brand；用户侧 多域容错 拉升成功进入率。

2.6.1 举报类场景

举报应急 SOP（产品定案）：

1. 收到「品牌域打不开/被墙」→ 运维先验：curl -sI Brand 是否仍 301、Body 是否为空。
2. 若 Brand 本身污染 → 换新 Brand 指向同一 Gate（Site 不动）。
3. 若仅 Site 被封 → 技术池内摘除，不动 Brand。
4. 禁止「把业务面临时挂回 Brand 救急」—— 会重复 vty.vip 75% 问题并加速举报。

2.6.2 机器扫描 / 爬虫类场景

2.6.3 区域不可用 / 弱网（拉升 75%→88% 的关键）

2.6.4 应对能力总览（评审一张表）

2.8 安全审视：杜绝品牌域 / 主站域被标记危险或不可访问

本章定位： 从 安全 / 风控 / 合规 角度审视方案 漏洞与遗漏；最终目标：品牌域长期干净可访问，主站域 可轮换、可牺牲，不因连带导致 Brand 被标红或全网封禁。
评审入口 Tab： index.html →「安全」分册。

2.8.1 安全目标（North Star）

         【必须保护】              【可轮换牺牲】
    Brand + Landing          Site 主站域（池内 N 个）
    零内容 · 无业务特征        业务承载 · 随时 disabled

2.8.2 威胁模型与攻击面

2.8.3 已覆盖能力评估

2.8.4 漏洞与遗漏清单（须补齐）

2.8.5 分层加固清单（执行项）

A. 品牌域（最高优先级 · 绝不能标危险）

B. 落地域（中间层 · 可换不可脏）

C. 主站域（可牺牲 · 与 Brand 隔离）

2.8.6 无法 100% 杜绝的情况（边界声明）

产品口径： 域名架构保证 Brand 举报材料无业务特征；不能保证 Site 永不被标红——保证 Site 可换、Brand 不连带。

2.8.7 安全验收用例（TC-SEC · P0）

三、运维实施手册

运维职责一句话： 品牌域 只做 301，Gate/Site 分桶部署，禁止 品牌域指向业务源站；监控与应急按本章执行。

3.1 职责清单

3.2 URL 桶 / CDN 配置

bucket-brand-winbet      → 无文件；仅 301 → 落地域
bucket-landing-a         → entry-a.vty.net：landing/index.html（Gate bootstrap <2KB）
bucket-landing-b         → entry-b.vty.net：热备落地域
bucket-site-play-a       → 【主站域】H5 构建产物 + __health.json
bucket-site-play-b       → 同上
bucket-site-play-c       → 同上

禁止： 落地域桶 不得 部署完整 Site 产物；主站域桶 不得 绑定 Brand 301。

Brand CDN 规则示例（逻辑）：

server {
  listen 443 ssl http2;
  server_name winbet.com www.winbet.com;
  location / {
    return 301 https://entry-a.vty.net/r/winbet?ts=$msec&sig=$gate_sig;
  }
}

sig 由边缘函数或配置中心下发，禁止在仓库写死可伪造密钥。

3.3 品牌域「零内容」规范

允许： DNS、TLS、301/308、必要安全响应头。
禁止： HTML/JS/CSS/图片、反代站点、下载页、客服页、业务 Set-Cookie、目录索引。

自检：

curl -sI https://winbet.com/
# 期望：301 + Location → Gate

curl -sL --max-redirs 0 https://winbet.com/ | wc -c
# 期望：Body 为 0 或极短

3.4 监控与告警

3.5 应急 Runbook

四、技术实施方案

技术职责一句话： Gate 双检 + 加密 Resolve + 统一域名池 + 探活 Worker + H5/App SDK 轮询 + App 签名校验。

4.1 研发工单清单

4.2 域名池合并（H5 + App）

现状

后台 H5 池、App 池 分开 → 切换不同步、双份探活、分享与 App 不一致。

目标表 site_domain_pool

迁移： 双池导入 → 重复域合并 channels → 删旧 API /api/h5/domains、/api/app/domains → 统一 /api/v1/admin/domains。

Resolve 过滤：

WHERE status='active' AND health='ok'
  AND (channels @> ARRAY['all'] OR channels @> ARRAY[:channel])
ORDER BY weight DESC LIMIT 3

4.3 风控：IP + 浏览器指纹（AND · 完整规则）

总规则（产品定案）：

pass = (ip_verdict == NORMAL) AND (fp_verdict == NORMAL) AND (rate_limit_ok)
任一 FAIL → Gate 空页 或 Resolve 拒绝，不下发域名

判定顺序（研发按序短路）：

1. 黑名单 / 白名单（硬规则）
2. 频率限流
3. IP 评分 ip_score
4. 浏览器指纹评分 fp_score（H5 必填；App 用 device 信号，见 §4.3.4）
5. 通过 → 进入 Resolve

4.3.1 IP 异常规则（完整）

A. 硬拒绝（ip_verdict=BLOCK，不计算分数，直接空页）

B. 硬放行（仅内网/调试，生产默认关闭）

C. IP 评分模型（ip_score：0～100，≥60 为 NORMAL）

初始分 100，逐项扣分，最低 0：

判定：

配置项： IP_SCORE_PASS=60（可调）；IP_RATE_MIN=30/min；IP_RATE_BURST=5/10s。

D. IP 检测伪代码（服务端）

def check_ip(req) -> IpResult:
    ip = req.client_ip
    if in_blacklist(ip): return BLOCK("ip_blacklist")
    if in_whitelist(ip): return NORMAL(skip_score=True)

    if rate_over(ip, "30/min") or rate_over(ip, "5/10s"):
        return BLOCK("ip_rate")  # 也可只扣分到 SUSPICIOUS

    score = 100
    for rule in IP_SCORE_RULES:
        if rule.match(ip, req.headers):
            score -= rule.penalty
    score = max(0, score)

    if score >= 60: return NORMAL(score=score)
    return ABNORMAL(score=score, reason="ip_score_low")

4.3.2 浏览器指纹异常规则（H5 · 完整）

A. 采集时机与字段（Gate bootstrap 页）

页面加载 ≤800ms 内采集并提交；超时未提交视为 fp 异常。

提交格式：

{
  "fp_hash": "sha256(canonical_json_signals + FP_SALT)",
  "fp_signals": "base64(aes_compress(signals))",
  "session_id": "uuid",
  "collect_ms": 320
}

canonical_json：字段名 ASCII 排序后 JSON 序列化，确保同设备 hash 稳定。

B. 硬拒绝（fp_verdict=BLOCK）

C. 指纹评分模型（fp_score：0～100，≥60 为 NORMAL）

初始分 100：

判定：

配置项： FP_SCORE_PASS=60；FP_COLLECT_TIMEOUT_MS=3000。

D. 双检合并决策表

响应码映射：

4.3.3 已知爬虫 / Bot 处理策略

4.3.4 App 端风控差异（不经 Gate 页）

App 无浏览器 Canvas，改用 设备信号 + 签名：

App 不采 fp_score 时：pass = ip_verdict == NORMAL && app_sign_valid && app_version_ok。

版本校验（与 H5 差异 · 切流必开）：

4.3.5 空页规范（异常时必须满足）

HTTP/2 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 0
Cache-Control: no-store

禁止： 302 到 Site、JSON 带域名、错误文案暴露「域名池」。

4.3.6 IP 如何收集与如何判断（服务端 · 技术直接实现）

要点： IP 仅服务端从连接/边缘头获取，不信任客户端上报。

收集（Request → client_ip）

实现清单：

function getClientIp(req) {
  const cf = req.headers['cf-connecting-ip'];
  if (cf) return cf.trim();
  const real = req.headers['x-real-ip'];
  if (real) return real.trim();
  const xff = req.headers['x-forwarded-for'];
  if (xff) return xff.split(',')[0].trim();
  return req.socket.remoteAddress;
}

enrich（ipIntel.lookup）

Redis 键（频率与撞库）

判断输出（写入 Resolve 日志）

{
  "ip": "1.2.3.4",
  "ip_score": 72,
  "ip_verdict": "NORMAL",
  "ip_rules_hit": ["IP-S9"],
  "asn": "AS4134",
  "country": "CN"
}

参考代码： 仓库 js/gate-ip-check.reference.js（checkIp / gateAllowResolve）。

4.3.7 浏览器指纹如何收集与如何判断

A. 收集（Gate bootstrap 页 · 客户端）

采集字段与代码： 见 §4.3.2 A 表；参考 js/gate-fp-collect.js。

// Gate 页主流程（前端必须实现）
VtyGateFp.collectFingerprint().then(function (fp) {
  if (!VtyGateFp.clientPrecheck(fp).ok) {
    document.documentElement.innerHTML = ''; // 本地预检失败也空页
    return;
  }
  return fetch('/api/v1/gate/resolve', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      brand_id: 'winbet',
      channel: 'h5',
      fp_hash: fp.fp_hash,
      session_id: fp.session_id,
      collect_ms: fp.collect_ms,
      ts: Math.floor(Date.now() / 1000),
      nonce: crypto.randomUUID(),
      sig: signResolve(...),
    }),
  });
});

B. 判断（服务端 · 硬规则优先于评分）

if FP-H1～H8 任一命中 → fp_verdict=BLOCK, code=40302
else 计算 fp_score → ≥60 NORMAL / 否则 SUSPICIOUS → 空页
if ip_verdict != NORMAL → 不执行 fp，直接空页

C. 服务端 fp 日志示例

{
  "fp_hash": "a1b2...",
  "fp_score": 85,
  "fp_verdict": "NORMAL",
  "fp_rules_hit": [],
  "collect_ms": 320,
  "session_id": "uuid"
}

D. 运维/客服说明

4.4 接口契约

4.4.1 何时返回域名（决策表）

4.4.2 POST /api/v1/gate/resolve（H5）

Request

{
  "brand_id": "winbet",
  "channel": "h5",
  "fp_hash": "a1b2...",
  "ts": 1735689600,
  "nonce": "uuid",
  "sig": "hmac(brand_id|ts|nonce|fp_hash, gate_secret)"
}

Response 成功

{
  "code": 0,
  "data": {
    "key_id": "k2026-03",
    "expires_at": 1735689900,
    "ttl_sec": 300,
    "payload": "<BASE64 AES-256-GCM>"
  }
}

payload 明文（加密前）

{
  "v": 1,
  "domains": ["play-a.com", "play-b.com", "play-c.com"],
  "primary": "play-a.com",
  "hop_id": "hop_8f3k...",
  "brand_id": "winbet"
}

4.4.3 POST /api/v1/app/resolve（App）

Headers（缺一则 403）

X-Client-Type: app
X-App-Id: com.vty.app
X-App-Version: 3.2.0
X-Timestamp: 1735689600
X-Nonce: uuid
X-App-Sign: HMAC-SHA256(app_secret, method|path|timestamp|nonce|body_sha256)

Body

{
  "channel": "app",
  "platform": "ios",
  "device_id": "哈希",
  "fp_hash": "...",
  "bundle_id": "com.vty.app"
}

40310 响应体：

{
  "code": 40310,
  "message": "force_update",
  "data": {
    "min_version": "4.0.0",
    "latest_version": "4.0.2",
    "update_url": {
      "ios": "https://apps.apple.com/app/idXXXX",
      "android": "https://download.example/app-v4.apk"
    },
    "brand_pack_version": "2026-brand-v2",
    "title_key": "app.force_update_title",
    "body_key": "app.force_update_body"
  }
}

4.4.5 GET /api/v1/app/bootstrap（App · 冷启动第一请求）

调用时机： App 启动 Splash 阶段，早于 Keychain 读域与 app/resolve。切流日配置在此接口生效。

Headers

X-Client-Type: app
X-App-Id: com.vty.app
X-App-Version: 4.0.0
X-Platform: ios
X-App-Sign: HMAC-SHA256(...)   # 与 resolve 同算法，path=/api/v1/app/bootstrap

Response 成功（可继续 resolve）

{
  "code": 0,
  "data": {
    "min_version": "4.0.0",
    "latest_version": "4.0.2",
    "force_update": true,
    "optional_update": false,
    "brand_pack_version": "2026-brand-v2",
    "required_brand_pack": "2026-brand-v2",
    "official_brand_url": "https://winbet.com",
    "update_url": {
      "ios": "https://apps.apple.com/app/idXXXX",
      "android": "https://download.example/app-v4.apk"
    },
    "resolve_enabled": true,
    "cutover_bundle": "2026-brand-v2"
  }
}

Response 强制更新（客户端不得继续 resolve）

{
  "code": 40310,
  "message": "force_update",
  "data": { "...同上 update_url..." }
}

服务端判定顺序

1. 签名校验 → 403
2. semver(AppVersion) < min_version → 40310
3. force_update=true 且 AppVersion < latest_version → 40310
4. brand_pack 本地版本 < required_brand_pack → 40310
5. 通过 → code=0

配置中心键（切流 T 日一键改）

客户端实现要点

1. Splash → bootstrap（超时 5s，失败重试 2 次）
2. code=40310 → 全屏 ForceUpdateActivity（禁返回键 / 禁侧滑）
3. code=0 → 比对 brand_pack_version，加载包内或 CDN 主题资源
4. 再进入 §2.3.10 A1～A5
5. resolve 若仍返回 40310 → 同全屏强更（双保险）

4.4.4 Site 健康检查

HEAD https://{site}/__health
→ 200 {"ok":true,"ts":1735689600}

4.5 加密方案

4.6 客户端轮询与域名切换（完整方案）

目标： 单域 regional 失败时 ≤3s 自动切下一域；全失败 ≤10s 内重拉 Resolve；运行期故障 无感切换。

4.6.1 名词与本地缓存

持久化（H5）： sessionStorage（优先）+ localStorage 备份；键名 vty_ds_v1。
持久化（App）： Keychain / EncryptedSharedPreferences；键名 vty.baseUrl.v1。

4.6.2 状态机

                    ┌─────────────┐
                    │   INIT      │
                    └──────┬──────┘
                           │ 有未过期 resolve_meta?
              ┌────────────┼────────────┐
              ▼ yes                     ▼ no
     ┌────────────────┐        ┌────────────────┐
     │ LOAD_CACHED    │        │ FETCH_RESOLVE  │
     └───────┬────────┘        └───────┬────────┘
             │                         │
             └──────────┬──────────────┘
                        ▼
               ┌────────────────┐
               │ PROBE_LIST     │  按序探活 domain_list
               └───────┬────────┘
                       │ 有 ok 域?
          ┌────────────┼────────────┐
          ▼ yes                     ▼ no
 ┌─────────────────┐      ┌─────────────────┐
 │ ENTER_SITE      │      │ RETRY_RESOLVE   │  最多 3 轮
 └────────┬────────┘      └────────┬────────┘
          │                          │ 仍失败
          │                          ▼
          │                 ┌─────────────────┐
          │                 │ MAINTENANCE_UI  │
          │                 └─────────────────┘
          ▼
 ┌─────────────────┐
 │ RUNNING         │  业务运行 + 后台探活
 └────────┬────────┘
          │ 当前域失败
          ▼
 ┌─────────────────┐
 │ FAILOVER        │  切列表下一域 或 RETRY_RESOLVE
 └─────────────────┘

4.6.3 阶段一：冷启动 / 品牌进入（H5）

Resolve 重试（RETRY_RESOLVE）： 最大 3 轮 · 间隔 2s · 仍失败 → MAINTENANCE_UI。

4.6.4 PROBE_LIST：域名探活（H5 / App 共用）

对 domain_list 按服务端返回顺序依次探活：

for i, domain in enumerate(domain_list):
  result = probe(domain)   # 单次 ≤3s，不重试
  if result.ok:
    current_domain = domain
    persist(...)
    return SUCCESS
return FAIL

4.6.5 阶段二：运行期 FAILOVER

触发（任一）： 当前域 API 连续 3 次失败 · /__health 2 次失败（30s 间隔）· 主接口超时 >5s 且重试仍失败 · WebView onReceivedError。

流程： 标记 local_bad → probe 列表下一域 → 成功则切换并上报 domain_switch → 无 ok 域则 RETRY_RESOLVE（2 轮）→ 仍失败 MAINTENANCE_UI。

后台探活： 每 5min HEAD 当前域；App/H5 回前台 立即探活 1 次。

4.6.6 App 冷启动差异

先读 Keychain current_domain → probe 1 次；成功且 meta 未过期则 跳过 resolve；否则 app/resolve + PROBE_LIST。expires 默认 300s，过期前 60s 后台静默 refresh。

4.6.7 服务端探活 Worker

4.6.8 切换场景速查

4.6.9 SDK 配置常量（实现必须对齐）

const CFG = {
  probeTimeoutMs: 3000,
  probeListBudgetMs: 9000,
  resolveMaxRounds: 3,
  resolveBackoffMs: 2000,
  runningProbeIntervalMs: 300000,
  apiFailThreshold: 3,
  healthFailThreshold: 2,
  resolveTtlSec: 300,
  resolveRefreshBeforeExpirySec: 60,
};

4.6.10 轮询埋点（必填）

4.10 前端异常提示规范（完整文案 · 技术/UI 直接实现）

截图 Demo： demos/h5-error-states.html（430px 首页/登录 · 全部态）

4.10.1 UI 形态定案

4.10.2 文案表（i18n key · zh-CN / vi-VN 定稿）

语言包路径约定： locales/zh-CN/gate.json、locales/vi-VN/gate.json、locales/{lang}/app.json
切换规则： Accept-Language → 用户设置 → 默认 zh-CN；key 完全一致，仅 value 不同。

zh-CN（简体中文）

{
  "gate.connecting": "正在连接最佳线路…",
  "gate.switching_line": "当前线路响应较慢，正在为您切换备用线路…",
  "gate.switched_line": "网络异常，已为您切换至备用线路",
  "gate.unavailable_title": "暂时无法连接",
  "gate.unavailable_body": "网络或服务繁忙，请稍后重试。若持续无法访问，请联系在线客服。",
  "gate.retry": "重新连接",
  "gate.contact": "联系客服",
  "gate.load_fail_title": "加载失败",
  "gate.load_fail_body": "页面数据异常，请刷新重试。如问题仍存在，请清除浏览器缓存后再试。",
  "gate.refresh": "刷新重试",
  "gate.rate_limit_title": "访问过于频繁",
  "gate.rate_limit_body": "请 1 分钟后再试。",
  "gate.retry_later": "稍后重试",
  "app.force_update_title": "请更新至最新版本",
  "app.force_update_body": "品牌服务已升级，当前版本无法继续使用。请更新 App 后重新打开。",
  "app.go_store": "立即更新"
}

vi-VN（Tiếng Việt · 越南语）

{
  "gate.connecting": "Đang kết nối tuyến tốt nhất…",
  "gate.switching_line": "Tuyến hiện tại phản hồi chậm, đang chuyển sang tuyến dự phòng…",
  "gate.switched_line": "Mạng bất thường, đã chuyển sang tuyến dự phòng",
  "gate.unavailable_title": "Tạm thời không thể kết nối",
  "gate.unavailable_body": "Mạng hoặc dịch vụ đang bận, vui lòng thử lại sau. Nếu vẫn không truy cập được, hãy liên hệ CSKH trực tuyến.",
  "gate.retry": "Kết nối lại",
  "gate.contact": "Liên hệ CSKH",
  "gate.load_fail_title": "Tải thất bại",
  "gate.load_fail_body": "Dữ liệu trang bất thường, vui lòng làm mới và thử lại. Nếu vẫn lỗi, hãy xóa bộ nhớ đệm trình duyệt rồi thử lại.",
  "gate.refresh": "Làm mới và thử lại",
  "gate.rate_limit_title": "Truy cập quá thường xuyên",
  "gate.rate_limit_body": "Vui lòng thử lại sau 1 phút.",
  "gate.retry_later": "Thử lại sau",
  "app.force_update_title": "Vui lòng cập nhật phiên bản mới nhất",
  "app.force_update_body": "Dịch vụ thương hiệu đã nâng cấp, phiên bản hiện tại không thể tiếp tục sử dụng. Vui lòng cập nhật App rồi mở lại.",
  "app.go_store": "Cập nhật ngay"
}

中越对照速查（供 UI 走查）

E-GATE-01 中越一致：空页，无任何用户文案。

进站后： 地址栏 = 主站域；业务 API 基址 = https://{current_domain}。

4.10.5 报错归属域规则（落地域 vs 主站域）

实现约束：

// 落地域 bootstrap 内
const ERROR_DOMAIN = 'landing'; // location.hostname === LANDING_FQDN

function showError(code) {
  if (getPhase() === 'landing') {
    // 判定失败：不 location 到 play-*.com
    renderOnLandingShell(code);
    return;
  }
  renderOnSiteShell(code); // 主站域报错
}

function onProbeSuccess(siteFqdn) {
  location.replace('https://' + siteFqdn + '/?hop=' + hopId);
  // 此后 phase = 'site'
}

4.10.3 展示页面规则

4.10.4 禁止文案（安全）

• 不得出现：「IP 被封」「指纹异常」「域名池」「40301」
• 不得出现具体 Site 域名
• Gate 失败不得用「访问受限」全屏（仅允许空页）

4.11 轮询过程 UI 与提示（逐步映射）

「重新连接」： 清空 resolve_meta + local bad → INIT 重跑。
「联系客服」： 跳转 Site 客服路由或配置中心备用外链。

4.7 分享 Resolve

• GET /api/v1/resolve/current-site（鉴权）→ 返回与 Resolve 同一 is_primary。
• 用户短链 GET /{code} → 302 当前 Site。

4.8 埋点字段

4.9 分期排期

五、测试方案

测试职责一句话： 按 P0 用例验收 品牌零内容、双检空页、加密 3 域、轮询切换、App 403、池合并一致；P0 全过方可上线。

5.1 测试策略

5.2 P0 用例（必须全过）

品牌域与 Gate

Resolve 与加密

客户端轮询

前端异常提示（§4.10 / §4.11）

App

探活与运维

安全审视（§2.8）

埋点

5.3 P1 用例

成功率 KPI 验收（相对 vty.vip）

5.4 自动化建议

// Playwright 示例
test('brand zero content', async ({ request }) => {
  const r = await request.get('https://winbet.com/', { maxRedirects: 0 });
  expect(r.status()).toBe(301);
  expect(r.headers()['location']).toMatch(/gate\./);
});

test('headless gets empty gate', async ({ browser }) => {
  const ctx = await browser.newContext({ userAgent: 'HeadlessChrome' });
  const page = await ctx.newPage();
  await page.goto('https://gate.example/r/winbet');
  const body = await page.content();
  expect(body.replace(/\s/g, '')).toBe('<html><head></head><body></body></html>');
});

5.5 验收签字

附录

A. RACI

B. 开放问题

D. 名词数据字典（Glossary）

用途： 产品 / 运维 / 前端 / 后端 / App / 测试 统一口径；工单、埋点、接口字段、会议沟通均以此为准。
约定： 「中文名」为口头沟通首选；「英文/代码名」为实现与 JSON 字段；勿混用 Gate 与落地域（Gate=服务，Landing=域名角色）。

D.1 域名角色（五层）

易混辨析：

D.2 入口与归因

D.3 域名池（site_domain_pool）

D.4 客户端/SDK 运行时对象

resolve_meta 结构：

{
  "payload": "<加密串>",
  "expires_at": 1735689900,
  "hop_id": "hop_8f3k2j",
  "key_id": "k2026-03",
  "resolved_at": 1735689600,
  "domain_list": ["play-a.com", "play-b.com", "play-c.com"]
}

D.5 接口与 API

D.6 风控与评分

D.7 加密与密钥

D.8 SDK 状态机

D.9 前端异常文案（UI ID）

i18n 前缀：gate.*（H5 落地/主站壳）、app.*（App 强更）。已支持语言： zh-CN、vi-VN（§4.10.2）。

D.10 App 版本与皮肤

D.11 埋点事件（核心）

fail_stage 常用值： brand_dns / landing_unreachable / gate_ip / gate_fp / resolve / decrypt / probe / enter

D.12 运维与 CDN

D.13 缩写与项目代号

D.14 端到端一句话（各端对齐用）

C. 修订记录

文档结束。