搬瓦工部署 Highlight 会话回放平台教程

Highlight 是一款开源的全栈可观测平台，其核心亮点是会话回放（Session Replay）功能。它能够录制用户在前端页面上的每一次点击、滚动和输入操作，当用户遇到错误时，开发者可以像观看视频一样回放用户的操作过程，从而快速理解问题的上下文。除了会话回放，Highlight 还提供错误追踪和日志收集功能。本文将介绍如何在搬瓦工 VPS 上部署 Highlight。部署前请确保已安装 Docker 和 Docker Compose。

一、Highlight 核心功能

会话回放：录制并回放用户在前端的完整操作，包括 DOM 变化、鼠标移动和网络请求。
错误追踪：自动捕获前端和后端异常，关联到具体的用户会话。
日志收集：收集后端应用的日志数据，支持全文搜索。
追踪：分布式追踪能力，追踪请求在各服务间的流转。
隐私保护：支持配置敏感数据脱敏规则。
团队协作：支持在回放中添加评论，方便团队沟通。

二、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 4GB，推荐 8GB。
CPU：至少 2 核。
磁盘：至少 20GB 可用空间。
Docker：Docker 和 Docker Compose。

建议选择搬瓦工高配方案。购买时使用优惠码 NODESEEK2026 可享 6.77% 折扣，购买入口：bwh81.net。

三、克隆项目并部署

cd /opt
git clone --recurse-submodules https://github.com/highlight/highlight.git
cd highlight/docker

四、配置环境变量

cp .env.example .env

编辑 .env 文件，修改以下关键配置：

# 前端访问地址
REACT_APP_FRONTEND_URI=https://your_domain.com
# 后端 API 地址
REACT_APP_PUBLIC_GRAPH_URI=https://your_domain.com/public
# 管理员邮箱
ADMIN_EMAIL=admin@example.com

五、启动服务

cd /opt/highlight/docker
docker compose up -d

查看服务状态：

docker compose ps

Highlight 默认在端口 3000（前端）和 8082（后端）上运行。

六、前端 SDK 接入

在你的 Web 应用中接入 Highlight SDK：

// npm install highlight.run

import { H } from 'highlight.run';

H.init('your_project_id', {
  serviceName: 'my-frontend-app',
  tracingOrigins: true,
  networkRecording: {
    enabled: true,
    recordHeadersAndBody: true,
  },
  backendUrl: 'https://your_domain.com/public',
});

// 标识用户（可选）
H.identify('user@example.com', {
  name: '张三',
  plan: 'premium',
});

七、后端 SDK 接入（Python）

# pip install highlight-io

import highlight_io
from highlight_io.integrations.flask import FlaskIntegration

H = highlight_io.H(
    "your_project_id",
    integrations=[FlaskIntegration()],
    instrument_logging=True,
    otlp_endpoint="https://your_domain.com:4318",
)

八、配置反向代理

cat > /etc/nginx/sites-available/highlight <<'EOF'
server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /public {
        proxy_pass http://127.0.0.1:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

ln -s /etc/nginx/sites-available/highlight /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d your_domain.com

九、使用会话回放

SDK 接入后，用户的操作会自动被录制。在 Highlight 控制台中：

在 Sessions 页面查看所有录制的会话。
点击具体会话，可以像视频一样回放用户的操作。
回放中会标记错误发生的时间点，可直接跳转查看。
在 Errors 页面查看所有捕获的异常，每个错误都关联到用户会话。

十、常见问题

会话录制未出现

确认前端 SDK 的 backendUrl 配置正确，检查浏览器控制台是否有网络请求错误。

磁盘空间增长过快

会话回放数据量较大，可以在项目设置中限制录制采样率或缩短数据保留时间。

总结

Highlight 的会话回放功能为错误排查提供了独特的视角，让开发者能够真实地看到用户遇到的问题。如果你只需要错误追踪功能，可以参考更轻量的 GlitchTip；如需完整的 APM 方案，参考 SigNoz。选购搬瓦工 VPS 使用优惠码 NODESEEK2026 可享 6.77% 折扣。