# WebAI-2ApiGeo

**Repository Path**: web/web-ai-2-api-geo

## Basic Information

- **Project Name**: WebAI-2ApiGeo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web2API + GEO 探测系统

> English version: see [`README.en.md`](./README.en.md)

Web2API 是一个**双功能服务**：

1. **AI 桥接服务**：将网页端 AI 服务（Claude Web 等）包装成标准 OpenAI / Anthropic 兼容接口
2. **GEO AI 搜索营销探测系统**：自动探测 AI 平台输出内容的来源引用、分享链接、营销提及等，用于 SEO 监测与品牌保护

---

## 功能

### AI 桥接（原有功能）
- 支持图片输入
- 支持流式/非流式输出
- 支持 tagged tool protocol 工具调用
- 支持 OpenAI / Anthropic 双协议
- 可视化配置页（代理组、账号池、指纹、时区等）

### GEO 探测（新增功能）
- **多平台探测**：通过 HTTP 配置 AI 平台（豆包、千问、Perplexity、DeepSeek 等），无需改代码
- **引用提取**：结构化提取 AI 回答中的引用来源（标题 + URL），返回数组
- **分享链接提取**：自动获取 AI 平台的分享链接（可扩展多平台支持）
- **反检测浏览器**：底层使用 Camoufox 反指纹浏览器，支持 Canvas/WebGL 指纹随机化
- **多 UA 轮询**：每个平台可配置多个 User-Agent，随机选取降低风控风险
- **双端探测**：支持 PC（1920×1080）和 Mobile（390×844）视口切换
- **PC/Mobile 选择器分离**：支持为移动端单独配置选择器和清洗规则，适配不同 DOM 结构
- **独立 Page 隔离**：每次探测创建新 BrowserContext，杜绝历史对话污染
- **生产队列模式**：Redis 队列 + Worker 并发处理，支持批量任务
- **调试模式**：HTTP 同步接口 + 命令行调试工具，单条任务即时返回
- **无快照存储**：仅输出结构化文本结果，不存储页面截图

---

## 架构概览

```
┌─────────────────────────────────────────────────────────────────────┐
│                        客户端（PHP / curl / SDK）                    │
└────────────┬──────────────────────┬─────────────────────────────────┘
             │ HTTP API             │ Redis PUSH / HTTP POST
             ▼                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Python web2api (FastAPI)                          │
│                                                                     │
│  ┌─────────────────────┐  ┌──────────────────────────────────────┐  │
│  │   /geo/v1/* 路由    │  │   Redis Worker                      │  │
│  │  • detect 调试接口  │  │   • 监听 geo:detect:queue           │  │
│  │  • platforms CRUD   │  │   • 并发执行探测任务                  │  │
│  │  • tasks 查询       │  │   • 结果入库                         │  │
│  └─────────┬───────────┘  └──────────────┬───────────────────────┘  │
│            │                              │                         │
│            ▼                              ▼                         │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    GEODetector                              │    │
│  │  ┌──────────────┐  ┌───────────────┐  ┌────────────────┐  │    │
│  │  │UniversalAI   │  │ GEOBrowserMgr │  │ AccountPool   │  │    │
│  │  │Crawler       │  │ (Camoufox)   │  │ (账号/代理池) │  │    │
│  │  └──────────────┘  └───────────────┘  └────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌────────────────────┐  ┌─────────────────────────────────────┐   │
│  │  SQLite 数据库     │  │  引用/分享链接提取                    │   │
│  │  • ai_platform    │  │  • references 数组(标题+链接)        │   │
│  │  • ai_detect_task │  │  • share_links 数组(可扩展)          │   │
│  └────────────────────┘  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 快速开始

### 方式一：Docker Compose（推荐）

包含 web2api + Redis + GEO Worker，一键启动全套服务。

```bash
# 1. 克隆项目
git clone https://github.com/caiwuu/web2api.git
cd web2api

# 2. 启动服务（含 Redis + GEO Worker）
docker compose up -d

