Linux Server 部署与自动化指南

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

完成本指南后你将获得

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

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

一个可用的 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

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

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

在 Local API 区域中即可看到：

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

APP ID：应用标识

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

HubStudio 开发者中心 — 从 Local API 区域复制 APP ID 和 APP Secret

3.2 获取团队 ID

点击 HubStudio 右上角头像

进入 「用户中心」

在 「团队信息」 区域即可看到 团队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 端口是动态分配的（启动环境时才确定），工作流程为：

先建立 API 端口隧道：

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

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

连接 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 尚未完成启动，或进程已崩溃。

解决方案：

启动后等待 5–10 秒

检查日志：tail -f hubstudio.log

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

socat 端口转发失败

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

解决方案：

Playwright CDP 连接超时

解决方案：

确认 socat 转发正常运行

检查 SSH 配置：ssh user@host

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

确保已安装 Playwright：

目标	链接
HubStudio API 接口文档	API Reference
HubStudio 客户端下载	下载页面

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 连接超时#

相关资源#

完成本指南后你将获得

架构总览

前置条件

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 连接超时

相关资源