highlight.io 开发环境部署指南：从克隆仓库到本地全栈调试

可观测性后端【免费下载链接】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 开源仓库的开发环境Development Deployment搭建展开面向希望本地运行完整全栈监控平台、进而参与源码贡献的开发者。读完本文你将掌握从环境依赖检查、带子模块克隆仓库、一键启动基础设施与前后端服务到登录仪表盘、回放第一个会话以及排障恢复的完整开发部署流程并了解每个启动脚本背后的真实实现。环境准备依赖版本与资源要求在开始之前需要先确认本机满足开发环境的基础依赖。开发部署围绕 Go 后端、React 前端与 Docker 基础设施展开因此要求如下依赖最低版本要求验证命令Go1.21go versionNode.js18node --versionyarn1yarn --versionDocker25.0docker --versionDocker Compose 插件2.24docker compose versionGit2.13git --version原文档给出的参考验证输出如下$ go version go version go1.21.6 linux/arm64$ node --version v18.15.0$ yarn --version 4.0.2$ docker --version Docker version 25.0.3, build 4debf41$ docker compose version Docker Compose version v2.24.5同时建议为 Docker 分配至少 8GB 内存、4 个 CPU 与 64GB 磁盘空间。这是因为开发部署会同时拉起 ClickHouse、Kafka、PostgreSQL、Redis、ZooKeeper 等重负载基础设施容器资源配置不足将直接导致容器无法进入 healthy 状态这一健康状态要求会在下文排障章节再次用到。克隆仓库务必带上子模块highlight.io 是一个 monorepo仓库中部分依赖例如前端回放渲染相关的 rrweb 产物通过 Git 子模块submodule引入。因此克隆时必须使用--recurse-submodules标志一次性拉取全部子模块内容否则后续构建阶段会因缺失子模块文件而失败git clone --recurse-submodules https://gitcode.com/gh_mirrors/hi/highlight仓库根目录下可以直接看到子模块相关内容例如__generated/rr/rrweb与rrweb/目录它们正是开发与构建流程所需的渲染依赖。子模块的完整克隆是保证./run.sh一键启动能够成功的前提。一键启动运行 docker/run.sh克隆完成后整个开发环境的启动入口位于仓库的docker目录。进入该目录并执行启动脚本cd highlight/docker; ./run.sh;./run.sh并非简单地拉起容器而是一个编排了基础设施 → 前端 → 后端 → 健康等待完整链路的启动器。从 docker/run.sh 源码可以看到它的真实执行顺序source env.sh加载docker/.env中的环境变量并依据是否传入--go-docker决定后端连接本机端口还是容器内服务地址./start-infra.sh先启动全部基础设施容器./run-frontend.sh 与./run-backend.sh 以后台进程方式同时启动前端与后端开发服务使用yarn dlx wait-on -l -s 2 ${REACT_APP_FRONTEND_URI}/index.html ${BACKEND_HEALTH_URI}轮询前端入口页面与后端健康检查接口直到两者均在线打印Highlight started on ${REACT_APP_FRONTEND_URI}随后wait保持前台进程存活CtrlC 即可整体停止。可以看到一键启动脚本内部会同时挂起多个进程因此该方案适合只想快速跑起来看看的场景如果你需要更细粒度地控制开发流程可以跳过run.sh改用下文的分终端手动方式。基础设施编排start-infra.sh 究竟启动了哪些服务./start-infra.sh是开发部署的地基。阅读 docker/start-infra.sh 源码其核心逻辑如下SERVICESclickhouse kafka postgres redis zookeeper collector predictions BUILD_ARGS--build-arg OTEL_COLLECTOR_ALPINE_IMAGE_NAME${OTEL_COLLECTOR_ALPINE_IMAGE_NAME} \ --build-arg OTEL_COLLECTOR_IMAGE_NAME${OTEL_COLLECTOR_IMAGE_NAME} docker compose pull $SERVICES docker compose build --pull $BUILD_ARGS $SERVICES docker compose up --detach --wait --remove-orphans $SERVICES即按序执行pull、build与up --detach --wait一次性拉起 7 个基础设施服务。其中--wait会阻塞直到所有容器通过健康检查collector 通过 Dockerfiledocker/collector.Dockerfile现场构建因此需要--build-arg注入 OpenTelemetry Collector 的镜像名称。各服务的作用与暴露端口可以从 docker/compose.yml 中确认服务端口在开发栈中的角色zookeeper2181容器内Kafka 的协调服务kafka9092事件/日志/会话数据的消息队列redis6379缓存与事件暂存postgres5432主业务元数据存储带 pgvector 的镜像clickhouse8123 / 9000日志、trace、会话明细等分析型数据存储collector4317/4318 等OpenTelemetry Collector接收 OTLP 遥测数据predictions—预测相关任务服务容器启动完成后start-infra.sh还会执行一次数据库迁移在../backend目录运行go run ./migrations/main.go对应 backend/migrations/main.go并将输出写入/tmp/highlightSetup.log若日志中出现OPENSEARCH_ERROR关键字则判定迁移失败并终止启动。这一步保证了 PostgreSQL 表结构与后端代码保持同步。分终端手动开发可选精细控制启动流程一键脚本内部采用后台进程方式前端与后端共用同一终端输出。如果你希望更精细地控制开发流程、分别观察各进程日志可以按原文档建议在多个终端中手动执行。第一个终端启动基础设施cd highlight/docker; ./start-infra.sh;第二个终端启动后端cd highlight/docker; ./run-backend.sh./run-backend.sh的执行路径值得展开它先运行./telemetry.sh与source env.sh随后设置会话存储目录export OBJECT_STORAGE_FS/tmp/highlight-data并创建该目录接着安装 Go 热重载工具air与调试器delve最后执行make start-no-doppler。对应 backend/Makefile 中的定义start-no-doppler: air -c .air.toml即通过air依据.air.toml配置监听 Go 源码变更并自动重编译重启实现后端热重载。该进程会一直阻塞直到你按 CtrlC 停止。第三个终端启动前端cd highlight/docker; ./run-frontend.sh./run-frontend.sh先执行yarn安装前端依赖再运行yarn docker:frontend。该命令在根目录 package.json 中定义为docker:frontend: yarn turbo run dev --filter highlight-run/frontend --filter highlight.run它通过 Turborepo 同时以开发模式启动highlight-run/frontend主控制台应用Vite 驱动与highlight.run浏览器 SDK 构建同样支持热更新并阻塞直至 CtrlC 停止。由于start-infra.sh在未传--go-docker参数时会通过 docker/env.sh 将后端连接地址指向本机端口例如CLICKHOUSE_ADDRESSlocalhost:9000、KAFKA_SERVERSlocalhost:9092、PSQL_HOSTlocalhost、OTLP_ENDPOINThttp://localhost:4318因此这三个终端的进程可以在宿主机上直接相互通信。访问仪表盘与完成登录前后端启动完成后打开浏览器访问REACT_APP_FRONTEND_URI所指向的地址默认即前端开发服务地址即可进入仪表盘并走一遍登录流程。登录凭据的规则非常简单邮箱地址可以是任意合法格式密码则使用docker/.env文件中ADMIN_PASSWORD变量的值。也就是说docker/.env是开发环境的关键配置入口其中还包含REACT_APP_FRONTEND_URI、REACT_APP_PUBLIC_GRAPH_URI等服务地址变量env.sh会将这些变量统一导出并注入后端进程。查看你的第一个会话登录后在仪表盘上随意点击操作一段时间前端 SDK 会采集交互与回放数据并经 Kafka 管道写入 ClickHouse。此时访问http://localhost:3000/1/sessions即可看到新产生的会话记录。点击任意会话即可进入会话详情页查看完整的 Session Replay 回放、错误事件与时间线信息——这是验证埋点采集 → 消息队列 → 存储 → 前端展示全链路是否打通的最直接方式。故障排查从健康检查到彻底重置如果部署过程中遇到问题原文档提供了三级排障手段第一步检查容器健康状态docker ps确保所有容器都处于healthy状态。start-infra.sh的up --wait依赖的就是这套健康检查例如 PostgreSQL 使用pg_isready探活见 docker/compose.yml因此任何容器未能通过健康检查都会导致启动失败。第二步查看基础设施日志docker compose logs观察 ClickHouse、Kafka、PostgreSQL 等容器的输出定位具体报错原因。第三步彻底重置编排栈如果日志显示容器状态异常且无法修复可以直接销毁整个 docker compose 栈从干净状态重新开始docker compose down --remove-orphans --volumes --rmi local该命令会删除容器、孤儿容器、全部数据卷以及本地构建的镜像等价于清空所有开发数据。执行完毕后重新运行./start-infra.sh或直接./run.sh即可重建一套全新的开发环境。如果以上步骤仍无法解决问题可以前往 highlight.io 官方社区寻求帮助。结合 docker/run.sh 与 docker/start-infra.sh 的源码多数本地部署问题都集中在资源配置不足导致容器无法 healthy、子模块未完整克隆、docker/.env中关键变量缺失或端口被占用这几类原因上。赞分享可观测性后端【免费下载链接】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点击查看免费下载相关推荐10分钟搭建GitHub Readme Stats本地开发环境从克隆到调试全指南10分钟搭建GitHub Readme Stats本地开发环境从克隆到调试全指南 你是否曾因GitHub API限制导致统计卡片加载失败是否想自定义统计卡片后端数据可视化highlight.io 本地开发部署指南在 Docker 中搭建可热重载的全栈监控开发环境highlight.io 本地开发部署指南在 Docker 中搭建可热重载的全栈监控开发环境 本文基于仓库中 1_self host dev.md https可观测性后端Code Blocks与highlight.js揭秘Google Docs代码高亮背后的技术原理Code Blocks与highlight.js揭秘Google Docs代码高亮背后的技术原理 想要在Google Docs文档中优雅地展示代码片段吗Co上一篇3分钟上手QKeyMapperWindows最强开源按键映射工具完全指南下一篇WaveTools3分钟快速上手让《鸣潮》游戏体验提升42%的终极工具箱创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考