highlight.io 本地开发部署指南:在 Docker 中搭建可热重载的全栈监控开发环境

原创2026-09-24 15:06:481,920 阅读
文章标签:可观测性后端

highlight.io 本地开发部署指南:在 Docker 中搭建可热重载的全栈监控开发环境

本文基于仓库中 1_self-host-dev.md 与其指向的 开发部署指南 展开,结合仓库内 docker/ 目录的真实脚本与 Quickstart 组件源码,完整讲解如何在本地机器上以开发模式(Dev Deployment)部署 highlight.io,实现在 highlight.io 代码库中进行开发与贡献。读完本文,你将掌握从环境准备、克隆仓库、一键启动到手动分终端启动、登录 Dashboard、查看第一条 Session 以及故障排查的完整实战流程。

highlight.io 是一个开源的、全栈的可观测性平台,提供错误监控、Session 回放、日志、分布式追踪等能力。对开发者而言,最关心的问题往往是:如何在自己的机器上把整个 highlight.io 跑起来,以便修改源码、热重载并验证改动? 本文介绍的就是官方面向贡献者的「Development Deployment」(开发部署)方式——一种基于 Docker 的本地部署形态,支持前后端热重载,适合直接上手开发 Highlight 代码库。

前置条件:工具链版本与资源要求

在开始之前,请先确认本地开发环境满足以下工具版本要求。这些要求来自 dev-deploy.tsx 所引用的 dependencies 步骤(见 shared-snippets.tsx):

工具 最低/建议版本 说明
Go 1.21 后端语言运行时
Node.js 18+ 前端构建与运行
yarn 1+ 依赖管理(仓库内示例输出为 4.0.2,即 Yarn Berry 亦可)
Docker 25.0+ 容器运行时
docker compose 插件 2.24+ 编排多容器基础设施
Git 2.13+ 克隆仓库与子模块

资源建议:文档建议将 Docker 配置为至少 8 GB 内存、4 个 CPU、64 GB 磁盘空间。这是因为本地开发部署会同时拉起 ClickHouse、Kafka、PostgreSQL、Redis、Zookeeper、Collector、Predictions 等多套基础设施容器,资源占用不容小觑。

安装完成后,可以用以下命令快速核验版本是否达标:

$ 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

克隆仓库并检出子模块

开发部署的第一步是获取完整源码。highlight.io 使用 Git 子模块管理部分依赖,因此克隆时必须加上 --recurse-submodules 标志,确保子模块一并检出:

git clone --recurse-submodules https://gitcode.com/gh_mirrors/hi/highlight

克隆完成后,仓库根目录下你应该能看到几个关键目录:backend/(Go 后端)、frontend/(React 前端应用)、docker/(本地开发部署脚本与 Compose 配置)、highlight.io/(Next.js 落地页与文档站点)、sdk/(各语言 SDK)。

一键启动:运行 ./run.sh

官方推荐的最快启动方式是在 docker/ 目录下执行 ./run.sh:

cd highlight/docker;
./run.sh;

这条命令会依次完成「启动基础设施 → 启动后端 → 启动前端 → 等待服务就绪」的完整链路。从源码看(docker/run.sh),它实际上做了四件事:

  1. source env.sh:加载 docker/env.sh 中定义的环境变量(CLICKHOUSE_ADDRESS、KAFKA_SERVERS、OTLP_ENDPOINT、PSQL_HOST 等),并依据 .env 文件导出配置;
  2. ./start-infra.sh:启动全部基础设施容器;
  3. 后台并行执行 ./run-frontend.sh & 与 ./run-backend.sh &;
  4. 用 yarn dlx wait-on -l -s 2 "${REACT_APP_FRONTEND_URI}"/index.html "${BACKEND_HEALTH_URI}" 轮询等待前端首页与后端健康检查接口就绪,最后打印 Highlight started on ${REACT_APP_FRONTEND_URI} 并 wait 阻塞,直到你 Ctrl+C 停止。

start-infra.sh:基础设施容器与数据库迁移

开始基础设施脚本 是整套部署的地基,它一次性拉起以下服务(对应 docker compose 服务名):

SERVICES="clickhouse kafka postgres redis zookeeper collector predictions"

执行流程为:docker compose pull 拉取镜像 → 带 OTEL_COLLECTOR_* 构建参数 build → docker compose up --detach --wait --remove-orphans 以分离模式启动并等待全部容器健康。

