Helicone 开发者本地环境搭建指南从零启动全套 LLM 可观测性平台【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/heliconeHelicone 是一个开源的 LLM 可观测性平台开发者只需一行代码即可完成对 LLM 请求的监控、评估与实验项目简介见 README.md。本文是面向贡献者的本地开发环境搭建指南围绕 DEVELOPER_README.md 的三步流程展开先用 Docker Compose 拉起基础设施与迁移再分别启动 Web 前端Next.js与 Jawn 后端 API 两个进程最后通过注册账号与邮件验证确认整条链路可用。读完本文你将能独立跑通一套基于 better-auth 的 Helicone 完整开发栈并理解每个命令背后的组件构成。环境与组件概览在动手之前先看清这套开发栈由哪些部分构成。Helicone 仓库采用 monorepo 结构本地开发主要涉及以下模块模块目录职责基础设施编排docker/docker-compose.ymlPostgreSQL、ClickHouse、MinIO、MailHog、Redis 及数据库迁移服务Compose 辅助脚本docker/helicone-compose.sh以 profile 方式简化docker compose调用Web 前端web/package.jsonNext.js 14 应用控制台 UIdev:better-auth脚本以 3008 端口启动后端 APIJawnvalhalla/jawn/package.jsonExpress tsoa 后端默认监听 8585 端口认证服务web/lib/auth.tsbetter-auth 配置注册、邮箱验证、SMTP 发送数据库迁移docker/dockerfiles/dockerfile_migrationsFlywayPostgreSQL ClickHouse 迁移执行容器其中helicone-compose.sh是关键入口脚本它将 Docker Compose 的 profile 机制包装成直观的参数infra仅基础设施、helicone完整栈、dev开发模式带热重载、workers、kafka和all全部。helicone up实际等价于docker compose --profile include-helicone up -d见 docker/helicone-compose.sh默认以 detached 模式后台运行。第 1 步启动服务与数据库迁移1.1 拉起全套服务在仓库根目录执行./helicone-compose.sh helicone up该命令会启动两类服务基础设施默认 profile始终运行PostgreSQL 17.4、ClickHouse 24.3、MinIO 对象存储、MailHog 邮件测试工具、Redis 8以及执行数据库迁移的migrations容器核心服务include-heliconeprofilejawn后端与web前端容器见 docker/docker-compose.yml。各基础设施的默认端口映射如下服务镜像对外端口用途dbpostgres:17.454388 → 5432主业务数据库helicone_testclickhouseclickhouse/clickhouse-server:24.3.13.4018123 / 19000LLM 请求日志与指标存储miniominio/minio9000 / 9001S3 兼容对象存储请求/响应体mailhogmailhog/mailhog1025 / 8025本地邮件捕获8025 为 Web 界面redisredis:8.0.2-alpine6379缓存与限流启动完成后可先用./helicone-compose.sh helicone ps查看容器状态用./helicone-compose.sh helicone logs jawn查看 Jawn 日志。提示若只想先起基础设施再手动跑前后端对应下文的分步开发模式可执行./helicone-compose.sh infra up。1.2 迁移做了什么migrations容器在db与clickhouse健康检查通过后自动运行见 docker/docker-compose.yml。其执行逻辑在 docker/dockerfiles/dockerfile_migrations 中定义PostgreSQL 迁移基于 supabase/flyway.conf 配置Flyway 依次执行 supabase/migrations 与 supabase/migrations_without_supabase 下的 SQL 文件迁移命名遵循YYYYMMDDHHMMSS_description.sql约定ClickHouse 迁移调用 clickhouse/ch_hcone.py 执行 clickhouse/migrations 目录下的 schema 脚本。需要留意的是迁移容器依赖postgres_flyway_data、minio_data、clickhouse_data三个持久化卷见 docker/docker-compose.yml首次启动会拉取镜像并完成全量建表耗时较长属正常现象之后再次启动会复用卷数据增量执行迁移。第 2 步启动 Web 与 Jawn双终端开发模式Docker 之外贡献者通常更倾向于在宿主机直接跑 Web 与 Jawn以获得更快的迭代反馈。此时需要两个终端。2.1 终端 A启动 Web 前端cp web/.env.example.better-auth web/.env.better-auth cd web yarn yarn dev:better-authcp生成 better-auth 专用环境文件其中已预设好本地数据库连接串、MinIO 凭证、Jawn 服务地址http://localhost:8585与BETTER_AUTH_SECRET见 web/.env.example.better-authyarn安装依赖仓库要求 Node 20见 web/package.jsonyarn dev:better-auth实际执行npx dotenv -e .env.better-auth -- next dev -p 3008以3008端口启动 Next.js 开发服务器见 web/package.json。之所以是 3008 而非 3000是因为这套 better-auth 流程与 Docker Compose 中 web 容器3000 端口并存3008 用于隔离本地手动开发web/lib/auth.ts中trustedOrigins的默认值也相应取http://localhost:3008。2.2 终端 B启动 Jawn 后端 APIcp valhalla/jawn/.env.example.better-auth valhalla/jawn/.env cd valhalla/jawn yarn yarn devcp生成 Jawn 的环境文件核心变量包括SUPABASE_DATABASE_URL指向本地 54388 端口的 PostgreSQL、MinIO 凭证、HELICONE_WORKER_URL、BETTER_AUTH_SECRET等见 valhalla/jawn/.env.example.better-authyarn dev使用concurrently同时运行 nodemon 与genTypes.py见 valhalla/jawn/package.jsonnodemon 监听 valhalla/jawn/src 与shared目录下的 TS 文件变化自动重启见 valhalla/jawn/nodemon.json后端入口 valhalla/jawn/src/index.ts 会创建 Express 服务并监听PORT默认8585同时挂载 tsoa 生成的公开/私有路由、Swagger UI、CORS 与限流中间件并在upgrade事件上提供 WebSocket 控制面服务。2.3 双进程如何协作Web3008与 Jawn8585通过环境变量建立连接Web 通过NEXT_PUBLIC_HELICONE_JAWN_SERVICEhttp://localhost:8585调用后端 API而 Jawn 侧通过SUPABASE_DATABASE_URL直连 PostgreSQL通过 S3 端点读写 MinIO 中的请求/响应体对象。认证方面Web 的 web/lib/auth.ts 使用 better-auth 完成注册、登录与邮箱验证并通过customSession插件在会话中注入authUserIdJawn 侧则通过BETTER_AUTH_SECRET校验来自 Web 的会话凭据。第 3 步注册账号与邮箱验证两个服务都起来后浏览器打开http://localhost:3008/signup创建账号打开http://localhost:8025/MailHog Web 界面查看注册时触发的验证邮件点击邮件中的 Start Building 验证链接完成邮箱确认即可进入控制台。这里的邮件链路由 better-auth 的emailVerification配置驱动注册即发送验证邮件sendOnSignUp: true并通过 nodemailer 将邮件投递到SMTP_HOST本地为mailhog/localhost:1025。开发环境下 SMTP 不启用认证与 TLS见 web/lib/auth.ts因此无需真实邮箱服务即可完成全流程验证。常用排障与调试技巧以下命令与常见问题来自脚本与源码中的实际配置查看容器与日志./helicone-compose.sh helicone ps查看服务状态./helicone-compose.sh helicone logs jawn查看 Jawn 容器日志./helicone-compose.sh helicone logs migrations确认迁移是否成功完成切换开发模式./helicone-compose.sh dev up会以devprofile 启动带热重载的jawn-dev与web-dev容器见 docker/docker-compose.yml并将本地web、valhalla、shared目录挂载进容器停止服务./helicone-compose.sh helicone down迁移失败migrations容器会先执行flyway repair再flyway migrate见 docker/dockerfiles/dockerfile_migrations用于修复校验和不一致若仍需手动重跑可参考supabase/flyway.conf中flyway.url、flyway.user、flyway.password与flyway.locations配置端口冲突Jawn 端口可通过JAWN_PORT环境变量覆盖Compose 中默认 8585Web 开发端口由dev:better-auth固定为 3008与 Docker 模式的 3000 互不干扰依赖版本前提本地直接跑 Node 服务要求 Node 20见 web/package.jsonPostgreSQL/ClickHouse/MinIO 等基础设施由 Compose 管理宿主机无需预装。总结至此一条完整的 Helicone 本地开发链路已经跑通helicone-compose.sh helicone up拉起基础设施并完成 PostgreSQL/ClickHouse 迁移 → 两个终端分别以 better-auth 模式启动 Web3008与 Jawn8585→ 注册账号并在 MailHog8025中完成邮箱验证。这套流程不仅是贡献者接入开发的入口也完整呈现了 Helicone 核心组件Next.js 控制台、Express API、ClickHouse 日志存储、MinIO 对象存储与 better-auth 认证之间的协作关系后续无论是调试新功能还是编写测试都可以在此环境中快速验证。【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考