Aurorium 本地 API v1

本地 API 允许计算机上运行的脚本管理 Aurorium 配置文件、浏览器会话、文件夹、代理和 Cookie。服务器随桌面应用启动，仅可在同一台计算机上访问。

#快速开始

  1. 启动 Aurorium 并登录您的账户。
  2. 打开“自动化”→“API”，生成 API 密钥。
  3. 立即保存密钥：后端仅显示一次。
  4. 每次请求都使用 Authorization: Bearer <api_key> 发送密钥。
bash
curl "http://127.0.0.1:50325/api/v1/health" \
  -H "Authorization: Bearer $AURORIUM_API_KEY"

基础 URL：

text
http://127.0.0.1:50325/api/v1

服务器仅监听 127.0.0.1，不监听外部网络接口。当前固定端口为 50325。

#响应格式

成功结果和应用错误使用相同的响应外层结构：

json
{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "req_0d30b83f3fbb43e6a2e1b255e21d24b8"
}
  • code = 0 表示成功。
  • code != 0 表示应用错误；仅检查 HTTP 状态并不足够。
  • 在集成日志中保存 request_id，以便诊断问题。
  • 即使发生应用错误，服务器通常仍返回 HTTP 200。
  • 如果 JSON 请求体超过 5 MiB，API 将返回 code: 1001 和 msg: "request body too large"。

错误示例：

json
{
  "code": 1201,
  "msg": "profile not found",
  "data": null,
  "request_id": "req_7f3ab37ea65048f99ebd0fdbe6f4da63"
}

#通用参数

列表端点接受以下参数：

参数默认值限制
page1最小 1
page_size50最大 200；更大的值会被限制为 200

列表响应的 data 格式：

json
{
  "list": [],
  "page": 1,
  "page_size": 50,
  "total": 0
}

#端点概览

方法路径用途
GET/health应用与云端连接的就绪状态
GET/version应用与 API 版本
GET/profile列出未归档的配置文件
POST/profile创建配置文件
GET/profile/:id获取配置文件详情
PATCH/profile/:id部分更新配置文件
DELETE/profile/:id删除配置文件
GET/folder列出文件夹
POST/folder创建文件夹
PUT/folder/:id重命名文件夹
DELETE/folder/:id删除文件夹
GET/browser/status获取配置文件启动状态
GET/browser/active列出正在运行的配置文件
POST/browser/start启动配置文件并提供 CDP
POST/browser/stop停止配置文件
POST/browser/stop-all停止本地配置文件
POST/proxy/check检查代理
PUT/profile/:id/proxy替换配置文件代理
GET/profile/:id/cookies导出 Cookie
POST/profile/:id/cookies/import导入 Cookie
GET/device列出账户设备
GET/catalog获取允许的指纹值

#系统

#GET /health

返回本地应用就绪状态、云端连接状态和当前设备 ID。

json
{
  "ready": true,
  "cloud_connected": true,
  "device_id": "device-id-or-null"
}

即使是健康检查也需要身份验证。

#GET /version

json
{
  "app_version": "0.3.1",
  "core_version": null,
  "api_version": "v1"
}

core_version 尚未实现，始终返回 null。

#配置文件

#GET /profile

查询参数：

参数取值说明
folder_idObjectId按文件夹筛选
name字符串按名称搜索
statusall, running, idle默认为 all
page, page_size整数分页

列表项：

json
{
  "profile_id": "507f1f77bcf86cd799439011",
  "name": "Automation profile",
  "folder_id": null,
  "status": "idle",
  "location": null,
  "os": "windows",
  "os_version": "Windows 11",
  "core": "chrome",
  "core_version": "134",
  "description": "",
  "created_at": "2026-07-24T10:00:00Z",
  "updated_at": "2026-07-24T10:00:00Z"
}

不会返回已归档的配置文件。running|idle 筛选仅在页面加载后由客户端应用，因此 total 和页面项目数量可能与筛选后的列表不一致。

#POST /profile

最小请求：

json
{
  "name": "Automation profile"
}

支持的字段：

字段类型必填备注
name字符串是非空名称
description字符串否默认为 ""
folder_id字符串或 null否Mongo ObjectId；null 表示无文件夹
tags数组否默认为 []
os字符串否windows, macos, linux
os_version字符串否用于生成指纹的操作系统版本提示，例如 "11" 或 "Tahoe"；推荐值请参阅 /catalog
is_arm布尔值否ARM 提示；省略时根据 GPU 厂商推断
proxy对象否按下述格式内联提供代理
proxy_id字符串否现有代理引用；proxy 优先
launch_arguments字符串否以单个字符串提供启动参数
start_page字符串否起始页
fingerprint对象否部分覆盖指纹设置