随后(除非传入 --go-docker 参数),脚本会进入 backend/ 目录执行数据库迁移:

go run ./migrations/main.go > /tmp/highlightSetup.log 2>&1

并检查迁移日志中是否出现 OPENSEARCH_ERROR——一旦出现即判定迁移失败,打印完整日志并以非零状态退出。这正是本部署链路中最容易出问题的环节之一,排查时可重点关注该日志文件 /tmp/highlightSetup.log。

run-backend.sh 与 run-frontend.sh:热重载开发环境

后端脚本(docker/run-backend.sh)的核心动作:

export OBJECT_STORAGE_FS=/tmp/highlight-data
mkdir -p ${OBJECT_STORAGE_FS}
go install github.com/air-verse/air@latest
go install github.com/go-delve/delve/cmd/dlv@latest
make start-no-doppler

它先在本地创建 /tmp/highlight-data 作为 Session 存储目录,然后安装两个关键开发工具:air(Go 热重载工具,改代码即自动重启后端)与 dlv(Delve Go 调试器),最后以 make start-no-doppler 启动后端——no-doppler 表示无需 Doppler 密钥管理服务,纯本地开发模式。

前端脚本(docker/run-frontend.sh)则先执行 yarn 安装依赖,再运行 yarn docker:frontend 启动 Vite/React 开发服务器,同样支持热重载。

(可选)在多个终端中手动启动各部分

./run.sh 虽然方便,但它是把前端、后端串在同一进程中等待,调试单个组件时不够灵活。如果你希望更细粒度地控制开发栈的每一层,可以分别在多个终端中手动启动。官方 Quickstart(dev-deploy.tsx)给出了三步走方案。

终端一:先启动基础设施容器

cd highlight/docker;
./start-infra.sh;

终端二:启动后端(阻塞运行,Ctrl+C 停止)

cd highlight/docker;
./run-backend.sh

终端三:启动前端(阻塞运行,Ctrl+C 停止)

./run-frontend.sh

注意第三个终端命令在当前目录即 highlight/docker 下执行;若从其他目录进入,需先 cd highlight/docker。手动方式与一键方式共用同一套环境变量与 Compose 配置,因此两种方式可以按需混用——例如先 ./run.sh 验证整体,再改为分终端模式单独重启后端。

访问 Dashboard 并登录

服务就绪后,打开浏览器访问 REACT_APP_FRONTEND_URI(默认为 http://localhost:3000)即可看到 Dashboard,随后走一遍登录流程。登录凭据遵循以下约定(见 shared-snippets.tsx 的 dashboard 步骤):

  • 密码:使用 docker/.env 中的 ADMIN_PASSWORD 变量值;
  • 邮箱:任意合法邮箱地址均可(本地开发环境不做邮箱校验)。

查看你的第一条 Session

登录并在 Dashboard 上随便点击操作一番后,前端埋点即会采集到 Session 数据。片刻之后,你应当能在 http://localhost:3000/1/sessions 看到一条新 Session 出现(实际域名端口以 REACT_APP_FRONTEND_URI 为准)。点击该 Session 即可进入 Session 详情页,查看完整的回放与事件时间线——这标志着「前端采集 → 后端摄取 → ClickHouse 存储 → Dashboard 查询」的整条链路已经打通,你的本地开发环境可以正式投入使用了。

故障排查指南

如果部署过程中遇到问题,官方推荐按以下步骤逐一排查(命令来自 Quickstart 的 troubleshoot 步骤):

# 1. 检查容器健康状态
docker ps

# 2. 查看基础设施容器的日志
docker compose logs

# 3. 若容器不健康,清空整个 compose 栈重新来过
docker compose down --remove-orphans --volumes --rmi local

具体来说:

  1. docker ps:确认所有容器都处于 healthy 状态(而不是 starting 或 unhealthy);
  2. docker compose logs:查看各基础设施容器的输出。若发现容器不健康,结合上文提到的 /tmp/highlightSetup.log(迁移日志)与容器日志定位具体服务;
  3. docker compose down --remove-orphans --volumes --rmi local:该命令会删除 compose 栈中的所有容器、孤立容器、数据卷与本地构建镜像,实现「从零开始」的干净重置。注意 --volumes 会连带清空 ClickHouse/PostgreSQL 中的数据,非必要时慎用。

如果以上方法仍无法解决,可以到社区渠道寻求帮助。

深入阅读与相关资源

登录后查看全文
highlight