Local API Documentation

灵盾浏览器本地 API 使用说明

本地 API 运行在当前电脑，用于让 ERP、RPA、自动化测试脚本或内部工具控制本客户端的浏览器环境。你可以创建环境、打开环境、关闭环境、删除环境，并在打开后取得 Puppeteer、Selenium、Debugger 和 WebDriver 连接信息。

创建环境示例 查看指纹字段
Base URL: http://127.0.0.1:19088
使用前请先在客户端「API 中心」启动本地 API。默认只允许当前电脑访问，需要局域网调用时再开启局域网访问。
Quick Check cURL 
curl "http://127.0.0.1:19088/health"
成功返回
{
  "success": true,
  "data": {
    "status": "running",
    "host": "127.0.0.1",
    "port": 19088
  }
}

接口列表

所有接口都通过客户端本地 API 调用，环境查询和分页由服务端完成，本地接口只作为当前电脑的控制入口。

方法 地址 说明 常见用途
GET/health查看本地 API 是否运行脚本启动前检查
GET/status查看开放状态、端口和访问范围运维巡检
GET/docs返回接口列表和线上文档地址快速发现接口
GET/openapi返回接口说明摘要内部工具集成
GET/profiles?page=1&pageSize=20&keyword=服务端分页查询环境按名称、ID 或编码检索
POST/profiles/random按后台指纹规则树创建随机环境批量初始化环境
POST/profiles创建指定指纹环境精确指定 UA、WebGL、TLS 等
GET/profiles/{idOrCode}按环境 ID、自增 ID 或 6 位编码查询环境打开前确认环境
POST/profiles/{idOrCode}/start打开环境并返回自动化连接信息Puppeteer / Selenium 接管
POST/profiles/{idOrCode}/close关闭环境结束当前浏览器窗口
POST/profiles/{idOrCode}/stop关闭环境，等同于 close兼容不同调用习惯
DEL/profiles/{idOrCode}删除环境，删除前会尝试关闭会话清理无效环境
POST /profiles/random

创建随机环境

随机环境会从后台指纹规则树取值，保证 Windows 环境不会随机到 Linux UA、macOS 字体或不匹配的 WebGL/TLS。

browserType浏览器类型，当前使用 Chrome。
browserMajor浏览器主版本，例如 138。
osType操作系统，例如 Windows 11、Windows 10、macOS、Linux。
fingerprintPlatform平台节点，例如 windows-x64、macos-arm64、linux-x64。
cURL JSON 
curl -X POST "http://127.0.0.1:19088/profiles/random" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API 随机环境",
    "browserType": "Chrome",
    "browserMajor": "138",
    "osType": "Windows 11",
    "fingerprintPlatform": "windows-x64",
    "startupUrls": "https://example.com"
  }'
POST /profiles

创建指定指纹环境

当你需要确定的浏览器环境时，可以手动指定指纹字段。手动指定的值应当与浏览器版本、系统和平台匹配。

时区、语言和 WebRTC 默认建议跟随代理出口。手动指定时需要同时提供具体值。
cURL 指定指纹 
curl -X POST "http://127.0.0.1:19088/profiles" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API 指定指纹环境",
    "browser": "Chrome",
    "os": "Windows 11",
    "startupUrls": "https://example.com",
    "fingerprint": {
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
      "timezoneMode": "跟随代理",
      "languageMode": "跟随代理",
      "webRtcMode": "指定当前 IP",
      "screenResolution": "1920x1080",
      "hardwareConcurrency": "8",
      "deviceMemory": "8",
      "webglMode": "噪声",
      "webglVendor": "Google Inc. (Intel)",
      "webglRenderer": "ANGLE (Intel, Intel(R) UHD Graphics Direct3D11 vs_5_0 ps_5_0, D3D11)",
      "fontMode": "随机",
      "tlsMode": "随机"
    }
  }'
POST /profiles/{idOrCode}/start

打开环境并返回连接信息

{idOrCode} 可以替换为环境 ID、用户内自增 ID 或 6 位环境编码。默认会加载该环境已启用的浏览器插件；如不加载插件，可传 {"loadPlugins": false}。

debugPort浏览器 DevTools 调试端口。
puppeteer.browserURLPuppeteer 连接地址。
selenium.debuggerAddressSelenium 附加到已打开浏览器的调试地址。
webdriver.pathchrome.exe 平级目录下的 WebDriver 路径。
Start Response 
curl -X POST "http://127.0.0.1:19088/profiles/A1B2C3/start" \
  -H "Content-Type: application/json" \
  -d '{"source":"local-api"}'
成功返回 JSON 示例
{
  "success": true,
  "data": {
    "profile": { "id": "egprof_xxx", "name": "API 随机环境" },
    "session": { "id": "sess_xxx" },
    "launch": {
      "pid": 12345,
      "debugPort": 28901,
      "automation": {
        "debugger": {
          "httpUrl": "http://127.0.0.1:28901",
          "listUrl": "http://127.0.0.1:28901/json/list",
          "versionUrl": "http://127.0.0.1:28901/json/version",
          "websocketUrl": "ws://127.0.0.1:28901/devtools/page/xxx"
        },
        "puppeteer": {
          "browserURL": "http://127.0.0.1:28901",
          "browserWSEndpoint": "ws://127.0.0.1:28901/devtools/page/xxx"
        },
        "selenium": {
          "debuggerAddress": "127.0.0.1:28901",
          "chromeDriverPath": "D:\\Chrome\\chromedriver.exe"
        },
        "webdriver": {
          "path": "D:\\Chrome\\chromedriver.exe",
          "detected": true
        }
      }
    }
  }
}

