调试本地会话回放
当开发者称「本地回放不工作」或「录制没有显示出来」时，需要按以下层次依次排查。本地回放流水线包含多个活动部件，且故障通常是静默的。
快速症状指南
| 症状 | 可能原因 |
|---|---|
| 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 中的会话回放设置（Project settings > Session replay）。移除或调整触发器以允许开始录制。
- 项目设置中禁用了录制。会话回放可能被关闭。
- 采样率设置过低。如果
$replay_sample_rate< 1.0，会话可能被采样排除。 - SDK 未以录制模式初始化。检查本地应用的 PostHog 初始化——
session_recording不能被显式禁用。 - PostHog 主机错误。本地应用必须指向
http://localhost:8000（或本地 Caddy 代理运行的位置）。 - 广告拦截器。即使在本地开发中，浏览器扩展也可能拦截录制脚本或 /s 端点。
- 录制脚本加载失败（MIME 类型 / CORS 错误）。浏览器控制台可能显示
MIME type ('text/html') is not executable针对 posthog-recorder.js，或 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-replay | 3306 | 接收 /s 的 Rust 服务，写入 Kafka |
| ingestion-sessionreplay | 6740 | 从 Kafka 处理录制的 Node 消费者 |
| recording-api | 6741 | 向前端提供回放数据的 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-main 缺失，回放 Docker profile 可能未激活——检查 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
采集会将录制 blob 写入 SeaweedFS。验证其可访问：
curl -s http://localhost:8333/ | head -5
SESSION_RECORDING_V2_S3_ENDPOINT 环境变量必须正确设置。在 bin/start 中，它默认为 http://seaweedfs:8333（Docker 主机名）。主机进程通过 Docker 网络解析此地址。
常见失败参考
参见常见失败以获取以下问题的详细诊断：
- 孤立 Node 进程占用 Kafka 消费者组
- 进程卡在
bin/wait-for-docker - tsx watch 静默吞掉崩溃
- Docker 与主机进程之间的端口冲突
- 启动时的 Cargo 构建锁争用