# 3. 查看服务日志
docker compose logs -f web2api
```

启动后：
- API 服务：`http://127.0.0.1:9000`
- 配置页：`http://127.0.0.1:9000/config`
- GEO API：`http://127.0.0.1:9000/geo/v1/`
- Redis：`redis://127.0.0.1:6379/0`（容器内部通信）

### 方式二：Docker 单容器

```bash
mkdir web2api && cd web2api
mkdir -p docker-data

# 复制容器配置文件（已包含 GEO 配置段）
curl -sL -o docker-data/config.yaml https://raw.githubusercontent.com/caiwuu/web2api/master/docker/config.container.yaml

# 修改 docker-data/config.yaml 中的配置

# 启动（内置 Redis + GEO Worker）
docker run -d --name web2api --restart unless-stopped --shm-size=1g \
  -p 9000:9000 \
  -e ENABLE_GEO_WORKER=1 \
  -e GEO_MAX_CONCURRENT=2 \
  -v "$(pwd)/docker-data:/data" \
  ghcr.io/caiwuu/web2api:latest
```

### 方式三：源码启动

**环境要求**：

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.12+ | 必需 |
| Redis | 3.0+ | 仅使用 List 基础操作（lpush/rpop/brpop），调试模式可省略 |
| Camoufox | 0.5.0+ | 反检测浏览器，GEO 探测核心依赖 |
| 操作系统 | Windows 10+ / Linux / macOS | 已在 Windows x86_64 测试通过 |

#### 步骤 1：克隆并安装依赖

```bash
git clone https://gitee.com/web/web-ai-2-api-geo.git
cd web-ai-2-api-geo

# 推荐使用虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .
```

#### 步骤 2：安装 Camoufox 浏览器

Camoufox 浏览器下载默认从 GitHub Releases 获取，国内网络不稳定时可能超时或失败。本项目提供了**国内镜像加速工具**，自动测速选择最快镜像站下载。

**方式 A：使用国内镜像加速（推荐，国内用户首选）**

```bash
# 自动测速并使用最快镜像下载浏览器 + uBlock Origin
python install_camoufox.py

# 如需强制重新下载
python install_camoufox.py --force

# 指定浏览器版本（覆盖自动检测）
set CAMOUFOX_BROWSER_VERSION=v152.0.4-beta.28
python install_camoufox.py
```

该工具会自动：
1. 测速多个国内镜像站（down.nigx.cn / ghfast.top / gh-proxy.com / ghps.cc）
2. 下载 Camoufox 浏览器压缩包（含 SHA256 校验）
3. 下载 uBlock Origin 广告拦截插件
4. 安装到正确目录并生成配置文件
5. 补丁 `pkgman.py` 添加镜像支持 + SSL 修复 + 离线加载
6. 启动浏览器验证可用性

**方式 B：使用官方命令（需稳定访问 GitHub）**

```bash
python -m camoufox fetch
```

**方式 C：使用国内镜像手动触发**

```bash
# 使用 install_camoufox.py 完成安装
python install_camoufox.py
# 或直接运行补丁脚本（仅打补丁，不下载）
python _apply_patch.py
```

#### 步骤 3：启动 Redis

```bash
# Linux / macOS
redis-server --daemonize yes

# Windows - 下载 Redis 或使用 Memurai
# 参考: https://github.com/tporadowski/redis/releases
```

#### 步骤 4：启动服务

**方式 A：一键启动（推荐）**

```bash
# Windows
start.bat

# Linux / macOS
chmod +x start.sh && ./start.sh
```

一键脚本自动完成：
1. 检查虚拟环境（`.venv`）
2. 自动检测/安装 Camoufox 浏览器（使用国内镜像加速）
3. 检测并启动 Redis 服务
4. 启动 API 服务（端口 9000）
5. 启动 GEO Worker 消费任务队列
6. 显示所有服务地址和常用命令

**方式 B：手动逐步启动**

```bash
# 启动 API 服务
python main.py

# 启动 GEO Worker（生产模式需要，调试模式可省略）
python -m core.queue.worker --redis-url redis://localhost:6379/0
```

