mcpField
D
debugging-local-replay

debugging-local-replay

github.com/posthog开发76261 次安装今天更新
代码仓库

关于 debugging-local-replay

面向 PostHog 本地开发者的会话回放排障指南，按浏览器 SDK、服务进程、Kafka、存储到前端的链路逐步定位故障。针对无录制、列表缺失和播放卡顿等症状提供检查方法。

主要功能

  1. 01按数据链路分层定位故障
  2. 02检查浏览器请求与录制设置
  3. 03核对本地服务进程和端口
  4. 04验证 Kafka 数据与 SeaweedFS
  5. 05对照常见启动和进程故障

适用场景

  1. 01浏览器未发送回放数据请求
  2. 02请求成功但回放未出现在列表
  3. 03录制可见但播放持续缓冲
  4. 04排查本地服务或依赖未启动

MCP 相关

该技能未说明与 MCP 的关系。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill debugging-local-replay

安装后在 Claude Code 中输入/debugging-local-replay确认已加载。

附带文件references/common-failures.md

详细介绍

调试本地会话回放

当开发者说“本地回放无法正常工作”或“看不到录制内容”时， 请按顺序检查以下各层。 本地回放流水线涉及多个环节，故障通常不会显示任何提示。

常见症状速查

症状可能原因
Network 标签页中没有 /s 调用SDK 未录制——触发条件、设置或录制器脚本问题（步骤 1）
/s 调用返回 200，但列表中没有录制内容数据接收流水线故障——capture-replay、Kafka 或 ingestion-sessionreplay（步骤 2-3）
列表中有录制内容，但播放卡在“Buffering...”recording-api（端口 6741）未运行（步骤 2）
控制台中出现录制器脚本 MIME 类型或 CORS 错误前端构建过期——需要运行 pnpm build + pnpm copy-scripts（步骤 1）

本地回放流水线

Browser SDK  →  /s endpoint (Caddy proxy :8000)
             →  capture-replay (Rust, :3306)
             →  Kafka (session_recording_snapshot_item_events topic)
             →  ingestion-sessionreplay (Node, :6740, PLUGIN_SERVER_MODE=recordings-blob-ingestion-v2)
             →  SeaweedFS (blob storage, :8333)
             →  recording-api (Node, :6741, PLUGIN_SERVER_MODE=recording-api)
             →  Frontend

这条链路中的任何环节出现故障，都会导致 UI 中没有录制内容。 诊断时需要找出链路在哪个位置中断。

步骤 1 — SDK 是否尝试进行录制？

请开发者打开浏览器 DevTools 的 Network 标签页，并筛选 /s。

如果完全没有 /s 调用： SDK 没有尝试发送录制数据。请排查客户端原因：

  • 项目设置中配置了触发条件。 如果设置了 URL 触发条件、事件触发条件或关联标记触发条件， 录制要等到触发条件触发后才会开始。这是体验过触发条件功能的开发者最常遇到的问题。 检查本地 UI 中的会话回放设置（项目设置 > 会话回放）。移除或调整触发条件，让录制可以开始。
  • 项目设置中已禁用录制。 会话回放可能已关闭。
  • 采样率设置过低。 如果 $replay_sample_rate < 1.0，会话可能不会被采样。
  • SDK 初始化时未启用录制。 检查本地应用的 PostHog 初始化配置—— 不得显式禁用 session_recording。
  • PostHog host 不正确。 本地应用必须指向 http://localhost:8000（或本地 Caddy 代理的运行地址）。
  • 广告拦截器。 即使在本地开发环境中，浏览器扩展也可能拦截录制器脚本或 /s 端点。
  • 录制器脚本加载失败（MIME 类型 / CORS 错误）。 浏览器控制台中可能会显示 posthog-recorder.js 的 MIME type ('text/html') is not executable 错误，或 lazy-recorder.js 的 CORS 错误。 这表示 Django 返回的是 HTML 页面（通常是登录重定向页面），而不是 JS 文件——静态录制器脚本已过期或缺失。 请参阅录制器脚本构建失败。

如果 /s 调用返回 200 响应： SDK 正在录制，capture 也在接收数据。故障发生在下游——继续检查步骤 2。

如果 /s 调用返回错误（4xx/5xx）： capture 服务可能已停止或配置有误。请在 phrocs 中检查 capture-replay。

步骤 2 — 必需的进程是否正在运行？

检查以下 phrocs 进程是否正在运行且状态正常。 如果某个进程显示为“运行中”，但在执行 tsx watch src/index.ts 后始终没有产生输出，实际上就已停止工作。

关键进程及其端口
进程端口功能
capture-replay3306接收 /s 的 Rust 服务，并写入 Kafka
ingestion-sessionreplay6740处理 Kafka 中录制数据的 Node 消费者
recording-api6741向前端提供回放数据的 Node 服务

验证方式：

lsof -nP -i :3306 -i :6740 -i :6741

如果端口未在监听： 这些进程尚未启动或已卡住。请参阅常见故障。

如果端口正在监听： 管道进程正在运行。请继续执行步骤 3。

Docker 依赖项

以下 Docker 容器必须正在运行且处于健康状态：

容器用途
posthog-kafka-1录制事件的消息总线
posthog-db-1用于元数据的 Postgres
posthog-redis7-1用于状态的 Redis
posthog-clickhouse-1用于会话数据的 ClickHouse
seaweedfs-main用于录制数据的 Blob 存储

检查方式：

docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "kafka|db|redis7|clickhouse|seaweed"

除 seaweedfs 外，所有容器都应显示 (healthy)，因为 seaweedfs 没有健康检查。 如果缺少 seaweedfs-main，则可能未启用 replay Docker 配置文件 — 请检查 docker-compose phrocs 进程输出中是否包含 --profile replay。

步骤 3 — 数据是否正在通过 Kafka 流动？

如果 capture-replay 正在运行并接收 /s 调用，数据应写入 session_recording_snapshot_item_events Kafka 主题。请检查 Kafka UI http://localhost:8080（如果已启用 debug_tools intent），或使用 kcat：

kcat -b localhost:9092 -t session_recording_snapshot_item_events -C -c 5 -e

如果主题为空或不存在： capture-replay 未向 Kafka 写入数据。请检查其 phrocs 日志中是否有 Kafka 连接错误。

如果主题中有数据，但没有显示录制内容： ingestion-sessionreplay 未在消费数据。请检查它是否卡住、崩溃，或是否有 孤立进程占用了消费者组（请参阅常见故障）。

步骤 4 — 检查 SeaweedFS

Ingestion 会将录制数据 Blob 写入 SeaweedFS。请验证其是否可访问：

curl -s http://localhost:8333/ | head -5

必须正确设置 SESSION_RECORDING_V2_S3_ENDPOINT 环境变量。 在 bin/start 中，该变量默认为 http://seaweedfs:8333（Docker 主机名）。 主机进程通过 Docker 网络解析此地址。

常见故障参考

请参阅常见故障，了解以下问题的详细诊断方法：

  • 占用 Kafka 消费者组的孤立 Node 进程
  • 卡在 bin/wait-for-docker 的进程
  • tsx watch 悄无声息地吞掉崩溃
  • Docker 进程与主机进程之间的端口冲突
  • 启动时 Cargo 构建锁争用

评论

支持 Markdown