PostHog 部署完整指南:单机三步起栈,一路打通到生产级自托管

PostHog 部署完整指南:单机三步起栈,一路打通到生产级自托管

【免费下载链接】posthog :hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP. 【免费下载链接】posthog 项目地址: https://gitcode.com/GitHub_Trending/po/posthog

PostHog 是一个把事件分析、会话回放、特性标志与错误追踪装进同一个平台的开源产品分析工具。本文手把手带你完成 PostHog 部署:30 秒选对路线,3 条命令拉起全套服务,再看懂内部数据流向和生产自检,拿回一个开箱即用的实例。

部署路线对比:30 秒对号入座

不同的使用目的对应不同的启动方式,先按下表对号,再走后面的最短路径:

方式最适合前提条件建议资源
Hobby 单机(docker-compose.hobby.yml)团队正式自用、对外提供服务一台带域名的 Linux 机器8GB 内存起
本地开发栈(docker-compose.dev.yml)读代码、调功能、跑测试本机装好 Docker8GB 内存
官方托管 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 评估服务

事件从产生到可查询的完整旅程:

mermaid

💡 排障定位法:界面没数据时,就沿着"采集 → 队列 → 消费 → 落库"四段逐段查日志。

能力试跑:从第一个洞察到进阶查询

服务就绪后,浏览器打开 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 的联动:

PostHog部署实例中的异常追踪界面

生产加固与自检:放心扩容的路径

外部化与扩容

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%

症状式排障

症状:容器反复重启或健康检查一直不通过

  1. 看 docker compose -f docker-compose.hobby.yml ps,找到红色容器
  2. 用 docker compose -f docker-compose.hobby.yml logs web 抓最近报错
  3. 核对 80/443 端口是否被占用、DOMAIN 是否已有 A 记录指向本机
  4. 用 free -h 确认可用内存 ≥ 8GB

症状:事件发送成功,界面却查不到数据

  1. 确认 Kafka 消费者无积压、ingestion-general 容器状态正常
  2. 翻摄入消费者日志,看是否有反序列化或限流报错
  3. 直连 ClickHouse 查目标表,判断是"没写进去"还是"查询口径不对"

上线验收清单

✅ 验收标准:/_health 返回 200;可完成账户初始化并建项目;测试事件出现在 Insights;能播放一条会话回放。四项全过即视为部署成功。

收尾:单机到底能带走什么

  • 一份编排管全栈:15+ 服务收敛进一个 compose 文件,启停、升级、回滚各是一条命令的事
  • 存储与计算解耦:Postgres、ClickHouse、对象存储各自独立成卷,任何一件都能单独外移,不停机迁数据
  • 观测能力自带:/_health、容器健康检查、结构化日志一应俱全,接监控几乎零改造
  • 单机边界明确:Hobby 版按每月约 10 万事件设计,超线前先把数据库外部化,比事后救火便宜得多

当事件量开始爬升,这套配置可以从单机平滑演进为外部数据库加多副本 web——同一份 .env,跟着业务一起长大。

【免费下载链接】posthog :hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP. 【免费下载链接】posthog 项目地址: https://gitcode.com/GitHub_Trending/po/posthog

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值