#### Linux 无显示器环境

```bash
sudo apt install -y xvfb redis-server
xvfb-run -a -s "-screen 0 1920x1080x24" python main.py
```

#### Windows 无 GPU 环境

```bash
# config.yaml 中添加以下配置以禁用 GPU 加速
browser:
  disable_gpu: true
  disable_gpu_sandbox: true
```

---

### Camoufox 安装常见问题

| 问题 | 解决方案 |
|------|----------|
| `ImportError: cannot import name 'CONFIG_FILE'` | 运行 `python install_camoufox.py --force` 强制重装，工具会自动打补丁 |
| `requests.exceptions.SSLError` SSL 证书错误 | 工具已自动处理。如需手动：将 `pkgman.py` 中所有 `requests.get()` 添加 `verify=False` |
| 下载速度慢或超时 | 使用国内镜像工具 `python install_camoufox.py`，自动选择最快镜像 |
| `404 Not Found` 下载失败 | 镜像源可能暂不可用，工具会自动切换到备用镜像或回退到 GitHub |
| 浏览器启动立即退出 | Linux 环境使用 `xvfb-run`；配置 `no_sandbox: true` 和 `disable_gpu: true` |
| `uBlock Origin` 下载失败 | 可先跳过 UBO，将 `browser.py` 中 `exclude_addons` 传入 `[DefaultAddons.UBO]` |
| 版本不匹配 | 运行 `python install_camoufox.py --force` 强制重新安装匹配版本 |

---

## GEO 探测 API

### 平台管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/geo/v1/platforms` | 获取所有平台列表 |
| `POST` | `/geo/v1/platforms` | 创建/注册 AI 平台 |
| `GET` | `/geo/v1/platforms/{id}` | 获取单个平台详情 |
| `PUT` | `/geo/v1/platforms/{id}` | 更新平台配置 |
| `DELETE` | `/geo/v1/platforms/{id}` | 删除平台 |
| `POST` | `/geo/v1/platforms/{id}/test` | 测试平台选择器是否有效 |

### 探测执行

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/geo/v1/detect` | 同步执行单条探测（调试模式） |
| `POST` | `/geo/v1/tasks` | 创建异步探测任务（入队 Redis） |
| `GET` | `/geo/v1/tasks` | 查询任务列表 |
| `GET` | `/geo/v1/tasks/{task_id}` | 查询单个任务结果 |

### 探测请求示例

**同步探测（调试）：**

```bash
curl -X POST "http://127.0.0.1:9000/geo/v1/detect" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI搜索营销优化最佳实践",
    "platform_code": "doubao",
    "device_type": "pc",
    "user_agent": ""
  }'
```

响应示例：

```json
{
  "success": true,
  "data": {
    "task_id": "geo_1710000000_a1b2c3d4",
    "query": "AI搜索营销优化最佳实践",
    "platform": "doubao",
    "success": true,
    "status": "success",
    "clean_content": "AI搜索营销优化的核心包括...",
    "references": [
      {
        "title": "AI搜索营销指南 2024",
        "url": "https://example.com/guide",
        "source": "cite_structured"
      }
    ],
    "share_links": [
      "https://doubao.com/share/abc123"
    ],
    "user_agent_used": "Mozilla/5.0 ... Chrome/120",
    "elapsed_seconds": 45.2
  }
}
```

**异步任务（生产）：**

```bash
# 1. 创建任务
curl -X POST "http://127.0.0.1:9000/geo/v1/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "品牌关键词监测",
    "platform_id": 1,
    "device_type": "pc"
  }'

