PostHog：开源产品工程平台

PostHog 真正解决的不是"少装一个分析工具"，而是把分散在各处的产品数据，收拢到同一个事件模型上。Google Analytics 看流量、Mixpanel 看事件、FullStory 看回放、Sentry 看报错——各管一段，互不相通；PostHog 把这四段拼成了一条时间线，一次埋点，全平台通用。

它给自己的定位是：the open source platform for building self-driving products——不仅把数据收拢到一处，还让 AI 代理直接消费这些数据，从报错、rage clicks、失败查询里自动生成报告甚至 pull request。主仓库 PostHog/posthog 已有 4 万余 stars，MIT Expat 协议开源（ee/ 目录的企业功能除外）。更少见的，是团队连自己的公司手册（handbook）也开源了——从战略到工作方式到流程全透明。

下面拆成三条主线来看：产品矩阵、技术架构、开源策略。它们分别回答"能做什么"“怎么组织代码"“为什么敢把一切摊开”。

读完这篇文章，你应该能：

1. 说出 PostHog 的主要产品模块，以及每个模块解决什么具体问题
2. 用自己的话解释 PostHog 如何用 facade、tach、Turbo 三件套强制产品隔离，并说出破坏隔离的代价
3. 对比 Cloud 部署与自托管两种方式，判断自己的团队该选哪个
4. 面对一个具体需求（比如"想看用户报错前的操作路径”），能指出该用 PostHog 的哪几个模块组合

一、为什么需要 PostHog：解决产品开发的痛点

做产品的人通常面临几个痛点：

1. 数据散：Google Analytics 看流量，Mixpanel 看事件，FullStory 看回放，Sentry 看报错——四个工具，四套数据，互不相通
2. 定位慢：用户报错了不知道是怎么走到那个页面的，用户流失了不知道卡在哪一步
3. 发布险：Feature flag 能力弱，改个参数要重新发版，灰度全靠运气

PostHog 的解题思路是：把所有产品构建需要的数据能力聚合到一个平台，一次安装，全套拥有。

先给一张总览，后面每个模块只展开一次，不会再翻回来：

这张表也是一个快速检索：读到"会话回放"时，把它当作"还原报错现场"的答案来记，而不是一个孤立的录制工具。下文每一节都会回到这张表的某个格子。

二、产品矩阵：核心模块一览

官方 README 列出了 13 个产品，还在持续增加——本文写作时，日志、自驾驶模式（self-driving mode）、PostHog AI 都已在列。下面挑最常用的 12 个逐一介绍：

2.1 产品分析（Product Analytics）

autocapture（自动采集）+ 手动埋点双轨并行，支持事件级分析、可视化图表和 SQL 查询。autocapture 会自动捕获点击、页面浏览、输入等行为，不需要手动埋点就能看到用户在做什么。

2.2 Web 分析（Web Analytics）

类 Google Analytics 体验，监控网站流量、会话数据和转化漏斗，天然集成 Core Web Vitals 和收入数据看板。

2.3 会话回放（Session Replay）

录制用户在网页或移动端的真实操作，播放交互过程，用于诊断可用性问题和还原 bug 现场。类似 FullStory，但原生集成在 PostHog 生态里，不需要额外采购。

2.4 Feature Flags

安全地将功能灰度推送给指定用户或群组，支持百分比分割、用户属性条件、过期时间等精细化控制。配合 Experiments 使用，可以做完整的 A/B 测试。

2.5 实验（Experiments）

在 PostHog 内部直接创建和运行 A/B 测试，测量变更对目标指标的统计影响，支持 no-code 配置。

2.6 错误追踪（Error Tracking）

捕获前端和后端异常，支持报警、分组、去重，并关联到具体的 session replay，帮你快速还原事故现场。

2.7 调研（Surveys）

no-code 问卷模板或自定义问卷，触达用户收集反馈，数据直接进 PostHog 分析。

2.8 数据仓库（Data Warehouse）

将外部工具（Stripe、HubSpot、自建数据仓库）的数据同步到 PostHog，和产品事件数据一起用 SQL 做联合分析。

2.9 数据管道（Data Pipelines / CDP）

PostHog 的 CDP（Customer Data Platform，客户数据平台）能力：对流入数据做过滤和转换，实时转发到 25+ 外部工具或任意 Webhook，或批量导出到数据仓库。

2.10 AI 可观测性（AI Observability）

专门针对 LLM 应用的分析能力（曾用名 LLM Analytics）：捕获 traces、generations、latency 和 cost，让 AI 应用开发者也能像分析普通产品一样分析 AI 行为。

2.11 工作流（Workflows）

自动化操作和消息推送，根据用户行为触发工作流。

2.12 日志（Logs）

采集、检索和分析日志数据，和其余产品数据放在同一个平台里查询——排查问题时不用再在日志系统和分析工具之间切换。

