使用 Rumable 一键接入 Web RUM¶

Rumable 通过 Nginx 或 IIS 在网站返回的 HTML 中加入 Web RUM 脚本，适合能够管理 Web 服务器、希望避免修改前端源码的网站。SDK 在访问者浏览器中运行，将数据直接上报到 观测云 的 OpenWay 或你配置的 DataKit。CLI 完成接入后退出，不是常驻采集服务。

首次接入推荐一键接入，无需手写配置；离线或希望逐步审查的环境使用分步安装。SDK 来源、加载方式和完整 TOML 示例见配置说明，已接入站点的更新与恢复见运维说明。安装和日常使用不需要 Git、Go、Node.js 或数据库。

一键接入（推荐）¶

打开配置页 → 填写应用参数 → 复制安装命令 → 在 Web 服务器执行 → 选择网站 → 验收数据。 不需要自己编写 TOML，也不需要预先安装 CLI；命令会下载、校验并安装对应平台的 CLI，然后接入网站。服务器需能访问下载地址，并满足下方服务器条件。

第一步：在页面填写参数¶

先在「用户访问监测 > 应用列表」创建 Web 应用，取得应用 ID 和上报参数，并检查服务器条件。

打开 一键接入配置页，填写应用参数，选择平台。先采用默认同域异步完成验证；首次验证建议会话采样 100%、回放关闭。

以“Linux / Nginx + 网站同域 + 异步”为例，在页面中填写：

同一流程支持同域/CDN 与同步/异步的四种组合，无需手写 TOML。选择 CDN 时填写 SDK 的 HTTPS 脚本地址；需要先初始化 SDK 再执行后续业务脚本时，选择“同步”。具体区别见SDK 来源与加载方式。

第二步：读取发布版本并复制命令¶

1. 点击“读取发布版本”，确认页面显示 Rumable 和 Web SDK 版本。
2. 下载 TOML 留存，用于后续修改和恢复；不需要手动编辑它。
3. 切换到“安装命令”，复制页面生成的完整命令。只复制命令不会改服务器，执行后才开始接入。

命令包含你填写的配置，不能使用别人的命令。下面仅展示自动发现接入的一键命令结构。安装器地址、发布目录和编码配置都由页面填写；不要直接运行占位示例。实际执行时复制页面生成的完整命令，不需要手改版本号。

第三步：在服务器执行一键命令¶

Linux / Nginx：登录运行 Nginx 的服务器，使用具备 sudo 权限的终端，粘贴页面生成的 Bash 命令。命令形式如下：

bash -o pipefail -c 'curl --proto "=https" --proto-redir "=https" -fsSL "INSTALLER_URL_FROM_PAGE" | sudo sh -s -- --base-url "ARTIFACT_BASE_FROM_PAGE" --config "CONFIG_FROM_PAGE" --discover'

Windows / IIS：以管理员身份打开 Windows PowerShell 5.1+，粘贴页面生成的 PowerShell 命令，不在 cmd.exe 中运行。命令形式如下：

执行前确认目标应用使用已启动的独占应用池，子应用也需单独分配池。接入会回收目标池并等待旧工作进程退出，进程内会话可能丢失，请在可接受回收影响的维护窗口操作。

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'INSTALLER_URL_FROM_PAGE').Content)) -BaseUrl 'ARTIFACT_BASE_FROM_PAGE' -Config 'CONFIG_FROM_PAGE' -Discover

安装器自动选择系统和 CPU 对应的安装包，校验压缩包摘要、安装 CLI、读取配置并发现网站。只有一个候选时自动选择；多个站点或绑定时按终端提示选择目标，必要时补充访问 URL 或确认压缩调整。一键安装器已包含接入确认，执行命令即同意应用变更；选定目标并完成必要提示后，工具直接执行注入和 HTTP 验证。

一键接入仍需在有歧义时选择网站；它不会默认修改第一个站点，也不会自动安装 Nginx、IIS 或 URL Rewrite。需要自定义目标时，可以在页面勾选“手动指定站点与路径”后继续生成一键命令；复杂配置或离线服务器再使用分步安装。

第四步：保存结果并验收¶

终端显示 RUM setup complete 后，记录输出的站点 ID 和 URL；高级手动模式以配置中的 id 和 publicURL 为准。保存所选版本、下载的 TOML，以及按下表确定的 CLI 路径和状态目录；完整备份状态目录，Nginx 输出 Backup: 时另行记录其路径。随后按检查接入结果确认浏览器采集和真实数据入库，验收通过即完成首次接入，无需再执行分步安装。

页面在本地浏览器生成配置，不把应用配置提交到下载站点。命令中的 Base64 只是编码，不是加密；不要公开包含 Client Token 的完整命令。一键安装器会清理临时 TOML，因此应保留页面下载的配置。

默认安装位置：

表中的版本取配置页显示的本次所选版本；一键安装不会把 CLI 自动加入 PATH。状态目录保存部署、恢复和归属信息，应保留并备份。后续操作继续使用原站点 ID 和状态目录，按原配置类型选择更新方式。

固定入口与安装包选择¶

• 在线配置页：填写配置并生成安装命令。
• 发布清单：读取推荐安装包、内置 SDK、下载文件和校验信息。

配置页读取一次清单后，会将命令指向该次发布的安装器和安装包，并使用配套摘要校验。文档入口始终使用 latest；具体版本、包名和校验信息由发布流程更新，不需要用户在文档里替换版本号。

读取 latest 只决定本次选用哪个安装包，不会自动升级已接入的网站。已接入站点继续使用安装时记录的 CLI 路径和状态目录；升级时按升级步骤主动选择和应用新包。