# 2. 查询结果
curl "http://127.0.0.1:9000/geo/v1/tasks/geo_1710000000_a1b2c3d4"
```

---

## GEO 配置说明

GEO 配置在 `config.yaml` 的 `geo:` 段中管理：

```yaml
geo:
  browser:
    engine: 'camoufox'          # 浏览器引擎: camoufox | playwright
    headless: true              # 无头模式
    proxy_url: ''               # 全局代理（留空则用账号池代理）

  queue:
    redis_url: 'redis://localhost:6379/0'
    queue_name: 'geo:detect:queue'

  device:
    viewport_width: 1920
    viewport_height: 1080
    user_agents:                # PC端UA列表（随机选取）
      - 'Mozilla/5.0 ... Chrome/120'
      - 'Mozilla/5.0 ... Chrome/121'
    mobile_user_agents:         # 移动端UA列表
      - 'Mozilla/5.0 ... iPhone'

  crawler:
    wait_timeout_seconds: 120  # 等待AI响应超时
    first_chunk_timeout_seconds: 30
    max_references: 20         # 最大引用提取数
    max_share_links: 10        # 最大分享链接数
```

### AI 平台配置

通过 API 创建平台时，需提供 CSS 选择器配置：

```json
{
  "name": "豆包",
  "code": "doubao",
  "base_url": "https://www.doubao.com",
  "selectors": {
    "chat_input": "textarea[data-testid='chat-input']",
    "send_button": "button[aria-label='发送']",
    "message_list": "div[class*='chat-list']",
    "user_message": "div[class*='user-message']",
    "ai_message": "div[class*='assistant-message']",
    "cite_selector": "div[class*='source'] a",
    "share_btn_selector": "button[class*='share']"
  }
}
```

### PC / Mobile 选择器分离

每个平台支持为 **PC** 和 **Mobile** 设备配置独立的选择器和清洗规则。当移动端 DOM 结构与 PC 端不同时（如 DeepSeek 使用原子化 CSS），需要单独配置 `mobile_selectors` 和 `mobile_clean_rules`。

```json
{
  "name": "DeepSeek",
  "code": "deepseek",
  "selectors": {
    "chat_input": "textarea",
    "send_button": ".ds-button--primary",
    "message_list": "div.ds-virtual-list",
    "user_message": "div.ds-message",
    "ai_message": "div.ds-markdown.ds-assistant-message-main-content",
    "cite_selector": "div.ds-assistant-message-main-content a[href]",
    "share_btn_selector": ".ds-message .ds-button--iconLabelTertiary"
  },
  "mobile_selectors": {
    "chat_input": "textarea",
    "send_button": ".ds-button--primary",
    "message_list": "div.ds-virtual-list",
    "user_message": "div.ds-message",
    "ai_message": "div.ds-markdown.ds-assistant-message-main-content",
    "cite_selector": "div.ds-assistant-message-main-content a[href]",
    "share_btn_selector": ".ds-message .ds-button--iconLabelTertiary"
  },
  "clean_rules": [
    {"selector": "div[role='button']", "enabled": true},
    {"selector": "button", "enabled": true}
  ],
  "mobile_clean_rules": [
    {"selector": "div[role='button']", "enabled": true},
    {"selector": "button", "enabled": true}
  ]
}
```

> 如果 `mobile_selectors` 为空，系统会自动回退使用 `selectors`（PC 配置）。

---

## AI 桥接 API（原有功能）

### 协议路由

`{provider}` 对应账号 `type`（如 `claude`）。

- OpenAI 协议
  - `GET /openai/{provider}/v1/models`
  - `POST /openai/{provider}/v1/chat/completions`
- Anthropic 协议
  - `GET /anthropic/{provider}/v1/models`
  - `POST /anthropic/{provider}/v1/messages`

### 配置路由

- `GET /login`
- `GET /config`
- `GET /api/types`
- `GET /api/config`
- `PUT /api/config`
- `POST /api/admin/login`
- `POST /api/admin/logout`

### AI 桥接请求示例

```bash
curl -s "http://127.0.0.1:9000/openai/claude/v1/chat/completions" \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "s4", "stream": false, "messages": [{"role":"user","content":"你好"}]}'
```

---

## 配置账号

访问 `http://127.0.0.1:9000/login`（若未配置 `auth.config_secret` 则配置页不开放），登录后到 `/config` 填入 fingerprint_id、账号 name、type、auth，以及代理。

