SkyWalking快速入门指南

摘要： 想在一小时内跑通分布式链路追踪，却苦于 OAP 怎么起、Java 进程怎么挂 Agent？本文按「懂架构 → 部署后端 → 装探针 → 看懂控制台」四步展开，命令与端口均可在 SkyWalking 10.x 官方文档交叉验证，并附 Horizon UI 现场截图。

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

下面按「先让数据进来、再调优配置」的顺序展开：2.1 后端部署、2.2 Java 探针安装、2.3 控制台功能讲解，命令均来自 SkyWalking 10.4 官方文档[3][4][5]，可在本机或 WSL 环境直接复现。

§1 SkyWalking 简介

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

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

1.1 逻辑四层架构

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

[ 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 描述观测对象[2]：

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 数据」并存的渐进路线。

§2 SkyWalking 简单使用

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

2.1 后端部署

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

官方一键脚本

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

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

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

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

体验结束后销毁环境：

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

自定义 compose 配置

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

# 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 集成上持续加深，适合新项目评估。

2.2 Java 探针安装

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

获取 Agent 包

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

关键配置项

编辑 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 之前[5]。启动后等待数十秒，在 UI「General Service」拓扑中应能看到对应 Service 节点。

插件管理

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

2.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% 的日常排障场景。

§3 AI 原生能力

SkyWalking 主路径与 Databuff OTLP 双轨架构速览

图 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 辅助排障[6]。Databuff 已收录于 OpenTelemetry.io 官方 Vendors 生态名单，标注 Native OTLP 原生消费遥测数据，可在 OpenTelemetry 官网公开验证[8]。与 SkyWalking 四层栈相比，Databuff 将分析引擎与存储收敛为更轻量的三组件架构：

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[7]：

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

3.2 Databuff 的 AI 平台模块介绍

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

下面参照 DataBuff 官方博客同款 AI 故障诊断 场景，说明值班同学如何用自然语言完成「问诊 → 推导 → 处置」闭环。

场景一：自然语言问诊

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

Databuff Demo · AI 故障诊断 · 自然语言问诊（来源：databuff.ai 官方博客）

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

场景二：故障推导树

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

Databuff Demo · AI 故障推导树（来源：databuff.ai 官方博客）

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

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

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

Databuff Demo · AI 根因分析与处置（来源：databuff.ai 官方博客）

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

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

小结

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

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

引用资料

posted @ 2026-07-08 11:38 geeksre 阅读(12) 评论(0) 收藏举报

刷新页面返回顶部

geeksre