cfspider 1.9.0
Cloudflare Workers proxy IP pool client
License: Apache-2.0
Requires Python: >=3.8
Keywords: cloudflare, workers, proxy, spider, scraper, crawler

﻿# CFspider - Cloudflare Workers Spider

[![PyPI version](https://img.shields.io/pypi/v/cfspider)](https://pypi.org/project/cfspider/)
[![Python](https://img.shields.io/pypi/pyversions/cfspider)](https://pypi.org/project/cfspider/)
[![License](https://img.shields.io/github/license/violettoolssite/CFspider)](LICENSE)

**v1.9.0** - 基于 Cloudflare Workers 的免费代理 IP 池，支持 **VLESS 协议**（完全隐藏特征）和 **HTTP 代理**（轻量爬虫），利用全球 300+ 边缘节点作为出口，支持隐身模式、TLS 指纹模拟、网页镜像和浏览器自动化。

---

## v1.9.0 重大更新：双模式 Workers + 一键自动部署

> **无需手动部署！** 只需 API Token 和 Account ID，即可自动创建、部署和管理 Cloudflare Workers。
> 
> **新增双模式选择：** VLESS 模式（完全隐藏特征）或 HTTP 模式（轻量爬虫）

```python
import cfspider

# 方式 1：运行时交互式选择模式
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id"
)
# 运行后弹出选择菜单：[1] VLESS模式  [2] HTTP模式

# 方式 2：代码中指定 VLESS 模式（代理软件推荐）
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id",
    mode='vless'  # 完全隐藏 CF 特征
)

# 方式 3：代码中指定 HTTP 模式（爬虫推荐）
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id",
    mode='http'  # 轻量快速，随机 UA/Referer
)

# 直接使用代理
response = cfspider.get("https://httpbin.org/ip", cf_proxies=workers)
print(response.json())  # 显示 Cloudflare IP
```

**核心特性：**

| 功能 | 说明 |
|------|------|
| **双模式选择** | VLESS（隐藏特征）或 HTTP（轻量爬虫），运行时选择或代码指定 |
| **一键部署** | 自动创建 Workers，无需手动复制代码 |
| **自动重建** | Workers 失效时自动重新创建（保持相同模式） |
| **环境变量** | 支持 UUID、PROXYIP、KEY 等配置 |
| **自定义域名** | 支持 `my_domain` 参数自动配置域名 |

**获取 API Token 和 Account ID：**

1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com)
2. **Account ID**：Workers & Pages → 右侧边栏
3. **API Token**：头像 → My Profile → API Tokens → Create Token → 选择 "Edit Cloudflare Workers"

**完整参数：**

```python
workers = cfspider.make_workers(
    api_token="xxx",           # Cloudflare API Token（必需）
    account_id="xxx",          # Account ID（必需）
    uuid="your-uuid",          # VLESS UUID（可选）
    proxyip="1.2.3.4",         # 优选 IP（可选，支持多个逗号分隔）
    key="encrypt-key",         # 加密密钥（可选）
    accesskey="access-key",    # 访问密钥（可选）
    my_domain="proxy.example.com",  # 自定义域名（可选）
    auto_recreate=True,        # 失效自动重建（默认 True）
)

# 返回对象属性
print(workers.url)            # Workers URL
print(workers.uuid)           # UUID
print(workers.healthy)        # 健康状态
print(workers.custom_url)     # 自定义域名 URL
```

---

### 致谢

本项目的 VLESS 协议实现借鉴了 [edgetunnel](https://github.com/cmliu/edgetunnel) 项目，感谢 [@cmliu](https://github.com/cmliu) 的开源贡献。

---

## 重要：破皮版 Workers（增强反检测）

> **如果你的 Workers 被 Cloudflare 检测封禁（错误代码 1101），请使用 `workers/破皮版workers.js`！**
>
> 所有 Workers 脚本文件位于 `workers/` 目录下。

### 安全警告

**强烈建议使用 Cloudflare 小号部署！** 代理类 Workers 存在被 Cloudflare 检测封禁的风险：

- **不要使用主账号**：主账号被封禁可能导致所有服务（域名、DNS、CDN）受影响
- **注册专用小号**：使用临时邮箱注册一个专门用于部署代理的 Cloudflare 账号
- **小号被封无损失**：即使被封禁也不会影响你的主要业务
- **代码仍有风险**：破皮版虽经混淆处理，但无法保证 100% 不被检测

**推荐使用 [公益平台临时邮箱](https://free.violetteam.cloud/) 注册小号**，无需真实邮箱，用完即弃。

### 破皮版特性

| 特性 | 说明 |
|------|------|
| **伪装首页** | 根路径 `/` 显示 Nginx 默认欢迎页面，伪装成普通 HTTP 服务器 |
| **隐藏入口** | 真实 API 需访问 `/x2727admin` 路径获取访问密钥 |
| **双重验证** | 需先获取密钥，再访问 `/x2727admin/{密钥}` 获取数据 |
| **X27CN v2 加密** | 所有 API 响应使用动态密钥加密，需专用工具解密 |
| **代码混淆** | 全部代码压缩为单行，移除所有中文字符 |
| **降低特征** | 移除部分可被检测的关键词和特征模式（但无法完全消除风险） |

**快速使用：**

```bash
# 1. 使用小号登录 Cloudflare
# 2. 部署 workers/破皮版workers.js 到 Workers
# 3. 访问根路径会看到 Nginx 伪装页面
# 4. 访问 /x2727admin 获取加密的密钥提示
# 5. 使用解密工具（密钥: x27cn2026）解密获得访问密钥
# 6. 访问 /x2727admin/{你的密钥} 获取加密的配置
# 7. 使用解密工具（密钥: 你的密钥）解密获取 VLESS 链接
```

**自定义配置（环境变量）：**

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `UUID` | VLESS UUID（必需） | `xxxxxxxx-xxxx-4xxx-8xxx-xxxxxxxxxxxx` |
| `ACCESSKEY` | 自定义访问密钥（优先级最高） | `mykey123` |
| `ACCESS_KEY` | 自定义访问密钥（备选） | `mykey123` |
| `AKEY` | 自定义访问密钥（简写） | `mykey123` |
| `KEY` | X27CN 加密密钥（可选） | `x27cn2026` |
| `PROXYIP` | 优选 IP（可选，多个逗号分隔） | `proxyip.fxxk.dedyn.io` |
| `TWO_PROXY` | 双层代理（可选） | `host:port:user:pass` |

如果不设置 `ACCESSKEY`/`ACCESS_KEY`/`AKEY`，系统会基于你的 UUID 自动生成唯一的 8 位密钥。

**解密工具：** [https://x27cn.cfspider.com](https://x27cn.cfspider.com)

**完整部署流程：**

```
1. 注册 Cloudflare 小号（推荐使用临时邮箱）
2. 创建 Worker，粘贴 workers/破皮版workers.js 代码
3. 设置环境变量 UUID（必需）和其他可选变量
4. 部署 Worker，获取 Workers 地址
5. 访问 https://你的workers地址/ → 看到 Nginx 伪装页面
6. 访问 https://你的workers地址/x2727admin → 获取加密的密钥提示
7. 使用 https://x27cn.cfspider.com（密钥: x27cn2026）解密 → 获得访问密钥
8. 访问 https://你的workers地址/x2727admin/{你的密钥} → 获取加密配置
9. 使用解密工具（密钥: 你的密钥）解密 → 获取 VLESS 链接和配置
```

**X27CN 解密演示：**

![X27CN 解密获取 VLESS 链接](x27cn.gif)

> 使用 X27CN 在线工具解密破皮版加密数据，获取 VLESS 链接的完整流程演示

### Workers 双模式（v1.9.0 新增）

CFspider 现支持两种 Workers 模式，可通过 `mode` 参数选择：

| 模式 | 文件 | 特点 | CF特征头 | 适用场景 |
|------|------|------|----------|----------|
| **VLESS 模式** | `破皮版workers.js` | 完整代理功能 | **完全隐藏** | V2Ray/Clash 代理软件、敏感网站 |
| **HTTP 模式** | `爬楼梯workers.js` | 轻量 HTTP 代理 | 会暴露 | 普通网页爬虫、不严格检测的网站 |

**自动部署时选择模式：**

```python
import cfspider

# 方式 1：运行时交互式选择（推荐新手）
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id"
)
# 运行后会弹出菜单：
# [1] VLESS 模式 (推荐)
# [2] HTTP 模式 (轻量)

# 方式 2：代码中直接指定 VLESS 模式
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id",
    mode='vless'  # 破皮版，完全隐藏 CF 特征
)

# 方式 3：代码中直接指定 HTTP 模式
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id",
    mode='http'  # 爬楼梯版，轻量爬虫
)
```

**模式详细对比：**

| 特性 | VLESS 模式 | HTTP 模式 |
|------|-----------|-----------|
| Workers 文件 | `破皮版workers.js` | `爬楼梯workers.js` |
| Cloudflare 特征头 | 完全隐藏 | 暴露（Cf-Ray、Cf-Worker 等） |
| 代理软件支持 | 是（V2Ray、Clash） | 否 |
| 需要 UUID | 是（自动获取或手动指定） | 否 |
| 随机 User-Agent | 取决于客户端 | 是（35+ 浏览器） |
| 随机 Referer | 否 | 是（13+ 来源） |
| 随机 Accept-Language | 否 | 是（23+ 语言） |
| 首页伪装 | Nginx 页面 | 简洁状态页 |
| 检测风险 | 低 | 中（目标网站可识别来自 CF Workers） |
| 复杂度 | 需要 UUID | 简单 |
| 推荐场景 | 代理软件、严格检测网站 | 普通爬虫、快速测试 |

**安全提醒：** 无论选择哪种模式，都**强烈建议使用 Cloudflare 小号**部署！

### Workers 版本对比（手动部署）

| 版本 | 文件名 | 首页 | API入口 | 数据加密 | 密钥验证 | 适用场景 |
|------|--------|------|---------|----------|----------|----------|
| **爬楼梯版** | `workers/爬楼梯workers.js` | 状态页 | `/proxy` `/batch` | 无 | 可选TOKEN | **普通爬虫（推荐）** |
| **破皮版** | `workers/破皮版workers.js` | Nginx伪装 | `/x2727admin` | X27CN加密 | 需要密钥 | **代理软件（推荐）** |
| **标准版** | `workers/workers.js` | 配置页面 | `/api/*` | 无 | 无 | 开发测试 |
| **明文版** | `workers/破皮版workers_明文.js` | Nginx伪装 | `/x2727admin` | X27CN加密 | 需要密钥 | 代码学习 |
| **超明文版** | `workers/破皮版workers_超明文.js` | Nginx伪装 | `/admin` | 无 | 无 | 快速测试 |

**版本选择建议：**

- **普通爬虫**：使用 `workers/爬楼梯workers.js`，轻量快速，随机 UA/Referer
- **代理软件**：使用 `workers/破皮版workers.js`，VLESS 协议，隐藏 CF 特征
- **开发测试**：使用 `workers/workers.js` 标准版，配置页面方便调试
- **代码学习**：参考 `workers/破皮版workers_明文.js`，可读的完整代码

**爬楼梯版路由：**
```
/           → 状态页
/proxy?url=TARGET → 代理请求
/batch      → 批量请求（POST JSON）
/ip         → 查看出口 IP
/health     → 健康检查
```

**超明文版路由：**
```
/           → Nginx 伪装首页
/admin      → 完整配置信息 (明文JSON)
/config     → 基本配置信息 (明文JSON)
/uuid       → UUID信息 (JSON)
/vless      → VLESS链接 (纯文本)
/proxyip    → 代理IP信息 (JSON)
/help       → 帮助信息
```

---

## X27CN 加密库 (v1.4.3)

X27CN 是 CFspider 使用的代码混淆加密算法，现已作为独立 Python 库发布。支持文本加密、密码安全、代码混淆和反调试保护。

### 安装

```bash
pip install x27cn
```

### 快速使用

```python
import x27cn

# 加密文本
encrypted = x27cn.encrypt('Hello World')
decrypted = x27cn.decrypt(encrypted)

# 密码加密（更安全）
encrypted = x27cn.encrypt_with_password('敏感数据', 'mypassword')
decrypted = x27cn.decrypt_with_password(encrypted, 'mypassword')

# 混淆整个 HTML/JS/CSS 文件
x27cn.obfuscate_file('index.html')  # 生成 index.obf.html
x27cn.obfuscate_file('app.js')      # 生成 app.obf.js

# 一键完整保护（混淆 + 反爬）
protected = x27cn.full_obfuscate(js_code, level=3)
```

### 数字混淆（v1.4.3 新增）

使用 JavaScript 类型转换表达式，极难直接阅读：

```python
import x27cn

code = 'var x = 5; var y = 100;'
obfuscated = x27cn.obfuscate_numbers(code)
# 输出: var x = (((-~[])+(+!+[]))+((+!![])+(~~+!![])+([]>[]|+!![]))); 
#       var y = (((+!+[])+(+!![]))*(((-~[])+(+!![]))*(~~5)));
```

**表达式说明：**
- `(+[])` = 0, `(+!![])` = 1, `(-~[])` = 1
- 乘法分解、加法组合、位运算混合

### 反调试保护

```python
# 一键添加反调试
protected = x27cn.full_obfuscate(js_code, level=3)
# 包含：无限 debugger、禁用 F12、控制台清除

# 域名锁定
protected = x27cn.full_obfuscate(js_code, domain_lock=['example.com'])
```

### 命令行工具

```bash
# 一键保护（推荐）
x27cn protect app.js --level=3

# 混淆文件
x27cn obfuscate index.html

# 加密/解密文本
x27cn encrypt -t "Hello World"
x27cn decrypt -t "<faee><38db>..."
```

### 在线工具

访问 [X27CN 在线工具](https://x27cn.cfspider.com) 可直接在浏览器中进行加密/解密和代码混淆。

**防爬保护：** 在线工具集成滑块人机验证 + 行为检测，有效阻止自动化工具抓取页面内容。

### 安全说明

X27CN 设计用于**代码混淆**，不是密码学安全的加密算法。适用于前端代码保护、API 响应混淆、防止代码被轻易复制等场景。密码加密功能使用 PBKDF2-SHA256 算法。

---

## 支持 v2ray/Xray 客户端

> **CFspider Workers 支持标准 VLESS 协议**，可直接在 v2ray/Xray 客户端中使用！

部署 Workers 后，访问首页即可获取 VLESS 链接，支持导入到以下客户端：

| 平台 | 支持的客户端 |
|------|-------------|
| **Windows** | v2rayN, Clash Verge, NekoRay |
| **macOS** | V2rayU, ClashX Pro, Surge |
| **Linux** | v2rayA, Clash |
| **Android** | v2rayNG, Clash for Android, NekoBox |
| **iOS** | Shadowrocket, Quantumult X, Surge |

**使用方式：**

1. 部署 `workers/workers.js` 到 Cloudflare Workers
2. 访问 Workers 首页获取 VLESS 链接（格式：`vless://uuid@host:443?...`）
3. 复制链接导入到任意支持 VLESS 的客户端
4. 即可使用 Cloudflare 全球节点作为代理出口

```
vless://你的UUID@your-workers.dev:443?encryption=none&security=tls&type=ws&host=your-workers.dev&path=%2F你的UUID#CFspider
```

## v1.8.7 新特性

| 特性 | 说明 |
|------|------|
| **VLESS 协议** | 使用 VLESS 协议代理，完全隐藏 CF-Ray、CF-Worker 等 Cloudflare 头 |
| **v2ray 支持** | 支持 v2rayN/v2rayNG/Clash 等客户端直接使用 |
| **动态 IP 池** | 每次请求自动获取新的出口 IP，从 300+ 全球节点选择 |
| **固定 IP 模式** | `static_ip` 参数，支持保持同一 IP 进行多次请求 |
| **双层代理** | `two_proxy` 参数，解决国内无法直连海外代理的问题，支持自定义出口 IP |
| **页面配置模式** | 无需设置环境变量，访问页面即可自动生成 UUID 并配置双层代理 |
| **环境变量模式** | 通过 Cloudflare Dashboard 设置 UUID 和 TWO_PROXY 环境变量 |
| **UUID 仅显示一次** | 页面配置模式下，UUID 仅在弹窗中显示一次，关闭后加密显示 |
| **简化 API** | 只需填写 Workers 地址，自动获取配置 |

## UUID 使用说明

| 方法 | 需要 UUID | 支持双层代理 | 说明 |
|------|----------|-------------|------|
| `cfspider.get/post/...` | 需要 | 支持 | 基础 HTTP 方法 |
| `cfspider.Session` | 需要 | 支持 | 会话管理 |
| `cfspider.StealthSession` | 需要 | 支持 | 隐身会话 |
| `cfspider.Browser` | 需要（可自动获取） | 支持 | 浏览器自动化 |
| `cfspider.WebMirror` | 需要（可自动获取） | 支持 | 网页镜像 |
| `cfspider.AsyncSession` | 无需 | 仅 HTTP | 异步会话 |
| `cfspider.aget/apost/...` | 无需 | 仅 HTTP | 异步方法 |
| `cfspider.impersonate_*` | 无需 | 受限 | TLS 指纹模拟 |

## 双层代理（国内无法直连代理时使用）

> **国内无法直接连接海外代理？** 双层代理功能专为解决这一问题设计。通过 Cloudflare Workers 作为中转，即使在国内网络环境下也能使用第三方代理服务。

**流量路径：**
```
本地（国内） → Cloudflare Workers (VLESS) → 第二层代理（海外） → 目标网站
```

### 为什么需要双层代理？

| 场景 | 问题 | 解决方案 |
|------|------|---------|
| **国内直连代理** | 无法连接海外代理服务器 | 连接失败 |
| **使用双层代理** | 通过 CF Workers 中转 | 正常访问 |

### 实测对比（国内网络环境）

```
本地 IP: xxx.xxx.xxx.xxx（中国大陆）

[测试 1] 直接使用 HTTP 代理
代理地址: proxy.example.com:3010
结果: 连接失败 - 403 Forbidden（代理服务器拒绝国内 IP）

[测试 2] 通过 CFspider 双层代理
Workers: https://your-workers.dev
第二层代理: proxy.example.com:3010
结果: 成功
代理出口 IP: xxx.xxx.xxx.xxx（日本）
```

**结论**：国内网络无法直连海外代理服务器，通过 CFspider Workers 中转后可正常使用。

**双层代理 vs 默认模式：**

| 对比项 | 默认模式 | 双层代理模式 |
|--------|---------|-------------|
| 出口 IP | Cloudflare WARP（荷兰/美国等） | 第二层代理的 IP（可指定地区） |
| IP 类型 | 数据中心 IP | 可选住宅/移动 IP |
| 适用场景 | 一般爬虫、匿名访问 | 需要特定地区 IP、住宅 IP、国内无法直连代理 |
| 国内可用性 | 可用 | 可用（解决直连问题） |

### 使用方式

**方式 1：Workers 环境变量配置（推荐）**

在 Cloudflare Dashboard 或使用 wrangler 配置：

```bash
# 格式: host:port:user:pass
echo "us.cliproxy.io:3010:username:password" | npx wrangler secret put TWO_PROXY --name cfspider
```

配置后，Python 和 v2ray 客户端都会自动使用双层代理：

```python
import cfspider

# 自动使用 Workers 配置的双层代理
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev",
    uuid="your-uuid"
)
print(response.json())  # 出口 IP 为第二层代理的 IP
```

**方式 2：Python 参数指定**

```python
import cfspider

# 手动指定第二层代理（优先级高于 Workers 配置）
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev",
    uuid="your-uuid",
    two_proxy="us.cliproxy.io:3010:username:password"
)
print(response.json())  # 出口 IP 为第二层代理的 IP
```

### 配置优先级

| Workers `TWO_PROXY` | Python `two_proxy` | 结果 |
|---------------------|--------------------|----- |
| 已配置 | 不传 | 自动使用 Workers 配置 |
| 未配置 | 传入 | 使用 Python 参数 |
| 已配置 | 传入 | **Python 参数优先** |
| 未配置 | 不传 | 使用 Cloudflare WARP IP |

### 代理 IP 购买

如需购买高质量的代理 IP（支持住宅 IP、移动 IP、指定地区），推荐：

- **Cliproxy**: [https://dash.cliproxy.com/](https://dash.cliproxy.com/) - 支持 HTTP/SOCKS5 代理，覆盖全球多个地区

- **1024proxy**: [https://1024proxy.com/](https://1024proxy.com/) - 全球住宅 IP 服务商，0.49/GB起。灵活适配各类业务场景，为企业级数据采集服务，提供稳定基础设施，助力业务增长。

- **Novproxy**: [https://novproxy.com/](https://novproxy.com/) - 1亿+ 住宅 IP，覆盖 190 个国家，$0.5/GB 起，支持动态住宅、长期静态 ISP、无限流量套餐，99% 成功率。

### 免费域名推荐

部署 CFspider Workers 需要自定义域名（避免 workers.dev 在国内被干扰），推荐：

- **DNSHE**: [https://my.dnshe.com/](https://my.dnshe.com/) - 提供免费域名注册，支持 GitHub 登录，适合个人开发者使用。注册后可将免费域名绑定到 Cloudflare Workers。

### EdgeOne / 第三方 CDN 注意事项

> ⚠️ **不建议使用第三方 CDN（如腾讯 EdgeOne）加速 Cloudflare Workers**

**测试结果：**

| 访问方式 | VLESS 连接 | 说明 |
|---------|-----------|------|
| 直接访问 Workers (`*.workers.dev`) | ✅ 成功 | 正常工作 |
| Cloudflare 自定义域名 | ✅ 成功 | 推荐方式 |
| 通过 EdgeOne CDN | ❌ 502 Bad Gateway | WebSocket 转发失败 |

**原因分析：**

1. **WebSocket 不兼容**：EdgeOne 等第三方 CDN 可能无法正确转发 VLESS 使用的 WebSocket 连接
2. **增加延迟**：Workers 本身就是边缘计算，再套一层 CDN 反而增加延迟
3. **Host 头问题**：第三方 CDN 可能修改 Host 头，导致 Workers 无法正确识别原始域名

**解决方案：**

1. **直接使用 Cloudflare 自定义域名（推荐）**：
   - 在 Cloudflare Dashboard → Workers → 选择 Worker → Settings → Triggers → Custom Domains
   - 添加自定义域名，DNS 直接指向 Cloudflare（橙色云）

2. **如必须使用第三方 CDN**：
   - 设置 `CUSTOM_HOST` 环境变量为你的自定义域名
   - 确保 CDN 启用 WebSocket 支持
   - 检查 CDN 是否正确传递 `X-Forwarded-Host` 或 `Host` 头

代理格式示例：
```
# HTTP 代理格式
host:port:username:password

# 示例
us.cliproxy.io:3010:2e75108689-region-JP:password123
```

## 核心优势：VLESS 动态 IP 池

> **CFspider v1.8.7 采用 VLESS 协议**，每次请求自动获取新的出口 IP，自动从 300+ 全球节点中选择最优节点。**完全隐藏 Cloudflare 特征**（无 CF-Ray、CF-Worker、Cf-Connecting-Ip 等头），实现真正的匿名代理。

### 动态 IP 池的优势

| 优势 | 说明 |
|------|------|
| **降低封禁风险** | IP 分散在 300+ 节点，单个 IP 被封不影响整体使用 |
| **提高成功率** | 自动选择最优节点，减少网络问题和连接失败 |
| **地理分布** | 模拟真实用户的地理分布，请求更自然 |
| **自动优化** | 根据目标网站位置和网络状况自动选择节点 |

**动态 IP vs 固定 IP：**

```python
import cfspider

# 动态 IP 模式（默认）- 每次请求自动获取新 IP
for i in range(5):
    response = cfspider.get(
        "https://httpbin.org/ip",
        cf_proxies="https://your-workers.dev",
        uuid="your-uuid"  # 需要 UUID
    )
    print(response.json()['origin'])  # 每次都是不同的 IP

# 固定 IP 模式 - 保持使用同一个 IP（适合需要会话一致性的场景）
for i in range(5):
    response = cfspider.get(
        "https://httpbin.org/ip",
        cf_proxies="https://your-workers.dev",
        uuid="your-uuid",
        static_ip=True
    )
    print(response.json()['origin'])  # 每次都是相同的 IP
```

**v2ray 客户端的 IP 变化机制：**

| 操作 | IP 是否变化 |
|------|-------------|
| 保持连接 | 不变（同一个 WebSocket 连接期间 IP 保持稳定） |
| 断开重连 | 变化（重新连接会获得新的出口 IP） |

> 如需在 v2ray 中换 IP，断开连接后重新连接即可获取新的出口 IP。

**关于出口 IP 地区：**

VLESS 协议通过 Cloudflare WARP 网络出口，出口 IP 主要来自 Cloudflare 的数据中心（如荷兰、美国等）。IP 地址会变化，但地区可能保持相对稳定。这是 Cloudflare WARP 网络的特性，不影响匿名性和反检测能力。

## 项目截图

### 官网首页

![官网首页](pages.png)

### Workers 部署界面

![Workers 部署界面](workers.png)

## 视频教程

**如何用 Cloudflare Workers 免费搭建代理 IP 池**

- [点击观看 B 站视频教程](https://b23.tv/1uzOf7M)
- [点击观看 YouTube 视频教程](https://youtu.be/oPeXiIFJ9TA?si=ukXsX8iP86ZTB4LP)

**完整部署演示视频**

观看完整的部署流程演示，了解如何从零开始搭建 CFspider 代理 IP 池：

![完整部署演示](cfspiderVideo.gif)

> 从 Workers 部署到测试使用的完整流程演示

**代码演示视频 - 快速上手**

观看完整的爬虫示例演示，了解如何使用 CFspider 进行数据提取和批量处理：

![示例代码演示](codeVideo.gif)

> 8 行代码完成爬虫示例：请求、提取、保存一步到位

> **重要声明**：本项目仅供学习研究、网络安全测试、合规数据采集等**合法用途**。使用者须遵守所在地法律法规及 Cloudflare 服务条款。**任何非法使用（包括但不限于网络攻击、侵犯隐私、规避版权保护等）均与本项目开发者无关，使用者自行承担全部法律责任。**

## 代理方案对比

| 代理方案 | 价格 | IP 质量 | 速度 | 稳定性 | IP 数量 | 反爬能力 | 动态 IP |
|---------|------|---------|------|--------|---------|----------|---------|
| **CFspider (Workers+VLESS)** | **免费** | **企业级** | **极快** | **99.9%** | **WARP 池** | **强** | **每次请求换 IP** |
| WARP 客户端 (1.1.1.1) | 免费/$5/月 | 企业级 | 快 | 高 | WARP 池 | 强 | 固定 IP |
| 直接扫描 CF CDN IP | 免费 | 无法使用 | - | 无法连接 | 理论很多 | 无 | - |
| 住宅代理 / 家庭代理 | $5-15/GB | 极高 | 中等 | 中等 | 百万+ | 极强 | 按需换 IP |
| 数据中心代理 | $1-5/月 | 中等 | 快 | 高 | 有限 | 中等 | 固定 IP |
| 免费公共代理 | 免费 | 极差 | 慢 | <10% | 数千 | 弱 | 随机 |
| VPN 服务 | $3-12/月 | 中等 | 中等 | 高 | 数十服务器 | 中等 | 固定 IP |
| 自建代理服务器 | $5-50/月 | 取决于IP | 快 | 高 | 1个 | 弱 | 固定 IP |

### CFspider vs WARP 客户端

| 对比项 | CFspider (Workers+VLESS) | WARP 客户端 (1.1.1.1) |
|--------|--------------------------|----------------------|
| **动态 IP** | 每次请求自动换 IP | 连接期间固定 IP |
| **编程集成** | Python 库，一行代码使用 | 需要系统代理配置 |
| **大陆可用性** | 需要自定义域名 | 直接连接困难 |
| **反爬能力** | 强（IP 轮换 + TLS 指纹） | 中等（IP 固定易被追踪） |
| **适用场景** | 爬虫、批量请求、自动化 | 日常上网、隐私保护 |
| **浏览器支持** | Playwright 自动化 | 全系统代理 |
| **v2ray 客户端** | 支持 VLESS 链接导入 | 独立客户端 |

### 代码对比：CFspider vs WARP 客户端爬虫

**方案一：CFspider（推荐）**

```python
# 步骤：pip install cfspider，然后直接使用
import cfspider

# 每次请求自动换 IP，无需任何系统配置
for i in range(10):
    response = cfspider.get(
        "https://httpbin.org/ip",
        cf_proxies="https://your-workers.dev",
        uuid="your-uuid"  # 需要 UUID
    )
    print(f"请求 {i+1}: {response.json()['origin']}")  # 每次都是不同的 IP
```

**方案二：WARP 客户端 + requests**

```python
# 步骤：
# 1. 下载安装 1.1.1.1 WARP 客户端（国内需要翻墙下载）
# 2. 注册账号（国内需要翻墙）
# 3. 连接 WARP（国内无法直接连接，需要其他代理中转）
# 4. 开启系统代理或 SOCKS5 代理模式
# 5. 编写代码使用代理

import requests

# WARP 客户端通常监听本地 40000 端口
proxies = {
    "http": "socks5://127.0.0.1:40000",
    "https": "socks5://127.0.0.1:40000"
}

for i in range(10):
    response = requests.get("https://httpbin.org/ip", proxies=proxies)
    print(f"请求 {i+1}: {response.json()['origin']}")  # 每次都是相同的 IP！
```

### 操作步骤对比

| 步骤 | CFspider | WARP 客户端 |
|------|----------|-------------|
| 1. 安装 | `pip install cfspider` | 下载 1.1.1.1 客户端（国内需翻墙） |
| 2. 部署 | 复制 workers/workers.js 到 CF Workers | 注册账号（国内需翻墙） |
| 3. 配置 | 无需配置 | 启动客户端并连接（国内无法直连） |
| 4. 使用 | 一行代码 `cfspider.get(...)` | 配置系统代理或 SOCKS5 |
| 5. 换 IP | 自动（每次请求） | 手动（断开重连） |
| 总耗时 | 约 5 分钟 | 约 30+ 分钟（还可能失败） |

### 国内使用限制

| 方案 | 国内可用性 | 解决方案 |
|------|-----------|----------|
| **CFspider** | 可用 | 使用自定义域名绑定 Workers |
| **WARP 客户端** | 不可用 | 无法直接连接，需要其他代理中转 |

**为什么 WARP 客户端在国内无法使用？**

1. **连接被阻断**：1.1.1.1 和 WARP 服务器 IP 在国内被屏蔽
2. **无法注册**：注册过程需要访问被屏蔽的服务器
3. **无法下载**：官方下载页面可能无法访问
4. **即使安装也无法连接**：握手过程会被干扰

**CFspider 为什么在国内可用？**

1. **自定义域名**：绑定自己的域名到 Workers，不走默认的 workers.dev
2. **WebSocket 连接**：VLESS 使用 WebSocket，与普通 HTTPS 流量无异
3. **TLS 加密**：所有流量都是标准 TLS 加密，无特征
4. **无需额外代理**：直接从国内连接你的自定义域名即可

```python
# 国内使用示例 - 使用自定义域名
import cfspider

# 绑定自定义域名后，直接连接
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://proxy.yourdomain.com"  # 你的自定义域名
)
print(response.json())
```

### 合规使用 vs 违规滥用

| 对比项 | 违规滥用：直接攻击 CF CDN IP | CFspider 官方方式：Workers 部署 |
|--------|------------------------------|--------------------------------|
| **本质** | 撬锁硬闯公共大门 | 租用独立办公室 |
| **行为性质** | 对基础设施的违规滥用 | 合规使用计算服务 |
| **IP 信誉** | 极易被封，污染 IP 池 | 信誉相对更高 |
| **影响范围** | 害人害己，殃及无辜 | 风险自担，行为可控 |
| **法律风险** | 高风险，可能违反计算机滥用法规 | 低风险，遵守 Cloudflare TOS |
| **可持续性** | 不可持续，IP 被封后需不断寻找 | 长期可用，Workers 稳定运行 |
| **数据控制** | 无法控制 | 完全可控，有完整日志 |

**违规滥用方式：**
```python
# 错误示范 - 直接使用 CF CDN IP
proxies = {"http": "172.64.155.xxx:80"}
requests.get(url, proxies=proxies)  # 无法工作且违规！
```
- 直接使用 172.64.x.x、104.21.x.x 等公共 CDN IP
- 这属于**对基础设施的违规滥用**
- 流量会**污染 IP 池**，极易被封
- 导致该 IP 段上其他正常网站遭殃
- 可能触发 Cloudflare 安全机制被封禁
- 存在法律风险

**CFspider 官方方式：**
```python
# 正确方式 - 使用你的 Workers
import cfspider
cfspider.get(url, cf_proxies="你的.workers.dev")
```
- 在你的 Cloudflare 账户中部署个人 Workers 脚本
- 这属于**合规使用 Cloudflare 计算服务**
- 流量来自你的独立 Worker，行为可控
- IP 信誉由 Cloudflare 维护，相对更高
- 符合 Cloudflare 服务条款

**简单说：一个是在撬锁硬闯公共大门（违规、害人害己），一个是在租用大楼里的独立办公室（合规、风险自担）。**

### 各方案详解

**直接爬取 Cloudflare CDN IP**
- Cloudflare CDN IP（如 172.64.x.x、104.21.x.x）是 Anycast IP
- 无法直接作为 HTTP/SOCKS5 代理使用
- 即使扫描出在线 IP，也无法建立代理连接
- CDN IP 仅用于边缘加速，不提供代理服务

**住宅代理 / 家庭代理**
- 使用真实家庭网络 IP，反爬能力最强
- 价格昂贵，按流量计费（$5-15/GB）
- 部分服务存在合规风险
- 适合对匿名性要求极高的商业爬虫场景

**数据中心代理**
- 速度快、价格适中
- IP 容易被识别为机房 IP
- 被大型网站封禁概率较高
- 适合目标网站防护较弱的场景

**免费公共代理**
- 完全免费但质量极差
- 可用率通常低于 10%
- 速度慢、不稳定
- 存在安全风险（可能被中间人攻击）

**CFspider 优势**
- 利用 Cloudflare Workers 的边缘计算能力
- 请求从 Cloudflare 300+ 全球节点发出
- IP 是 Cloudflare 企业级 IP（与大量正常网站共用）
- 不易被封禁，且完全免费
- Workers 免费版每日 100,000 请求

## 核心优势

### 企业级 IP 信誉
Cloudflare IP (AS13335) 被全球数百万网站使用，包括 Discord、Shopify、Medium 等知名服务。这些 IP 拥有极高的信誉度，不会像普通代理 IP 那样被轻易封禁。

### 零成本运营
Cloudflare Workers 免费版每日 100,000 请求，无需信用卡，无需付费。相比住宅代理每月数百美元的费用，这是真正的零成本方案。

### 全球边缘网络
请求自动路由到离目标网站最近的 Cloudflare 边缘节点。全球 100+ 个国家，300+ 个数据中心，确保最低延迟。

### Serverless 无服务器
无需购买服务器、无需运维、无需担心扩容。Cloudflare 自动处理所有基础设施，冷启动时间接近零毫秒。

### 数据完全可控
代码部署在你自己的 Cloudflare 账户，请求日志、访问数据完全由你掌控。100% 的隐私和控制权。

### 企业级安全
所有请求自动享受 Cloudflare 的 DDoS 防护、WAF 防火墙、SSL/TLS 加密。

## 适用场景

| 场景 | 说明 |
|------|------|
| 数据采集 / 爬虫 | 采集公开数据时避免 IP 被封禁，适合新闻聚合、价格监控、市场调研 |
| SEO 监控 | 从不同地理位置检查搜索引擎排名、网站可访问性 |
| 网站可用性测试 | 从全球各地测试网站的响应时间和可用性 |
| API 聚合服务 | 调用多个第三方 API 时隐藏真实服务器 IP |
| 内容验证 | 验证 CDN 缓存、检查不同地区的内容分发 |
| 学术研究 | 网络研究、互联网测量、安全研究等学术项目 |

## 技术架构

### VLESS 代理架构 (v1.8.7)

```
+------------------+                              +------------------+
|                  |   WebSocket + VLESS          |                  |
|   Your Python    | ─────────────────────────────|   Target Website |
|   Application    |    (完全隐藏 CF 特征)         |                  |
|                  |                              +------------------+
+------------------+                                      ▲
        │                                                 │
        │ wss://                                   HTTP/HTTPS
        ▼                                                 │
+------------------+      +----------------------+        │
|   cfspider lib   |      |   Cloudflare Edge    |────────┘
|   LocalVlessProxy| ────▶|   Workers (300+)     |
+------------------+      |   VLESS Protocol     |
                          +----------------------+
                                    │
                                    ▼
                          +----------------------+
                          |  动态 IP 池 (每次新 IP) |
                          |  172.64.x.x          |
                          |  104.21.x.x          |
                          |  162.159.x.x  ...    |
                          +----------------------+
```

**VLESS 工作流程：**
1. 你的应用调用 `cfspider.get(url, cf_proxies="https://your-workers.dev")`
2. CFspider 本地启动 VLESS 代理，通过 WebSocket 连接到 Workers
3. Workers 使用 VLESS 协议处理请求，自动路由到最近边缘节点
4. 每次请求自动获取新的出口 IP（从 300+ 节点中选择）
5. 响应返回，**目标网站看到的是完全干净的请求**（无 CF-Ray、CF-Worker、Cf-Connecting-Ip 等头）

**VLESS vs HTTP 代理对比：**

| 对比项 | 旧方案 (HTTP 代理) | 新方案 (VLESS v1.8.7) |
|--------|-------------------|------------------------|
| CF 特征暴露 | 暴露 CF-Ray, CF-Worker 等 | 完全隐藏 |
| IPv6 问题 | IPv6 固定不变 | 每次请求新 IP |
| 匿名性 | 中等 | 高 |
| 检测风险 | 容易被识别 | 难以检测 |

## 特性

### 核心特性 (v1.8.7)

- **VLESS 协议代理**：通过 VLESS 协议连接 Workers，完全隐藏 Cloudflare 特征
- **动态 IP 池**：每次请求自动获取新的出口 IP，从 300+ 全球节点自动选择
- **完全隐藏 CF 特征**：目标网站无法检测到 CF-Ray、CF-Worker、Cf-Connecting-Ip 等头
- **UUID 安全机制**：支持自定义 UUID，配置后 API 不公开返回，需手动填写
- **简化 API**：只需填写 Workers 地址，自动从 `/api/config` 获取配置

### 完整功能

- 使用 Cloudflare 全球 300+ 边缘节点 IP
- 与 requests 库语法一致，无学习成本
- 支持 GET、POST、PUT、DELETE 等所有 HTTP 方法
- 支持 Session 会话管理
- 返回 Cloudflare 节点信息（cf_colo、cf_ray）
- **支持浏览器模式**，可渲染 JavaScript 动态页面、截图、自动化操作
- **支持多种代理方式**：VLESS 链接、HTTP 代理、SOCKS5 代理
- **支持异步请求**（基于 httpx），可使用 async/await 语法
- **支持 HTTP/2 协议**，更快的连接复用和性能
- **支持流式响应**，高效处理大文件下载
- **支持 TLS 指纹模拟**（基于 curl_cffi），可模拟 Chrome/Safari/Firefox/Edge 浏览器指纹
- **支持 IP 地图可视化**（基于 MapLibre GL），生成 HTML 地图文件，显示代理 IP 地理位置
- **支持网页镜像**（基于 Playwright + BeautifulSoup），一键保存完整网页到本地，自动下载所有资源
- **支持隐身模式**：自动添加完整浏览器请求头（Sec-Fetch-*、Accept-* 等 15+ 个头）
- **支持会话一致性**（StealthSession）：保持 User-Agent 和 Cookie 一致，模拟真实用户
- **支持行为模拟**：请求随机延迟、自动 Referer、多浏览器指纹轮换
- 完全免费，Workers 免费版每日 100,000 请求

## 测试结果

| 功能 | 状态 | 说明 |
|------|------|------|
| **VLESS 动态 IP** | OK | 每次请求新 IP（IPv4 + IPv6） |
| **CF 特征隐藏** | OK | 无 CF-Ray、CF-Worker 等头 |
| **UUID 安全** | OK | 自定义 UUID 不公开返回 |
| HTTP GET 请求 | OK | 返回 Cloudflare IP |
| HTTP POST 请求 | OK | 发送数据成功 |
| 自定义 Headers | OK | Header 正确传递 |
| Session 会话 | OK | 多次请求正常 |
| Workers Debug | OK | 返回 CF 机房信息 |
| 浏览器(VLESS) | OK | Cloudflare IP 出口 |
| 浏览器(HTTP代理) | OK | 支持本地/远程代理 |
| 浏览器(无代理) | OK | 本地 IP 出口 |
| IP 地图可视化 | OK | 生成 HTML 地图文件 |
| 网页镜像 | OK | 保存完整网页到本地 |
| 隐身模式 | OK | 自动添加 15+ 个请求头 |
| StealthSession | OK | 会话一致性、自动 Referer |
| 随机延迟 | OK | 请求间随机等待 |

## 部署 Workers

![GitHub stars](https://img.shields.io/github/stars/violettoolssite/CFspider?style=social)
![GitHub forks](https://img.shields.io/github/forks/violettoolssite/CFspider?style=social)
![GitHub watchers](https://img.shields.io/github/watchers/violettoolssite/CFspider?style=social)

### Stars 增长趋势

![Star History Chart](https://api.star-history.com/svg?repos=violettoolssite/CFspider&type=Date)

### 部署步骤

1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. 进入 Workers & Pages
3. 点击 Create application → Create Worker
4. 将 `workers/workers.js` 代码粘贴到编辑器中
5. 点击 Deploy

部署完成后，你将获得一个 Workers 地址，如 `https://xxx.username.workers.dev`

如需自定义域名，可在 Worker → Settings → Triggers → Custom Domain 中添加。

### UUID 配置（推荐）

为了增强安全性，强烈建议配置自定义 UUID：

1. 在 Worker → Settings → Variables and Secrets 中添加环境变量
2. 变量名：`UUID`
3. 变量值：你的 UUID（