---

## 项目结构

```
web2api/
├── main.py                          # 服务入口
├── _debug.py                        # 🆕 GEO 统一调试工具
├── init_geo_db.py                   # 🆕 GEO 数据库初始化脚本
├── geo_worker.py                    # GEO Worker 独立进程入口
├── core/
│   ├── app.py                       # 应用组装
│   ├── api/
│   │   ├── geo_routes.py            # GEO RESTful API 路由
│   │   └── ...                      # OpenAI/Anthropic 兼容接口
│   ├── geo/                         # 🆕 GEO 核心模块
│   │   ├── models.py                #   数据模型（平台配置、任务、设备）
│   │   ├── config.py                #   SQLite CRUD（平台/任务管理）
│   │   ├── crawler.py               #   通用 AI 抓取清洗器
│   │   ├── browser.py               #   Camoufox 反检测浏览器管理器
│   │   └── detector.py              #   GEO 探测器核心
│   ├── plugin/
│   │   └── geo_detector.py          #   GEO 插件（注册到 PluginRegistry）
│   ├── queue/                       # 🆕 任务队列
│   │   ├── tasks.py                 #   任务定义、Payload 构建、Redis 操作
│   │   └── worker.py                #   Redis Worker 消费者
│   ├── runtime/                     # 浏览器、tab、会话调度
│   ├── account/                     # 账号池管理
│   └── config/                      # 配置与持久化
├── docker/
│   ├── entrypoint.sh                # Docker 入口脚本（含 Redis + GEO Worker）
│   ├── config.container.yaml        # 容器默认配置
│   └── ...
├── Dockerfile
├── compose.yaml                     # Docker Compose 配置
├── config.yaml                      # 主配置文件
├── install_camoufox.py              # 🆕 Camoufox 国内镜像安装工具
├── install_ubo.py                   # 🆕 uBlock Origin 独立安装脚本
├── test_browser.py                  # 🆕 Camoufox 浏览器测试脚本
├── start.bat                        # 🆕 Windows 一键启动脚本
├── pyproject.toml
└── geo.sqlite3                      # GEO SQLite 数据库（运行时生成）
```

---

## 调试工具

系统提供了统一的命令行调试工具 `_debug.py`，用于本地开发和问题排查。

### 任务管理

```bash
# 列出所有任务
python _debug.py task list

# 执行指定任务（单个任务调试）
python _debug.py task run <task_id>

# 重置所有卡住的任务
python _debug.py task reset
```

### 平台配置检查

```bash
# 列出所有平台及选择器配置
python _debug.py platform list

# 查看指定平台详细配置（选择器、清洗规则、设备配置等）
python _debug.py platform show <id>
```

### 账号池检查

```bash
# 查看账号池状态
python _debug.py account list
```

### DOM 分析与选择器验证

```bash
# 分析指定平台的 DOM 结构（PC 端）
python _debug.py dom analyze <platform_code>

# 分析指定平台的 DOM 结构（移动端）
python _debug.py dom analyze <platform_code> mobile

# 验证选择器是否能正确匹配 DOM 元素
python _debug.py dom verify <platform_code>
```

支持的平台代码：`deepseek`、`doubao`、`qianwen`、`wenxin`、`kimi`、`spark`、`baidu`、`quark`、`zhipu`、`douyin`、`yuanbao`、`nami`

### 数据库检查

```bash
# 检查数据库表结构和记录数
python _debug.py db check
```

---

## 工具脚本说明

| 脚本 | 用途 | 使用场景 |
|------|------|----------|
| `_debug.py` | GEO 统一调试工具（任务/平台/账号/DOM分析） | 本地开发调试、问题排查 |
| `init_geo_db.py` | 初始化 GEO 数据库表（ai_platform、ai_detect_task） | 首次部署或需要重置数据库时 |
| `start.bat` / `start.sh` | 一键启动 API + Worker + Redis | Windows / Linux / macOS 源码启动 |
| `install_camoufox.py` | 国内镜像加速安装 Camoufox 浏览器 + UBO | 首次安装或升级版本时运行 |
| `install_ubo.py` | 独立安装 uBlock Origin 插件 | UBO 单独安装/重装时 |
| `test_browser.py` | 快速测试 Camoufox 浏览器是否可用 | 安装后验证浏览器功能 |

