Qiyuan SDK 接口文档

仅 client / all 模式可用。读取当前客户端使用的共享 Token，用于初始化系统设置页面。

响应示例

{ "success": true, "data": { "token": "your-token" } }

仅 client / all 模式可用。更新客户端本地 Token，不修改服务端 Token。

JSON 参数

响应示例

{ "success": true, "data": { "updated": true } }

仅 client / all 模式可用，使用 multipart/form-data。内核只保存到浏览器应用数据目录。

表单参数

响应示例

{ "success": true, "data": { "kernels": { "chrome": { "installed_versions": ["150.0.7871.116"] } } } }

Query 参数

响应示例

{
  "success": true,
  "data": {
  "total": 100,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "code": "a1b2c3d4...",         // string  环境唯一标识，后续操作均使用此字段
      "name": "测试账号-01",
      "platform": "Win32",          // Win32 / MacIntel / Linux x86_64
      "browser_kernel": "chrome", // chrome（Chromium）/ firefox
      "browser_version": "150.0.7871.115",
      "user_agent": "Mozilla/5.0 ...",
      "proxy_code": "1716523...",    // 绑定代理的唯一标识，未绑定为 null
      "open_home_page": false,
      "remark": "备注信息",
      "tag_ids": [1, 2],
      "status": "stopped",          // running | stopped
      "pid": null,                  // 进程 pid，running 时有值
      "create_time": "2026-01-01 00:00:00",
      "update_time": "2026-06-01 12:00:00"
    }
  ],
  "total_pages": 5
  }
}

指纹字段（均可选，表单风格；不传走随机默认）

响应示例

{ "success": true, "data": { "code": "新环境的唯一标识" } }

返回单个环境的完整字段 + 扁平指纹，供编辑表单回填。

Query 参数

响应示例

{
  "success": true,
  "data": {
  "code": "...", "name": "...", "platform": "Win32",
  "browser_kernel": "chrome",
  "browser_version": "147.0.7727.102", "user_agent": "...",
  "proxy_code": null, "open_home_page": false,
  "enable_tabs": false, "tabs": "", "sync_user_info": false,
  "cookie": "", "launch_args": "", "remark": "",
  "fingerprint": { /* 扁平指纹：webgl_type, webgl_value, timezone_type, ... */ }
  }
}

响应示例

{ "success": true }

响应示例

data 为新生成的指纹对象。

{ "success": true, "data": { "webgl_vendor": "Google Inc. (Intel)", "canvas": "random" } }

删除环境记录，并自动关闭其运行中的浏览器、清理本地缓存目录。

响应示例

{ "success": true }

client 模式启动：以 --mode=client --uuid={code} --token={token} 拉起启元定制内核（路径 %USERPROFILE%\.qiyuan\client\{browser_version}\QyBrowser.exe，user-data-dir = %USERPROFILE%\.qiyuan\user_data\{uuid}）。不再传 --user-agent / --proxy-server / --remote-debugging-port——浏览器自身回调 GET /api/v1/browser/md5/{uuid} 拉取并解密指纹后内部应用。打开前 SDK 会把 admin 服务地址写入 config.json 的 base_api_path。

响应示例

{ "success": true, "data": { "pid": 12345, "debug_port": 19222, "browser_kernel": "chrome", "debug_protocol": "cdp" } }

Query 参数

响应示例

{ "success": true, "data": { "code": "...", "status": "running", "pid": 12345 } }

删除该环境的本地 user-data-dir 缓存目录。若浏览器正在运行会先关闭。

Query 参数

响应示例

{
  "success": true,
  "data": {
  "total": 3,
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "items": [
    {
      "code": "f3a9...",
      "proxy_name": "美国节点",
      "proxy_type": "http",   // http / https / socks5
      "proxy_addr": "1.2.3.4",
      "proxy_port": 8080,
      "proxy_input_type": "manual"
    }
  ]
  }
}

Query 参数

响应示例

{ "success": true, "data": { "code": "f3a9...", "proxy_name": "美国节点", "proxy_type": "http", "proxy_addr": "1.2.3.4", "proxy_port": 8080 } }

响应示例

{ "success": true, "data": { "code": "新代理的唯一标识" } }

响应示例

{ "success": true }

响应示例

{ "success": true }

鉴权：Authorization: Bearer {token}。返回加密后的指纹（base64 字符串）。

Query 参数

响应

{ "code": 200, "success": true, "data": "<base64 密文 或 明文对象>" }

解密方式 · AES（默认）

base64 解码 → 前 16 字节为 IV → AES-256-CBC / PKCS7 → 指纹 JSON 明文。

version=1.0（默认）密钥：字符串 aes-key-32-bytes-change!!!!! 末尾补 \0 到 32 字节。

version=2.0 密钥：SHA-256( "aes-key-32-bytes-change!!!!!" + "_qiyuan_" + 用户认证token ) 的 32 字节摘要（token 即请求头 Bearer）。每用户唯一；内核须用同一算法派生密钥。

