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 等多组件栈，部署与运维成本显著降低。

对比维度	专有 Agent APM	OTLP + 开源 APM（Databuff）
接入协议	厂商私有格式	OTLP gRPC 4317 / HTTP 4318
应用改造	绑定特定 SDK	任意 OTel SDK / Auto-Instrumentation
部署组件	Probe + OAP + Storage + UI 等	Ingest + Doris + Web（3 容器）
许可	商业 / 混合开源	AGPL-3.0全栈开源

源码中 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-fsSLhttps://databuff.ai/databuff/ai-apm-install.sh|bash# 指定版本curl-fsSLhttps://databuff.ai/databuff/ai-apm-install.sh|bash-s----version0.1.1

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

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

服务	端口	用途
Web UI	27403	应用性能监控控制台、AI 平台入口
Ingest (OTLP HTTP)	4318	Trace / Metrics HTTP 上报
Ingest (OTLP gRPC)	4317	Trace / Metrics gRPC 上报
Doris FE	8030 / 9030	存储引擎（内部，一般无需直连）

常用运维命令：

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

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

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

Demo 一键造数

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

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

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

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

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

exportOTEL_SERVICE_NAME=order-serviceexportOTEL_EXPORTER_OTLP_ENDPOINT=http://<ingest-host>:4318exportOTEL_EXPORTER_OTLP_PROTOCOL=http/protobufjava-javaagent:opentelemetry-javaagent.jar-jarorder-service.jar

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

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

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

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

Step 1 · 服务列表

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

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

Step 2 · 全局大盘

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

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

Step 3 · 链路追踪首条 Trace

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

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

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

§5 常见问题

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

问题	原因 / 处理
4317 / 4318 端口不通	检查云安全组 / iptables 是否放行；容器内用`curl http://127.0.0.1:4318/health`确认 Ingest 健康；业务侧 Exporter 地址填宿主机 IP而非 Docker 内部 hostname（跨主机上报时）
8 GB 内存够吗？	本地开发 / Demo 验证足够。Doris FE 768m + BE 3G + ingest/web 各 384m，合计约 5 GB 容器上限；生产建议 16 GB+ 并调大 Doris 堆内存
AI 问数需要 LLM Key 吗？	APM 链路追踪不依赖 LLM，无 Key 也能完整使用服务列表、拓扑、Trace。AI 平台需在「配置管理 → 模型配置」填入 API Key 后启用智能问数 / 巡检（可选）
安装脚本报 Docker 不可用	确认`docker info`正常、当前用户为 root；Compose 需 v2 及以上
服务列表为空	先装 Demo 或确认应用 Exporter 已指向正确 Ingest；等待 1–2 分钟让分钟级聚合完成；检查`OTEL_SERVICE_NAME`是否已设置