复制页面 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: → 127.0.0.1: │ └──────────────────────────────────────────────────────────┘ │ 外部机器 (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 . 登录 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: —— 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 命令行操作指南