Rumable 升级、回滚与排错¶

本页用于已经接入的站点。操作前保留原配置、站点 ID、CLI 路径、状态目录和 Web 服务器配置备份。初次接入见安装说明，SDK 选择见配置说明。

准备原部署信息¶

以下命令都使用原部署的 CLI、状态目录和站点 ID。重新打开终端时先设置变量；如果使用了自定义状态目录，将默认值改为原值。每一步成功后再继续，发生错误时先按终端提示处理。

Linux（具备 sudo 权限）：

rumable="/请替换为原部署实际安装目录/rumable"
state="/var/lib/rumable"
site_id="替换为原站点ID"

Windows（管理员终端）：

$rumable = Read-Host '输入原部署使用的 rumable.exe 完整路径'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host '输入原站点 ID'

修改已接入站点¶

先备份原 TOML、完整状态目录和服务器配置，再按保存的 TOML 格式选择流程：

自动发现配置¶

以留存的 TOML 为准，回到配置页填写完整参数，仅调整需要修改的选项，保留原来的采样、回放和 SDK 设置。读取并核对所选安装包后，保存新 TOML，在原服务器执行生成的命令，选择原网站和绑定。重新运行一键命令也会安装所选包，应同时核对其 SDK 版本。

如果原部署使用自定义状态目录，或只想用当前 CLI 应用修改后的发现配置，执行以下命令，配置路径替换为保存的实际文件。

Linux：

sudo "$rumable" setup --discover --config /etc/rumable/discovery.toml --state-dir "$state"

Windows：

& $rumable setup --discover --config 'C:\ProgramData\RumableConfig\discovery.toml' --state-dir $state
if ($LASTEXITCODE -ne 0) { throw '配置应用失败，请先检查原因' }

同目标发现会复用原 ID、URL 和路径范围。核对输出的站点 ID 与原记录一致，不要用新的手动 ID 接管已有部署。发现配置不能直接交给 enable。

完整站点配置¶

编辑原 TOML，保留原站点 ID 和部署目标，再执行 enable。不重复 init/render，不删除状态目录。以下配置路径替换为原文件。

Linux：

config="/etc/rumable/website.toml"
sudo "$rumable" enable --config "$config" --state-dir "$state" --site "$site_id"

Windows：

$config = 'C:\ProgramData\RumableConfig\website.toml'
& $rumable enable --config $config --state-dir $state --site $siteId
if ($LASTEXITCODE -ne 0) { throw '配置应用失败，请先检查原因' }

两种方式完成后，都按检查接入结果执行 status/probe，并检查新页面与实际数据。SDK 来源、加载方式和 RUM 参数都按这套流程更新。

调整自动站点的路径范围或 probePaths 时，按原 ID、URL 和服务器目标整理完整配置，核对身份后再执行 enable。更改 publicURL、Nginx 程序/启动参数或 IIS 站点/应用属于迁移部署目标，不能用普通配置更新完成。

SDK 如何更新¶

同域 SDK 固定在安装包中，不会后台自动更新。发布维护者同步并校验 SDK 后发布新包；网站管理员需要主动升级并应用。仅替换 CLI、读取 latest、修改业务 version 或启用 remoteConfiguration 都不会更新已部署的同域 SDK。

升级步骤：

1. 备份原 TOML、完整状态目录和服务器配置，保留旧 CLI。
2. 从发布清单选择新包，校验摘要后安装到新目录；核对 rumable version 和包内版本信息。
3. 将 rumable / $rumable 指向新 CLI，保留原站点 ID 与状态目录；按配置类型执行 enable 或 setup --discover。
4. IIS 首次接管旧部署时会记录池归属并回收一次；后续配置完全相同的重复操作不额外回收。先在原浏览器页面保留缓存普通刷新，确认取得当前初始化脚本，再运行 status/probe。
5. 若 CDN、代理或 Service Worker 仍返回旧 HTML，保存响应证据后按对应缓存策略处理。随后检查新页面、新会话、SDK 下载、原业务、真实 RUM 入库和回放。

官方可变 CDN 先更新时，旧 CLI 的 check/enable/probe 可能因摘要不一致而失败。此时使用包含匹配 SDK 的新包，或改用与当前包一致的固定 CDN 文件；不要关闭摘要检查来绕过不匹配。已打开页面不会热替换 SDK，外置 Worker 也需保持版本一致。

IIS 应用池与配置生效¶

