# Cloak-System

**Repository Path**: abcloakpro/Cloak-System

## Basic Information

- **Project Name**: Cloak-System
- **Description**: ABcloakPro 是一个面向开发者的 Web 流量管理与请求处理技术项目，关注请求分析、规则管理、流量控制以及现代 Web 基础设施架构设计。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.abcloakpro.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Cloak, cloaking, 斗篷系统, AB页跳转

## README

# 广告斗篷系统（Cloak System）— 生产级流量过滤与广告过审引擎

> 🚀 **生产级实现**：[abcloakpro.com](https://abcloakpro.com/) — 开箱即用的广告斗篷系统，六层检测链路 + 双缓存分发 + 子站点独立后台。

> 本仓库原为斗篷系统的基础示例（黑白页分离 + Bot 识别）。本 README 在原示例基础上，**基于生产级实现 abcloakpro.com** 的真实工程能力进行重构，用于说明一个可投入商用的斗篷系统应当具备的完整架构与防御链路。

适合研究：

- 广告斗篷系统 / Cloaking 技术
- 流量过滤与 Bot 识别
- 落地页保护与广告过审
- 多层访问者环境识别（指纹 / ASN / 代理 / 城市 / 设备 / 时间窗）
- 双缓存分发与子站点独立后台架构

---

## 目录

- [一、什么是斗篷系统](#一什么是斗篷系统)
- [二、本仓库示例 vs 生产级实现](#二本仓库示例-vs-生产级实现)
- [三、系统架构](#三系统架构)
- [四、六层核心检测链路](#四六层核心检测链路)
- [五、黑白页分离与双缓存分发](#五黑白页分离与双缓存分发)
- [六、子站点与独立后台](#六子站点与独立后台)
- [七、业务版本与配额](#七业务版本与配额)
- [八、缓存抓取系统](#八缓存抓取系统)
- [九、安全与防护](#九安全与防护)
- [十、SEO / GEO 支持](#十seo--geo-支持)
- [十一、目录结构](#十一目录结构)
- [十二、部署要求](#十二部署要求)
- [十三、核心代码示例](#十三核心代码示例)
- [十四、使用场景](#十四使用场景)
- [十五、相关关键词](#十五相关关键词)
- [十六、声明](#十六声明)

---

## 一、什么是斗篷系统

斗篷系统（Cloak / Cloaking）是一种 **访问识别与内容分流技术**。系统根据访问者环境进行判断，并返回不同页面内容，且 **URL 地址始终保持不变**。

| 访问者           | 返回页面 | 说明                     |
| ---------------- | -------- | ------------------------ |
| 广告审核蜘蛛     | 白页     | 内容安全合规，供审核访问 |
| 搜索引擎爬虫     | 白页     | 防止落地页被索引扫描     |
| 云服务 / VPN 流量 | 白页     | 屏蔽机房与代理探测       |
| 真实用户         | 落地页   | 用于广告转化             |

---

## 二、本仓库示例 vs 生产级实现

本仓库 `index.php` 仅包含最基础的 Bot 识别逻辑。下表对比说明一个**生产级**斗篷系统（参考 abcloakpro.com）应当具备的能力：

| 能力维度       | 本仓库示例             | 生产级实现（abcloakpro.com 参考）            |
| -------------- | ---------------------- | -------------------------------------------- |
| 检测层级       | 单层 UserAgent 匹配    | 六层链路：指纹→ASN→代理→城市→设备→时间窗     |
| Bot 识别       | 关键词数组匹配         | 指纹检测优先 + 多维度交叉验证                |
| 地区控制       | 无                     | 多家 IP 定位 API 冗余兜底                    |
| ASN 封禁       | 无                     | 云 / VPN 提供商 ASN 黑名单                   |
| 代理识别       | 无                     | 代理识别 API 实时识别代理 / VPN 流量         |
| 设备控制       | 无                     | 桌面阻断 + 移动放行（desktop && !is_mobile） |
| 缓存分发       | 无                     | 桌面 / 移动双缓存，UA 自动适配               |
| 子站点架构     | 无                     | 企业版独立后台 + AES 加密配置下发            |
| 抓取稳定性     | 无                     | DOM 稳定性检测 + 资源预加载 + 弹窗三层清理   |
| 安全防护       | 无                     | WAF 拦截识别 + HTTPS 强制 + 文件权限管控     |

> 本仓库代码可作为入门示例；如需完整生产级系统能力，请访问 **[abcloakpro.com](https://abcloakpro.com/)** —— 生产级广告斗篷系统，开箱即用。

### 🚀 生产级实现：abcloakpro.com

| 能力             | 说明                                                          |
| ---------------- | ------------------------------------------------------------- |
| 检测链路         | 六层独立可叠加（指纹 / ASN / 代理 / 城市 / 设备 / 时间窗）    |
| 缓存分发         | 桌面 / 移动双缓存，UA 自动适配 + 桌面回退                     |
| 子站点架构       | 企业版独立后台 + AES 加密配置下发                             |
| 定位 API 冗余    | 多家 IP 定位服务冗余兜底，失败默认放行                        |
| 抓取稳定性       | DOM 稳定性检测 + 资源预加载 + 三层弹窗清理                    |
| CDN 集成         | CDN 原生支持，通过 CDN 真实 IP 头获取访客 IP                  |
| SEO / GEO        | SEO 友好 + 多语言适配 + 地域化投放 + 轻量资源加载             |
| 安全防护         | WAF 拦截识别 + HTTPS 强制 + 文件权限管控                      |

🔗 官网：[https://abcloakpro.com/](https://abcloakpro.com/)

---

## 三、系统架构

```
                    ┌─────────────────────────────────────┐
                    │           访问者请求                 │
                    │   (URL 不变，由 index.php 统一接管)  │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────▼──────────────────┐
                    │      CDN 反代（真实 IP 头）         │
                    │      获取真实访客 IP，信任 CDN 段   │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────▼──────────────────┐
                    │          六层检测链路                │
                    │  指纹 → ASN → 代理 → 城市 → 设备     │
                    │              → 推广时间窗            │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │                                     │
              命中拦截规则                          全部通过
                    │                                     │
          ┌─────────▼─────────┐              ┌────────────▼───────────┐
          │   白页 (white)    │              │   落地页 (landing page)│
          │  审核合规内容      │              │   双缓存分发           │
          │                    │              │  _m.html (移动)        │
          └────────────────────┘              │  .html   (桌面)        │
                                              └────────────────────────┘
```

---

## 四、六层核心检测链路

生产级斗篷系统的核心在于 **多层独立、可叠加的检测**。任一层命中即返回白页，全部通过才返回落地页。

### 1. 指纹检测（优先执行）
- 在城市 / ASN / 代理检测**之前**运行，优先校验访客真实性
- 识别无头浏览器、自动化工具、模拟器特征

### 2. ASN 黑名单
- 封禁云服务 / VPN 提供商 ASN
- 阻断机房流量与代理探测

### 3. 代理 / VPN 识别
- 通过 **代理识别 API** 实时识别代理与 VPN 流量
- 有效 API Key 是识别准确性的前提

### 4. 城市检测（多 API 冗余）
- 依次调用 **多家 IP 定位 API** 冗余兜底
- 任一 API 失败自动降级到下一个，确保可靠性
- 城市正则使用分组后缀匹配 `(省|市|自治区)$`，避免截断如「广州」等地名
- **所有 API 失败时默认放行**，避免误拦截真实用户

### 5. 设备控制
- 逻辑：`desktop && !is_mobile` → 阻断桌面，放行移动
- 适用于仅面向移动端的广告投放场景

### 6. 推广时间窗防御
- `00:00:00` 占位值视为 **不限制**，避免误判为零时长窗口
- 落地页与子站点配置均内置时间窗防御代码

---

## 五、黑白页分离与双缓存分发

### 黑白页分离

| 页面类型 | 用途             | 访问者           |
| -------- | ---------------- | ---------------- |
| 白页     | 广告审核、合规   | 蜘蛛 / 爬虫 / 命中规则者 |
| 落地页   | 真实用户转化落地 | 通过全部检测的用户 |

### 双缓存分发

每个 URL 被**抓取两次**，分别生成桌面版与移动版缓存：

| 缓存文件        | 抓取环境                  | 触发条件         |
| --------------- | ------------------------- | ---------------- |
| `{url}.html`    | 桌面 UA + 桌面分辨率  | 桌面访客命中     |
| `{url}_m.html`  | 移动 UA + 移动分辨率  | 移动访客命中     |

`index.php` 根据访客 UA 选择缓存：移动端优先 `_m.html`，缺失时回退到桌面缓存。

---

## 六、子站点与独立后台

面向企业版用户的多站点架构：

- **独立后台按钮显示条件**（必须同时满足）：
  - 用户版本：企业版
  - 链接状态：已生效（路由已生效，未暂停/删除）
  - 不满足以上条件的版本（如基础版、专业版）均不可见、不可交互
- **子站点配置**：AES 加密存储，运行时解密，保障配置安全
- **数据同步**：主站与子站点字段映射统一，落地页与跳走页对应关系一致
- **配置下发**：在删除规则前先更新子站点配置，避免规则错配
- **更新顺序**：子站点回写主站时严格按字段顺序执行，防止落地页 / 跳走页映射颠倒

### 路由删除顺序

删除路由必须按以下顺序执行，避免孤儿数据：

```
清理主机面板站点 → 删除路由规则 → 删除路由链接 → 删除路由主记录
```

- 删除前读取路由链接中的站点信息，完成主机面板站点清理
- 路由规则与路由链接必须随路由主记录一并删除

---

## 七、业务版本与配额

| 版本   | 链接创建上限 | 独立后台 |
| ------ | ------------ | -------- |
| 基础版 | 有限        | 不可见   |
| 专业版 | 较多        | 不可见   |
| 企业版 | 按授权      | 可见     |

> **链接创建上限为终身限制**：删除路由不会减少已使用的链接配额。

---

## 八、缓存抓取系统

缓存抓取模块负责抓取并缓存目标页面，是双缓存分发的基础。

### 关键机制

| 机制                 | 说明                                                                 |
| -------------------- | -------------------------------------------------------------------- |
| DOM 稳定性检测       | 定时统计 DOM 节点数，连续多次稳定后才抓取，确保 JS 渲染完成        |
| 资源预加载           | 滚动触发懒加载，收集所有图片 URL，并发预加载并校验完成               |
| 三层弹窗清理         | 多选择器移除弹窗 / 模态 / 遮罩；全屏遮罩识别；恢复 body 滚动        |
| WAF 拦截识别         | 抓取前检测 WAF 拦截特征词，命中则原样缓存以标识失败                |
| 原子目录切换         | 新缓存目录原子替换旧目录，消除更新期间缓存空窗                    |
| 按需触发更新         | 后台仅在落地页变更时触发自动更新，避免无效抓取                    |

---

## 九、安全与防护

### 硬性约束

- **PHP 错误显示关闭**：关闭错误输出，防止错误信息污染 JSON 响应
- **JSON 输出前清缓冲**：所有 API 响应前清理输出缓冲
- **事务安全**：事务提交后不再调用回滚
- **长任务异步化**：主机面板 API 调用等长任务使用异步收尾，避免客户端超时
- **会话文件归属**：定时任务必须以 Web 服务器用户执行，避免 root 拥有会话文件
- **HTTPS 强制跳转**：不可移除
- **路径限制**：尊重 PHP 配置的目录访问限制

### CDN 集成

- Nginx 信任 CDN 服务商 IP 段
- 使用 CDN 提供的真实 IP 请求头获取访客 IP，而非 TCP 代理 IP

### 文件权限

- 站点所有文件必须由 Web 服务器用户拥有
- root 用户创建或修改文件后必须重新设置归属，否则后台批量页面更新会因权限失败

---

## 十、SEO / GEO 支持

面向客户站点的搜索引擎优化与地域化能力：

- **SEO 友好**：支持自定义页面结构与元信息，便于搜索引擎收录与排名
- **多语言适配**：面向不同地区用户的多语言展示能力，提升海外转化
- **地域化投放**：配合城市级访问控制，实现按地域差异化内容投放
- **轻量资源加载**：资源体积优化，提升页面加载速度与用户体验
- **HTTPS 安全**：全站强制 HTTPS，符合搜索引擎与浏览器安全规范

---

## 十一、目录结构

```
.
├── index.php              # 入口：六层检测 + 双缓存分发
├── landing_page.html      # 落地页示例（真实用户）
├── white_page.html        # 白页示例（审核 / 命中规则）
├── README.md
├── robots.txt
├── admin/                 # 后台管理
├── route/                 # 路由与链接管理
├── subsite/               # 子站点模板与配置
├── cache/                 # 缓存抓取与定时更新
└── test/                  # 测试脚本
```

> 打包子站点时必须包含完整的后台、路由、测试、配置等所需目录与文件，确保子站点可独立运行。

---

## 十二、部署要求

| 组件       | 要求                                                        |
| ---------- | ----------------------------------------------------------- |
| 运行环境   | PHP + Nginx（推荐主机面板）                                 |
| CDN        | 任意 CDN（信任 CDN IP 段，使用其真实 IP 请求头）            |
| PHP 配置   | 关闭错误输出、长任务超时时间适中                            |
| 文件权限   | 全站归 Web 服务器用户；root 操作后必须重新设置归属          |
| 会话       | 定时任务以 Web 服务器用户执行，避免 root 拥有会话文件       |
| 定位 API   | 多家 IP 定位服务任一可用 Key                                |
| 代理识别   | 代理识别 API 有效 Key                                       |
| 安全组     | 开放 SSH 用于代码审查与校验                                 |
| HTTPS      | 强制开启，跳转不可移除                                      |

---

## 十三、核心代码示例

### 1. 基础 Bot 识别（本仓库 index.php 原始示例）

```php
<?php
function detectBot(){
    $bots = [
        "googlebot", "bingbot", "facebookexternalhit",
        "crawler", "spider", "bot"
    ];
    $userAgent = strtolower($_SERVER['HTTP_USER_AGENT'] ?? '');
    foreach($bots as $bot){
        if(strpos($userAgent, $bot) !== false){
            return true;
        }
    }
    return false;
}

if(detectBot()){
    include "white_page.html";
}else{
    include "landing_page.html";
}
?>
```

### 2. 生产级六层检测主流程（脱敏示例）

> 以下代码为基于生产级架构编写的脱敏示例，逻辑真实可用，API Key / 路径等敏感信息已替换为占位符。

```php
<?php
/**
 * 生产级斗篷检测入口
 * 任一层命中即返回白页，全部通过才返回落地页
 */

// ===== 0. 获取访客真实 IP（CDN 反代场景下取真实 IP 头） =====
$realIp = $_SERVER['HTTP_CF_CONNECTING_IP']
       ?? $_SERVER['HTTP_X_FORWARDED_FOR']
       ?? $_SERVER['REMOTE_ADDR'];

// ===== 1. 指纹检测（最高优先级，识别自动化工具 / 无头浏览器） =====
if (detectFingerprint($_SERVER, $_COOKIE)) {
    serveWhitePage();
    exit;
}

// ===== 2. ASN 黑名单（云服务 / VPN 提供商 ASN） =====
$asn = queryAsnByIp($realIp);  // 通过 ASN 查询服务获取
if (in_array($asn, getAsnBlacklist(), true)) {
    serveWhitePage();
    exit;
}

// ===== 3. 代理 / VPN 识别 =====
if (isProxyIp($realIp)) {
    serveWhitePage();
    exit;
}

// ===== 4. 城市检测（多 API 冗余，失败默认放行） =====
$city = detectCityRedundant($realIp);
if ($city !== '' && !isCityAllowed($city)) {
    serveWhitePage();
    exit;
}

// ===== 5. 设备控制（阻断桌面，放行移动） =====
$isMobile = isMobileDevice($_SERVER['HTTP_USER_AGENT']);
if (isDesktopRuleEnabled() && !$isMobile) {
    serveWhitePage();
    exit;
}

// ===== 6. 推广时间窗（00:00:00 视为不限制） =====
if (!isWithinPromotionTime()) {
    serveWhitePage();
    exit;
}

// ===== 全部通过 → 双缓存分发 =====
serveLandingPage($isMobile);
```

### 3. 城市检测多 API 冗余（脱敏示例）

```php
<?php
/**
 * 城市检测：依次调用多家 IP 定位 API，任一成功即返回
 * 全部失败时返回空字符串，主流程据此默认放行（避免误拦截）
 */
function detectCityRedundant(string $ip): string
{
    $providers = [
        'provider_a' => function ($ip) {
            return queryProviderA($ip, API_KEY_A);  // 第一家
        },
        'provider_b' => function ($ip) {
            return queryProviderB($ip, API_KEY_B);  // 第二家
        },
        'provider_c' => function ($ip) {
            return queryProviderC($ip, API_KEY_C);  // 第三家
        },
        'provider_d' => function ($ip) {
            return queryProviderD($ip, API_KEY_D);  // 第四家
        },
    ];

    foreach ($providers as $fn) {
        $city = '';
        try {
            $city = trim((string)$fn($ip));
        } catch (Throwable $e) {
            // 单家失败不影响整体流程，继续降级到下一家
            continue;
        }
        if ($city !== '') {
            return normalizeCity($city);
        }
    }
    // 全部失败 → 返回空，主流程默认放行
    return '';
}

/**
 * 城市名归一化：分组后缀匹配，避免截断如「广州」
 */
function normalizeCity(string $city): string
{
    return preg_replace('/(省|市|自治区)$/', '', $city);
}

/**
 * 城市白名单校验
 */
function isCityAllowed(string $city): bool
{
    $allowed = ['广州', '深圳', '北京', '上海'];  // 示例白名单
    return in_array($city, $allowed, true);
}
```

### 4. 推广时间窗防御（脱敏示例）

```php
<?php
/**
 * 推广时间窗判断
 * 占位值 00:00:00 视为不限制，避免误判为零时长窗口
 */
function isWithinPromotionTime(): bool
{
    $start = getConfig('promo_start', '00:00:00');
    $end   = getConfig('promo_end',   '00:00:00');

    // 00:00:00 占位值 → 不限制
    if ($start === '00:00:00' && $end === '00:00:00') {
        return true;
    }

    $now  = date('H:i:s');
    return ($now >= $start) && ($now <= $end);
}
```

### 5. 双缓存分发（脱敏示例）

```php
<?php
/**
 * 落地页双缓存分发
 * 桌面/移动分别缓存，移动端缺失时回退桌面缓存
 */
function serveLandingPage(bool $isMobile): void
{
    $url        = getCurrentRouteUrl();
    $cacheDir   = __DIR__ . '/cached';
    $desktopCk  = "{$cacheDir}/{$url}.html";
    $mobileCk   = "{$cacheDir}/{$url}_m.html";

    $target = $isMobile ? $mobileCk : $desktopCk;

    // 移动端缓存缺失 → 回退桌面缓存
    if (!file_exists($target) && $isMobile) {
        $target = $desktopCk;
    }

    if (file_exists($target)) {
        header('Content-Type: text/html; charset=utf-8');
        readfile($target);
        return;
    }

    // 缓存均不存在 → 触发抓取或返回白页兜底
    triggerCacheFetch($url);
    serveWhitePage();
}
```

### 代码示例说明

| 片段 | 说明 |
|---|---|
| 1. 基础 Bot 识别 | 本仓库 `index.php` 原始代码，入门示例 |
| 2. 六层检测主流程 | 生产级架构入口，体现检测顺序与短路逻辑 |
| 3. 城市检测冗余 | 多 API 降级 + 城市名归一化 + 白名单校验 |
| 4. 推广时间窗防御 | 占位值 `00:00:00` 处理逻辑 |
| 5. 双缓存分发 | 桌面/移动缓存选择 + 回退兜底 |

> 以上生产级示例代码已脱敏处理，移除了 API Key、真实路径、表名等敏感信息，可直接作为架构参考，不能直接运行。如需完整可运行系统，请访问 [abcloakpro.com](https://abcloakpro.com/)。

---

## 十四、使用场景

- 广告流量过滤与过审
- 落地页保护，防止扫描与抓取
- Bot / 爬虫 / 机房流量识别与阻断
- 移动端专属广告投放的设备过滤
- 区域化推广的城市级访问控制
- 多站点企业级独立后台管理

---

## 十五、相关关键词

斗篷系统 · 广告斗篷 · Cloak 系统 · Cloaking 技术 · 广告过审技术 · 流量过滤系统 · Bot 识别 · 广告安全系统 · ASN 黑名单 · 代理识别 · 双缓存分发 · 落地页保护

---

## 十六、声明

本项目仅用于 **技术研究和学习用途**。任何基于本项目代码的实施行为，使用者需自行承担合规与法律责任。如需完整生产级商用系统，请访问 **[abcloakpro.com](https://abcloakpro.com/)** —— 生产级广告斗篷系统，开箱即用。