Highlight.io 开源可观测平台开发指南：从 Monorepo 结构到全栈构建部署的实战手册

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本指南以 Highlight.io 开源仓库根目录的CLAUDE.md为骨架系统讲解这个全栈可观测平台的仓库组织方式、后端/前端/SDK 的开发命令、架构设计与数据流、常见开发模式、数据库操作以及构建部署流程。阅读完本文你将掌握如何在本地快速启动 Highlight.io 的完整开发环境理解双 GraphQL 端点、Kafka 异步链路与 ClickHouse 分析存储的协作方式并能在修改 GraphQL Schema 后正确完成代码生成与测试。文中所有命令与配置均可直接在仓库根目录、backend/、frontend/或docker/目录下运行。仓库总体概览Highlight.io 是一个提供会话回放Session Replay、错误监控Error Monitoring、日志Logging与分布式追踪Distributed Tracing能力的全栈可观测性平台。整个代码库以 Monorepo 形式组织Yarn Workspaces 与 Turborepo 负责 JavaScript/TypeScript 包的依赖管理与构建缓存Go 模块则独立管理后端依赖。从 package.json 中的workspaces字段可以看出仓库至少包含以下工作区docs-content文档站点、frontendReact 仪表盘、highlight.io营销与官网站点、e2e/*各语言示例应用、packages/*UI、AI、邮件模板等共享包、render服务端渲染工具以及一系列sdk/highlight-*客户端库。根目录package.json的preinstall脚本还会执行git submodule update --init --recursive用于拉取 RRWeb 等子模块。按 CLAUDE.md 的划分仓库由五大块构成Backend基于 Go 的 GraphQL API 服务提供 public / private 双 GraphQL 端点Frontend基于 React/TypeScript、由 Vite 驱动的仪表盘应用SDKs对接 Highlight 的多语言客户端库RRWebFork 的会话回放录制库子模块InfrastructureDocker Compose 与部署相关配置。关键技术选型与架构后端架构依据 CLAUDE.md 的 Architecture Overview并结合 backend/go.modgo 1.23.8与 backend/main.go 的导入清单后端的技术栈如下语言与路由Go 1.23HTTP 路由使用 Chigithub.com/go-chi/chi应用数据库PostgreSQL GORM用于存放项目、用户、工作区等业务数据分析数据库ClickHouse承载高吞吐的日志、会话、追踪与指标时间序列数据相关实现见 backend/clickhouse消息队列Apache Kafka负责异步处理数据接入队列抽象见 backend/kafka-queue缓存Redis用于缓存与会话管理见 backend/redisGraphQL双端点设计——public数据接入与 private仪表盘查询分别由 gqlgen 生成运行模式既可一体化all-in-one运行也可拆分为 public-graph、private-graph、worker 三个独立服务。运行模式的枚举定义在 backend/util/runtime.goall、graph前后端 GraphQL 合一、worker、public-graph、private-graph。后端进程通过-runtime启动参数选择模式-worker-handler参数则在 worker 模式下指定具体的处理函数如public-worker-main、log-alerts、metric-monitors等参见 backend/env/environment.go。前端架构前端仪表盘frontend/包名highlight-run/frontend的技术栈与 frontend/package.json 完全对应框架React 18 TypeScript构建工具Vite并使用vitejs/plugin-react-swc做转译状态管理Apollo Client 3.7apollo/client负责 GraphQL 状态样式Tailwind CSS 与 CSS Modules 并存另有部分组件使用 antd路由React Router v6MonorepoYarn Workspaces Turborepo根目录依赖turbo。前端还内置了大量可观测性相关组件依赖例如日志查询用的 CodeMirrorcodemirror/*、SQL 语言高亮popsql/monaco-sql-languages、表格tanstack/react-table、图表recharts以及会话回放播放器rrwebworkspace 引用。核心数据流CLAUDE.md 给出了四条关键数据链路可在源码中得到印证数据接入客户端 SDK → Public GraphQL → Kafka → Worker 进程 → 数据库。这条链路中healthRouter会向 Kafka 写入健康检查消息见 backend/main.goKafka 队列封装在 backend/kafka-queue/kafkaqueue.go。仪表盘查询前端 → Private GraphQL → 数据库查询。对应 backend/private-graph 与 backend/public-graph 两套 gqlgen 配置。会话回放RRWeb 录制 → 压缩 → S3/文件系统存储。存储抽象位于 backend/storage/storage.go。实时更新通过 WebSocket 订阅推送实时数据main.go 中导入了github.com/gorilla/websocket与subscriptions-transport-ws相关能力。开发环境搭建与核心命令前置条件按 CLAUDE.md 的 Development Workflow本地开发需要Go 1.23后端编译见 backend/go.mod 的go 1.23.8Node.js 18Docker用于启动 PostgreSQL、ClickHouse、Kafka、Redis 等基础设施Doppler CLI推荐用于开发环境的密钥管理见下文。后端开发命令在backend/目录下执行backend/Makefilemake start # 通过 doppler 启动后端推荐等价于 doppler run -- air -c .air.toml make start-no-doppler # 不依赖 doppler 启动等价于 air -c .air.toml make debug # 启动并附加 delve 调试器监听 :2345 make test # 以竞态检测--race运行全部 Go 测试 make migrate # 运行数据库迁移等价于 doppler run -- go run ./migrations/main.go make public-gen # 生成 public GraphQL schema 代码 make private-gen # 生成 private GraphQL schema 代码make start背后是 backend/.air.toml 配置的 Air 热重载cmd go build -gcflagsall-N -l -o ./tmp/main .并且full_bin支持在热重载的同时启动 delve 调试会话。make debug实际执行的是doppler run -- dlv debug --headless --listen:2345 --api-version2 --accept-multiclient。make test会注入一组本地测试环境变量PSQL_HOSTlocalhost、CLICKHOUSE_ADDRESSlocalhost:9000等并以-p 1 --race串行执行全部测试make test-and-coverage则额外生成覆盖率文件coverage.out。前端开发命令在frontend/目录下执行yarn dev # 启动开发服务器Vite GraphQL codegen watch reflame yarn build # 类型检查后构建生产包NODE_OPTIONS--max-old-space-size32768 vite build yarn test # TZUTC vitest --run 运行单元测试 yarn test:watch # vitest 监视模式 yarn types:check # tsc -noEmit 仅做类型检查 yarn lint # eslint ./src yarn codegen # 依据 codegen.yml 生成 GraphQL 类型frontend的脚本定义在 frontend/package.json。其中dev通过npm-run-all并行启动dev:vite、dev:reflame、dev:tsm、dev:gql四个子任务因此前端热更新同时覆盖了 Vite 编译、TypeScript 增量检查和 GraphQL 类型生成。根目录 Monorepo 命令在仓库根目录执行package.jsonyarn build:all # yarn turbo run build构建全部包 yarn test:all # yarn turbo run test跳过 rrweb、render 等包的测试 yarn dev # 并行启动全部 dev:* 任务前端 后端 yarn dev:frontend # 仅启动前端doppler run -- yarn turbo run dev --filter highlight-run/frontend yarn dev:backend # 仅启动后端cd backend make start yarn lint # turbo lint排除 rrweb 及其子包Docker 开发与一键部署docker/目录提供了三套 Compose 编排与配套脚本开发环境docker-compose up根目录脚本为docker compose -f docker/compose.yml up启动全部基础设施服务Hobby 部署./run-hobby.sh单节点自托管方案脚本会先跑 docker/start-infra.sh 启动基础设施再docker compose -f compose.hobby.yml up --detach backend frontend并可通过--no-pull跳过镜像拉取见 docker/run-hobby.shEnterprise 部署./run-enterprise.sh使用 docker/compose.enterprise.yml 提供可水平扩展的多服务部署。以 Hobby 为例docker/compose.hobby.yml 暴露了后端8082端口以及前端的3000、6006、8080端口并将../backend/env.enc、../backend/env.enc.dgst与本地 SSL 证书挂载进容器同时使用名为highlight-data的卷保存会话回放等数据。快速起步流程综合 CLAUDE.md 的 Getting Started 章节一次完整的本地起步如下# 1. 启动基础设施PostgreSQL / ClickHouse / Kafka / Redis cd docker docker-compose up # 2. 初始化后端数据库并启动后端 cd ../backend make migrate make start # 3. 启动前端 cd ../frontend yarn dev常见开发模式与代码生成GraphQL Schema 生成流程Highlight.io 的 GraphQL 代码生成采用「后端 gqlgen 前端 graphql-codegen」双轨制修改后端 schemabackend/public-graph/graph/*.graphqls或backend/private-graph/graph/*.graphqls后运行make public-gen或make private-gen修改前端 GraphQL 查询后运行yarn codegen。gqlgen 的配置见 backend/public-graph/gqlgen.ymlschema 位于graph/*.graphqls生成代码输出到graph/generated/generated.go模型输出到graph/model/models_gen.goresolver 采用follow-schema布局放在graph/目录autobind将backend/model包中的 Go 类型与 GraphQL 类型绑定。make public-gen实际执行(cd ./public-graph; go run github.com/99designs/gqlgen)见 backend/Makefile。测试策略后端Go 测试默认开启竞态检测--race由 backend/Makefile 的test目标注入本地环境变量后运行fuzz目标会自动发现所有func Fuzz*并执行 5 秒模糊测试。前端Vitest 单元测试TZUTC vitest依赖happy-dom与testing-library/react-hooks并支持 GraphQL mock。数据库通过环境变量指定独立的测试数据库例如CLICKHOUSE_TEST_DATABASEtest、PSQL_DB等。代码生成与构建系统Backendgqlgengithub.com/99designs/gqlgen见 backend/go.modFrontendgraphql-codegengraphql-codegen/*生成 TypeScript 类型Build SystemTurborepo 管理依赖图与缓存加速同时承担跨 workspace 的任务编排。数据库操作与环境变量数据库迁移后端数据库迁移入口是 backend/migrations/main.go它调用model.SetupDB建立连接后执行model.MigrateDB。CLI 方式为make migrate即doppler run -- go run ./migrations/main.go。迁移文件位于 backend/migrationsGo 迁移程序与 backend/clickhouse/migrations292 个 SQL 迁移文件。ClickHouse 的迁移在服务启动时自动执行无需手动操作。关键环境变量后端配置通过环境变量注入结构体定义在 backend/env/environment.go字段与 env 名一一对应如SQLHost对应PSQL_HOST。开发时推荐使用 Doppler 管理密钥。核心变量包括环境变量用途PSQL_HOST/PSQL_PORT/PSQL_USER/PSQL_PASSWORD/PSQL_DBPostgreSQL 连接CLICKHOUSE_ADDRESS/CLICKHOUSE_USERNAMEClickHouse 连接KAFKA_SERVERSKafka broker 地址REDIS_EVENTS_STAGING_ENDPOINT/REDIS_PASSWORDRedis 连接REACT_APP_PUBLIC_GRAPH_URI/REACT_APP_PRIVATE_GRAPH_URI前后端 GraphQL 端点地址SESSION_RETENTION_DAYS会话数据保留天数WORKER_MAX_MEMORY_THRESHOLDWorker 内存阈值此外-runtime默认all与-worker-handler两个命令行 flag 由 backend/env/environment.go 声明其中-runtime可选dev/worker/public-graph/private-graph-worker-handler仅在runtimeworker时生效。构建与部署生产构建yarn build:all # 构建全部包 yarn build:frontend # 仅前端turbo filter highlight-run/frontend yarn build:backend # 仅后端cd backend go build yarn build:sdk # 构建 highlight.run 及各 SDK workspaceDocker 部署形态CLAUDE.md 将部署形态归纳为三种均在docker/下有对应脚本与配置Hobby单节点自托管./run-hobby.sh compose.hobby.yml适合个人/小团队快速体验Enterprise多服务可扩展部署./run-enterprise.sh compose.enterprise.yml可将 public-graph、private-graph、worker 拆分为独立任务deploy/下还提供了private-graph-task.json、public-graph-task.json、worker-task.json等 ECS 任务定义Development本地基础设施服务docker-compose up compose.yml。代码组织结构导航后端backendmain.go为入口含运行时配置与健康检查public-graph/与private-graph/分别承载数据接入与仪表盘查询的 schema/resolverworker/存放异步处理 handlermodel/为数据库模型store/为数据访问层clickhouse/为 ClickHouse 查询与 schema另有kafka-queue/队列、redis/缓存、storage/对象存储等支撑模块。前端frontend/srcindex.tsx为入口components/为可复用 UIpages/为路由级页面graph/为 GraphQL 查询与生成类型util/为工具函数。SDKsdksdk/highlight-*为各语言客户端Go、Python、Java、Ruby、Node、Next.js、React、Remix、Cloudflare、Hono 等sdk/highlight-run/为 JavaScript 核心 SDK各 SDK 遵循各自语言的约定与模式。开发注意事项速查CLAUDE.md 的 Important Notes 总结了若干关键约定可作为日常开发 checklist热重载前端基于 Vite 支持热更新后端使用 Airbackend/.air.toml实现文件变更自动重编译GraphQL修改 schema 后务必执行make public-gen/make private-gen/yarn codegen否则前后端类型不同步环境管理开发环境使用 Doppler 管理密钥doppler run --前缀调试后端支持 delve 调试器监听 2345 端口make debug性能高吞吐分析查询统一走 ClickHouse避免压到 PostgreSQL安全public 与 private 端点的 CORS 配置不同接入与仪表盘接口按需开放。结语通过本指南你已经了解了 Highlight.io 仓库从 Monorepo 划分、双 GraphQL 端点、Kafka 异步数据链路到后端 Air 热重载、前端 Vite 开发服务器、gqlgen/graphql-codegen 代码生成再到 Hobby/Enterprise 两种 Docker 部署形态的完整开发闭环。接下来可以按「启动基础设施 →make migrate make start→yarn dev」的顺序实际跑通一次本地环境并结合 backend、frontend、sdk 目录下的源码进一步深入每个模块的实现细节。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐mistral.rs 仓库开发实战指南从源码结构、构建测试到编码规范的 AGENTS 开发手册mistral.rs 仓库开发实战指南从源码结构、构建测试到编码规范的 AGENTS 开发手册 本文面向希望深入 mistral.rs 源码、参与构建与贡献的推理引擎模型推理服务AI Agent多模态Rayhunter 源码构建指南从编译、部署到开发调试的完整实战手册Rayhunter 源码构建指南从编译、部署到开发调试的完整实战手册 Rayhunter 是一个用 Rust 编写的开源工具用于在 Orbic 等移动热点设网络安全通信OneUptime 开源可观测性平台入门指南从 Uptime 监控到全栈可观测的一站式实践OneUptime 开源可观测性平台入门指南从 Uptime 监控到全栈可观测的一站式实践 OneUptime 是一个开源的监控与可观测性一体化平台本指南以可观测性后端运维前端云原生微服务AI Agent上一篇如何在macOS上运行Windows应用Whisky完整使用指南下一篇如何在macOS上运行Windows应用Whisky完整指南与安装教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考