使用代理的示例：

json
{
  "name": "Profile with proxy",
  "os": "windows",
  "proxy": {
    "type": "socks5",
    "host": "127.0.0.1",
    "port": 1080,
    "user": "login",
    "password": "secret"
  }
}

配置文件在后端异步创建。本地 API 等待完成事件，通常返回完整的配置文件模型。如果后续读取失败，可能仅返回 profile_id。

#GET /profile/:id

返回列表项，并附带 proxy 和 fingerprint 对象。代理密码绝不会以明文返回；存在密码时会替换为 ******。

#PATCH /profile/:id

部分更新配置文件：

json
{
  "name": "New name",
  "description": "Updated through API",
  "folder_id": null,
  "fingerprint": {
    "timezone_mode": "manual",
    "timezone": "Europe/Moscow"
  }
}

空请求体会成功返回，不执行任何操作。元数据立即应用。配置文件停止时，指纹更改立即应用；正在运行时则延迟到下次启动，并列在 deferred_fields 中。

json
{
  "profile_id": "507f1f77bcf86cd799439011",
  "deferred_fields": ["fingerprint.timezone_mode", "fingerprint.timezone"]
}

对于已停止的配置文件，deferred_fields 始终为空。

#DELETE /profile/:id

force=true 查询会在删除前停止当前设备上运行的配置文件。如果不提供 force，此类配置文件将返回 1203。

json
{
  "profile_id": "507f1f77bcf86cd799439011",
  "deleted": true
}

对于语法有效的 ObjectId，删除操作是幂等的：目前后端的“未找到”响应会被视为配置文件已删除。

#指纹

POST 和 PATCH 中的 fingerprint 对象支持部分更新以下字段：

字段类型或取值
timezone_modeauto, manual
timezone字符串或 null
language_modeauto, manual
languages字符串数组；使用第一项
language字符串；可作为简写替代
screen_resolution字符串
webrtc_modereal, replace
canvas_noise布尔值
webgl_image_noise布尔值
webgl_vendor字符串或 null
webgl_renderer字符串或 null
audio_noise布尔值
client_rects_noise布尔值
hardware_concurrency数值
device_memory数值
do_not_trackdefault, true
os_version字符串
dns_modereal, manual
dns_server字符串或 null
geolocation{mode, latitude, longitude, accuracy}
media_devices{audio_inputs, audio_outputs, video_inputs}

使用 /catalog 获取兼容的操作系统、GPU、CPU、RAM、屏幕、时区和语言值。

#文件夹

#GET /folder

支持 name、page 和 page_size。

json
{
  "folder_id": "507f1f77bcf86cd799439012",
  "name": "QA",
  "profile_count": 3,
  "system": false
}

#POST /folder

json
{ "name": "QA" }

#PUT /folder/:id

json
{ "name": "QA automation" }

#DELETE /folder/:id

删除文件夹不会删除配置文件。后端会将团队配置文件移到系统文件夹，将个人配置文件设为无文件夹状态。

json
{
  "folder_id": "507f1f77bcf86cd799439012",
  "deleted": true,
  "moved_profiles": 3,
  "moved_to": null
}

moved_profiles 和 moved_to 在删除前尽力计算；无法读取云端状态时，结果可能不准确。

#浏览器生命周期

#GET /browser/status?profile_id=:id

返回 idle 或 running、启动设备以及本地可用的进程连接与标识信息。

#GET /browser/active

scope 查询接受以下值：

  • this_device — 本地运行的配置文件，为默认值；
  • account — 根据云端注册表，列出该账户所有设备上运行的配置文件。

支持标准分页。

#POST /browser/start

json
{
  "profile_id": "507f1f77bcf86cd799439011",
  "headless": false,
  "open_urls": ["https://example.com"],
  "launch_args": ["--window-size=1280,800"],
  "load_extensions": true
}

成功响应：

json
{
  "profile_id": "507f1f77bcf86cd799439011",
  "already_running": false,
  "debug_port": 51432,
  "ws": "ws://127.0.0.1:51432/devtools/browser/...",
  "webdriver": null,
  "pid": 12345,
  "lease": {
    "device_id": "device-id",
    "device_name": "Workstation",
    "is_current_device": true
  }
}