---

## 图片输入

支持 OpenAI `image_url` 和 Anthropic `image`（base64）。格式：png/jpeg/webp/gif，单张最大 10MB，最多 5 张。远程 URL 会由服务端下载后上传。

---

## 客户端注意

项目会把会话 ID 以**不可见字符**附在 assistant 回复末尾。用 OpenAI SDK / Cursor 通常不用管；若自己保存聊天记录，不要把零宽字符清洗掉，否则下一轮可能无法复用会话。

---

## 代理与账号准备

- **家宽代理**：[Cliproxy](https://share.cliproxy.com/share/ftdzwxt2n)，选择「流量代理-账密模式」，会话类型选择 **Sticky IP**
- **IP 纯度检测**：[`https://ping0.cc/ip/`](https://ping0.cc/ip/)
- **AI 账号**：自行注册或购买成品号

---

## 开发检查

```bash
pip install ruff
ruff check .
```

---

## 安全提醒

请勿提交到公开仓库：`db.sqlite3`、`geo.sqlite3`、代理账号密码、`sessionKey`、抓包数据、真实对话。不要在同一个代理组下堆很多同类型账号，建议分散到不同 IP 降低风控风险。

---

## 常见问题

**为什么不直接封装网络包？** 登录态、前端协议、风控、会话复用都依赖真实浏览器环境。

**GEO 探测支持哪些 AI 平台？** 支持所有基于 Web 的 AI 平台。通过 API 配置 CSS 选择器即可接入新平台，无需改代码。

**Camoufox 和 Playwright 有什么区别？** Camoufox 是反检测浏览器，内置 Canvas/WebGL 指纹随机化，更难被 AI 平台的风控系统识别。Playwright 是回退方案。

**生产环境如何部署？** 推荐 Docker Compose 模式，自动启动 Redis 队列 + GEO Worker，支持并发任务处理。

**国内下载 Camoufox 慢怎么办？** 使用 `python install_camoufox.py`，工具会自动测速多个国内镜像站并选择最快的下载。安装工具内置了 pkgman.py 补丁，添加了：国内镜像重写、SSL 证书验证跳过、离线 config.json 加载等功能。

**Camoufox 浏览器支持哪些系统？** Windows 10+（x86_64）、Linux（x86_64/arm64）、macOS（x86_64/arm64）。已在 Windows x86_64 实测通过。

**如何跳过 uBlock Origin 插件？** 如果 UBO 下载失败，可在 `core/geo/browser.py` 中将 `exclude_addons` 参数传入 `[DefaultAddons.UBO]` 即可在无插件模式下运行。

**浏览器安装在哪个目录？** 默认安装到系统缓存目录：`%LOCALAPPDATA%\camoufox\camoufox\Cache`（Windows）或 `~/.cache/camoufox`（Linux/macOS）。可通过 `python -c "from camoufox.pkgman import INSTALL_DIR; print(INSTALL_DIR)"` 查看。

---

## 文档

- [GEO 改造方案](./GEO改造方案.md)
- [架构文档](docs/architecture.md)
- [配置说明](docs/config.md)
- [FAQ](docs/faq.md)

### Camoufox 相关

- [Camoufox 安装脚本](./install_camoufox.py) — 国内镜像加速，自动测速，内置 pkgman.py 补丁
- [uBlock Origin 安装脚本](./install_ubo.py) — 独立 UBO 安装
- [Camoufox 浏览器测试](./test_browser.py) — 快速验证浏览器可用性

### 调试工具

- [GEO 统一调试工具](./_debug.py) — 任务管理、平台检查、DOM 分析、选择器验证
- [GEO 数据库初始化](./init_geo_db.py) — 创建 ai_platform 和 ai_detect_task 表