机器与浏览器

目标

创建机器与浏览器实例，并维护浏览器运行包版本，为远程浏览器访问、站点登录和工作空间运行提供基础环境。

前置条件

• 已登录管理后台。
• 当前账号拥有“浏览器管理”相关权限。
• 已准备可用机器节点或浏览器运行环境。
• 管理服务配置了 app.keeperbase，用于保存浏览器 client 和 engine 运行包。

操作步骤

1. 进入“浏览器管理 > 机器列表”。

2. 点击“添加机器”，填写机器地址和端口号。

   • 机器地址 -- 填写keeper服务所在地址，keeper服务默认就是安装所在服务器上，填写服务器默认内网地址就行。
   • 端口号 -- 默认是 7000。
   • 内置版本 -- 添加或更新机器时，系统会调用 keeper 绑定接口自动获取并保存，不需要在页面手工填写。

3. 保存后确认机器记录存在，并且 keeper 服务可访问、可被调度。

4. 进入“浏览器管理 > 浏览器列表”。

5. 创建浏览器实例，选择机器、填写浏览器编号，并选择浏览器版本。

   • 机器 -- 创建的浏览器将会运行在所选择的机器上。
   • 浏览器编号 -- 请取一个自己易记的内容，需要唯一，内容英文或者字符构成且不要空格，例如: chrome100
   • 浏览器版本 -- 可选择版本管理中提供的浏览器版本，也可选择“内置版本”。选择“内置版本”时，系统会使用所选机器保存的内置版本。
   • 网络模式:
     • 普通网络: 使用常规浏览器网络，可配置 HTTP/SOCKS5 代理，适合一般使用场景。
     • 隔离网络: 为浏览器创建独立网络环境，完整接管浏览器网络流量，支持更完整的 DNS、UDP、WebRTC 等网络隔离，适合更高要求的场景。
   • 网络槽位: 仅隔离网络需要填写，请输入大于 0 的唯一数字。
   • DNS 配置: 仅隔离网络需要填写，选择 tcp 或 udp，填写 DNS IP 和端口，并通过“是否走代理”选择 direct 或 proxy。direct 表示 DNS 请求直连，proxy 表示 DNS 请求走代理。
   • 代理配置: 仅隔离网络需要填写，选择 socks5 或 http，并填写代理主机和端口，用户名和密码可选。

6. 浏览器创建后，可在浏览器列表中编辑网络模式和隔离网络配置。

7. 点击 "开始" 按扭 启动浏览器，直到状态变为 running。

浏览器配置

在浏览器列表中点击浏览器实例的配置操作，可以调整该浏览器的启动方式和环境标识。

• 基础配置:
  • 内核版本: 选择浏览器实例使用的 Chromium 运行版本。可点击字段旁的“编辑”维护可选 Chromium 版本。
  • 操作系统: 选择浏览器使用的操作系统画像。可点击“编辑”维护操作系统列表。
  • 品牌和品牌版本: 选择 Google Chrome、Microsoft Edge、Opera 或 Vivaldi 等浏览器品牌，再选择匹配的品牌版本。切换品牌会清空已选品牌版本。
  • 移动机型: 当浏览器需要模拟移动端环境时，选择移动设备机型。可点击“编辑”维护机型选项。
  • 时区: 搜索并选择浏览器时区，也可以重置为本地时区。
• 高级配置:
  • 启动参数: 以键值对方式添加、编辑或删除 Chromium 启动参数。常见默认项包括 disable-gpu、no-sandbox、ignore-certificate-errors、lang 和 autoplay-policy。更多 Chromium 启动参数可参考 List of Chromium Command Line Switches。
  • 临时目录和缓存目录: 设置浏览器写入临时文件和缓存数据的位置。
  • 图片最大尺寸: 设置浏览器抓取图片时使用的最大图片尺寸，单位为像素。
  • 硬件加速: 仅在运行环境支持稳定 GPU 加速时开启。
  • 清理用户数据: 需要干净会话时开启，用于清理浏览器用户数据。

修改浏览器配置后点击“保存”。如果配置需要在新的浏览器进程中生效，请重启该浏览器实例。

浏览器版本管理

在“浏览器管理 > 浏览器列表”中点击“版本管理”，进入浏览器版本管理页面。

版本管理页面会展示版本名称、engine 状态、client 状态和下载操作。状态含义如下：

状态	含义
未下载	许可证服务返回了该版本，但 app.keeperbase 本地目录中没有对应类型的运行包
有更新	本地存在该版本运行包，但许可证服务上的构建版本更高
已是最新	本地构建版本大于或等于许可证服务返回的构建版本，或本地版本未出现在许可证服务返回列表中

下载时，系统会在后台线程执行下载任务，并在页面显示下载进度。下载过程支持断点续传，临时文件会先保存到临时目录；下载完成后，再移动到 app.keeperbase/<版本名称>/ 目录。移动前会清理该版本目录下旧的同类型运行包，避免同一版本下保留多个 client 或 engine 包。

运行包文件名遵循以下格式：

client_<version>_<buildVersion>.tar.gz
engine_<version>_<buildVersion>.tar.gz

version 是浏览器版本名称，buildVersion 是构建版本。系统会根据文件名前缀识别类型：client 表示浏览器 client，engine 表示浏览器 engine。

Keeper 内部接口

管理服务会对外提供 keeper 版本查询和下载接口，供 engine 与 client 节点自动更新使用。调用这些接口需要携带内部接口使用的 JWT token。

接口	说明
GET /internal/navi/keepers	从 app.keeperbase 收集本地运行包，返回版本、类型、构建版本和文件名
GET /internal/navi/downKeeper?version=<version>&type=<type>	下载指定版本和类型的本地运行包，支持 HTTP Range 断点下载

engine 节点会定时请求 /internal/navi/keepers，检查 keeperBag.config.enginePath 下对应版本目录的 BUILD 文件。如果本地构建版本低于服务端返回的 engine 构建版本，或本地没有该版本，则调用 /internal/navi/downKeeper 下载 engine 包，并解压到 engine 目录。

client 节点也会定时请求 /internal/navi/keepers，检查 /var/sa/caddy/client 下对应版本目录的 BUILD 文件。如果本地构建版本低于服务端返回的 client 构建版本，或本地没有该版本，则调用 /internal/navi/downKeeper 下载 client 包，并解压到 client 目录。

结果验证

• 机器列表显示新机器。
• 机器列表显示机器的内置版本；该值来自 keeper 绑定接口。
• 浏览器列表显示新浏览器实例。
• 浏览器列表显示浏览器版本；选择内置版本时，会同时展示所关联机器的内置版本。
• 浏览器列表显示网络模式和网络槽位。隔离网络浏览器可点击“网络详情”查看 DNS、DNS 是否走代理和代理配置。
• 浏览器版本管理页面能显示本地与许可证服务对比后的 client/engine 状态。
• 用户访问站点或工作空间时，能够分配到可用浏览器环境。

常见问题

• 浏览器实例需要和机器节点匹配，机器节点或 keeper 服务不可用会影响远程访问。
• 浏览器版本、品牌版本和操作系统配置会影响站点识别与兼容性。创建浏览器时如果选择“内置版本”，请确认机器列表中的内置版本已经正确获取。
• 如果版本管理页面一直显示“未下载”，请检查 app.keeperbase 目录权限、许可证服务连通性和下载任务状态。
• 如果自动更新没有生效，请检查节点是否能访问管理服务的 /internal/navi/keepers 与 /internal/navi/downKeeper 接口，并确认 JWT token 配置正确。
• 窗口列表用于观察当前运行中的浏览器窗口和排查占用问题。