5分钟部署开源APM Databuff：OpenTelemetry全链路追踪入门实战

面向首次接触开源 APM 的后端与 DevOps 工程师——一条 curl 命令跑起平台，配置标准 OTLP 接入，在 Web UI 里看到第一条分布式追踪。

§1 为什么选 OTLP 标准 + 开源 APM

告别专有 Agent 绑定，用 OpenTelemetry 生态通用协议接入应用性能监控。

痛点： 传统 APM 往往绑定自家探针，换后端就要改 SDK、重采数据。OpenTelemetry（OTel）把 Trace / Metrics / Logs 统一成 OTLP 协议，应用侧只需配置 Exporter 指向后端 Ingest 地址，即可实现应用性能监控与全链路追踪。

Databuff 是国产开源 APM，以 OTLP 为唯一接入标准。架构上只有三个核心容器：Ingest（接入）、Doris（存储）、Web（平台），对比 SkyWalking 等多组件栈，部署与运维成本显著降低。

源码中 Ingest 服务暴露的标准 OTLP 端口定义如下（deploy/local/docker-compose.yml）：

  ai-apm-ingest:
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

入门建议： HTTP 4318 端点 http://<host>:4318/v1/traces 对 curl / Demo / 多数 SDK 最友好；gRPC 4317 适合高吞吐生产场景。

§2 环境准备与 ai-apm-install.sh 安装

Docker + Compose · root 执行 · 约 5 分钟出 Web UI

前置条件

• 操作系统： Linux（amd64 / arm64 均支持，脚本自动识别架构下载镜像包）
• 依赖： Docker、Docker Compose、curl、tar
• 权限： 需 root 运行（安装目录默认 /opt/databuff-ai-apm）
• 内存： 建议 ≥ 8 GB 可用内存（Doris FE/BE + 三服务容器）

一条命令安装平台

官方安装脚本 ai-apm-install.sh 完成 5 步全自动流程：检查环境 → 下载部署包 → 加载镜像 → 清理旧版本 → 安装并启动。

# 最新版一键安装
curl -fsSL https://databuff.ai/databuff/ai-apm-install.sh | bash

# 指定版本
curl -fsSL https://databuff.ai/databuff/ai-apm-install.sh | bash -s -- --version 0.1.1

安装成功后，脚本 show_summary() 会打印 Web UI、默认账号与 Ingest 地址：

Web UI http://<host-ip>:27403 账号 admin / Databuff@123 Ingest http://<host-ip>:4318/v1/traces

常用运维命令：

cd /opt/databuff-ai-apm
./start.sh    # 启动
./stop.sh     # 停止

§3 Demo 应用安装与 OTLP Exporter 配置

不想先改业务代码？先装 Demo 造数，再对照配置自己的应用。

Demo 一键造数

平台装好后，执行 Demo 安装脚本，会持续向 Ingest 上报模拟 Trace，打开 UI 即可看到服务拓扑与全链路追踪数据。

curl -fsSL https://databuff.ai/databuff/ai-apm-demo-install.sh | bash

Demo 容器通过环境变量指向 Ingest，与业务应用配置方式一致：

  ai-apm-demo:
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://ai-apm-ingest:4318
      SEED_INTERVAL_SECONDS: 30

自有应用接入示例（Java / Spring Boot，OpenTelemetry Java Agent）：

export OTEL_SERVICE_NAME=order-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<ingest-host>:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
java -javaagent:opentelemetry-javaagent.jar -jar order-service.jar

Node.js（@opentelemetry/sdk-node）核心配置：

const exporter = new OTLPTraceExporter({
  url: 'http://<ingest-host>:4318/v1/traces',
});
// serviceName 设为可识别的服务名，便于服务列表聚合

验证上报是否成功： 安装 Demo 后等待约 30 秒（SEED_INTERVAL_SECONDS），刷新 Web UI 服务列表；若仍为空，检查防火墙是否放行 4318 端口、Exporter URL 是否带 /v1/traces 后缀（HTTP 协议）。

§4 Web UI 验证：服务列表 → 链路追踪

登录 http://<host>:27403，按「拓扑 → 指标 → 链路」路径确认数据可见。

Step 1 · 服务列表

进入应用性能 → 服务，可看到 Demo 产生的 service-a、service-b 等服务，以及调用数、错误率、响应时间等指标——这是应用性能监控的入口视图。

Databuff 服务列表

图 1 · 服务列表 — Top 图表 + 服务表格，证明 OTLP 数据已成功入库

Step 2 · 全局大盘

打开全局大盘，按分钟查看各服务健康时间轴与告警分布，快速判断整体运行态势。

Databuff 全局大盘

图 2 · 全局大盘 — 各服务健康时间轴一览

Step 3 · 链路追踪首条 Trace

进入应用性能 → 链路追踪，选择最近 1 小时时间范围，即可看到 Trace 数量分布与响应时间散点图。点击任意 Trace 可下钻到 Span 瀑布图，完成从「部署」到「看到第一条分布式追踪」的闭环。

Databuff 链路追踪列表

图 3 · 链路追踪 — Trace 数量与响应时间分布，分布式追踪能力验证

推荐排查路径： 全局拓扑发现异常节点 → 服务详情确认指标 → 链路追踪定位慢 Span。

§5 常见问题

部署与接入阶段最高频的问题：