PostHog 手动开发环境搭建完全指南从外部服务到hogli start的逐步实战【免费下载链接】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.项目地址: https://gitcode.com/GitHub_Trending/po/posthogPostHog 是一个庞大的单体仓库monorepo前端React/Vite/Kea、后端Django、事件流Kafka/ClickHouse、工作流编排Temporal、CDP 与 Node.js 服务等组件需要协同运行。本文基于仓库内的 manual-dev-setup.md 手册系统讲解在不依赖 Flox 自动环境的前提下如何手动从零搭建一套可用的 PostHog 本地开发环境涵盖外部服务启动、前端/Node.js/Django 三端依赖准备、数据库迁移、全栈启动与日常开发技巧并给出仓库内的源码与配置佐证。重要提示仓库手册明确指出本文对应的手动流程已标记为 deprecated弃用仓库现在推荐使用基于 Flox 的即时环境搭建见 developing-locally。但手动流程依然是理解 PostHog 各组件依赖关系、排查环境问题、以及在不使用 Flox 的场景下搭建环境的宝贵路线图。本文所有命令与配置均以当前仓库实际内容为准。1. 启动外部服务基础设施先行PostHog 的开发环境依赖一整套外部基础设施。在手动搭建流程中第一步就是通过 Docker Compose 把它们全部拉起来。1.1 配置/etc/hosts打通容器间主机名解析PostHog 的 ClickHouse 与 Kafka 数据服务需要互相通信为此必须把以下主机名映射到本机echo 127.0.0.1 kafka clickhouse clickhouse-coordinator objectstorage | sudo tee -a /etc/hosts echo ::1 kafka clickhouse clickhouse-coordinator objectstorage | sudo tee -a /etc/hosts两条命令分别写入 IPv4 与 IPv6 的解析记录。这些主机名在 docker-compose.dev.yml 的 Caddy 代理配置extra_hosts: - web:host-gateway等以及 ClickHouse 的 Kafka 引擎配置docker-compose.base.yml 中 ClickHouse 服务设置了KAFKA_HOSTS: kafka:9092中都会被引用。Podman 用户注意如果使用的是 4.1 及以上版本的 Podman 而非 Docker宿主机/etc/hosts会默认作为容器的基础 hosts 文件Docker 则使用容器自身/etc/hosts可能导致 ClickHouse 容器内主机名解析失败。解决办法是在containers.conf中设置base_hosts_filenone。1.2 启动 Docker Compose 开发栈仓库根目录提供了专为本地开发设计的 Compose 文件注意其头注释明确写明used ONLY for local developmentdocker compose -f docker-compose.dev.yml up该文件通过extends继承 docker-compose.base.yml 中的基础服务定义并覆盖端口映射、资源限制与开发参数。启动后docker ps应能看到类似下面的一整套服务版本以当前仓库配置为准与手册中的历史版本略有差异容器镜像当前仓库实际配置暴露端口用途posthog-db-1postgres:15.12-alpine5432主关系数据库用户、组织、功能开关等posthog-clickhouse-1clickhouse/clickhouse-server:26.6.2.1588123/9000/9009/9440/8443分析型列式数据库事件、漏斗等posthog-kafka-1redpandadata/redpanda:v25.1.99092事件流中间件兼容 Kafka 协议posthog-zookeeper-1zookeeper:3.7.02181Kafka 协调Redpanda 与 ClickHouse 均依赖posthog-redis-1redis:7.2-alpine6379缓存与任务队列posthog-maildev-1maildev/maildev:2.0.51025/1080本地邮件捕获与预览posthog-objectstorage-1seaweedfs19000-19001对象存储会话录制、批量导出等posthog-elasticsearch-1elasticsearch:7.16.29200Temporal 可视化的检索后端posthog-temporal-1temporalio/auto-setup:1.20.07233工作流编排引擎posthog-temporal-ui-1temporalio/ui:2.10.38081Temporal 管理界面手册中的示例docker ps输出展示的 Kafka 镜像为bitnami/kafka:2.8.1-debian-10-r99而当前仓库的 docker-compose.base.yml 已将 Kafka 服务替换为redpandadata/redpanda:v25.1.9Redpanda 兼容 Kafka 协议且 dev 栈通过kafka-init服务使用 docker/kafka/topics.txt 预创建全部 topic。这也解释了手册中Kafka 是唯一 x86 容器、在 ARM 上可能随机段错误的提示——Redpanda 在 Apple Silicon 上运行更稳定。1.3 验证服务健康状态启动后建议逐项确认服务就绪# 查看容器列表与状态 docker ps # 各服务的就绪日志-n 1 只看最后一行 docker logs posthog-db-1 -n 1 # 期望database system is ready to accept connections docker logs posthog-redis-1 -n 1 # 期望Ready to accept connections docker logs posthog-clickhouse-1 -n 1 # 期望Saved preprocessed configuration ... # ClickHouse 日志写入文件而非 stdout出问题时直接查看 docker exec posthog-clickhouse-1 cat /var/log/clickhouse-server/clickhouse-server.log docker exec posthog-clickhouse-1 cat /var/log/clickhouse-server/clickhouse-server.err.logClickHouse 容器日志中可能出现get_mempolicy: Operation not permitted提示手册说明这不会影响应用启动。如需彻底确认 ClickHouse 可用可进入容器执行一条基本查询docker exec -it posthog-clickhouse-1 bash clickhouse-client --query SELECT 1常见启动报错排查报错原因与解法Error while fetching server API version: 500 Server Error ...Docker Engine 未运行先启动 Docker/OrbStackExit Code 137容器内存耗尽在 OrbStack 设置中增加 RAM 配额Ports are not available: exposing port TCP 0.0.0.0:5432本机已有 Postgres 占用 5432 端口用lsof -i :5432定位并停掉Permission deniedLinux参考 Docker 官方文档配置非 root 用户运行或改用支持 rootless 的 Podman手册对 Linux 用户给出了停用本机 Postgres 服务的建议流程sudo service postgresql stop sudo systemctl disable postgresql.service sudo lsof -i :5432 sudo kill -9 sudo lsof -t -i :54321.4 本机安装 Postgres 客户端psycopg2 编译依赖即便 Postgres 服务运行在 Docker 内本机仍需要一份 Postgres11的 CLI 工具与开发库/头文件——pip/uv安装psycopg2时需要它们完成编译。macOSbrew install postgresql注意这会同时安装服务端与工具但安装后不要启动服务以免与 Docker 容器争抢 5432 端口。Debian 系 Linux只装客户端与驱动不装服务端sudo apt install -y postgresql-client postgresql-contrib libpq-dev不同发行版包名可能不同例如postgres、postgres-server、libpostgres-dev请以各自发行版仓库为准。2. 准备前端nvm pnpm Kea 类型生成2.1 安装 nvm 与固定 Node 版本前端依赖 nvm 管理 Node 版本macOS 可用brew install nvm其他平台按官方安装脚本执行fish shell 用户可改用 nvm.fish。安装后务必把 nvm 加入$PATH否则命令行会回落到系统 Node.js 版本。然后从仓库根目录读取.nvmrc安装并激活 PostHog 生产环境使用的 Node 版本——当前仓库固定为v24.13.0nvm install # nvm 会读取仓库根目录的 .nvmrc nvm use2.2 启用 pnpmCorepackPostHog 使用 pnpm 管理前端依赖版本通过根目录 package.json 的packageManager字段锁定当前为pnpm10.29.3。用 Corepack 一键激活corepack enable pnpm --version # 验证激活的版本2.3 安装依赖并生成 Kea 类型pnpm i随后生成前端大量使用的 Kea 状态管理逻辑的类型定义pnpm --filterposthog/frontend typegen:writeKea 是 PostHog 前端的状态管理框架其kea()逻辑会在运行时动态生成 reducer/selector 等TypeScript 无法静态推导因此必须借助 typegen 工具把类型写入.kea-typegen相关文件。如果只想迭代某一个 logic 文件用pnpm --filterposthog/frontend typegen:file path-to-logic-filepath可以是绝对路径、仓库相对路径如frontend/src/scenes/foo/fooLogic.ts或前端相对路径如src/scenes/foo/fooLogic.ts。首次运行 typegen 可能陷入死循环此时按CtrlC取消git reset --hard丢弃所有改动后重新运行pnpm typegen:write第二轮生成完成后可能还需要再丢弃一次改动。3. 准备 Node.js 服务brotli Rust 工具链PostHog 的部分 Node.js 服务CDP 工作流、会话录制、日志摄取等见 hogli.yaml 中 nodejs 单元的说明在构建时需要系统库与 Rust 工具链。macOSbrew install brotli rustup rustup default stable rustup-init # 选择 1 使用默认安装Debian 系 Linuxsudo apt install -y brotli curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # 选择 1 使用默认安装然后安装 Node.js 服务的全部依赖服务本体稍后统一启动pnpm --filterposthog/nodejs install常见报错与解法报错解法ld: symbol(s) not found for architecture arm64OpenSSL 构建标志来自错误位置。执行export CPPFLAGS-I/opt/homebrew/opt/openssl/include与export LDFLAGS-L/opt/homebrew/opt/openssl/lib后重装import gyp # noqa: E402缺少python-setuptoolsmacOS 上brew install python-setuptoolsNode.js 服务启动异常进入nodejs目录执行pnpm rebuild与pnpm i重建原生模块4. 准备 Django 后端SAML 依赖 Python 3.13 uv4.1 SAML 相关的系统依赖SAML 认证依赖xmlsec需要系统级库支持macOSbrew install libxml2 libxmlsec1 pkg-configDebian 系 Linuxsudo apt install -y libxml2 libxmlsec1-dev libffi-dev pkg-config4.2 安装 Python 3.13macOSbrew install python3.13Debian 系 Linux使用 deadsnakes PPAsudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install python3.13 python3.13-venv python3.13-dev -y手册特别强调虚拟环境外请始终使用python3而非python后者在某些系统上仍指向 Python 2.x若通过 deadsnakes 安装了多个 Python 3 版本请使用python3.13精确指定。也可以用 pyenv 管理多版本。4.3 安装 uv 并同步依赖uv是 PostHog 后端首选的 Python 虚拟环境与依赖管理工具安装后任何pip命令都可以前缀uv提速。一条命令完成建环境与装依赖uv sync该命令读取根目录的 pyproject.toml 与uv.lock。若创建环境时出现Failed to parse警告与pyproject.toml解析有关只要末尾出现Activate with:行即说明环境创建成功。随后激活虚拟环境# bash/zsh 等 source .venv/bin/activate # fish source .venv/bin/activate.fishApple Silicon Mac 用户首次安装 Python 包时必须指定自定义 OpenSSL 头文件用于编译grpcio与psycopg2brew install openssl CFLAGS-I /opt/homebrew/opt/openssl/include $(python3.13-config --includes) LDFLAGS-L /opt/homebrew/opt/openssl/lib GRPC_PYTHON_BUILD_SYSTEM_OPENSSL1 GRPC_PYTHON_BUILD_SYSTEM_ZLIB1 uv sync此后只要这两个包未变更直接uv sync即可。若出现ERROR: Could not build wheels for xmlsec需要核对 xmlsec 的已知编译问题。5. 准备数据库运行迁移脚本此时后端代码已就绪Postgres 与 ClickHouse 容器也在运行但两者都是空白库需要执行迁移创建全部表结构cargo install sqlx-cli # 若尚未安装 DEBUG1 ./bin/migrate注意./bin/migrate是仓库根目录下的 shell 脚本bin/migrate并非 Django 自带的manage.py migrate的别名。5.1bin/migrate到底做了什么从源码看bin/migrate 是一个聚合迁移入口按 scope 分发执行clickhouse后台并行运行python manage.py migrate_clickhouse与python manage.py sync_replicated_schemapostgres运行 Djangomanage.py migrate --noinput内置最多 10 次重试MIGRATE_MAX_RETRIES重试间隔指数退避默认从 3 秒起、倍增系数 2并通过report_migration_metric上报耗时与尝试次数若设置了POSTHOG_POSTGRES_DIRECT_HOST则走default_direct直连绕过 PgBouncer 以支持lock_timeoutproduct databases / persons / async / cyclotron / behavioral-cohorts / flags-read-store / temporal-schedules / tasks-oauth等更多 scope各自对应不同的数据库与迁移工具如 Rust 侧的migrate-cyclotron-node、migrate-behavioral-cohorts、migrate-flags-read-store。在本地开发DEBUG1下persons 迁移会先--ensure-database确保 persons 库存在再执行temporal-schedules 与 tasks-oauth 等生产专用步骤会被跳过。5.2 常见迁移报错报错解法fe_sendauth: no password supplied数据库设置了密码但DATABASE_URL未带用户密码。执行export DATABASE_URLpostgres://posthog:posthoglocalhost:5432/posthogpsycopg2相关错误ARM 机器参考 psycopg2 官方 issue 中针对 ARM 的编译/安装步骤迁移连不上库确保容器正在运行前台窗口或独立终端迁移与容器是两回事6. 启动 PostHog一条命令拉起全部服务6.1hogli start基础设施、三端依赖与迁移都就绪后启动整个 PostHog后端、worker、Node.js 服务、前端同时运行hogli starthogli是仓库根目录 hogli.yaml 定义的统一开发者命令行工具。从配置看start命令会拉起 django、frontend、celery、nodejs、ingestion、postgresql、redis、kafka、clickhouse、temporal 等全部服务单元。它内部调用bin/start脚本通过 phrocsPostHog 自研的进程运行器基于 Bubble Tea 构建见 tools/phrocs/README.md把开发进程集中在一个终端窗口内管理支持tab切换焦点、r重启进程、q退出等快捷键。bin/start还承担了环境预检职责bin/start如果.env.local中存在 1Password 引用op://前缀会自动通过op run --env-file解析密钥同时用flock加独占锁防止重复启动多个 worktree 共享名为posthog的 Compose 项目。如需按需定制服务集合用交互式向导生成配置文件之后hogli start会自动采用hogli dev:setupmacOS/Linux 用户首次运行hogli start时会自动安装 phrocs通过 Homebrew Tapposthog/tap或仓库内源码构建。手册提示若出现Configuration property enable.ssl.certificate.verification not supported in this build: OpenSSL not available at build time说明环境中 OpenSSL 版本不对需设置对应的环境变量后重新hogli start。6.2 验证与演示数据启动完成后打开http://localhost:8010查看应用8010 端口由 docker-compose.dev.yml 中 proxy 服务的 Caddy 容器映射到内部 Django 的 8000 端口Caddy 还按路径把/e、/i/v0/*等流量反向代理给 capture、feature-flags、plugins 等独立服务。首次启动若报layout.html is not defined请等待前端编译完成再刷新。为让新实例获得可直接操作的演示数据运行DEBUG1 ./manage.py generate_demo_data该命令是仓库内的 Django 管理命令generate_demo_data.py支持通过--help查看参数。首次启动时也可用内置测试账号登录用户名testposthog.com密码12345678。7. 日常开发项目结构、分支与常用命令环境就绪后你可以在 http://localhost:8010 上看到 PostHog 应用并随意修改代码Django 与 Vite 均带热重载。仓库结构介绍可参考 project-structure提交变更时请基于master新建分支。基于 hogli.yaml日常开发还可使用以下高频命令类别命令说明服务控制hogli up -d/hogli stop后台模式启动 / 停止开发进程Docker 容器保持运行服务控制hogli docker:services:down停止全部 Docker 基础设施服务服务控制hogli docker:services:remove停止服务并清除全部数据卷完全重置健康检查hogli doctor开发环境快速体检健康检查hogli doctor:ports预检开发栈所需宿主机端口数据库hogli db:pg/hogli db:ch连接本地 Postgres / ClickHouse数据库hogli db:dump/hogli db:restorePostgres 备份与恢复迁移hogli migrations:run并行运行全部迁移ClickHouse、Postgres、async迁移hogli migrations:check/hogli migrations:status校验迁移就绪 / 查看迁移差异演示数据hogli dev:demo-data生成演示数据等价于python manage.py generate_demo_data测试hogli test自动检测测试类型Python/Jest/Playwright/Rust/Go并运行代码质量hogli lint/hogli format运行 Python JS/TS 的 lint / 格式化构建hogli build运行代码生成流水线含智能变更检测状态hogli dev:reset完整重置清卷、迁移、加载演示数据、同步开关8. 走向推荐路径Flox 即时环境手册开头明确建议新开发者改用 Flox 方案developing-locally其核心优势是所有开发者获得完全一致的、可复现的工具与依赖版本无需逐项手动安装。hogli.yaml的 services 元数据也印证了这一点——flox 被描述为管理可复现开发环境所有开发者获得完全相同的工具与依赖版本。手动流程虽然繁琐但每一步都对应着 PostHog 真实的组件依赖/etc/hosts对应容器间服务发现、Postgres 客户端对应psycopg2编译、brotli/Rust 对应 Node.js 原生模块、bin/migrate对应多数据库的迁移编排、hogli start对应 phrocs 进程编排。理解这套手动流程能让你在 Flox 环境出问题时依然可以定位并修复底层环境故障。参考链接本文主要依据manual-dev-setup.md开发 Compose 覆盖docker-compose.dev.yml基础 Compose 服务docker-compose.base.yml开发者命令行定义hogli.yaml聚合迁移脚本bin/migrate进程运行器tools/phrocs/README.md演示数据管理命令generate_demo_data.pyKafka topic 清单docker/kafka/topics.txt【免费下载链接】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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考