自动化连接示例

打开环境后，外部工具不需要重新启动浏览器，只需要连接返回的 Debugger 或 WebDriver 信息即可。

推荐先调用打开环境接口，再把返回的连接信息交给 Puppeteer、Playwright 或 Selenium。
Puppeteer Selenium 
import puppeteer from "puppeteer-core";

const response = await fetch("http://127.0.0.1:19088/profiles/A1B2C3/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ source: "puppeteer-demo" })
});

const result = await response.json();
const browser = await puppeteer.connect({
  browserURL: result.data.launch.automation.puppeteer.browserURL
});

const pages = await browser.pages();
await pages[0].goto("https://example.com");
Selenium 附加到已打开窗口
import { Builder } from "selenium-webdriver";
import chrome from "selenium-webdriver/chrome.js";

const automation = result.data.launch.automation;
const options = new chrome.Options();
options.debuggerAddress(automation.selenium.debuggerAddress);

const service = new chrome.ServiceBuilder(automation.webdriver.path);
const driver = await new Builder()
  .forBrowser("chrome")
  .setChromeOptions(options)
  .setChromeService(service)
  .build();
POST /profiles/{idOrCode}/close DEL /profiles/{idOrCode}

关闭与删除环境

关闭环境只结束当前浏览器窗口，环境数据仍然保留。删除环境会移除该环境记录，删除前会尝试关闭正在运行的会话。

Close Delete 
curl -X POST "http://127.0.0.1:19088/profiles/A1B2C3/close" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X DELETE "http://127.0.0.1:19088/profiles/A1B2C3"

指纹字段关系表

后台规则树结构为：浏览器类型 -> 浏览器主版本 -> 操作系统 -> 平台 -> 指纹类型 -> 候选值。如果一个值依赖另一个值，它会作为上一个值的子项，例如 WebGL Renderer 依赖 GPU。

字段 位置 取值范围或内容 依赖关系 说明
browserTypeprofiles/randomChrome根节点浏览器类型
browserMajorprofiles/random138 或后台已维护主版本browserType浏览器主版本
osTypeprofiles/randomWindows 11；Windows 10；macOS；LinuxbrowserMajor操作系统
fingerprintPlatformprofiles/randomwindows-x64；windows-arm64；macos-arm64；macos-x64；linux-x64osType指纹平台
nameprofiles/random 或 profiles1-120 个字符无环境名称
groupIdprofiles/random 或 profiles已存在分组 ID无不传使用默认分组
proxyIdprofiles/random 或 profiles已存在代理 ID无不传则不绑定代理
startupUrlsprofiles/random 或 profilesURL 文本，可换行无启动后打开的网址
browserVersionIdprofiles/random 或 profiles后台浏览器版本 IDplatform不传使用默认浏览器版本
fingerprint.userAgentprofiles后台 UA 候选或完整 UA 字符串browserMajor + osType + platform必须与系统平台匹配
fingerprint.timezoneModeprofiles跟随代理；手动指定proxy默认跟随代理出口
fingerprint.timezoneprofilesIANA 时区，例如 Asia/ShanghaitimezoneMode=手动指定手动指定时必填
fingerprint.languageModeprofiles跟随代理；手动指定proxy默认跟随代理出口
fingerprint.languageprofilesBCP47 语言，例如 zh-CN；en-USlanguageMode=手动指定手动指定时必填
fingerprint.webRtcModeprofiles指定当前 IP；手动指定 IP；禁用proxy默认跟随代理出口 IP
fingerprint.webRtcIpprofilesIPv4webRtcMode=手动指定 IP手动指定时必填
fingerprint.geolocationModeprofiles跟随代理；手动指定；禁用proxy默认跟随代理出口
fingerprint.screenResolutionprofiles1366x768；1440x900；1536x864；1600x900；1920x1080；2560x1440platform屏幕分辨率
fingerprint.hardwareConcurrencyprofiles2；4；6；8；10；12；16；24；32platformCPU 线程数
fingerprint.deviceMemoryprofiles2；4；8；16；32platform设备内存 GB
fingerprint.canvasModeprofiles真实；噪声无Canvas 指纹模式
fingerprint.clientRectsModeprofiles真实；噪声无ClientRects 指纹模式
fingerprint.audioContextModeprofiles真实；噪声无AudioContext 指纹模式
fingerprint.webglModeprofiles真实；噪声；禁用GPUWebGL 指纹模式
fingerprint.webglVendorprofiles后台 WebGL vendor 候选GPU需要与 renderer 成对
fingerprint.webglRendererprofiles后台 WebGL renderer 候选GPU需要与 vendor 成对
fingerprint.fontModeprofiles随机；手动指定；禁用platform基础字体默认包含
fingerprint.fontsprofiles字体名数组platform附加字体候选
fingerprint.tlsModeprofiles随机；指定platformTLS 指纹模式
fingerprint.tlsProfileprofiles后台 TLS 候选 JSONtlsMode=指定指定 TLS 时传入
fingerprint.mediaDevicesModeprofiles真实；模拟；禁用platform媒体设备模式
fingerprint.mediaDevicesprofilesJSON videoInput/audioInput/audioOutputmediaDevicesMode=模拟设备数量