解密方式 · RSA（encrypt_type=rsa，AES 加密 + RSA 签名）

密文 = base64( SIGN[keysize/8] + IV[16] + AES-256-CBC(PKCS7(json)) )。其中 SIGN = RSASSA-PKCS1-v1_5( 私钥, SHA-256( IV+密文 ) )（2048-bit = 256 字节）。AES 密钥恒用 version=2.0 的 token 派生密钥。

内核侧：base64 解码 → 前 256 字节为签名、其余为 IV+密文 → 用内置公钥 SHA-256 验签（失败即拒绝，不解密）→ 用 token 派生 AES key 解出 16 字节 IV 与密文 → AES-CBC 得 JSON。

方向：服务端持私钥签名，内核仅内置公钥验签，私钥永不下发。SDK 与 backend 各自独立密钥对（PEM 随仓库提供：SDK sdk/keys/、backend app/config/keys/；只把对应 rsa_public.pem 编入内核）。

明文结构（节选）

{
  "platform": "Win32",
  "user_agent": "Mozilla/5.0 ...",
  "browser_version": "147.0.7727.102",
  "webgl": { "type": "custom", "value": "Google Inc. (NVIDIA)|ANGLE (NVIDIA, NVIDIA GeForce RTX 4070 Ti Direct3D11 vs_5_0 ps_5_0, D3D11)" },
  "webgpu": { "type": "custom", "value": "nvidia|..." },
  "timezone": { "type": "ip", "value": null },
  "language": { "type": "ip", "value": null },
  "geo_location": { "type": "ip", "value": null },
  "hardware_info": { "color_depth": "24", "cpu_cores": "8", "memory_gb": "8" },
  "font": "1", "canvas": "0.37", "audio": "42",
  "speech_voices": true, "media_devices": ["a1b2..."],
  "open_home_page": false, "enable_tabs": false, "tabs": "",
  "cookie": "", "launch_args": "",
  "proxy_info": { "proxy_type": "http", "proxy_addr": "1.2.3.4", "proxy_port": "8080", "username": "u", "password": "p" }
}

无需 token。

响应

{ "code": 200, "success": true, "data": { "code": "a1b2c3d4" } }  // code 用于拼错误页

仅当该环境 enable_tabs=true 时保存；按域名去重、跳过起始页/内部地址（chrome://、about: 等）、最多 5 条。

经该代理访问 geo 服务，返回与 ip-geo 兼容的结构。

响应

{ "success": true, "ip": "1.2.3.4", "country_code": "US",
  "latitude": 37.7, "longitude": -122.4,
  "timezone": { "id": "America/Los_Angeles" } }

鉴权：Authorization: Bearer {token}。

Query 参数

响应

同 check-proxy（success / ip / country_code / latitude / longitude / timezone.id …）。

响应

{ "success": true }

Query 参数

响应示例

{ "success": true, "data": { "items": [{ "code": "demo", "name": "示例扩展", "version": "1.0", "browser_kernel": "chrome", "extension_type": "normal", "environment_codes": ["*"] }], "total": 1, "page": 1, "page_size": 20, "total_pages": 1 } }

Query 参数

响应示例

{ "success": true, "data": { "code": "demo", "name": "示例扩展", "version": "1.0", "browser_kernel": "chrome", "extension_type": "normal", "status": 1, "environment_codes": ["*"] } }

请求类型：multipart/form-data。

响应示例

{ "success": true, "data": { "code": "demo", "name": "示例扩展", "version": "1.0", "environment_codes": ["*"] } }

请求类型：multipart/form-data。

响应示例

{ "success": true, "data": { "code": "demo", "version": "1.1", "environment_codes": ["*"] } }

JSON 参数

响应示例

{ "success": true, "data": { "code": "demo" } }

JSON 参数

响应示例

{ "success": true, "data": { "code": "demo", "environment_codes": ["*"] } }

JSON 参数

响应示例

{ "success": true, "data": [{ "code": "demo", "status": "success", "target_path": "..." }] }

开启起始页时浏览器加载的页面：顶部 IP 检测横幅 + 环境信息 + 指纹信息。Query：md5（环境唯一标识）。有代理时通过 check-proxy 进行检测。

启动异常时浏览器加载的页面，展示错误编号 / 标题 / 时间。Query：code（错误编号，来自 error/report）。

无需 token。返回 { browser, fingerprint, proxy } 三段（中文化展示值）。

{ "code": 200, "success": true, "data": {
  "browser": { "name": "...", "proxy_mode_cn": "集成代理", "sync_user": "关闭", ... },
  "fingerprint": { "platform": "Windows", "webgl": "自定义 - NVIDIA / RTX 4090", ... },
  "proxy": { "proxy_mode": "existing", "proxy_addr": "1.2.3.4", "proxy_port": 8080, ... }
} }

无需 token。

{ "code": 200, "success": true, "data": { "code": "a1b2c3d4", "title": "启动失败", "error_time": "2026-06-24 12:00:00" } }