三、技术架构：Monorepo 分层设计

PostHog 的代码库是标准的 Python Monorepo，按官方 docs/internal/monorepo-layout.md 的说法，核心设计原则是垂直切分（Vertical Slices）+ 产品隔离，配套一套强制隔离的工程机制。

3.1 顶层目录结构

posthog/               # 遗留单体代码（Django）
  api/                 # DRF views, serializers
  models/              # Django models
  queries/             # HogQL query runners

ee/                    # 企业版功能（正逐步迁往 products/ 与 posthog/）

products/              # 产品垂直切分（推荐新代码放这里）
  <product>/
    backend/           # Django app（models, logic, routes, facade/, presentation/, tasks/, tests/）
    frontend/          # React（scenes, components, logics, hooks, generated/）
    manifest.tsx       # 路由、场景、URL 配置
    package.json       # Turborepo 包定义
    mcp/ skills/       # 多数产品带 MCP 工具定义与 agent skills
    services/ packages/ # 可选：产品自有的服务与库

services/              # 不归属任何单一产品的独立服务
  llm-gateway/         # LLM 代理服务
  mcp/                 # Model Context Protocol 服务
  oauth-proxy/         # OAuth 代理（Cloudflare Worker）
  stripe-app/          # Stripe 集成应用
  agent-proxy/ integration-service/  # 等后续新增服务

packages/              # 跨产品/跨服务共享库（如 quill、agent 运行时）

common/                # 共享代码暂存区（官方目标：缩小直至消失）
  hogql_parser/        # HogQL 解析器

tools/                 # 开发者/CI 工具（运行时代码不引用）
  hogli/               # 开发者 CLI 框架

devenv/                # 本地开发环境配置
frontend/ cli/ rust/   # 主前端应用、CLI、Rust 组件等其余顶层目录

3.2 核心机制：怎么把产品隔离开

模块化说起来容易，难在强制执行。PostHog 用了三层机制，全部落在 CI 里：

1. Facade（外观层）+ 冻结 dataclass 契约。每个产品把 facade/api.py 作为唯一公开接口，跨产品传递的数据用 facade/contracts.py 里的冻结 dataclass（frozen dataclasses）定义。其他产品只能 import facade，碰不到内部实现；DRF 展示层（presentation/）在 facade 之外，不得反向泄漏业务逻辑。
2. tach 强制 import 边界。产品之间的依赖关系在 tach.toml 里显式声明，谁 import 了不该 import 的东西，lint-imports 直接在 CI 拦下。这条规则没有"口头约定"的余地。
3. Turbo 选择性测试。一个产品就是一个 Turborepo 包，contract 文件（冻结 dataclass、枚举）作为缓存输入——改了产品内部实现，只重跑该产品的测试；改了契约，才级联重跑下游产品。

隔离被破坏的代价是具体的：没有边界时，任何一处改动都要跑全量 Django 测试套件，CI 时间随代码量线性恶化——这正是官方架构文档开头给出的动机。

core（posthog/ 和 ee/）偶尔需要调用产品的行为，比如查询分发、AI 工具注册。这类"接线"只能走批准的接口基类——QueryRunner、MaxTool、Temporal workflow、Celery shared_task——core 只依赖基类接口，不依赖任何具体产品的成员。

一个细节：为什么没有顶层的 platform/ 共享基础设施目录？官方文档给的答案很朴素——Python 标准库里已经有个模块叫 platform，顶层建这个包会遮蔽标准库。所以共享代码按归属下沉：单个产品用的放进产品目录，真正跨产品的进 packages/。

3.3 Products：垂直切分的典范

每个 product 是一个完整的垂直切片：

products/feature-flags/
  backend/           # Django app（models, logic, routes, facade/, presentation/, tasks/）
  frontend/          # React（scenes, components, logics）
  manifest.tsx       # 路由 + URL 配置
  mcp/ skills/       # MCP 工具定义与 agent skills

产品之间不互相导入内部代码，只通过 facade 通信。这使得：

• 每个 product 可以独立开发、测试（Turbo 只重跑受影响的测试）
• 新人接手一个 product 不需要理解整个代码库
• 改动的影响范围天然隔离

3.4 Services：独立部署的业务逻辑

Services 是不归属任何单一产品的独立部署服务，有自己的领域逻辑。当前 services/ 下有 llm-gateway、mcp、oauth-proxy、stripe-app、agent-proxy、integration-service、hogql-language-service 等。

3.5 HogQL：SQL 查询接口

PostHog 自研了 HogQL 作为 SQL 查询接口，官方对它的定义是"effectively a wrapper around ClickHouse SQL"——最终编译成 ClickHouse 查询执行（API 响应里带生成的 clickhouse 字段可查）。它在 ClickHouse SQL 之上做了三件事：简化事件与用户属性访问（properties.$current_url 直接写，不用拼长路径）、提供 {filters} 占位符（SQL insight 的日期范围和属性筛选可以在界面上调，不用改 SQL）、与可视化打通（SQL 表达式直接接入趋势、漏斗、分组图表）。解析器 hogql_parser 放在 common/ 下。

