SkyWalking快速入门指南

SkyWalking · 开源 APM · OpenTelemetry · Databuff · 全链路追踪

很多初学者把 SkyWalking 当成「又一个 Zipkin」——其实它是一套覆盖 Trace、Metrics、Logs、Profiling 的云原生可观测平台。下文从官方四层架构出发，用 Docker 脚本快速起后端、用 Java Agent 无侵入接入业务，再对照 Demo 控制台讲解拓扑与链路查询；最后简要介绍 AI 原生可观测方案 Databuff，供后续演进参考。

1SkyWalking 简介

Apache SkyWalking 是一套完整的应用性能监控（APM）与可观测性分析系统。与只做链路展示的轻量工具不同，它在同一平台内聚合五类遥测数据：

Tracing（链路追踪）：原生 Segment 格式，兼容 Zipkin v1/v2
Metrics（指标）：原生 Meter、OpenTelemetry Metrics、Telegraf；可与 Istio/Envoy 集成
Logging（日志）：磁盘或网络采集，Agent 可自动绑定 Trace 上下文
Profiling（性能剖析）：语言 Agent 与 eBPF Agent 提供代码级热点分析
Event（事件）：记录发布、配置变更等关键事件，与指标/链路关联排障

1.1 逻辑四层架构

官方文档将 SkyWalking 逻辑划分为四段，理解这四层是快速入门的前提：

[ Probe 探针 ]  →  gRPC / OTLP / Zipkin / Prometheus …
        ↓
[ OAP 平台后端 ]  →  聚合 · 流式分析 · 告警规则
        ↓
[ Storage 存储 ]  →  Elasticsearch / BanyanDB / JDBC …
        ↓
[ UI ]  →  拓扑 · Trace · 指标 · 日志 · Profiling

图 1-1 · Probe 采集多协议遥测，OAP 承担分析与聚合，Storage 插件化选型，UI 提供可视化控制台。v10.x 起 Booster UI 逐步演进为 Horizon UI。

1.2 核心数据模型

SkyWalking 用 Service → Service Instance → Endpoint → Process 描述观测对象：

Service：一组提供相同行为的工作负载（如 order-service）
Service Instance：Service 下的单个实例，Java Agent 场景通常对应一个 OS 进程
Endpoint：HTTP URI 或 gRPC 方法签名等入口路径
Process：进程级元数据，便于与 K8s Pod 关联

跨 K8s、Mesh、OS 等多 Layer 时，可通过 Service Hierarchy 关联同一逻辑服务在不同层级的视图。这也是 Horizon UI 左侧按 Layer 分组导航的原因。

Probe 形态丰富：除 Java/C#/Go/Node.js/PHP/Python 等语言 Agent 外，还支持 Service Mesh Receiver、eBPF K8s 监控，以及 OpenTelemetry、Prometheus、Zipkin 等第三方格式接入——适合「存量 Agent + 新 OTel 数据」并存的渐进路线。

◆ ◆ ◆

2SkyWalking 简单使用

三步跑通：起后端 → 挂 Java Agent → 在 UI 中验证数据

入门实践建议遵循「先让数据进来、再调优配置」的顺序。下面 2.1–2.3 分别对应后端部署、Java 探针安装与控制台功能讲解，命令均来自 SkyWalking 10.4 官方文档，可在本机或 WSL 环境直接复现。

◆ ◆ ◆

3.1 后端部署

Docker Quick Start 是最快的体验路径；生产环境需单独规划 Storage 集群

官方一键脚本

SkyWalking 文档页提供交互式脚本，启动时会提示选择 Elasticsearch 或 BanyanDB 作为存储后端，并拉起 OAP + UI。

Linux / macOS / WSL：

