Helicone 全链路本地开发实战：从零搭建 Gateway Worker 可观测性管道

Helicone 全链路本地开发实战从零搭建 Gateway Worker 可观测性管道【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone本文基于仓库根目录的 FULL_AGENT_LOOP.md 整理并深化。它完整记录了一条「客户端 → Gateway Worker → LLM 提供商 → Jawn → ClickHouse/Postgres/MinIO → Web 控制台」的全链路本地开发流水线先启动 Supabase、MinIO 与 ClickHouse 基础设施并跑通迁移再分别启动 Jawn 后端、Web 前端与 Gateway Worker 三个服务最后用一条带Helicone-Target-Url头部的 curl 请求触发真实日志采集并在控制台验证。读完本文你将能在一台开发机上复现 Helicone 的完整可观测性闭环并理解其请求代理、组织隔离与数据存储的底层实现。环境准备在开始之前请确保开发机具备以下条件Docker已安装并处于运行状态用于承载 Supabase、ClickHouse、MinIO 等基础设施HomebrewmacOS用于安装各类系统级工具NVMNode Version Manager用于管理 Node.js 版本。Node.js 版本固定Helicone 仓库是一个由 Yarn workspaces 管理的 monorepoNode 20参见 AGENTS.md。文档约定使用 Node 22# 若尚未安装 NVM请先安装官方地址github.com/nvm-sh/nvm # 安装并使用 Node 22 nvm install 22 nvm use 22固定 Node 大版本是本地链路稳定的第一步valhalla/jawn后端 API、webNext.js 前端与workerCloudflare Worker 网关三个工作区会共享同一 Node 运行时版本不一致容易导致原生依赖或构建产物不兼容。基础设施搭建1. 启动 SupabaseSupabase 提供本地 PostgreSQL 数据库是 Helicone 的应用数据层。文档建议在本地开发时排除非必需服务只保留核心数据库能力npx supabase start -x realtime,storage-api,imgproxy,mailpit,edge-runtime,logflare,vector,supavisor-x参数显式排除 realtime、storage-api、imgproxy、mailpit、edge-runtime、logflare、vector、supavisor 等扩展服务从而缩短启动时间并降低资源占用。启动后PostgreSQL 会监听在 Supabase 默认分配的本地端口上供 Jawn 与 Web 连接。2. 启动 Docker 服务MinIO 与 ClickHouse仓库根目录的 docker-compose.yml 中定义了完整的基础设施编排。文档推荐的最小集合是 MinIO对象存储与 ClickHouse分析型数据库docker compose up minio minio-setup clickhouse -d三个服务各司其职clickhouse使用clickhouse/clickhouse-server:24.3.13.40镜像暴露18123HTTP 接口与19000原生接口两个端口用于存储请求/响应日志、缓存命中、令牌统计等分析型数据minio使用minio/minio镜像暴露9000API与9001Console端口用于保存大体积对象如请求响应体、Prompt 体minio-setup基于minio/mc客户端在 MinIO 健康后自动创建request-response-storage、prompt-body-storage、hql-store三个 bucket——这些 bucket 名与 Jawn 服务中的S3_BUCKET_NAME、S3_PROMPT_BUCKET_NAME配置一一对应见 docker-compose.yml 中jawn服务的环境变量。3. 运行 ClickHouse 迁移ClickHouse 的建表与演进脚本存放在 clickhouse/migrations 目录按schema_0.sql到schema_79_property_value_index.sql顺序递增由迁移脚本 ch_hcone.py 驱动执行。文档给出的步骤是# 创建并激活 Python 虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 python3 -m pip install tabulate yarl # 执行 ClickHouse 迁移 python3 clickhouse/ch_hcone.py --upgrade --skip-confirmation --no-password从 ch_hcone.py 源码可以看到其工作机制脚本扫描migrations目录按文件名中的数字序号排序schema_sort_key逐条拆分 SQL 语句并通过 curl 以--data-binary -方式提交到 ClickHouse 的 HTTP 接口--no-password用于跳过交互式密码输入--skip-confirmation跳过执行前确认适合本地无密码的默认实例default用户。若连接失败或 ClickHouse 返回DB::Exception脚本会打印错误并退出见 ch_hcone.py。4. 种子数据种子文件位于 supabase/seeds/0_seed.sql在 Supabase 启动时通常会自动应用。它创建了两个测试组织、两位用户及对应的 Helicone API Key同时为 e2e 组织开启了credits与ptb_enabled两个功能开关ptb_enabled用于开启 AI Gateway 的 pass-through billing。基础设施小结完成以上四步后本地应同时运行三套数据基础设施组件角色端口参考SupabasePostgreSQL应用数据组织、用户、API Key由 supabase CLI 分配ClickHouse分析/时序数据请求日志、指标18123 / 19000MinIO对象存储请求体、Prompt 体等9000 / 9001启动三个核心服务基础设施就绪后需要在三个独立终端中分别启动 Jawn、Web 与 Worker# 终端 1 - Jawn后端 API cd valhalla/jawn yarn dev # 监听 http://localhost:8585 # 终端 2 - Web前端 cd web yarn dev:local -p 3000 # 监听 http://localhost:3000 # 终端 3 - Gateway Worker代理网关 cd worker npx wrangler dev --var WORKER_TYPE:GATEWAY_API --port 8789 # 监听 http://localhost:8789三个服务在链路中的分工如下Jawnvalhalla/jawnHelicone 的 TypeScript 后端 API负责处理日志写入、查询、组织与密钥管理等业务逻辑默认监听8585WebwebNext.js 前端控制台负责请求列表、分析图表与实验界面的展示默认监听3000。yarn dev:local在 web/package.json 中定义为next dev --turbo -p 3000启用 Turbopack 加速本地开发WorkerworkerCloudflare Worker 形态的 LLM 代理网关通过WORKER_TYPE环境变量切换工作模式GATEWAY_API是面向任意 LLM 提供商的通用网关模式。健康检查启动完成后可以通过 Jawn 的健康检查接口确认后端可用curl http://localhost:8585/healthcheck # 预期返回{status:healthy :)}测试账号与 API Key从 supabase/seeds/0_seed.sql 中可以查到完整的种子账号信息用户邮箱Helicone API Key组织Testtesthelicone.aisk-helicone-aizk36y-5yue2my-qmy5tza-n7x3aqaOrganization for TestAdminadminhelicone.aisk-helicone-zk6xu4a-kluegtq-sbljk7q-drnixziAdmin统一登录密码password种子 SQL 的对应关系值得留意sk-helicone-aizk36y-...对应的helicone_api_keys记录中organization_id指向83635a30-...即 Organization for Test用户f76629c5-...testhelicone.ai是该组织的 owner。这正是API Key 决定日志归属组织这一机制的落地点。测试完整请求链路发送一条测试请求以 Gemini 为例将 Gateway Worker端口 8789作为代理通过Helicone-Target-Url头指定真实 LLM 提供商地址curl -X POST http://localhost:8789/v1beta/models/gemini-2.0-flash:generateContent \ -H Content-Type: application/json \ -H Helicone-Auth: Bearer sk-helicone-aizk36y-5yue2my-qmy5tza-n7x3aqa \ -H Helicone-Target-Url: https://generativelanguage.googleapis.com \ -H x-goog-api-key: YOUR_GEMINI_API_KEY \ -d { contents: [{ parts: [{text: Say hello in exactly 3 words}] }] }这条请求的关键在于三个请求头它们的底层解析逻辑集中在 shared/proxy/heliconeHeaders.tsHelicone-Auth: Bearer api-key向 Helicone 证明调用者身份。getHeliconeAuthV2()会依次检查helicone-auth、authorization与helicone-jwt三个来源解析出 token 类型与内容见 heliconeHeaders.tsHelicone-Target-Url: provider-base-url指定 LLM 提供商的基础地址。getHeliconeHeaders()将其读入targetBaseUrl字段见 heliconeHeaders.tsx-goog-api-key: provider-key提供商自身的鉴权头由 Gateway 原样透传给上游。在控制台验证打开 http://localhost:3000使用testhelicone.ai/password登录关键步骤在左上角组织选择器中切换到 Organization for Test进入 Requests 页面查看刚才记录的请求。数据流架构整条链路的架构与数据流向如下源自 FULL_AGENT_LOOP.md┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Client │────▶│ Gateway Worker │────▶│ LLM Provider │ │ (curl) │ │ (port 8789) │ │ (Gemini, etc.) │ └─────────────┘ └────────┬────────┘ └─────────────────┘ │ │ Logs request/response ▼ ┌─────────────────┐ │ Jawn │ │ (port 8585) │ └────────┬────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ Postgres │ │ClickHouse │ │ MinIO │ │ (Supa) │ │(Analytics)│ │ (Files) │ └──────────┘ └───────────┘ └──────────┘ │ ▼ ┌─────────────────┐ │ Web (UI) │ │ (port 3000) │ └─────────────────┘从源码层面印证这一流程Gateway Worker 收到请求后gatewayRouter.ts 中的getProvider()会先校验targetBaseUrl是否合法必须是合法 URL、不能带 path再据此匹配 provider 并调用proxyForwarder转发给上游 LLM 提供商请求与响应在转发过程中被记录最终由 Jawn 分别写入 PostgreSQL应用数据、ClickHouse分析数据与 MinIO大体积对象Web 前端再从这三处聚合呈现见 gatewayRouter.ts。关键经验总结1. 组织上下文至关重要请求通过 Helicone API Key 归属于某个组织。因此查看控制台时默认的 My Organization 展示的是演示/预览数据必须切换到正确的组织如 Organization for Test才能看到真实请求。组织隔离的实现同样落在种子数据上每个 API Key 的哈希记录都绑定了一个organization_id见 0_seed.sqlWorker 在认证后即以该组织身份写入与查询数据。2. Worker 类型Worker 通过WORKER_TYPE变量区分职责仓库 wrangler.toml 中默认值为OPENAI_PROXY本地开发时可用--var WORKER_TYPE:xxx覆盖端口Worker 类型用途8787OPENAI_PROXYOpenAI 专属代理8788HELICONE_APIHelicone API Worker8789GATEWAY_API通用网关任意提供商8790ANTHROPIC_PROXYAnthropic 专属代理8793AI_GATEWAY_API统一路由 计费测试任意提供商如 Gemini时应使用GATEWAY_API8789配合Helicone-Target-Url头。值得注意的是通用网关对非白名单域名还有每日 10,000 次的限流保护approvedDomains匹配与 KV 计数逻辑均可在 gatewayRouter.ts 中看到。3. 鉴权请求头Helicone-Auth: Bearer api-key— 向 Helicone 认证Helicone-Target-Url: provider-base-url— 指定 LLM 提供商提供商自有鉴权头如 Gemini 的x-goog-api-key由网关透传。4. 演示数据 vs 真实数据控制台出现演示/预览数据的两种情况该组织还没有任何被记录的请求当前查看的是错误组织。判断标志是横幅提示This is a preview. Integrate your LLM app with Helicone to see your actual requests.5. Web 开发命令变体yarn dev:better-auth使用 better-auth 认证在 web/package.json 中定义为npx dotenv -e .env.better-auth -- next dev -p 3008需要额外加载.env.better-auth环境文件yarn dev:local -p 3000更简单的本地开发模式也是全链路联调推荐的方式。故障排查请求未出现在控制台确认当前处于正确的组织见上文组织上下文检查 Jawn 日志中的错误输出本地可通过tail -f /tmp/claude/.../tasks/jawn-task-id.output之类的任务日志观察确保使用的 Helicone API Key 与目标组织匹配。Worker 连接问题先确保 Jawn 已启动再通过 Worker 发请求检查 Worker 能否访问 localhost:8585Jawn 的 VALHALLA_URL。数据库连接问题确认 Supabase 运行中docker ps | grep supabase确认 ClickHouse 运行中docker ps | grep clickhouse。下一步方向全链路跑通后可以在本地继续深入通过 Gateway 测试不同的 LLM 提供商OpenAI、Anthropic、OpenRouter 等深入探索请求日志与分析能力对应 ClickHouse 中的各张 schema 表在可观测性管道之上构建自定义功能测试缓存命中、限流、重试等其他 Helicone 特性——相关能力在 shared/proxy/heliconeHeaders.ts 中均有对应的请求头支持如Helicone-RateLimit-Policy、helicone-retry-enabled等可作为本地实验的入口。【免费下载链接】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），仅供参考