Show HN: RePlaya – 基于 S2 的自托管浏览器会话回放系统深度解读

背景

在现代 Web 应用开发中，会话回放（Session Replay）是排查用户端 Bug、优化用户体验的关键工具。然而，传统的会话回放方案通常架构复杂，依赖数据库、消息总线、对象存储和搜索引擎等多个独立组件来存储和检索事件数据。这种复杂性不仅增加了运维成本，还可能导致数据一致性问题和延迟。

RePlaya 是一个开源的自托管会话回放系统，它提出了一种极简的架构理念：将“存储”与“计算/检索”统一。该系统完全构建在 S2（一种高性能、流式数据存储协议）之上。其核心创新在于，每个用户会话被存储为单一的 S2 流（Stream），该流既是后端的全部，也是唯一的存储介质。这种设计消除了传统架构中分离的数据库、消息队列或搜索索引，使得系统能够以极低的延迟实现“实时尾随”（Live Tailing）功能——即在用户仍在页面上操作时，开发者即可实时观看其操作过程。

核心内容

RePlaya 的技术实现围绕 S2 流式存储展开，以下是其核心工作机制与配置细节：

1. 极简架构：流即后端

RePlaya 摒弃了传统多组件架构，每个会话对应一个 S2 流。

• 存储：rrweb 事件通过 S2 Producer API 追加到会话流的尾部。S2 处理背压（backpressure）并确认批次持久化。大型事件被分帧存储为多个 S2 记录，读取时自动重组。
• 无缓冲：数据从摄入到存储没有服务器端缓冲，流本身就是录制文件，无需额外的 Blob 存储。
• 时间线：会话流使用 timestamping.mode: client-require 模式，将 rrweb 捕获时间写入每条记录的 S2 时间戳，用于回放的时间轴 scrubbing。创建、停止和心跳记录则使用服务器墙钟时间。
• 列表排序：S2 按字典序列出流，因此会话流名采用倒序时间戳命名。通过 streams.list({ prefix: "sessions/" }) 配合 startAfter 分页，即可实现“最新优先”的列表，无需数据库维护排序。

2. 实时回放与 Live Tailing

• 实时观看：通过 GET /api/sessions/:id/live 端点，系统打开一个从快照尾部开始的 S2 读取会话，并通过 SSE（Server-Sent Events）将新记录桥接至浏览器。这使得回放播放器可以实时追加新事件，实现真正的“直播”式调试。
• 历史回放：同一根流既用于实时边缘数据，也用于历史数据的完整回放。

3. 并发控制与数据完整性

• ** fencing 机制**：流的创建和停止操作写入 active/stopped 围栏令牌（fencing tokens）。事件和心跳的追加仅在 active 状态下进行。这确保了即使有延迟写入，已结束的会话也不会被意外“复活”或篡改。
• 自动创建：流在首次追加时自动创建（createStreamOnAppend），继承 Basin 的默认配置，无需预先配置流资源。

4. 隐私与安全

• 输入掩码：默认情况下，记录器会屏蔽所有 input、select 和 textarea 的值（基于 rrweb maskAllInputs），防止密码、邮箱等敏感信息上传。
• 局部忽略：对于需要捕获原始表单状态的内网管理界面，可通过传递 maskAllInputs: false 或在脚本标签中添加 data-mask-all-inputs="false" 来禁用全局掩码。
• 区域屏蔽：敏感区域可包裹在 replaya-block 类中以完全省略，或使用 replaya-ignore 类跳过子树的变化。
• 生产环境隔离：
  • 公开面：仅暴露收集器路由（/recorder.js, /vendor/rrweb.min.js, POST /api/sessions, /events, /heartbeat, /stop）。
  • 私有面：仪表盘和读取 API 必须通过 SSO、VPN 或 Cloudflare Access 等访问控制层保护，严禁直接暴露在互联网。
  • 身份验证：会话创建返回短期追加令牌（Append Token），记录器使用该令牌发送事件、心跳和停止请求。

5. 部署与配置

• 环境依赖：需要 S2 Access Token 和 Basin。
• 配置文件：

  S2_ACCESS_TOKEN=replace-with-an-s2-access-token
  S2_BASIN=replaya-your-name
  S2_STREAM_PREFIX=sessions/
  PORT=8787
  

• 自定义端点：若使用 s2-lite 或其他兼容部署而非 S2 Cloud，需显式设置 S2_ACCOUNT_ENDPOINT 和 S2_BASIN_ENDPOINT。
• 启动方式：
  • 开发模式：pnpm install -> pnpm dev（API 在 8787，Vite 仪表盘在 5173）。
  • 生产模式：pnpm build -> pnpm start（Express 统一服务所有端口）。
• 前端集成：

  replaya("init", {
    apiHost: "https://replaya.example.com",
    source: "web-app", // 可选元数据，用于分组
    // projectKey: "pk_live_..." // 生产环境需配置
  });
  

6. 关键配置参数

• REPLAYA_SESSION_CREATE_RATE_LIMIT: 默认 60/分钟/客户端/项目。
• REPLAYA_SESSION_APPEND_RATE_LIMIT: 默认 600/分钟/客户端/会话。
• REPLAYA_APPEND_TOKEN_TTL_MS: 默认 86400000（24小时）。
• NODE_ENV=production: 启用生产模式，强制摄入认证，拒绝无来源摄入，禁用测试夹具。
• REPLAYA_APPEND_TOKEN_SECRET: 必须设置稳定的随机值（如 openssl rand -hex 32），否则服务器拒绝启动。

关键要点

• 架构极简主义：RePlaya 用单一的 S2 流替代了数据库、消息总线、对象存储和搜索引擎，大幅降低了系统复杂性和运维负担。
• 原生实时能力：得益于 S2 流的尾随特性，RePlaya 原生支持“Live Tailing”，允许开发者在用户在线时实时观看会话，无需轮询或复杂的 WebSocket 管理。
• 隐私优先设计：默认屏蔽所有输入框内容，提供细粒度的 DOM 忽略机制，确保敏感数据（如密码）不会泄露到服务器。
• 严格的访问控制：生产部署严格区分公开写入面（Collector）和私有读取面（Dashboard/API），并通过短期令牌和 IP 白名单防止未授权访问。
• 自托管友好：完全支持自托管（Self-hosted），可对接 S2 Cloud 或本地部署的 s2-lite，数据完全由用户掌控，URI 可寻址，支持配置保留策略。
• 并发安全：利用围栏令牌（Fencing Tokens）确保会话状态的一致性，防止并发写入导致的数据混乱或会话复活。

意义与影响

RePlaya 的出现代表了会话回放工具向轻量化、去中心化存储演进的一个新方向。

1. 降低技术门槛：传统会话回放方案往往需要维护复杂的微服务架构。RePlaya 通过依赖单一的 S2 流，将后端复杂度降至最低，使得中小团队也能轻松部署高性能的自托管回放系统。
2. 数据主权与隐私：在 GDPR 等数据隐私法规日益严格的背景下，自托管方案允许企业将用户行为数据完全保留在自己的基础设施中，避免了第三方 SaaS 服务的数据合规风险。
3. **实时调试的新范式