0 Fork 0

Files

T

admin9webs 322b7737eb archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）

来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。
只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。

2026-10-05 12:11:35 +00:00

15 KiB

Raw Blame History

复制页面

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 接口返回各自的端口号。上图中为占位符。

前置条件

| 条件 | 说明

| 操作系统 | 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 .

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: —— 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：

15 KiB Raw Blame History Unescape Escape

Linux Server 部署与自动化指南

完成本指南后你将获得

架构总览

前置条件

Step 1 — 安装系统依赖

安装字体（可选）

Step 2 — 启动 HubStudio

2.1 赋予可执行权限

2.2 后台启动

2.3 验证启动

Step 3 — 获取 HubStudio API 凭据

3.1 获取 APP ID 和 APP Secret

3.2 获取团队 ID

3.3 验证 API 可用

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

4.1 转发 Local API 端口

4.2 转发 CDP 调试端口

4.3 开放防火墙端口

4.4 推荐：使用 SSH 隧道

Step 5 — 运行自动化脚本

5.1 安装 Python 依赖

5.2 修改配置参数

5.3 自动化流程说明

5.4 运行测试

性能基准

生产环境部署（systemd）

创建服务文件

启用并启动

管理服务

项目结构

故障排查

HubStudio 启动失败

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

外部机器 CDP 连接被拒绝

API 返回"连接被拒绝"

socat 端口转发失败

Playwright CDP 连接超时

相关资源

15 KiB

Raw Blame History