PostHog本地开发环境全栈Docker部署指南

概述

PostHog是一款开源的现代产品分析平台，为开发者提供用户行为分析、会话回放、功能标志等能力。本文重点介绍如何使用Docker Compose配置完整的PostHog本地开发环境，帮助开发者快速搭建包含所有依赖服务的开发环境。

核心服务架构

PostHog的本地开发环境由多个相互依赖的服务组成，主要分为以下几类：

1. 基础数据存储服务：PostgreSQL、Redis、ClickHouse
2. 消息队列系统：Kafka + Zookeeper
3. 应用服务：Web服务、Worker、Capture服务等
4. 辅助服务：邮件开发服务器、对象存储、Webhook测试器等
5. 可观测性工具：OpenTelemetry Collector + Jaeger

详细服务配置解析

1. 数据存储服务

PostgreSQL (db)

• 端口映射：5432:5432
• 作为主数据库存储用户、团队等核心数据

Redis

• 端口映射：6379:6379
• 用于缓存和临时数据存储

ClickHouse

• 多端口映射：8123(HTTP)、9000(Native)、9440(HTTPS)、9009(Interserver)
• 挂载了多个配置文件：
  • 主配置文件config.xml
  • 默认配置default.xml
  • 用户配置users-dev.xml
  • UDF配置user_defined_function.xml
• 依赖Kafka和Zookeeper服务

2. 消息队列系统

Zookeeper

• 为Kafka提供协调服务

Kafka

• 端口映射：9092:9092
• 作为事件总线处理分析数据

3. 核心应用服务

Web服务

• 端口映射：8000:8000
• 挂载本地代码目录实现热更新
• 依赖数据库、Redis、ClickHouse和Kafka
• 配置了调试模式和本地JS资源路径

Worker服务

• 处理后台异步任务
• 同样挂载本地代码目录
• 配置了调试模式和插件服务器空闲设置

Capture服务

• 处理事件捕获
• 依赖Redis和Kafka

Replay-Capture服务

• 处理会话回放数据
• 依赖Redis和Kafka

4. 辅助服务

对象存储(ObjectStorage)

• 模拟S3兼容存储
• 端口映射：19000(API)、19001(管理)

邮件开发服务器(Maildev)

• 端口映射：1080(Web界面)、1025(SMTP)
• 方便测试邮件功能

Webhook测试器

• 端口映射：2080
• 用于测试出站Webhook

5. 工作流与监控

Temporal工作流引擎

• 端口映射：7233(API)、8081(UI)
• 用于管理长时间运行的工作流

OpenTelemetry Collector

• 收集分布式追踪数据
• 与Jaeger集成

Jaeger

• 提供分布式追踪可视化

开发环境特点

1. 全容器化：所有服务都运行在容器中，与主机环境隔离
2. 调试友好：多数服务配置了DEBUG=1环境变量
3. 代码热加载：Web和Worker服务挂载本地代码目录
4. 完整依赖：包含开发所需的所有依赖服务
5. 可观测性：内置OpenTelemetry和Jaeger支持

使用建议

1. 开发时重点关注web、worker和plugins服务，它们直接运行应用代码
2. 利用maildev和webhook-tester调试邮件和Webhook功能
3. 通过Jaeger界面分析请求链路
4. 修改ClickHouse配置时注意对应的挂载文件位置
5. 数据库迁移通过migrate服务处理

这套配置为PostHog开发者提供了完整的本地环境，可以模拟生产环境的绝大多数功能，同时保持开发调试的便利性。