browser-docs-archive/md/hs-api/api-docs.hubstudio.cn/8945881m0.md

<!-- source: https://api-docs.hubstudio.cn/8945881m0 | fetched: 2026-10-05 10:33:51 | http: 200 -->

复制页面

Hubstudio

- API 使用说明文档

- Linux Server 部署与自动化指南

- Hubstudio CLI 命令行操作指南

-

Hubstudio local API

-

环境管理

- 获取环境列表

- 创建环境

- 更新环境

- 更新环境代理

- 导入Cookie

- 导出Cookie

- 删除环境

- 获取随机UA

- 清除环境本地缓存

- 清理环境内插件缓存

- 刷新指纹

- 查询webglVendor和webglRenderer

- 批量修改备注

- 下载内核

- 更新环境基础信息

- 更新环境标签

-

浏览器环境

- 打开环境

- 关闭环境

- 关闭所有环境

- 获取浏览器状态

- 切换浏览器窗口

- 获取所有打开环境

- 获取全部屏幕（物理机的屏幕）

- 浏览器窗口自定义排列

-

云手机

- 应用管理
- APP列表(分页)\查询可安装应用列表

- 已安装应用列表查询

- 新增团队应用

- app应用安装

- APP启动

- APP重启

- APP停止

- APP卸载

- 添加自定义到团队应用

- 设置隐藏无障碍服务

- 文件管理
- 选择本地上传文件到云手机

- 公网文件上传文件到云手机

- 设置keyBox

- RPA
- RPA模板参数填写规范

- RPA-计划分页查询

- RPA-个人模板分页查询

- RPA-市场模板分页查询

- RPA-保存计划

- RPA-取消计划

- RPA-执行记录分页查询

- RPA-取消记录

- RPA-记录详情查询

- RPA-快速保存一次性计划

- 云手机商品列表

- 云手机分页列表

- 添加云手机

- 国家时区语言列表

- 批量开启云手机

- 批量关闭云手机

- 更新代理

- 批量获取云手机ADB状态

- 批量更新云手机ADB状态

- 一键新机

- 获取一键新机状态及可用数量

- 查询品牌机型

- 执行shell命令

- 修改云手机信息

- 发送短信到云手机

- 批量删除云手机

- 批量修改云手机分组

- 截图

- Base64截图

- 查询团队预装应用列表

- 触控-单击

- 触控-双击

- 触控-拖拽

- 触控-长按

- 触控-滑动

-

平台账号管理

- 账号分页列表

- 账号删除

- 添加环境账号

- 账号更新

-

分组管理

- 删除环境分组

- 新建环境分组

- 获取环境分组列表

-

TK 运营自动化

- 创建批量发视频任务

- 创建TikTok智能养号任务

- 创建批量改资料任务

- 分页查询自动化任务

- 分页查询自动化任务执行明细

- 查询自动化任务结果

- 取消自动化任务

-

团队工具

- 创建或覆盖团队 Webhook

- 获取云手机远程连接

- 查询团队账户余额

- 查询团队环境打开次数

-

用户登录态

- 退出登录

- 账号登录

- Hubstudio open API

-

认证

- 获取调用凭证

- 查询当前凭证信息

-

环境管理

- 获取环境列表

- 创建环境

- 更新环境

- 更新环境代理

- 删除环境

- 导入Cookie

- 导出Cookie

- 获取随机UA

- 刷新指纹

- 批量修改备注

- 查询webglVendor和webglRenderer

-

平台账号

- 账号分页列表

- 账号更新

- 添加环境账号

- 账号删除

-

环境分组

- 获取环境分组列表

- 新建环境分组

- 删除环境分组

-

云手机

- 云手机商品列表

- 云手机分页列表

- 添加云手机

- 批量删除云手机

- 国家时区语言列表

- 批量开启云手机

- 批量关闭云手机

- 更新代理

- 批量获取云手机ADB状态

- 批量更新云手机ADB状态

- 查询品牌机型

- 一键新机

- 获取一键新机状态及可用数量

- 公网文件上传文件到云手机

- APP列表(分页)\查询可安装应用列表

