PostHog 部署完整指南:单机三步起栈,一路打通到生产级自托管
PostHog 是一个把事件分析、会话回放、特性标志与错误追踪装进同一个平台的开源产品分析工具。本文手把手带你完成 PostHog 部署:30 秒选对路线,3 条命令拉起全套服务,再看懂内部数据流向和生产自检,拿回一个开箱即用的实例。
部署路线对比:30 秒对号入座
不同的使用目的对应不同的启动方式,先按下表对号,再走后面的最短路径:
| 方式 | 最适合 | 前提条件 | 建议资源 |
|---|---|---|---|
| Hobby 单机(docker-compose.hobby.yml) | 团队正式自用、对外提供服务 | 一台带域名的 Linux 机器 | 8GB 内存起 |
| 本地开发栈(docker-compose.dev.yml) | 读代码、调功能、跑测试 | 本机装好 Docker | 8GB 内存 |
| 官方托管 Cloud | 不想碰运维、快速验证业务 | 一个邮箱 | 无 |
Hobby 单机版是本文主角:一份编排文件拉齐 15+ 个协同容器,官方定位是支撑每月约 10 万条事件的规模,是单机自托管里省心程度最高的方案。
最短启动路径:3 条命令拉齐全栈
第一步:拿回仓库代码
git clone https://gitcode.com/GitHub_Trending/po/posthog
cd posthog
第二步:写入最小配置
整个栈只需要 3 个变量:对外域名、应用密钥、加密盐。Caddy 会基于域名自动签发 TLS 证书,无需手工配证书。
cat > .env << 'EOF'
DOMAIN=ph.example.com
POSTHOG_SECRET=$(openssl rand -hex 32)
ENCRYPTION_SALT_KEYS=$(openssl rand -hex 32)
EOF
第三步:启动并等待就绪
编排文件就是 docker-compose.hobby.yml,一条命令全部拉起:
docker compose -f docker-compose.hobby.yml up -d
首次启动要跑数据库迁移和签发证书,预留 5-10 分钟。期间可以循环确认健康状态:
curl -s https://ph.example.com/_health
🚀 起步口诀:改好 .env,一条 up 命令,剩下的交给 _health 轮询。
内部机制拆解:每条事件落在哪
Hobby 栈看似庞杂,职责其实可以分成四组,记住它们就足够排障:
- proxy(Caddy):统一 80/443 入口,按路径把请求分发到 web、capture 等后端
- web / worker:Django 控制台与后台任务,负责查询、报表和账户体系
- capture / replay-capture / capture-logs:Rust 写的高性能采集端点,事件、录像、日志各走各的通道
- kafka + zookeeper:内部消息队列,把采集与消费解耦
- ingestion-*:Node 侧消费者群,把队列里的数据加工后写入存储
- clickhouse:列式分析库,所有查询的底座
- db(PostgreSQL):配置、用户、特性标志等元数据
- objectstorage + seaweedfs:对象存储,存放会话录像等大文件
- feature-flags / hypercache-server:特性标志与问卷的独立 Rust 评估服务
事件从产生到可查询的完整旅程:
💡 排障定位法:界面没数据时,就沿着"采集 → 队列 → 消费 → 落库"四段逐段查日志。
能力试跑:从第一个洞察到进阶查询
服务就绪后,浏览器打开 https://ph.example.com,完成管理员账户初始化并创建第一个项目。
基础验证:在项目设置里找到 API Key,往采集端点发一条测试事件:
curl -X POST https://ph.example.com/capture/ \
-H "Content-Type: application/json" \
-d '{"api_key":"<API_KEY>","event":"test_event","distinct_id":"user_123"}'
等一两分钟刷新 Insights,test_event 出现在图表里即说明全链路通了。
进阶验证:同一份数据可以换三种姿势消费——Insights 界面拖拽出趋势与漏斗、HogQL 查询框写 SQL 做自定义聚合、错误追踪里点进任意异常查看关联的会话时间线。下图是部署实例中异常追踪的会话视图,可以直观看到堆栈、属性与三个 Tab 的联动:
生产加固与自检:放心扩容的路径
外部化与扩容
Hobby 版默认把所有存储都放在本地卷,生产上建议按压力逐件外移:
- PostgreSQL:换成托管 RDS,
db服务改为指向外部地址,本地卷只做备份 - 对象存储:换成 S3 兼容存储,录像和大文件不再挤占本地磁盘
- web 副本:web 无状态,可先加副本扛并发,再考虑 ClickHouse 独立扩容
- 数据卷:postgres-data、clickhouse-data、seaweedfs 三个卷纳入定时备份,这是唯一"丢了不可恢复"的部分
关键自检阈值
| 自检项 | 查看方式 | 告警阈值 |
|---|---|---|
| Web 健康状态 | /_health 接口 | 10 分钟内未返回 200 |
| ClickHouse 内存占用 | docker stats | 持续高于 80% |
| Kafka 消费延迟 | 消费组 lag | 持续 60 秒以上不回落 |
| PostgreSQL 连接数 | 数据库监控 | 持续高于 150 |
| 磁盘使用率 | 数据卷所在盘 | 高于 85% |
症状式排障
症状:容器反复重启或健康检查一直不通过
- 看
docker compose -f docker-compose.hobby.yml ps,找到红色容器 - 用
docker compose -f docker-compose.hobby.yml logs web抓最近报错 - 核对 80/443 端口是否被占用、
DOMAIN是否已有 A 记录指向本机 - 用
free -h确认可用内存 ≥ 8GB
症状:事件发送成功,界面却查不到数据
- 确认 Kafka 消费者无积压、
ingestion-general容器状态正常 - 翻摄入消费者日志,看是否有反序列化或限流报错
- 直连 ClickHouse 查目标表,判断是"没写进去"还是"查询口径不对"
上线验收清单
✅ 验收标准:/_health 返回 200;可完成账户初始化并建项目;测试事件出现在 Insights;能播放一条会话回放。四项全过即视为部署成功。
收尾:单机到底能带走什么
- 一份编排管全栈:15+ 服务收敛进一个 compose 文件,启停、升级、回滚各是一条命令的事
- 存储与计算解耦:Postgres、ClickHouse、对象存储各自独立成卷,任何一件都能单独外移,不停机迁数据
- 观测能力自带:
/_health、容器健康检查、结构化日志一应俱全,接监控几乎零改造 - 单机边界明确:Hobby 版按每月约 10 万事件设计,超线前先把数据库外部化,比事后救火便宜得多
当事件量开始爬升,这套配置可以从单机平滑演进为外部数据库加多副本 web——同一份 .env,跟着业务一起长大。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



