From 19c02b1b97c4559ae021aedb3b557877e639e06d Mon Sep 17 00:00:00 2001 From: test01 Date: Sat, 3 Jan 2026 04:16:58 +0800 Subject: [PATCH] docs: detailed README with full documentation --- .gitignore | 8 +- README.md | 227 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 221 insertions(+), 14 deletions(-) diff --git a/.gitignore b/.gitignore index 2b12f7f..54d424a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,10 @@ pages/ node_modules/ wrangler.toml .wrangler/ - +cfspider/ +setup.py +pyproject.toml +dist/ +build/ +*.egg-info/ +__pycache__/ diff --git a/README.md b/README.md index 9bf569e..119dc2d 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,56 @@ # CFspider -Cloudflare Workers 代理 IP 池，使用 Cloudflare 全球边缘节点 IP 作为代理出口。 +基于 Cloudflare Workers 的代理 IP 池，使用 Cloudflare 全球边缘节点 IP 作为代理出口。 + +## 特性 + +- 使用 Cloudflare 全球 300+ 边缘节点 IP +- 与 requests 库语法一致，无学习成本 +- 支持 GET、POST、PUT、DELETE 等所有 HTTP 方法 +- 支持 Session 会话管理 +- 返回 Cloudflare 节点信息（cf_colo、cf_ray） +- 完全免费，Workers 免费版每日 100,000 请求 ## 部署 Workers -1. 将 `workers.js` 代码复制到 Cloudflare Workers -2. 绑定 KV 命名空间（名称为 `KV`） -3. 设置环境变量 `ADMIN`（管理密码） -4. 配置自定义域名（可选） +### 步骤 1：创建 Worker + +1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/) +2. 进入 Workers & Pages +3. 点击 Create application → Create Worker +4. 将 `workers.js` 代码粘贴到编辑器中 +5. 点击 Deploy + +### 步骤 2：创建 KV 命名空间 + +1. 进入 Workers & Pages → KV +2. 点击 Create a namespace +3. 输入名称（如 `cfspider`） +4. 创建后复制 Namespace ID + +### 步骤 3：绑定 KV + +1. 进入你的 Worker → Settings → Variables +2. 在 KV Namespace Bindings 中添加： + - Variable name: `KV` + - KV namespace: 选择刚创建的命名空间 +3. 点击 Save + +### 步骤 4：设置环境变量（可选） + +在 Worker Settings → Variables → Environment Variables 中添加： + +| 变量名 | 说明 | 示例 | +|--------|------|------| +| ADMIN | 管理密码 | your_password | +| UUID | 自定义 UUID | 留空则自动生成 | +| PROXYIP | 反代 IP | proxyip.example.com | + +### 步骤 5：绑定自定义域名（可选） + +1. 进入 Worker → Settings → Triggers +2. 添加 Custom Domain +3. 输入你的域名（需已托管在 Cloudflare） ## 安装 @@ -15,7 +58,66 @@ Cloudflare Workers 代理 IP 池，使用 Cloudflare 全球边缘节点 IP 作 pip install cfspider ``` -## 使用 +## 快速开始 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +response = cfspider.get("https://httpbin.org/ip", cf_proxies=cf_proxies) + +print(response.text) +``` + +## API 参考 + +### 请求方法 + +CFspider 支持以下 HTTP 方法，语法与 requests 库一致： + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +cfspider.get(url, cf_proxies=cf_proxies) +cfspider.post(url, cf_proxies=cf_proxies, json=data) +cfspider.put(url, cf_proxies=cf_proxies, data=data) +cfspider.delete(url, cf_proxies=cf_proxies) +cfspider.head(url, cf_proxies=cf_proxies) +cfspider.options(url, cf_proxies=cf_proxies) +cfspider.patch(url, cf_proxies=cf_proxies, json=data) +``` + +### 请求参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| url | str | 目标 URL | +| cf_proxies | str | Workers 地址（必填） | +| params | dict | URL 查询参数 | +| data | dict/str | 表单数据 | +| json | dict | JSON 数据 | +| headers | dict | 请求头 | +| cookies | dict | Cookies | +| timeout | int/float | 超时时间（秒） | + +### 响应对象 + +| 属性 | 类型 | 说明 | +|------|------|------| +| text | str | 响应文本 | +| content | bytes | 响应字节 | +| json() | dict | 解析 JSON | +| status_code | int | HTTP 状态码 | +| headers | dict | 响应头 | +| cf_colo | str | Cloudflare 节点代码（如 NRT） | +| cf_ray | str | Cloudflare Ray ID | + +## 使用示例 + +### GET 请求 ```python import cfspider @@ -23,15 +125,34 @@ import cfspider cf_proxies = "https://your-workers.dev" response = cfspider.get( - "https://httpbin.org/ip", - cf_proxies=cf_proxies + "https://httpbin.org/get", + cf_proxies=cf_proxies, + params={"key": "value"} ) -print(response.text) -print(response.cf_colo) +print(response.status_code) +print(response.json()) ``` -## 使用 Session +### POST 请求 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +response = cfspider.post( + "https://httpbin.org/post", + cf_proxies=cf_proxies, + json={"name": "cfspider", "version": "1.0"} +) + +print(response.json()) +``` + +### 使用 Session + +Session 可以复用 Workers 地址，无需每次请求都指定： ```python import cfspider @@ -41,12 +162,92 @@ cf_proxies = "https://your-workers.dev" session = cfspider.Session(cf_proxies=cf_proxies) r1 = session.get("https://httpbin.org/ip") -r2 = session.get("https://example.com") +r2 = session.post("https://httpbin.org/post", json={"test": 1}) +r3 = session.get("https://example.com") print(r1.text) +print(r2.json()) + session.close() ``` +### 获取 Cloudflare 节点信息 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +response = cfspider.get("https://httpbin.org/ip", cf_proxies=cf_proxies) + +print(f"出口 IP: {response.json()['origin']}") +print(f"节点代码: {response.cf_colo}") +print(f"Ray ID: {response.cf_ray}") +``` + +### 自定义请求头 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +response = cfspider.get( + "https://httpbin.org/headers", + cf_proxies=cf_proxies, + headers={ + "User-Agent": "MyApp/1.0", + "Accept-Language": "zh-CN" + } +) + +print(response.json()) +``` + +### 设置超时 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +response = cfspider.get( + "https://httpbin.org/delay/5", + cf_proxies=cf_proxies, + timeout=10 +) +``` + +## 错误处理 + +```python +import cfspider + +cf_proxies = "https://your-workers.dev" + +try: + response = cfspider.get("https://httpbin.org/ip", cf_proxies=cf_proxies) + response.raise_for_status() + print(response.text) +except cfspider.CFSpiderError as e: + print(f"请求失败: {e}") +except Exception as e: + print(f"其他错误: {e}") +``` + +## 注意事项 + +1. Workers 免费版限制：每日 100,000 请求，单次 CPU 时间 10ms +2. 请求体大小限制：免费版 100MB，付费版无限制 +3. 超时限制：免费版 30 秒，付费版无限制 +4. 不支持 WebSocket、gRPC 等非 HTTP 协议 + ## License -MIT +MIT License + +## 链接 + +- GitHub: https://github.com/violettoolssite/CFspider +- PyPI: https://pypi.org/project/cfspider/ +- 官网: https://spider.violetteam.cloud