- 新增团队应用

- 已安装应用列表查询

- app应用安装

- APP启动

- APP重启

- APP停止

- APP卸载

- 执行shell命令

- 设置keyBox

- 修改云手机信息

- 批量修改云手机分组

- 发送短信到云手机

- 获取云手机远程连接

- 截图

- Base64截图

- 触控-单击

- 触控-双击

- 触控-长按

- 触控-滑动

- 触控-拖拽

- 查询团队预装应用列表

- 设置隐藏无障碍服务

-

TK自动化

- 创建批量发视频任务

- 创建TikTok智能养号任务

- 创建批量改资料任务

- 分页查询自动化任务

- 查询自动化任务结果

- 分页查询自动化任务执行明细

- 取消自动化任务

# Linux Server 部署与自动化指南

复制页面

在 Ubuntu 无头服务器上部署 HubStudio 指纹浏览器，通过 Local API 实现浏览器环境的自动化管理 —— 无需桌面环境。

## 完成本指南后你将获得 #

1 .

一个在 Ubuntu 24.04 Server 上运行的 HubStudio 无头实例

2 .

通过 socat 配置网络转发，使外部机器可以通过 CDP（Chrome DevTools Protocol）连接浏览器

3 .

一个可用的 Python 压力测试脚本，能够批量创建、启动、控制和清理浏览器环境

## 架构总览 #

```
┌──────────────────────────────────────────────────────────┐
│ Ubuntu 24.04 Server │
│ │
│ ┌──────────────┐ ┌───────────────────────────────┐ │
│ │ xvfb │───▶│ HubStudio AppImage │ │
│ │ (虚拟显示) │ │ Local API :6873 │ │
│ │ │ │ CDP debug :<动态端口> │ │
│ │ │ │ (127.0.0.1, 每个环境不同) │ │
│ └──────────────┘ └───────────────────────────────┘ │
│ │ │
│ socat 端口转发 │
│ │ │
│ 0.0.0.0:6874 → 127.0.0.1:6873 │
│ 0.0.0.0:<N+1> → 127.0.0.1:<N> │
└──────────────────────────────────────────────────────────┘
│
外部机器
(Playwright / Puppeteer / Selenium)
```

📝 说明： CDP 调试端口是 动态分配 的 —— 每个浏览器环境启动后由 /api/v1/browser/start 接口返回各自的端口号。上图中 <N> 为占位符。

## 前置条件 #

| 条件 | 说明

| 操作系统 | Ubuntu 24.04 Server (x86_64)

| 推荐配置 | 8 vCPU、8 GB RAM（支持约 5 个并发环境）

| 网络 | 需要出站互联网访问；入站开放 6874 端口及所选择的 CDP 转发端口，或使用 SSH 隧道

| HubStudio | 已下载客户端（ 下载地址 ）

| Python （可选） | Python 3.8+ 及 pip ，用于运行自动化脚本

## Step 1 — 安装系统依赖 #

通过 SSH 连接到服务器，安装 HubStudio 运行所需的软件包：

```

```

### 安装字体（可选） #

如果浏览器页面出现文字缺失或乱码，安装对应的字体包：

```

```

其他语言可安装对应的 Noto 字体家族 。

## Step 2 — 启动 HubStudio #

### 2.1 赋予可执行权限 #

```

```

### 2.2 后台启动 #

使用 xvfb-run 提供虚拟显示，后台运行 HubStudio：

```

```

启动参数说明：

| 参数 | 说明

| --no-sandbox | 禁用沙盒模式（root 用户或容器环境下必需）

| --headless=true | 无头模式运行，不显示 GUI

| --disable-gpu | 禁用 GPU 加速

| --ozone-platform=x11 | 指定使用 X11 显示平台

| --app-id | HubStudio 开发者中心的 APP ID

| --app-secret | HubStudio 开发者中心的 APP Secret

| --login-group-code | 团队 ID（从用户中心获取）

⚠️ 注意： 请将 ${APP_ID} 、 ${APP_SECRET} 、 ${团队ID} 替换为实际值。获取方式见 Step 3 。