bash <(curl -sSL https://skywalking.apache.org/quickstart-docker.sh)

Windows PowerShell：

Invoke-Expression ([System.Text.Encoding]::UTF8.GetString(
  (Invoke-WebRequest -Uri https://skywalking.apache.org/quickstart-docker.ps1 -UseBasicParsing).Content))

脚本完成后，典型端口如下：

Agent / gRPC 上报：11800（OAP 默认 collector 端口）
OAP HTTP REST：12800
UI 控制台：8080（浏览器访问）

体验结束后销毁环境：

docker compose --project-name=skywalking-quickstart down

自定义 compose 配置

若需指定镜像版本或存储类型，可在官方仓库使用 profile 启动：

# Elasticsearch 存储
docker compose --profile elasticsearch up

# BanyanDB 存储（SkyWalking 自研时序+追踪库）
docker compose --profile banyandb up

也可单独运行 OAP 容器并指定 BanyanDB 后端：

export RELEASE_VERSION=10.4.0
docker run --name oap -d --restart always \
  -e SW_STORAGE=banyandb \
  -e SW_STORAGE_BANYANDB_TARGETS=banyandb:17912 \
  apache/skywalking-oap-server:${RELEASE_VERSION}

运维提示：生产环境常见拓扑是「OAP 集群 + ES/OpenSearch 或 BanyanDB 集群 + UI」。Storage 选型直接决定磁盘成本与 Trace 查询延迟；10.x 版本在 BanyanDB 集成上持续加深，适合新项目评估。

◆ ◆ ◆

4.2 Java 探针安装

字节码增强、无侵入接入；JDK 8–25 可用

获取 Agent 包

从 Apache SkyWalking Java Agent 发行包中解压 agent/ 目录，核心文件为 skywalking-agent.jar，插件位于 plugins/，配置位于 config/agent.config。

关键配置项

编辑 agent.config（或通过环境变量覆盖）：

# 服务名（英文标识，UI 中展示）
agent.service_name=${SW_AGENT_NAME:YourAppName}

# OAP 地址（默认本机 11800）
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}

在 Docker Compose 或 K8s 中，常用环境变量写法：

SW_AGENT_NAME=order-service
SW_AGENT_COLLECTOR_BACKEND_SERVICES=oap:11800

挂载到 JVM

可执行 JAR：

java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar \
     -jar yourApp.jar

IDEA 本地调试：在 Run Configuration → VM options 中添加：

-javaagent:D:\skywalking-agent\skywalking-agent.jar
-Dskywalking.agent.service_name=demo-app
-Dskywalking.collector.backend_service=127.0.0.1:11800

Tomcat（catalina.sh 首行）：

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/skywalking-agent.jar"; export CATALINA_OPTS

注意 -javaagent 必须放在 -jar 之前。启动后等待数十秒，在 UI「General Service」拓扑中应能看到对应 Service 节点。

插件管理

plugins/ 目录下插件默认全部启用，覆盖 Dubbo、Feign、HttpClient、JDBC 等常见中间件；删除某个 jar 即可禁用对应探针。可选插件在 optional-plugins/，按需拷贝到 plugins/ 激活。

◆ ◆ ◆

5.3 功能界面解释

以 Horizon UI 为例，对照官方 Demo 讲解核心视图

完成部署与探针接入后，打开 UI（默认 8080 端口，Demo 地址为 demo.skywalking.apache.org）。Horizon UI 左侧按 Layer 分组，「通用服务（General Service）」是最常用的入口。下面结合现场截图说明三个核心面板。

服务拓扑（Topology）

拓扑图展示服务间的调用依赖关系，节点大小反映流量，连线颜色标识健康状态。点击某个 Service 可下钻到实例、API 与 Trace 列表——这是排障时「先看全局、再定位单点」的第一步。

图 2-1 · 拓扑视图展示 gateway、app、user 等服务的调用关系与 RPM/错误率指标，可直观发现异常节点。

服务仪表板（Services Dashboard）

仪表板按 Layer 汇总所有 Service 的 RED 指标（请求量、错误率、响应延迟），支持按 APDEX、SLA 等维度排序。适合值班同学快速扫描「哪个服务今天变慢了」。

图 2-2 · 服务仪表板列出各 Service 的 RPM、成功率、P99 延迟，顶部告警入口显示当前活跃告警数。

链路追踪（Traces）

Trace 面板支持按实例、Endpoint、状态（成功/错误）、耗时区间、Trace ID 等条件筛选。点击「执行查询」后，列表展示每条 Trace 的 Endpoint、耗时条与状态标签；右侧分布图用散点标识正常与异常请求的时间分布。

图 2-3 · Trace 列表展示 /homepage 等 Endpoint 的耗时条（绿色正常、红色错误），可进一步点开查看 Span 瀑布图定位慢调用。

除上述三视图外，Horizon UI 还提供 Logs（日志与 Trace 关联）、告警（规则触发与通知）、Profiling（Trace Profiling / eBPF）等进阶能力。入门阶段掌握拓扑 + Trace 即可覆盖 80% 的日常排障场景。

◆ ◆ ◆

6AI 原生能力

图 3-0 · 同一 Probe 可经 gRPC 11800 走 SkyWalking 四层栈，或经 OTLP 4318 接入 Databuff 三组件栈，后者在 Web 平台内置 AI 问数能力。

需要说明的是：SkyWalking 目前尚未提供内置的 AI 智能体能力——控制台以拓扑、Trace、指标、日志等可视化查询为主，尚不支持自然语言问数或多智能体协同排障。若团队希望在跑通 SkyWalking 之后进一步探索「AI 辅助值班」，可以了解一下另一款国产开源项目 Databuff，它在 APM 存储之上内置了 AI 平台模块，下文作简要介绍。

3.1 Databuff 简介

Databuff 是面向 OpenTelemetry 标准的开源 APM，默认接收 OTLP Trace 与 Metrics，在同一存储上提供查询、告警与 AI 辅助排障。Databuff 已收录于 OpenTelemetry.io 官方 Vendors 生态名单，标注 Native OTLP 原生消费遥测数据，可在 OpenTelemetry 官网公开验证。与 SkyWalking 四层栈相比，Databuff 将分析引擎与存储收敛为更轻量的三组件架构：

图 3-1 · OTel 数据经 Ingest 接入，Doris 统一存储 Trace/指标/拓扑，Web 平台承载 APM UI 与 AI 多智能体。

[ OpenTelemetry SDK / Java Agent ]
        │ OTLP gRPC 4317 / HTTP 4318
        ▼
[ Ingest 接入 ] ── Trace 组装 · 指标分钟聚合
        ▼
[ Doris 统一存储 ] ── Trace / 指标 / 拓扑 / 告警
        ▼
[ Web 平台 ] ── APM UI + AI 多智能体

应用侧使用标准 OTel 环境变量即可接入，无需专有 Agent 协议。一条安装脚本可在 Docker 环境拉起 Demo：

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

3.2 Databuff 的 AI 平台模块介绍

许多 APM 工具的 AI 只是通用聊天窗；Databuff AI 平台的差异在于：通过 Skill 调用平台工具，直接查询 Doris 里已入库的 OTel 数据——不是读文档猜答案，而是拉取真实 Trace、RED 指标与拓扑关系后再推理。核心模块包括 Brain（意图拆解）、Query 专家（指标/链路查询）、Inspection 专家（异常巡检）与 MCP 扩展（对接 CMDB、工单等周边系统）。

下面参照 DataBuff 官方博客 (https://databuff.ai/blog/zh/databuff-joins-opentelemetry/) 同款 AI 故障诊断 场景，说明值班同学如何用自然语言完成「问诊 → 推导 → 处置」闭环。

场景一：自然语言问诊

在 AI 对话中输入「拓扑节点变红，帮我诊断原因」等描述，AI 大脑接收意图并派发 Query / Inspection 专家，从 APM 存储拉取相关服务的耗时、错误率与拓扑上下文——把「翻面板找线索」压缩成一句话。

图 3-2 · 询问服务故障原因：中文对话界面展示用户提问与 AI 大脑启动多步推理过程。

场景二：故障推导树

专家协同拉取服务耗时趋势、交叉验证拓扑与 Trace 后，输出结构化故障推导树：哪个节点异常、上下游谁受影响、证据来自哪条指标或 Span——排障路径一目了然。

图 3-3 · AI 给出故障推导树：将 OTel 存储中的拓扑、指标与链路关系组织为可追问的推理路径。

场景三：根因分析与处置建议

推导完成后，AI 进一步给出根因定位、处理意见与总结，把分布式追踪数据翻译为可执行的值班动作——从「看到告警」到「知道下一步做什么」在同一会话内完成。

图 3-4 · AI 给出根因分析与处理意见：结构化报告含根因、建议操作与排障摘要，数据均来自真实 APM 存储。

演进建议若团队已按本文完成 SkyWalking 后端 + Java Agent 接入，可保留存量链路；对新微服务并行挂载 OTel Agent 指向 Databuff，用同一业务流量对比「部署步骤、UI 查询、AI 问数」三项体验。二者并非互斥——SkyWalking OAP 本身也支持 OTLP Receiver，适合渐进式演进。

◆ ◆ ◆

7小结

Gartner 在可观测性平台研究中强调，系统复杂度的飞升和运营负担激增，推动了对 AI SRE 智能体的主动管理和可靠性的需求。在这一背景下，可观测工具正在从「人工翻面板」向「AI 辅助决策」演进。

SkyWalking 快速入门的核心路径是：理解四层架构 → Docker 脚本起 OAP + UI → -javaagent 挂 Java 进程 → 在拓扑与 Trace 面板验证数据。Horizon UI 将服务依赖、RED 指标与链路详情整合在同一控制台，足以支撑日常排障。需要 AI 智能体能力时，可进一步了解 Databuff 的 OTLP 三组件栈与 AI 问数模块，在真实流量上对比两种方案的落地体验。

◆ ◆ ◆

8引用资料

1. https://skywalking.apache.org/docs/main/v10.4.0/readme/
2. https://skywalking.apache.org/docs/main/v10.4.0/en/concepts-and-designs/overview/
3. https://skywalking.apache.org/docs/main/v10.4.0/en/setup/backend/backend-docker/
4. https://github.com/apache/skywalking/tree/v10.4.0/docker
5. https://skywalking.apache.org/docs/skywalking-java/v9.6.0/en/setup/service-agent/java-agent/readme/
6. https://www.databuff.ai/
7. https://www.databuff.ai/databuff/ai-apm-install.sh
8. https://opentelemetry.io/ecosystem/vendors/ （OpenTelemetry 官方 Vendors 生态名单 · Databuff 条目）
9. https://www.gartner.com/reviews/market/observability-platforms （Gartner Observability Platforms 市场定义与 AI 可观测论述）

◆ ◆ ◆

了解更多：github.com/databufflabs/databuff