接入前准备与服务器条件¶

1. 在「用户访问监测 > 应用列表」新建 Web 应用，取得 applicationId。
2. 选择一种上报方式：OpenWay 使用 site 和浏览器 clientToken；DataKit 直连使用 datakitOrigin。详细说明见 Web 应用接入。不要使用管理 API Key。
3. 确认网站没有重复接入同一个 SDK；打包在业务代码中的接入也需要人工检查。
4. 准备一个直接返回 HTTP 200 HTML 的验收地址。页面需要标准的 <head> 起始标签，不使用跳转页、登录页或下载地址代替。
5. 备份 Web 服务器配置，确认操作权限和维护窗口。启用会检查配置并重载 Nginx，或修改目标 IIS 应用的受管规则并回收其独占应用池。

浏览器须能访问上报地址；HTTPS 网站使用 HTTPS 上报端。CSP 需要允许同域初始化脚本、实际 SDK 地址、上报目标和所需 Worker。Rumable 不自动放宽 CSP，也不注入内联 JavaScript。

Linux / Nginx 条件¶

• Nginx 技术最低版本为 1.9.4，必须包含 http_sub_module；优先选择受维护的版本。
• 提供 Linux x86、x64、ARM64 包。一键安装选择现代包；旧系统使用匹配的 legacy 包。
• 使用 root 或 sudo；一键命令需要 Bash、curl、CA 证书及常用解压、校验工具。
• 进入替换阶段的 HTML 应未压缩。自动挂接会调整目标处理位置的源压缩、条件请求和缓存，需审查实际影响；输出 gzip 可以保留。
• Nginx 自动发现、自动挂接和挂接回滚目前仅支持 Linux。

Windows / IIS 条件¶

• IIS 7.5+、URL Rewrite 2.x、Static Content 和匿名静态文件访问已准备好；工具不自动安装这些组件。
• 一键安装要求管理员权限、Windows PowerShell 5.1+。CLI 的 IIS 管理桥接需要系统原生 64 位 PowerShell 3.0+。
• Windows 10 / Server 2016+ 使用现代包；旧 Windows 使用对应 legacy 包。真正的 32 位 Windows 不能管理 IIS。
• 目标应用池已启动，且仅服务该应用；父应用和子应用分别使用自己的池。在 IIS 管理器的「应用程序池 > 查看应用程序」中核对归属。共享池需先由运维调整，工具不自动分配或启动池，不回收共享池，也不执行整台 IIS 重启。
• 应用下的 /__rumable__/ 资源不能被业务路由、入站重写或应用处理器截获，JavaScript MIME 类型需有效。
• 允许关闭目标应用的 IIS 静态和动态压缩，停用时恢复原设置；这会影响该应用内其他响应的压缩。动态应用或反向代理的后端也须返回未压缩 HTML。

访问者的浏览器需满足 Web SDK 的兼容性要求。

离线或分步安装¶

在联网机器从发布清单选择与操作系统、CPU 和现代/legacy 类型匹配的压缩包，同时获取同版本 SHA256SUMS。校验文件名对应的 SHA-256 后再解压；离线服务器接收原始压缩包和校验清单后重复校验。完整压缩包包含 CLI、示例、使用指南和版本信息。

安装后先运行 rumable version。创建 UTF-8 TOML，参照完整站点配置填写实际值，再执行 setup。以下路径和站点 ID 仅为示例；不要覆盖已有的配置文件：

rumable="/请替换为实际安装目录/rumable"
sudo "$rumable" setup \
  --config /etc/rumable/website.toml \
  --state-dir /var/lib/rumable --site website

Windows 使用管理员终端，将路径替换为实际安装位置：

$rumable = Read-Host '输入实际安装的 rumable.exe 完整路径'
& $rumable setup `
  --config 'C:\Rumable\website.toml' `
  --state-dir "$env:ProgramData\Rumable" --site website
if ($LASTEXITCODE -ne 0) { throw 'Rumable 接入失败，请按终端输出检查' }

setup 负责准备和应用接入。Nginx 会展示拟修改的挂接，确认后写入、检查并重载；复杂或不受支持的处理配置应使用安装包指南中的手动挂接流程。只需预览 Nginx 挂接时，按指南先 render，再运行 attach --dry-run。

检查接入结果¶

IIS 接入后，先在原浏览器页面保留缓存执行一次普通刷新，不使用硬刷新或 Disable cache。检查首页及其他主要 HTML 页面：应返回 200、包含一条当前初始化脚本、业务内容正常。自动发现默认通常只检查首页，需要覆盖其他模板时配置相应 probePaths。异常时先保存请求、响应和失败输出，再按运维说明排查。

使用实际 CLI 路径、状态目录和终端记录的站点 ID 执行。以下路径和 ID 必须替换为原部署值。

Linux（具备 sudo 权限）：

rumable="/请替换为实际安装目录/rumable"
state="/var/lib/rumable"
site_id="替换为原站点ID"
sudo "$rumable" status --state-dir "$state" --site "$site_id"
sudo "$rumable" probe --state-dir "$state" --site "$site_id"

Windows（管理员终端）：

$rumable = Read-Host '输入实际安装的 rumable.exe 完整路径'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host '输入原站点 ID'
& $rumable status --state-dir $state --site $siteId
& $rumable probe --state-dir $state --site $siteId

验收需逐层确认：

probe 验证 HTTP 注入和资源可达，不执行浏览器 SDK；模拟接收端返回成功也不能代替真实入库检查。完整验收后再调整采样和回放。