### 2.3 验证启动 #

```

```

进程完全初始化可能需要 5–10 秒。

## Step 3 — 获取 HubStudio API 凭据 #

### 3.1 获取 APP ID 和 APP Secret #

1 .

登录 HubStudio 客户端

2 .

进入顶部导航栏 「开发者中心」

3 .

在左侧菜单选择 「浏览器&云手机API」

4 .

在 Local API 区域中即可看到：

接口地址 ：默认为 http://127.0.0.1:6873

APP ID ：应用标识

APP Secret ：应用密钥（点击复制图标获取）

### 3.2 获取团队 ID #

1 .

点击 HubStudio 右上角头像

2 .

进入 「用户中心」

3 .

在 「团队信息」 区域即可看到 团队ID

### 3.3 验证 API 可用 #

```

```

code 为 0 的响应表示 API 已就绪。

✅ 检查点： HubStudio 服务已完全启动。继续 Step 4 设置远程访问，或者如果脚本运行在同一台服务器上，可直接跳转到 Step 5 。

## Step 4 — 配置网络转发（socat） #

默认情况下，Local API（ :6873 ）和 CDP 调试端口都绑定在 127.0.0.1 。如果需要从外部机器访问（例如你的开发电脑），需要使用 socat 转发流量。

⚠️ 安全风险 — 不要将这些端口暴露到公网。

Local API 的大部分端点 没有内置鉴权

CDP 调试端口拥有浏览器的 完全远程控制权 （读取 Cookie、注入脚本、截屏）

建议：

优先使用 SSH 隧道 代替 socat（参见 4.4 节 ）

如果必须使用 socat，通过防火墙规则 限制到指定 IP

使用 VPN 或云服务商安全组限制入站流量

绝不要 在公网服务器上将端口开放到 0.0.0.0 而不做 IP 限制

### 4.1 转发 Local API 端口 #

```

```

外部机器现在可以通过 http://<服务器IP>:6874 访问 API。

### 4.2 转发 CDP 调试端口 #

通过 API 启动浏览器环境后，响应中会包含一个 动态 debuggingPort （如 36363 ）。每个环境的端口可能不同。转发它以便外部自动化工具（Playwright、Puppeteer、Selenium）连接：

```

```

⚠️ 注意： 同时运行多个环境时，确保转发端口不会与其他环境的调试端口冲突。建议使用较大偏移量或专用端口范围。

💡 提示： 在生产环境中，建议在每次 /api/v1/browser/start 调用后 动态创建 socat 转发，使用返回的 debuggingPort 。本项目的 Python 脚本 中已包含该实现。

如果自动化脚本运行在 同一台服务器 上，可以跳过 socat，直接连接 127.0.0.1 。

### 4.3 开放防火墙端口 #

如果使用 socat，建议限制到受信任的 IP：

```

```

### 4.4 推荐：使用 SSH 隧道 #

最安全的远程访问方式是使用 SSH 隧道 —— 无需修改防火墙或配置 socat。

由于 CDP 端口是 动态分配 的（启动环境时才确定），工作流程为：

1 .

先建立 API 端口隧道：

```

```

2 .

通过隧道启动环境 （ http://127.0.0.1:6873/api/v1/browser/start ），获取返回的 debuggingPort 。

3 .

为 CDP 端口建立第二个隧道：

```

```

4 .

连接 http://127.0.0.1:<debuggingPort> —— SSH 让远程端口看起来像本地端口。

💡 提示： 如果预先知道端口范围，可以在一条命令中合并多个隧道：

```

```

## Step 5 — 运行自动化脚本 #

### 5.1 安装 Python 依赖 #

```

```

Playwright 仅用于其 CDP 客户端（ connect_over_cdp ）。 不需要 运行 playwright install —— HubStudio 自带浏览器。如果你在脚本中使用了 Playwright 启动独立浏览器，则需要安装： playwright install chromium 。

### 5.2 修改配置参数 #

编辑 stress_test_cdp_hubstudio.py 文件顶部的配置项：

```

```

### 5.3 自动化流程说明 #

