# https://github.com/PostHog/posthog 项目说明书

生成时间：2026-07-21 20:56:04 UTC

## 目录

- [PostHog 平台概览与架构](#page-1)
- [核心产品功能:分析、回放、实验与数据仓库](#page-2)
- [Max AI 智能体、MCP 与 AI 可观测性](#page-3)
- [前后端实现、数据库与部署运维](#page-4)

<a id='page-1'></a>

## PostHog 平台概览与架构

### 相关页面

相关主题：[核心产品功能:分析、回放、实验与数据仓库](#page-2), [前后端实现、数据库与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/PostHog/posthog/blob/main/README.md)
- [docs/internal/monorepo-layout.md](https://github.com/PostHog/posthog/blob/main/docs/internal/monorepo-layout.md)
- [docs/published/handbook/engineering/project-structure.md](https://github.com/PostHog/posthog/blob/main/docs/published/handbook/engineering/project-structure.md)
- [docs/published/handbook/engineering/stack.md](https://github.com/PostHog/posthog/blob/main/docs/published/handbook/engineering/stack.md)
- [docker-compose.dev.yml](https://github.com/PostHog/posthog/blob/main/docker-compose.dev.yml)
- [posthog/celery.py](https://github.com/PostHog/posthog/blob/main/posthog/celery.py)
- [frontend/src/index.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/index.tsx)
- [plugin-server/src/index.ts](https://github.com/PostHog/posthog/blob/main/plugin-server/src/index.ts)
</details>

# PostHog 平台概览与架构

## 一、项目定位与核心目标

PostHog 是一个开源的产品分析平台，将多种开发者与产品团队所需的能力整合到同一代码库中。仓库 README 将其定位为"All-in-one product analytics, web analytics, session replay, feature flags, A/B testing, error tracking, surveys, data warehouse, LLM analytics, and more"的统一解决方案。资料来源：[README.md:1-40]()。

平台的设计目标包含三层：

1. **自托管友好**：提供完整的 Docker Compose 与 Helm 部署方案，使企业可以在自己的基础设施上运行，避免数据外流。
2. **多产品一体化**：把分析、会话回放、功能开关、实验、错误追踪、问卷、CDP/LLM 可观测性等产品整合在同一后端模型中，共享事件与用户身份。
3. **可扩展的插件体系**：通过 plugin-server 进程处理事件流水线与第三方集成，第三方插件以 TypeScript 编写并可热加载。

## 二、仓库与代码组织

仓库采用 monorepo 形式，按职责划分为多个子包。`docs/internal/monorepo-layout.md` 描述了顶层目录结构：`posthog/` 为 Django 后端、`frontend/` 为 React 前端、`plugin-server/` 为事件处理流水线、`hogvm/` 与 `rust/` 为 Rust 编写的查询与执行模块。资料来源：[docs/internal/monorepo-layout.md:1-50]()。

`docs/published/handbook/engineering/project-structure.md` 进一步将代码组织归纳为三段式：

- **应用代码（apps）**：前端 SPA 与 Django REST/GraphQL API。
- **后台任务与流水线**：Celery worker 与 plugin-server。
- **共享类型与协议**：通过 OpenAPI/TypeScript 自动生成的 `schema/` 目录统一前后端类型。资料来源：[docs/published/handbook/engineering/project-structure.md:1-80]()。

```mermaid
flowchart LR
    Client[Web / Mobile SDK] -->|events/decide| Ingest[/capture endpoint/]
    Ingest --> Plugin[plugin-server]
    Plugin --> Kafka[(Kafka)]
    Kafka --> Consumer[batch consumers]
    Consumer --> CH[(ClickHouse)]
    Consumer --> PG[(Postgres)]
    Plugin --> HogFlow[HogFlow / actions]
    Frontend[React App] --> API[Django API]
    API --> CH
    API --> PG
    API --> Worker[Celery]
```

## 三、技术栈与运行依赖

`docs/published/handbook/engineering/stack.md` 列举了主要技术组件：后端使用 Django + DRF + Celery，事件存储使用 ClickHouse，关系数据使用 PostgreSQL，缓存与队列使用 Redis，事件流使用 Kafka，查询语言为基于 SQL 的 HogQL。资料来源：[docs/published/handbook/engineering/stack.md:1-90]()。

`docker-compose.dev.yml` 描述了本地启动所需的依赖集合：Postgres、Redis、ClickHouse、Kafka、Zookeeper、MinIO（对象存储）、Mailhog（邮件测试）等容器，所有服务通过统一网络互联。资料来源：[docker-compose.dev.yml:1-120]()。

后端入口由 `posthog/celery.py` 提供异步任务调度能力，任务涵盖事件去重、属性刷新、外部 webhook 投递等长时间运行操作，与 Django 的 WSGI/ASGI 服务共存于同一进程模型。资料来源：[posthog/celery.py:1-40]()。

前端入口 `frontend/src/index.tsx` 启动 React 18 + TypeScript SPA，通过 PostHog 的 toolbar 与 GraphQL/REST API 与后端交互，并使用 Kea 作为状态管理框架。资料来源：[frontend/src/index.tsx:1-30]()。

## 四、核心产品模块与数据流

PostHog 围绕"事件 + 用户 + 组织"三层模型组织各产品模块，`plugin-server/src/index.ts` 描述了从 SDK 接收到事件后的处理流水线：解析 → 校验 → 持久化 → 触发插件/动作 → 写入下游（ClickHouse、Postgres、webhook）。资料来源：[plugin-server/src/index.ts:1-60]()。

| 模块 | 数据存储 | 关键能力 |
|------|---------|---------|
| Product Analytics | ClickHouse | 趋势、漏斗、留存、HogQL 查询 |
| Feature Flags | Postgres + Redis | 灰度发布、实验分组、SDK evaluate |
| Session Replay | ClickHouse + S3 | rrweb 录制、压缩、播放 |
| Experiments | ClickHouse | 曝光/转化指标、统计显著性 |
| Surveys | Postgres | 触发器配置、反馈收集 |
| Error Tracking | ClickHouse | 异常聚合、堆栈归因 |
| LLM Analytics | ClickHouse + PG | 提示词、成本、可观测性 |

各模块共享同一事件流和用户识别模型，因此一次 SDK 调用可以同时被多个模块消费，例如同一 `$pageview` 事件既能进入产品分析也能驱动会话回放录制。这与社区关注的"功能开关 + 实验 + 会话回放联动"用例高度契合。资料来源：[docs/published/handbook/engineering/project-structure.md:80-160]()。

## 五、面向开发者的扩展点

开发者可通过三类机制扩展 PostHog：

1. **SDK 接入**：JavaScript、Python、React Native、iOS、Android、Java 等多端 SDK 将事件发往 `/capture` 与 `/decide` 端点。社区中热度较高的"React Native Session Recordings"（issue #13269）与"iOS Session Recordings"（issue #12344）正是对移动端 SDK 与 plugin-server 录制管线的延伸请求。
2. **插件**：plugin-server 加载 TypeScript 插件，可在事件流水线各阶段插入处理逻辑，例如发送至 Slack、HubSpot 或执行 ETL。
3. **HogQL 与 API**：通过 SQL-like 的 HogQL 直接查询 ClickHouse，或使用 GraphQL/REST API 将数据嵌入自有产品。

CLI 与 Agent Skills 的独立发布通道（`posthog-cli`、`agent-skills-v0.x.x`）则为自动化与 LLM 代理场景提供了工具入口，使 PostHog 能够嵌入到工作流与 AI 助手链路中。资料来源：[docs/published/handbook/engineering/stack.md:90-140]()。

---

<a id='page-2'></a>

## 核心产品功能:分析、回放、实验与数据仓库

### 相关页面

相关主题：[PostHog 平台概览与架构](#page-1), [Max AI 智能体、MCP 与 AI 可观测性](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [frontend/src/queries/nodes/InsightViz/InsightViz.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/queries/nodes/InsightViz/InsightViz.tsx)
- [frontend/src/scenes/insights/Insights.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/scenes/insights/Insights.tsx)
- [frontend/src/scenes/replay/Replay.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/scenes/replay/Replay.tsx)
- [posthog/models/feature_flag/feature_flag.py](https://github.com/PostHog/posthog/blob/main/posthog/models/feature_flag/feature_flag.py)
- [posthog/models/experiment.py](https://github.com/PostHog/posthog/blob/main/posthog/models/experiment.py)
- [ee/clickhouse/views/experiment_holdouts.py](https://github.com/PostHog/posthog/blob/main/ee/clickhouse/views/experiment_holdouts.py)
- [posthog/warehouse/models/datawarehouse_saved_query.py](https://github.com/PostHog/posthog/blob/main/posthog/warehouse/models/datawarehouse_saved_query.py)
- [posthog/tasks/exports.py](https://github.com/PostHog/posthog/blob/main/posthog/tasks/exports.py)
</details>

# 核心产品功能:分析、回放、实验与数据仓库

PostHog 是一个开源的产品分析平台，其核心由四大功能支柱构成：**分析(Insights)**、**会话回放(Session Replay)**、**实验(Experiments & Feature Flags)** 与 **数据仓库(Data Warehouse)**。这些模块既可独立使用，也通过统一的事件模型、ClickHouse 存储层与查询架构互相协作,形成“采集 → 存储 → 查询 → 行动”的闭环。

## 1. 分析模块 (Analytics)

分析模块负责把原始事件流转化为可读的趋势、漏斗、留存和路径等图表。核心入口是 `InsightViz`,它包装任意查询节点并渲染为可视化组件。

- 查询节点体系: `InsightViz` 接受 `data-attr` 形式的查询节点,通过 `InsightContainer` 加载数据并下发给具体的 `Trends`、`Funnels`、`Retention`、`Paths` 等子组件 资料来源：[frontend/src/queries/nodes/InsightViz/InsightViz.tsx:1-80]()。
- 场景壳层: `Insights.tsx` 提供页面级布局、过滤器、查询历史与保存状态管理,是用户在 UI 中创建/编辑 insight 的主入口 资料来源：[frontend/src/scenes/insights/Insights.tsx:1-60]()。
- 后端执行: 后端通过 HogQL/HoGQ 编译器把 insight 查询翻译为 ClickHouse SQL,异步返回结构化结果。

## 2. 会话回放 (Session Replay)

回放模块捕获并重放用户在产品中的真实操作,以 rrweb 格式压缩存储,支持列表浏览与单条回放。

- 列表与播放器入口: `Replay.tsx` 是 `/replay` 路由的根组件,内含 `ReplayList` 与 `ReplayPlayer`,分别负责会话检索与时间轴/事件播放 资料来源：[frontend/src/scenes/replay/Replay.tsx:1-50]()。
- 数据格式: 前端使用 `posthog-js` 的 `rrweb-plugin-posthog` 捕获事件,后端将分片写入对象存储(S3)并把元数据落到 ClickHouse 的 `session_replay_events` 表。
- 社区关注: 移动端(React Native #13269、iOS #12344)的回放支持是长期热门请求,目前在 Web 之外仍属路线图阶段 资料来源：[GitHub Issue #13269]()、[GitHub Issue #12344]()。

## 3. 实验与功能标志 (Experiments & Feature Flags)

该模块覆盖特性开关、A/B 实验与多变量实验,并复用同一份曝光事件以对接分析。

- 功能标志模型: `FeatureFlag` 模型包含 `key`、`filters`(多变量/属性定向/变体比例)、`rollout_percentage` 等字段,本地评估逻辑在 `feature_flag.py` 中实现 资料来源：[posthog/models/feature_flag/feature_flag.py:1-120]()。
- 实验模型: `Experiment` 与 `ExperimentHoldout` 通过 ClickHouse 视图聚合曝光与转化,`experiment_holdouts.py` 视图定义了实验对照组的过滤规则,确保跨实验互不污染 资料来源：[ee/clickhouse/views/experiment_holdouts.py:1-60]()。
- 客户端 SDK: SDK 缓存标志配置并定期刷新,根据 `distinct_id` 与属性哈希到稳定变体,从而在低延迟下决定是否上报曝光事件。
- 社区关注: 对 Java 等语言 SDK 的特性标志支持请求较多(#16419),目前官方 SDK 优先覆盖 Web、Python、Node、Ruby 等 资料来源：[GitHub Issue #16419]()。

## 4. 数据仓库 (Data Warehouse)

数据仓库模块让用户把外部数据源(如 Stripe、HubSpot、S3)接入 PostHog,并与产品事件一起参与 HogQL 查询。

- 物化与保存查询: `DataWarehouseSavedQuery` 模型封装了外部表的视图化定义,支持定时刷新、增量列裁剪与 HogQL 联合查询 资料来源：[posthog/warehouse/models/datawarehouse_saved_query.py:1-80]()。
- 导出与同步: `posthog/tasks/exports.py` 提供异步任务把 insight、cohort、replay 等数据导出为 CSV/Parquet,用于 BI 工具或自托管分析 资料来源：[posthog/tasks/exports.py:1-60]()。
- 与分析协同: 仓库中的外部表可在 insight 中通过 HogQL 的 `JOIN events` 直接参与指标计算,这是 PostHog “事件 + 仓库一体化”的关键差异点。

## 四大模块协同关系

下表概括各模块在数据流中的角色与共享底座:

| 模块 | 主要输入 | 主要输出 | 共享底座 |
|------|---------|---------|---------|
| Analytics | 事件/属性 | Trends、Funnels 等图表 | ClickHouse、HogQL |
| Replay | rrweb 事件 | 会话列表与播放器 | S3 + ClickHouse |
| Experiments | 曝光/转化事件 | 显著性结果与变体分配 | FeatureFlag 模型、HogQL |
| Data Warehouse | 外部源表 | 物化视图、可 JOIN 资源 | ClickHouse 视图、Celery 任务 |

四大模块围绕 ClickHouse 这一统一事件存储层运转,前端通过 `InsightViz`、`Replay`、`Experiment` 等场景组件复用查询与可视化基础设施,从而在产品内实现“同一份事件、多种消费形态”的工程目标。

---

<a id='page-3'></a>

## Max AI 智能体、MCP 与 AI 可观测性

### 相关页面

相关主题：[核心产品功能:分析、回放、实验与数据仓库](#page-2), [前后端实现、数据库与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ee/hogai/chat_agent/graph.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/chat_agent/graph.py)
- [ee/hogai/core/runner.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/core/runner.py)
- [ee/hogai/mcp_tool.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/mcp_tool.py)
- [ee/hogai/llm_traces_summaries/summarize_traces.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/llm_traces_summaries/summarize_traces.py)
- [.agents/skills/implementing-mcp-tools/SKILL.md](https://github.com/PostHog/posthog/blob/main/.agents/skills/implementing-mcp-tools/SKILL.md)
- [ee/hogai/tools/execute_sql/tool.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/tools/execute_sql/tool.py)
</details>

# Max AI 智能体、MCP 与 AI 可观测性

## 概述与定位

Max AI 是 PostHog 内置的"产品分析师"型对话式智能体，面向 Dashboard、Insights、SQL、数据探索等场景，使用户可以通过自然语言与 PostHog 数据交互 资料来源：[ee/hogai/chat_agent/graph.py:1-40]()。其核心由三层组成：

1. **对话图（Conversation Graph）**：基于 LangGraph 的状态机，负责消息路由、上下文维护与多轮推理。
2. **MCP 工具层（Model Context Protocol）**：以标准化协议向 LLM 暴露"读 / 写 / 查询"等原子能力，例如 SQL 执行、Schema 查询、Insights 生成等。
3. **LLM 可观测性（LLM Observability）**：通过 trace 摘要、生成指标与错误聚合，让团队像分析事件一样分析自家 AI 调用。

整个体系强调"可控 + 可审计"，所有 LLM 调用必须经过可观测通道，以便在评测、合规与回放中复用。

## Max AI 智能体架构

### 对话图与核心运行器

`ee/hogai/chat_agent/graph.py` 定义了对话式智能体的状态机：节点代表推理 / 工具调用 / 答案合成，边由 LangGraph 的条件路由组成 资料来源：[ee/hogai/chat_agent/graph.py:1-80]()。该图通常包含：`assistant_node`（调用 LLM 生成回复或工具调用请求）、`tool_node`（执行被请求的工具）、`router`（决定下一步是回到 Assistant 还是给出最终答复）。

`ee/hogai/core/runner.py` 提供统一的运行入口，封装消息校验、租户上下文注入、可观测埋点与流式输出 资料来源：[ee/hogai/core/runner.py:1-60]()。所有上层路由（API endpoint、Slack、内部脚本）都通过 Runner 调度，保证行为一致。

### MCP 工具集成

`ee/hogai/mcp_tool.py` 是将 MCP 协议适配进 LangGraph 工具调用语义的桥梁：负责将工具元数据序列化为 OpenAI / Anthropic 兼容的 function-call 描述，并在执行后把结果回灌到对话上下文 资料来源：[ee/hogai/mcp_tool.py:1-90]()。

每个 MCP 工具都遵循统一的契约，例如 `ee/hogai/tools/execute_sql/tool.py` 实现了一个受控 SQL 执行工具：解析自然语言 → 生成 HogQL/SQL → 在受限沙箱中执行 → 返回带行数限制与脱敏的结果 资料来源：[ee/hogai/tools/execute_sql/tool.py:1-70]()。这种"以 MCP 工具封装一切副作用"的设计让权限边界、速率限制、审计日志得以集中治理。

## AI 可观测性（LLM Traces）

`ee/hogai/llm_traces_summaries/summarize_traces.py` 把对 LLM 的每次调用与每个工具调用都包装为一个 trace 节点，最终形成可被 Insights / Dashboards 查询的"生成事件流" 资料来源：[ee/hogai/llm_traces_summaries/summarize_traces.py:1-50]()。关键能力包括：

- **延迟 / token / 成本指标**：自动从 LLM 响应中抽取 usage 字段并写入 trace 属性。
- **错误归因**：将工具执行异常、JSON 解析失败、MCP 协议错误分类打标。
- **摘要生成**：异步调用更轻量的 LLM 对长轨迹做要点压缩，便于在 UI 中呈现"这轮对话在做什么"。
- **评估挂钩**：与 PostHog 的 Experiments 体系结合，允许把 trace 级反馈作为实验指标。

数据流如下（简化）：

```mermaid
flowchart LR
    U[用户消息] --> R[Runner]
    R --> G[LangGraph 状态机]
    G -->|function call| M[MCP Tool]
    M --> R
    G --> L[LLM]
    L -->|usage + output| T[Trace Store]
    T --> S[summarize_traces]
    S --> D[Insights / Dashboards]
```

资料来源：[ee/hogai/core/runner.py:60-120](), [ee/hogai/mcp_tool.py:90-160](), [ee/hogai/llm_traces_summaries/summarize_traces.py:50-110]()。

## 开发者技能（Agent Skills）

`.agents/skills/implementing-mcp-tools/SKILL.md` 为贡献者提供"如何在 Max AI 中安全地引入新 MCP 工具"的标准化指南 资料来源：[.agents/skills/implementing-mcp-tools/SKILL.md:1-40]()。该 skill 要求新工具必须：声明最小权限的数据范围、提供 schema 校验、接入可观测埋点、并附带回放测试用例。仓库通过 `agent-skills-v0.18x` 系列 release 持续迭代该体系，最近一次公开版本为 `agent-skills-v0.190.0` 资料来源：[github releases: agent-skills-v0.190.0]()。

## 小结

Max AI 将 PostHog 海量产品能力通过 MCP 工具的形式组合起来，以 LangGraph 作为推理骨架，以 LLM Traces 作为可观测底座。三者共同构成了"既能对话、又能落地、还能被审计"的 AI 平台形态。后续扩展应优先复用 MCP 工具合约，并在 PR 中附带 trace 回放用例，以符合现有治理规范。

---

<a id='page-4'></a>

## 前后端实现、数据库与部署运维

### 相关页面

相关主题：[PostHog 平台概览与架构](#page-1), [Max AI 智能体、MCP 与 AI 可观测性](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [posthog/settings.py](https://github.com/PostHog/posthog/blob/main/posthog/settings.py)
- [posthog/api/__init__.py](https://github.com/PostHog/posthog/blob/main/posthog/api/__init__.py)
- [posthog/models/__init__.py](https://github.com/PostHog/posthog/blob/main/posthog/models/__init__.py)
- [posthog/clickhouse/__init__.py](https://github.com/PostHog/posthog/blob/main/posthog/clickhouse/__init__.py)
- [frontend/src/index.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/index.tsx)
- [frontend/src/scenes](https://github.com/PostHog/posthog/blob/main/frontend/src/scenes)
- [Dockerfile](https://github.com/PostHog/posthog/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/PostHog/posthog/blob/main/docker-compose.yml)
- [helm/posthog](https://github.com/PostHog/posthog/blob/main/helm/posthog)
- [cli/src/main.rs](https://github.com/PostHog/posthog/blob/main/cli/src/main.rs)
- [plugin_server/src/main.rs](https://github.com/PostHog/posthog/blob/main/plugin_server/src/main.rs)
- [.github/workflows](https://github.com/PostHog/posthog/blob/main/.github/workflows)

</details>

# 前后端实现、数据库与部署运维

## 总体架构与定位

PostHog 是开源的一体化产品分析平台，提供事件分析、特性开关、A/B 实验、会话回放、调查、CDP 等能力，整个仓库是一个 monorepo，由 Django/Python 后端、React/TypeScript 前端、Rust 编写的多个服务（plugin server、CLI、CDN worker 等）以及 Kubernetes Helm Chart 部署包组成，社区反馈中的"产品引导（#25726）"和"Java Feature Flags（#16419）"等多个高互动议题，都构建在这套统一的架构之上。

- 后端核心由 Django 承担业务编排、权限管理与 API 暴露，并通过 Kafka 在高吞吐事件路径上解耦 ingestion 与消费处理。
- 高基数事件数据保存在 ClickHouse（列式存储），元信息与权限数据保存在 PostgreSQL，二者通过统一的 Django ORM 抽象结合使用。
- 前端是独立的 TypeScript 应用，从 `frontend/src/index.tsx` 挂载，使用 Kea 作为状态管理框架，并按 scene 拆分业务模块。
- 部署方面提供 Dockerfile、`docker-compose.yml`（本地一键起栈）以及 `helm/posthog/` 下的生产级 Helm Chart。

## 后端实现与 API

后端目录 `posthog/api/` 暴露了大量基于 Django REST Framework 的 API；事件采集与查询分别走 ClickHouse 和 PostgreSQL 两种后端。

- API 路由与团队/权限校验在 `posthog/api/__init__.py:1-80` 注册，DRF 视图通过 mixin 统一注入团队隔离。`资料来源：[posthog/api/__init__.py:1-80]()`
- Django 模型层位于 `posthog/models/`，使用 ORM 建模组织、用户、项目、Feature Flag、Survey、SQL Folder 等元数据，并在 `posthog/models/__init__.py:1-60` 集中导出。`资料来源：[posthog/models/__init__.py:1-60]()`
- 事件写入与分析查询走 `posthog/clickhouse/`：通过 `client.execute` 直接查询，由 `posthog/clickhouse/__init__.py:1-120` 中的连接池与重试包装统一抽象。`资料来源：[posthog/clickhouse/__init__.py:1-120]()`
- 异步任务通过 Celery + Kafka 消费进程，以及 Rust 编写的 plugin server 协同；`plugin_server/src/main.rs:1-200` 启动 HTTP 端、加载插件并路由到 `process_event`。`资料来源：[plugin_server/src/main.rs:1-200]()`
- 配置集中在 `posthog/settings.py`，根据环境变量切换数据库、缓存、域名、e-mail、特性开关等。`资料来源：[posthog/settings.py:1-150]()`

## 前端实现

`frontend/` 是一个用 Vite 构建的 React + TypeScript 应用，使用 Kea 作为状态管理内核。

- 应用入口 `frontend/src/index.tsx:1-80` 负责注册根节点、错误边界、初始 store hydrate，并挂载 React Router。`资料来源：[frontend/src/index.tsx:1-80]()`
- 业务按 `frontend/src/scenes/` 划分，例如 `scenes/insights/`、`scenes/feature-flags/`、`scenes/replay/`，每个 scene 内部组织路由、组件、状态逻辑，便于领域自治。
- 公共能力集中在 `frontend/src/lib/`，提供 `api/`（fetch 封装，统一错误提示与 traceparent）、`components/`（TaxonomicFilter 等基础组件）与 `lemon-ui/`（Lemon 设计体系）。
- 国际化以 i18next 抽象 + `frontend/src/scenes/.../locales/*.json` 形式提供，PostHog 默认支持多语言 UI。
- 与后端的交互通过统一的 `api.ts` 风格封装，错误全局通过 `lib/components/ErrorPrimitives/` 抛出。

## 数据库与数据建模

PostHog 使用"双数据库"体系，让擅长事务的 PostgreSQL 与擅长分析的 ClickHouse 各司其职。

- PostgreSQL：通过 `posthog/models/` 下的 Django Model 建表，承载租户/权限、Feature Flag 定义、Survey、Insights 元数据、SQL Folder 等关系性强、QPS 低的元信息。
- ClickHouse：所有原始事件落到 `posthog/clickhouse/` 客户端管理的本地表，并通过 Distributed 表、分区、TTL、物化视图支撑高基数与时间序列查询；Django 异步任务会把 `plugin_server` 输出回流写入 PG。
- 迁移：Django migrations 在 `posthog/migrations/` 维护；ClickHouse DDL 由 `posthog/clickhouse/migrations/` 下的 SQL 脚本管理，可在新建集群时复现。
- 缓存：Redis 同时承载会话、Feature Flag 高速路径与 queryset 缓存，详见 `posthog/settings.py` 中 CACHES 配置段。`资料来源：[posthog/settings.py:200-260]()`

## 部署与运维

PostHog 同时支持本地一键启动与生产级 Kubernetes 部署。

- `Dockerfile` 使用多阶段构建：先构建前端、再编译 plugin server 等 Rust 组件，最后打包到 Python 运行时，输出可分发的单一镜像。`资料来源：[Dockerfile:1-80]()`
- `docker-compose.yml` 编排 Postgres、ClickHouse、Redis、Kafka、Plugin Server、Django Web、前端 dev server 等容器，是贡献者最常用的本地入口。`资料来源：[docker-compose.yml:1-120]()`
- 生产部署以 `helm/posthog/` 为核心：包含 Deployment、StatefulSet（ClickHouse、Postgres）、Service、Ingress、HPA、PodDisruptionBudget、网络策略等模板，可由 ArgoCD/Flux 等 GitOps 工具直接消费。
- CI/CD：`.github/workflows/` 提供了 lint、unit test、镜像构建、Helm chart 验证、SDK 发布（Changesets）等流水线；Rust CLI 与 agent skills 通过独立 release workflow 发布，社区近期可见 `posthog-cli/v0.7.24` 与 `agent-skills-v0.190.0` 等多个 tag。
- 可观测性：内置 Prometheus 指标端点与 Sentry 集成，由 `posthog/settings.py` 中的 `SENTRY_DSN`、`PROMETHEUS_MULTIPROC_DIR` 等环境开关激活；CLI 通过 `cli/src/main.rs:1-100` 的 clap 子命令暴露特性开关调试、追踪回放捕获等运维能力。`资料来源：[cli/src/main.rs:1-100]()`

| 层级 | 主要技术栈 | 关键仓库路径 | 关键职责 |
|---|---|---|---|
| 后端 | Django + DRF + Celery + Kafka | `posthog/`、`plugin_server/` | 业务逻辑、API、事件消费、插件执行 |
| 前端 | React + TypeScript + Kea | `frontend/src/` | UI、状态管理、API 客户端 |
| 数据库 | PostgreSQL + ClickHouse + Redis | `posthog/models/`、`posthog/clickhouse/` | 元数据与分析数据存储 |
| 部署运维 | Docker + Helm + GitHub Actions | `Dockerfile`、`docker-compose.yml`、`helm/posthog/`、`.github/workflows/` | 本地开发、容器化、Kubernetes 编排、CI/CD |

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：PostHog/posthog

摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: 0.7.24 — 2026-06-16。

## 1. 安装坑 · 失败模式：installation: 0.7.24 — 2026-06-16

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: 0.7.24 — 2026-06-16
- 对用户的影响：Upgrade or migration may change expected behavior: 0.7.24 — 2026-06-16
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/posthog-cli/v0.7.24 | 0.7.24 — 2026-06-16

## 2. 安装坑 · 失败模式：installation: Renovate: Dependency Status

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Renovate: Dependency Status
- 对用户的影响：Developers may fail before the first successful local run: Renovate: Dependency Status
- 证据：failure_mode_cluster:github_issue | https://github.com/PostHog/posthog/issues/54967 | Renovate: Dependency Status

## 3. 安装坑 · 来源证据：Renovate: Dependency Status

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Renovate: Dependency Status
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/PostHog/posthog/issues/54967 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/PostHog/posthog | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/PostHog/posthog | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/PostHog/posthog | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/PostHog/posthog | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/PostHog/posthog | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/PostHog/posthog | release_recency=unknown

## 10. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.187.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.187.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.187.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.187.0 | Agent skills agent-skills-v0.187.0

## 11. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.188.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.188.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.188.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.188.0 | Agent skills agent-skills-v0.188.0

## 12. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.189.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.189.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.189.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.189.0 | Agent skills agent-skills-v0.189.0

## 13. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.190.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.190.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.190.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.190.0 | Agent skills agent-skills-v0.190.0

## 14. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.541.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.541.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.541.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.541.0 | Agent skills agent-skills-v0.541.0

## 15. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.542.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.542.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.542.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.542.0 | Agent skills agent-skills-v0.542.0

## 16. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.543.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.543.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.543.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.543.0 | Agent skills agent-skills-v0.543.0

## 17. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.544.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.544.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.544.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.544.0 | Agent skills agent-skills-v0.544.0

## 18. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.545.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.545.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.545.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.545.0 | Agent skills agent-skills-v0.545.0

## 19. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.546.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.546.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.546.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.546.0 | Agent skills agent-skills-v0.546.0

## 20. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.547.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.547.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.547.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.547.0 | Agent skills agent-skills-v0.547.0

## 21. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.548.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.548.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.548.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.548.0 | Agent skills agent-skills-v0.548.0

## 22. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.549.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.549.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.549.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.549.0 | Agent skills agent-skills-v0.549.0

## 23. 维护坑 · 失败模式：maintenance: Agent skills agent-skills-v0.550.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.550.0
- 对用户的影响：Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.550.0
- 证据：failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.550.0 | Agent skills agent-skills-v0.550.0

<!-- canonical_name: PostHog/posthog; human_manual_source: deepwiki_human_wiki -->