3.6 一次结账失败如何穿过整个平台

配一个动态案例，机制才看得见。假设用户 A 在结账页按支付按钮后报错，反馈里说不清卡在哪一步。PostHog 里，这条链路是这样走的：

1. 事件入站：前端 SDK 自动捕获 checkout_submit，后端在抛错处手动上报 payment_error。两条事件都挂在用户 A 的同一时间线上。
2. 数据分析：Product Analytics 里，checkout_submit → payment_error 的瀑布图上没有中间事件，说明问题出在提交本身，不是跳转或支付弹窗。
3. 回放还原：点进用户 A 的 Session Replay，看到按钮点击后页面无响应、按钮一直禁用，判定是请求卡住而非用户误操作。
4. 错误追踪：payment_error 的堆栈指向后端 validate 超时，Error Tracking 自动把这条记录和用户 A 的回放关联起来。
5. 定位范围：把报错用户按 Feature Flag 分组，发现全集中在开了"快速结账"flag 的 5% 灰度组里，其余 95% 正常——回归来源被锁在这个灰度。
6. 验证修复：回滚该 flag，用 Experiments 对比前后转化率，确认修复有效后再全量放量。

整段排查在同一平台、同一用户模型下完成。分散方案里，这六步要在四个工具各来一遍，而且每一步都带着独立的用户身份。

四、SDK 生态：多端覆盖

PostHog 为 12 个平台提供官方 SDK，前后端数据模型一致：

Go、.NET/C#、Django、Angular、WordPress、Webflow 等平台，官方提供的是接入文档和指南，不是团队维护发版的一等 SDK。选型时值得注意这个差别。

五、开源策略：透明到连公司手册都开源

PostHog 的开源策略有几个独到之处：

5.1 代码开源

主仓库是 MIT Expat 协议，但 ee/ 目录（企业功能）有自己的许可证。这意味着：

• 核心功能全开源，任意使用
• 企业高级功能闭源，但许可证是透明的（不是黑箱）

需要 100% FOSS 的场景，官方维护了 posthog-foss——从主仓库自动同步的只读镜像，剥离了全部专有代码，至今持续同步。注意 issue 和 PR 要回主仓库提，foss 仓库不接受直接贡献。

5.2 公司手册开源

PostHog 把自己的公司手册也开源了（https://posthog.com/handbook），包含：

• 战略：为什么 PostHog 存在（why-does-posthog-exist）
• 文化：工作方式和价值观
• 流程：团队结构、工程实践、产品开发流程

多数公司把手册当内部文档，PostHog 把它当公开读物——社区不仅能贡献代码，还能看到团队做事的逻辑。这种透明度直接换来的是信任：定价、路线图、决策过程全部可查，用户不用猜。

5.3 定价透明

PostHog 的定价完全公开在官网（https://posthog.com/pricing），云版本每月有免费额度：100 万事件、5k recordings、100 万 flag 请求、10 万 exceptions、1500 问卷响应，此外日志 10 GB、AI 可观测性 10 万事件，超出后按量付费。额度每月重置，不累计。

六、快速开始

云版本（推荐）：

# 访问 https://us.posthog.com/signup 或 https://eu.posthog.com/signup
# 免费额度：每月 100 万事件 + 5k recordings

自托管（Hobby 实例）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/deploy-hobby)"

最低配置：4GB 内存，适合个人项目或小团队起步。官方建议开源部署的规模上限约为每月 10 万事件，超过就该迁移到 Cloud；并且官方不为自托管部署提供客户支持或可用性保障。

安装 SDK：

# JavaScript
npm install posthog-js

# Python
pip install posthog

# Node.js
npm install posthog-node

七、适用场景与采用顺序

对照第一节的痛点表，可以给出更直接的判断：

• 内容站看 PV：Google Analytics 够用，不必为流量分析引入 PostHog。
• SaaS 或复杂交互产品（在线编辑器、后台系统）：从 Cloud 免费版开始，先接 Product Analytics 和 Session Replay 跑两周数据，再决定要不要把 Feature Flags 和 Experiments 切过来——这两块是替换 LaunchDarkly + A/B 工具组合的主要收益点。
• 数据不能出境（金融、医疗）：Hobby 自托管起步，4GB 内存、10 万事件/月规模内免费，超了迁移 Cloud 或上企业版。
• LLM 应用开发者：AI 可观测性单独就能用，不用整体迁移。
• 想借鉴工程实践：即使不用产品，products/ 的垂直切分 + facade 契约 + tach 边界这套组织方式，也值得在规划自己的 monorepo 时参考。