目标应用必须使用已启动的独占应用池，子应用也要有自己的池。启用、更新、停用、历史回滚和故障恢复会先写入配置、保存恢复状态，再回收目标池并等待旧工作进程退出，最后检查 HTTP。完全相同的重复安装或停用不会额外回收。

回收可能丢失进程内会话，请安排合适的维护窗口。工具不会自动分配应用池，不回收共享池，不重启整台 IIS。接入后不要直接更换受管池名或向其中加入其他应用；需调整时先按原部署信息停用并规划迁移，避免触发归属漂移保护。

IIS 接入会关闭所选应用的静态和动态压缩，停用时恢复原局部设置或继承关系。文件级压缩覆盖、后端压缩或外部 HTML 缓存仍可能影响页面。启用时到达目标 IIS 的受管 HTML 导航请求会清除旧的条件校验头，避免复用旧正文；排除路径和公共 SDK 资源不使用这项处理。

若旧 worker 迟迟未退出，操作可能失败并尝试恢复；恢复不完整时保留事务。先检查长请求和目标池状态，保留完整输出与状态备份，条件恢复后用原站点 ID 和状态目录执行 rollback。不要删除事务、手动编辑状态或强杀业务进程来绕过检查。

操作探测失败记录在站点私有状态目录的 last-operation-probe-failure.json，恢复探测失败另存 last-recovery-probe-failure.json。重试前保存这些文件，并按时间核对本次操作；自动恢复成功后旧失败记录仍会保留，文件存在不等于当前仍失败。向支持人员提供脱敏副本，不公开完整状态备份或令牌。

停用、回滚与卸载¶

停用采集¶

先设置本页开头的变量。只想停止采集时，执行停用和检查即可。

Linux：

sudo "$rumable" disable --state-dir "$state" --site "$site_id"
sudo "$rumable" probe --state-dir "$state" --site "$site_id"

Windows：

& $rumable disable --state-dir $state --site $siteId
if ($LASTEXITCODE -ne 0) { throw '停用失败，请先检查原因' }
& $rumable probe --state-dir $state --site $siteId

停用只停止新 HTML 注入，保留资源供旧页面使用。已有页面和旧 HTML 缓存仍可能继续运行 SDK。Nginx 自动挂接时的压缩、缓存或请求头调整也可能继续保留。

IIS 停用会恢复原压缩设置及继承关系，并回收目标池。普通刷新后，新加载的 HTML 应不含本部署注入。业务缓存策略恢复后可能返回 304，应核对实际复用的正文是否仍有注入；旧哈希脚本和公共资源映射保留给旧页面使用。

恢复前一次部署¶

回滚是另一项操作，可能重新启用采集。 只有需要恢复前一个成功部署时才执行，不要在正常停用后接着运行。

Linux：

sudo "$rumable" rollback --state-dir "$state" --site "$site_id"

Windows：

& $rumable rollback --state-dir $state --site $siteId

存在中断事务时，rollback 优先尝试恢复事务；否则在当前和前一次成功快照之间切换。它不是无限历史回退，也不自动恢复磁盘上的 TOML。回滚后再次 enable 会重新应用当前 TOML，应同时核对期望配置，再检查状态、页面和数据。

完整卸载¶

先停用、清理旧 HTML 缓存，再预览卸载范围。

Linux：

sudo "$rumable" uninstall --state-dir "$state" --site "$site_id" --dry-run

Windows：

& $rumable uninstall --state-dir $state --site $siteId --dry-run

检查预览结果，确认目标及变更范围后，再执行卸载。

Linux：

sudo "$rumable" uninstall --state-dir "$state" --site "$site_id"

Windows：

& $rumable uninstall --state-dir $state --site $siteId

uninstall 恢复受管设置、移除资源映射并归档状态，之后不能用普通 rollback 直接恢复该站点。它不自动删除 CLI 或用户自己安装的 Web 服务器。

仅撤销 Linux Nginx 首次自动挂接时，先 disable，再使用 rollback --attachment --dry-run 预览，确认后执行 rollback --attachment。外部修改或后来挂接到同一文件的其他站点可能阻止恢复，应审查差异；不要删除备份或状态文件强行继续。

手动加入的 Nginx include 没有自动挂接备份，不能承诺由 rollback --attachment 撤销。按安装包指南移除本次手动 include、恢复相关指令，配置检查和重载成功后再归档受管状态。不要直接删除仍被服务器引用的目录。

常见问题¶

Rumable 的默认自动接入处理浏览器 RUM；服务端 OTel 是独立能力。不要为了接入 Web SDK 顺带安装或修改服务端 Trace 组件。