在当前设备上再次启动配置文件是幂等操作。配置文件在其他设备上运行时返回 1204。如果所需浏览器内核缺失或正在下载，本地 API 返回 1304；此方法不会自动下载内核。

#POST /browser/stop

json
{ "profile_id": "507f1f77bcf86cd799439011" }

停止操作是幂等的，并返回 was_running。

#POST /browser/stop-all

停止当前设备上的所有配置文件：

json
{
  "stopped": ["507f1f77bcf86cd799439011"],
  "count": 1
}

#代理

内联代理格式：

字段类型备注
type字符串http, socks4, socks5, ssh, no_proxy
host字符串除 no_proxy 外均为必填
port整数/字符串1..65535，no_proxy 除外
user字符串可选
password字符串可选
refresh_url字符串可选

#POST /proxy/check

必须且只能提供一个来源：proxy 或 profile_id。

json
{
  "proxy": {
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080
  }
}
json
{
  "ok": true,
  "exit_ip": "203.0.113.10",
  "country": "DE",
  "city": "Frankfurt",
  "latitude": 50.11,
  "longitude": 8.68,
  "timezone": null,
  "latency_ms": null
}

#PUT /profile/:id/proxy

请求体是代理对象本身，无需 proxy 包装：

json
{
  "type": "no_proxy"
}

对于正在运行的配置文件，更改会延迟到下次启动，响应包含 deferred_fields: ["proxy"]。

#Cookie

Cookie 使用扁平格式：

json
{
  "domain": ".example.com",
  "name": "session",
  "value": "value",
  "path": "/",
  "expires": 1790000000,
  "http_only": true,
  "secure": true,
  "same_site": "lax"
}

expires 是以秒为单位的 Unix 时间；0 或 null 表示会话 Cookie。same_site 接受 unspecified、no_restriction、lax 或 strict。

#GET /profile/:id/cookies

优先读取本地 Chromium SQLite 数据库；不可用时，回退到云端存储的 Cookie。

#POST /profile/:id/cookies/import

json
{
  "clear": true,
  "cookies": [
    {
      "domain": ".example.com",
      "name": "session",
      "value": "value"
    }
  ]
}
  • clear=true 替换 Cookie，且为默认行为；
  • clear=false 将 Cookie 与现有云端副本合并；
  • 配置文件必须在所有设备上停止；
  • 每个接受的 Cookie 至少必须包含 domain 和 name。

#设备

#GET /device

返回分页列表：

json
{
  "device_id": "device-id",
  "device_name": "Workstation",
  "platform": "windows",
  "is_current_device": true,
  "online": true,
  "last_seen": "2026-07-24T10:00:00Z",
  "running_profiles": 1,
  "running_profile_ids": ["507f1f77bcf86cd799439011"]
}

#目录

#GET /catalog

返回允许的指纹值和 GPU → CPU/RAM/屏幕依赖关系。使用 os=windows|macos|linux 将结果限制为一个操作系统。

目录依赖云端；云端不可用时返回 1701。

#错误码

代码含义
0成功
1001JSON 无效或请求体过大
1002未知端点或 HTTP 方法
1003API 密钥缺失或无效
1101缺少必填参数
1103参数值或格式无效
1201未找到配置文件
1202配置文件已归档
1203配置文件正在此设备上运行
1204配置文件正在其他设备上运行
1301浏览器内核启动失败
1304浏览器内核缺失或正在下载
1401代理配置无效
1402代理检查失败
1501未找到文件夹
1503无法删除系统文件夹
1601Cookie 格式无效
1602无法向正在运行的配置文件导入 Cookie
1701云端不可用
1901内部错误

#最小 JavaScript 示例

js
const baseUrl = "http://127.0.0.1:50325/api/v1";
const token = process.env.AURORIUM_API_KEY;

async function aurorium(path, options = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  const result = await response.json();
  if (result.code !== 0) {
    throw new Error(`[${result.code}] ${result.msg}; ${result.request_id}`);
  }
  return result.data;
}

const profiles = await aurorium("/profile?page_size=10");
console.log(profiles.list);

#兼容性

  • API 版本包含在 URL 中：/api/v1。
  • 数值错误码在同一 API 主版本内保持稳定。
  • 客户端应忽略未知字段，因为响应可能在不破坏兼容性的情况下增加可选字段。
  • 不兼容变更需要新的主版本 URL（例如 /api/v2），或明确约定的迁移期。