第八节的常见问题里有更具体的迁移决策。

八、常见问题

Q1：我们已经在用 Google Analytics 了，还需要 PostHog 吗？

场景：团队有 2-3 个产品，GA 看流量、手动埋点看事件、Sentry 收报错，数据散在三处，出了问题要来回切换。

GA 擅长的是页面级流量分析，PostHog 的优势在于事件级——它能告诉你"谁点了哪个按钮之后去了哪里"，并且把 session replay、error tracking、feature flags 串在同一个用户时间线上。如果你的产品有复杂交互（比如 SaaS 后台、在线编辑器），换 PostHog 能省掉至少两套工具。如果只是内容站看 PV，GA 够用。

Q2：自托管最低要多少资源？和 Cloud 版功能一样吗？

场景：团队做金融/医疗 SaaS，数据不能出境，只能私有化部署。

Hobby 实例最低 4GB 内存，官方建议的规模上限是约每月 10 万事件。功能上，Cloud 和自托管的核心模块（Analytics、Replay、Feature Flags、Experiments、Error Tracking）一致，但 Cloud 多了托管便利性（自动升级、备份）。企业高级功能（ee/ 目录）需要单独授权，Cloud 和自托管都是如此。另外要接受官方的明确立场：自托管部署不提供客户支持或可用性保障。

Q3：PostHog 和 Sentry + Mixpanel + LaunchDarkly 组合有什么本质区别？

场景：团队已经买了 Sentry、Mixpanel 和 LaunchDarkly，三套数据不通，想评估是否值得迁移。

区别不在功能数量，而在数据模型统一。分散方案里，Sentry 的错误、Mixpanel 的事件、LaunchDarkly 的 flag 评估是三个独立的数据集，你没法在一条时间线上看到"用户开了 flag A → 触发错误 B → 在 session replay 里还原操作"。PostHog 把这几件事放在同一个用户/事件模型下，关联成本为零。代价是单点依赖——PostHog 挂了，这几块能力一起停。

Q4：HogQL 和标准 SQL 有什么不同？一定要学吗？

场景：团队有数据分析师，习惯用标准 SQL 写查询，担心 HogQL 学习成本高。

HogQL 是 ClickHouse SQL 的封装，标准 SQL 语法和函数都可用，查询最终编译为 ClickHouse 查询执行。它额外做了三件事：properties.$current_url 这样的属性简写、{filters} 占位符（让 insight 页面上的日期和筛选控件直接作用于 SQL）、与趋势/漏斗等可视化组件打通。日常的漏斗、留存、分群查询用可视化界面就够了，不需要写 SQL；只有做深度自定义分析（比如 JOIN 外部数据仓库的表）才需要。会标准 SQL 的话，上手 HogQL 几乎没有门槛。

Q5：PostHog 的免费额度够用吗？什么时候需要付费？

场景：3 人创业团队，日活几百，想知道能免费撑多久。

Cloud 免费额度每月 100 万事件 + 5k recordings + 100 万 flag 请求。以日均 1000 事件的小产品来算，免费额度完全够用。开始付费的典型节点是：recordings 超额（用户量大后回放消耗快）或者需要企业功能（SSO、权限控制）。自托管的 Hobby 实例也是免费的，只是你得自己运维。

自测

1. PostHog 的 autocapture 会自动采集哪些行为？什么场景下仍然需要手动埋点？
2. PostHog 靠哪三层机制强制产品隔离？如果去掉 tach 这一层，最可能先出现什么问题？
3. PostHog 的 Feature Flags 和 Experiments 是什么关系？能不能只用其中一个？
4. 你正在做一个 LLM 应用，需要追踪每次 API 调用的耗时、token 消耗和错误率。PostHog 的哪几个模块能覆盖这个需求？为什么不能只靠 Error Tracking？

总结

PostHog 不是一个简单的"分析工具"，它是一个产品工程平台——把构建成功产品所需的全部数据能力打包在一起，从用户行为分析到会话回放、从错误追踪到 Feature Flag、再到 AI 可观测性和日志，现在还朝着"AI 代理直接消费产品数据、自动生成修复"的方向走。

4 万余 stars 背后是一套可以直接参考的工程决策：Python/Django 后端、React 前端、垂直切片组织、facade 契约加 tach 边界做强制隔离。公司手册也开源意味着你不仅能读代码，还能看到他们为什么这么写。

如果你的团队还在用多套分散的工具做产品分析，可以从 Cloud 免费版开始试起：先接 Analytics 和 Session Replay，跑两周数据，再决定要不要把 Experiments 和 Feature Flags 也切过来。

相关链接：

• GitHub：https://github.com/PostHog/posthog（4 万余 stars）
• 官网：https://posthog.com
• 文档：https://posthog.com/docs
• 公司手册（开源）：https://posthog.com/handbook