API 技术文档

青果浏览器系统由两部分组成：

• 环境管理服务（远程） —— 管理用户、代理、指纹、环境等数据，部署在服务端
• 本地引擎（本机） —— 根据环境配置启动带指纹注入的浏览器，暴露 CDP 调试端口供自动化工具接管

两套服务共享同一个 API_KEY 鉴权体系。

一、快速开始

1. 获取 API Key（创建用户后自动生成），可以在客户端的【本地API】中查看到
2. 创建代理（可选） → POST 环境管理服务 /api/v1/proxy
3. 创建环境 → POST 环境管理服务 /api/v1/environment → 得到 env_id
4. 启动浏览器 → POST 本地引擎 /api/v1/browser/start → 得到 ws_endpoint / debug_port
5. 自动化接管 → Playwright / Selenium / DrissionPage 连接 ws_endpoint 或 debug_port
6. 关闭浏览器 → POST 本地引擎 /api/v1/browser/stop

二、通用约定

2.1 鉴权方式

所有业务接口（除健康检查外）均需在 HTTP Header 中携带：

Authorization: Bearer <API_KEY>

API_KEY 在用户创建后自动生成，环境管理服务和本地引擎共用同一个 Key。

2.2 统一响应结构

环境管理服务响应格式：

{
  "code": 200,
  "message": "success",
  "data": { }
}

本地引擎响应格式：

{
  "code": 0,
  "msg": "success",
  "data": { }
}

注意：两套服务的成功码不同——环境管理服务为 200，本地引擎为 0。HTTP 状态码均为 200（鉴权失败为 401）。

2.3 错误码汇总

本地引擎错误码：

环境管理服务错误码：

三、环境管理服务 API（远程）

基础地址：http://browser.qg.net:18082/api/v1（可通过 config.json 配置）
鉴权方式：Authorization: Bearer <API_KEY>

3.1 健康检查

3.2 代理管理

3.2.1 创建代理

{
  "name": "我的代理",
  "protocol_type": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "username": "user",
  "password": "pass",
  "ip_strategy": 0,
  "extraction_url": "",
  "remark": "备注信息"
}

3.2.2 检测代理连通性

{
  "protocol_type": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "username": "user",
  "password": "pass"
}

3.2.3 查询代理列表

3.3 环境管理

3.3.1 创建环境

{
  "name": "Facebook 环境 01",
  "platform": "facebook",
  "account": "myaccount@gmail.com",
  "password": "mypassword",
  "proxy_id": 1,
  "url": "https://www.facebook.com",
  "remark": "备注信息"
}

支持内联创建代理和自定义指纹，详见完整文档。

3.3.2 查询环境列表

3.3.3 查询环境详情

3.3.4 修改环境

3.3.5 删除环境

3.4 数据结构参考

包括 BrowserEnvironment、ProxyConfig、FingerprintConfig 对象，详细字段请参考技术文档。

四、本地引擎 API

监听地址：127.0.0.1:54345，基础路径：/api/v1

鉴权方式：Authorization: Bearer <API_KEY>

4.1 健康检查

{
  "status": "ok",
  "time": "2026-04-16T12:00:00+08:00"
}

4.2 启动浏览器

{
  "env_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "headless": false,
  "url": "https://www.facebook.com"
}

{
  "code": 0,
  "msg": "success",
  "data": {
    "env_id": "...",
    "ws_endpoint": "ws://127.0.0.1:19222/devtools/browser/...",
    "debug_port": 19222,
    "pid": 23456
  }
}

4.3 关闭浏览器

{ "env_id": "a1b2c3d4-..." }

4.4 关闭全部浏览器

4.5 查询浏览器状态

4.6 运行中浏览器列表

五、完整调用流程

环境管理服务（远程）
① POST /api/v1/proxy → 创建代理 → 得到 proxy_id
② POST /api/v1/environment → 创建环境（绑定 proxy_id + 指纹配置）→ 得到 env_id

本地引擎（本机）
③ POST /api/v1/browser/start { "env_id": "xxx" }
   → 自动拉取配置 → 启动浏览器 → 注入指纹 → 返回 ws_endpoint + debug_port

自动化工具
④ Playwright / Selenium / DrissionPage 连接接管
⑤ 执行自动化操作
⑥ POST /api/v1/browser/stop → 关闭浏览器

六、自动化接管示例

Playwright（推荐）

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(ws_endpoint)
    page = browser.contexts[0].pages[0]
    await page.goto("https://example.com")

Selenium

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.debugger_address = f"127.0.0.1:{debug_port}"
driver = webdriver.Chrome(options=options)
driver.get("https://example.com")

DrissionPage

from DrissionPage import ChromiumPage, ChromiumOptions

co = ChromiumOptions()
co.set_local_port(debug_port)
page = ChromiumPage(addr_or_opts=co)
page.get("https://example.com")

七、注意事项

• 鉴权一致：环境管理服务和本地引擎使用同一个 API_KEY。
• 端口范围：debug_port 由本地端口池动态分配（默认从 19222 起）。
• 代理认证：带用户名密码的代理由本地引擎通过 CDP 自动应答。
• 时区/语言自动填充：未配置时根据代理出口 IP 自动填充。
• 多实例隔离：每个 env_id 使用独立的 user-data 目录和调试端口。
• 自动清理：浏览器退出后自动释放端口并更新状态。
• 进程保障：主进程退出时子浏览器被终止，防止僵尸进程。
• 指纹校验：启动后打开本地校验页面展示指纹结果。

八、快速试用（curl）

# 创建代理
curl -X POST http://browser.qg.net:18082/api/v1/proxy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"测试代理","protocol_type":"http","host":"proxy.example.com","port":8080}'

# 创建环境
curl -X POST http://browser.qg.net:18082/api/v1/environment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo 环境","platform":"facebook","url":"https://www.facebook.com"}'

# 启动浏览器
curl -X POST http://127.0.0.1:54345/api/v1/browser/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"env_id":"a1b2c3d4-...","headless":false}'

# 查询列表
curl -H "Authorization: Bearer YOUR_API_KEY" http://127.0.0.1:54345/api/v1/browser/list

# 关闭浏览器
curl -X POST http://127.0.0.1:54345/api/v1/browser/stop \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"env_id":"a1b2c3d4-..."}'

九、Python SDK 与示例

完整的 Python SDK 封装和示例代码请参考附件。

主要文件：

• client.py - 本地引擎 API 轻量 SDK 封装
• demo_01_quickstart.py - 快速上手
• demo_02_playwright_attach.py - Playwright 接管
• demo_03_batch.py - 并行启动多个环境
• demo_04_selenium_attach.py - Selenium 接管
• demo_05_drissionpage_attach.py - DrissionPage 接管