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 -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

服务	端口	用途
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 -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 等服务，以及调用数、错误率、响应时间等指标------这是应用性能监控的入口视图。

图 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 是否已设置

---

§6 能力边界、Roadmap 与许可

诚实标注「今天能用什么」与「规划中什么」。

v0.1 已交付（本文覆盖范围）：

• OTLP Trace / Metrics 接入与全链路追踪
• 服务列表、全局拓扑、服务流、接口分析、告警中心
• AI 平台：多智能体问数、巡检（需配置 LLM Key）
• Docker / K8s 一键部署

Roadmap · 规划中（尚未交付，勿当作现有能力宣传）：

1. One-Agent 开源 --- 统一采集 Agent（Trace / 指标 / 日志 / 主机）
2. OpenTelemetry 日志 --- OTLP Logs 接入与 Trace 关联
3. eBPF 无侵入 APM --- 零代码改动内核级采集
4. Agent 观测 --- LLM / AI Agent 调用链、Token、工具调用追踪
5. AI Agent 记忆 --- 跨会话持久化诊断上下文

许可说明： Databuff 采用 GNU Affero General Public License v3.0（AGPL-3.0），非 Apache 2.0。若你在 SaaS 或网络服务中提供基于 Databuff 的可观测能力，需遵守 AGPL 源码开放义务。

---