每个测试任务执行以下完整生命周期：

```
① 创建环境 → ② 启动浏览器 → ③ 建立 socat 转发 → ④ CDP 连接
→ ⑤ 页面操作 & 截图 → ⑥ 关闭浏览器 → ⑦ 清理缓存 → ⑧ 删除环境
```

详细步骤：

| 步骤 | API 端点 | 说明

| ① 创建环境 | POST /api/v1/env/create | 创建指纹浏览器环境

| ② 启动浏览器 | POST /api/v1/browser/start | 启动浏览器，获取 CDP 调试端口

| ③ socat 转发 | SSH + socat | 在远程服务器上动态创建端口转发

| ④ CDP 连接 | Playwright CDP | 通过 CDP 协议连接浏览器（最多 5 次重试）

| ⑤ 页面操作 | — | 打开 Google 页面并截图

| ⑥ 关闭浏览器 | POST /api/v1/browser/stop | 停止浏览器实例

| ⑦ 清理缓存 | POST /api/v1/cache/clear | 清理本地缓存数据

| ⑧ 删除环境 | POST /api/v1/env/del | 删除浏览器环境

📝 说明： 并发由 asyncio.Semaphore 控制，所有任务异步执行但并发数不超过 CONCURRENCY 设定值。

### 5.4 运行测试 #

```

```

## 性能基准 #

以下结果在 Ubuntu 24.04 Server（8 vCPU、8 GB RAM）上测得：

| 指标 | 数值

| 总任务数 | 100

| 并发数 | 4（同时运行）

| 成功率 | 98.0%

| 总耗时 | 325.40 s

| 平均每任务耗时 | 3.25 s

| 吞吐量 | 0.31 tasks/s

以上数据仅供参考。实际性能取决于服务器配置、网络状况和页面复杂度。

如有失败任务，测试结束时会附带错误详情。截图保存在 screenshots/ 目录下（成功任务的截图会自动清理）。

## 生产环境部署（systemd） #

在生产服务器上，建议将 HubStudio 配置为 systemd 服务 ，实现开机自启、崩溃重启和集中日志管理。

### 创建服务文件 #

```

```

请调整 WorkingDirectory 、 ExecStart 路径及启动参数为实际值。

💡 提示： 生产环境建议创建专用用户（如 hubstudio ）而非以 root 运行，并相应调整文件权限。

### 启用并启动 #

```

```

### 管理服务 #

```

```

## 项目结构 #

```
hubstudio-demo/
├── stress_test_cdp_hubstudio.py # 压力测试主脚本
├── screenshots/ # 截图输出目录（自动创建）
└── README.md # 项目说明文档
```

## 故障排查 #

### HubStudio 启动失败 #

```
AppImages require FUSE to run.
```

解决方案： 安装 FUSE 支持：

```

```

### 浏览器页面文字缺失 / 乱码 #

解决方案： 安装目标语言的字体包（参见 Step 1 — 安装字体 ）。

### 外部机器 CDP 连接被拒绝 #

原因： CDP 调试端口默认绑定 127.0.0.1 。

解决方案： 配置 socat 转发（参见 Step 4 ），并确保防火墙放行转发端口。

### API 返回"连接被拒绝" #

原因： HubStudio 尚未完成启动，或进程已崩溃。

解决方案：

1 .

启动后等待 5–10 秒

2 .

检查日志： tail -f hubstudio.log

3 .

确认进程运行： ps aux | grep Hubstudio

### socat 端口转发失败 #

原因： socat 未安装，或端口已被占用。

解决方案：

```

```

### Playwright CDP 连接超时 #

解决方案：

1 .

确认 socat 转发正常运行

2 .

检查 SSH 配置： ssh user@host

3 .

确认防火墙放行了 CDP 转发端口

4 .

确保已安装 Playwright：

```

```

## 相关资源 #

| 目标 | 链接

| HubStudio API 接口文档 | API Reference

| HubStudio 客户端下载 | 下载页面

修改于 2026-06-09 06:08:34

上一页

API 使用说明文档

下一页

Hubstudio CLI 命令行操作指南