指纹浏览器 API 与 Local API 教程

在设置中开启 Local API

登录客户端，进入「设置 → Local API」并打开开关。默认端口为 54345，首次开启会生成以 fgbk_ 开头的密钥。复制密钥供脚本使用；端口被其他程序占用时，在设置里更换端口，并同步修改脚本的连接地址。

团队所有者、管理员或获授 Local API 权限的成员，且套餐包含该功能时，才能开启接口。退出登录、权限或套餐变化时服务会停止。接口只监听本机地址，脚本需要与客户端在同一台电脑运行，不能直接从另一台电脑访问这个端口。

请求鉴权与业务返回值

请求使用 POST 和 JSON，请求头带 Content-Type: application/json，再用 x-api-key 传密钥，也支持 Bearer 鉴权。密钥错误会返回未授权。重新生成密钥后，旧密钥立即失效，需要更新使用它的脚本。不要把实际密钥写进共享代码或提交到代码仓库。

HTTP 请求成功不一定表示业务完成。接口可能返回 HTTP 200，同时在正文中给出 success: false、错误说明和 code。脚本应同时检查 HTTP 状态与业务结果。环境参数可用 UUID，也可用环境编号；迁移脚本时要换成本客户端中的环境标识，不能沿用来源软件的 ID。

准备示例环境和依赖

先在客户端准备一个可用环境，确认代理正常、没有被其他设备占用，再记录环境编号。下面的两份脚本分别保存为 api-puppeteer.mjs 和 api-playwright.py，任选一种运行即可。它们读取密钥和环境编号，打开已有环境，访问示例网页并打印标题，结束时正常关闭环境。

Node.js 需要支持内置 fetch，并安装 puppeteer-core；Python 安装 requests 和 playwright。示例连接客户端已经启动的浏览器，不通过自动化库另开浏览器实例。以下命令用于 Bash 终端，运行前把环境编号和密钥换成自己的值，密钥在「设置 → Local API」里复制。

# Node.js 示例依赖
npm install puppeteer-core
# Python 示例依赖
python3 -m pip install requests playwright

# 两个示例共用的连接参数
export FGB_BASE='http://127.0.0.1:54345'
export FGB_PROFILE_ID='1'
export FGB_KEY='fgbk_xxxxxxxx'  # 换成「设置 → Local API」里的密钥

# 保存下方对应脚本后，任选一条运行
node api-puppeteer.mjs
# python3 api-playwright.py

使用 Puppeteer 连接环境

这份示例先调用打开接口，再把返回的 ws 交给 Puppeteer。连接时不覆盖默认视口，读取现有网页标签，不去操作环境窗口自己的地址栏和标签栏。正常执行或网页访问报错后，都会进入清理步骤，断开调试连接，再通过关闭接口结束环境。

环境已经在本机运行时，打开接口会接管现有环境，不会重新创建一个窗口。因此示例适合使用专门准备的环境，执行前确认其中没有需要保留的未提交网页内容。后续扩展脚本时，可以在读取标题的位置加入自己的网页操作。

import puppeteer from 'puppeteer-core';

const base = process.env.FGB_BASE || 'http://127.0.0.1:54345';
const key = process.env.FGB_KEY;
const id = process.env.FGB_PROFILE_ID;
if (!key || !id) throw new Error('请设置 FGB_KEY 和 FGB_PROFILE_ID');

async function call(path, body = {}) {
  const res = await fetch(base + path, {
    method: 'POST',
    headers: { 'x-api-key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const result = await res.json();
  if (!result.success) {
    throw new Error(`${result.code || 'API_ERROR'}: ${result.msg || '请求失败'}`);
  }
  return result.data;
}

await call('/health');
const info = await call('/browser/open', { id });
let browser;
try {
  browser = await puppeteer.connect({
    browserWSEndpoint: info.ws,
    defaultViewport: null
  });
  const [page] = await browser.pages();
  if (!page) throw new Error('环境中没有可用网页标签');
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  try {
    if (browser) await browser.disconnect();
  } finally {
    await call('/browser/close', { id });
  }
}

使用 Playwright 连接环境

Python 示例使用同一个打开接口，用 Playwright 连接返回的 CDP 地址，然后访问现有上下文里的网页。环境本身已经提供隔离，因此使用现有上下文即可，不要再调用新建隔离上下文的方法。打开接口成功后，即使后续连接或访问失败，脚本也会请求正常关闭环境。

如果需要增加网页标签，可以使用现有上下文的新建页面方法。关闭环境会执行正常同步流程；有关 Cookie 和本地存储分别在何时上传，可查看指纹浏览器云同步，不要用直接结束进程代替接口关闭。

import os
import requests
from playwright.sync_api import sync_playwright

BASE = os.environ.get('FGB_BASE', 'http://127.0.0.1:54345')
KEY = os.environ.get('FGB_KEY')
PROFILE_ID = os.environ.get('FGB_PROFILE_ID')
if not KEY or not PROFILE_ID:
    raise RuntimeError('请设置 FGB_KEY 和 FGB_PROFILE_ID')

def call(path, body=None):
    response = requests.post(
        BASE + path,
        json={} if body is None else body,
        headers={'x-api-key': KEY},
        timeout=120
    )
    response.raise_for_status()
    result = response.json()
    if not result.get('success'):
        raise RuntimeError(
            f"{result.get('code', 'API_ERROR')}: {result.get('msg', '请求失败')}"
        )
    return result['data']

call('/health')
info = call('/browser/open', {'id': PROFILE_ID})
try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(info['ws'])
        page = browser.contexts[0].pages[0]
        page.goto('https://example.com', wait_until='domcontentloaded')
        print(page.title())
finally:
    call('/browser/close', {'id': PROFILE_ID})

CDP 地址和环境关闭方式

Local API 的监听端口与环境的调试端口是两回事。每个环境打开后分配自己的调试端口，关闭重开后可能变化，每次都应使用打开接口最新返回的地址。返回地址只提供网页调试目标，客户端自身界面和开发者工具不在网页列表中。

新建网页标签受到支持，但无头模式和环境内另建隔离上下文不受支持。Puppeteer 的关闭浏览器操作也会进入正常关闭流程，先同步再退出。需要保留窗口继续人工操作时，可以只断开调试连接；本文示例则明确在结束后关闭所用环境。

连接失败和环境占用处理

连接被拒绝时先确认客户端已登录、接口已开启、地址端口一致；未授权时检查密钥是否重新生成过。环境被其他设备打开会返回 PROFILE_OCCUPIED，应先由使用方正常关闭，不能靠重复调用抢占。环境不存在时核对当前账号可见范围和环境编号。

开发批量流程时，先让单个环境完成打开、网页操作和关闭，再增加循环与错误记录。需要由运营成员在界面中选择环境、查看进度和处理人工步骤时，可以把固定流程做成自动化插件。接口兼容范围与网页脚本是否适配，应分别核对。

常见问题