news 2026/10/6 15:48:50

SkyWalking 6.x 安装、调试与 Java Agent 探针接入实战指南

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
SkyWalking 6.x 安装、调试与 Java Agent 探针接入实战指南
  • 文档
  • 教程
  • 技术博客

【免费下载链接】Linux-Tutorial

《Java 程序员眼中的 Linux》

项目地址：https://gitcode.com/gh_mirrors/li/Linux-Tutorial
点击查看免费下载

SkyWalking 是 Apache 基金会下的开源 APM（Application Performance Monitoring）系统。本篇技术指南以《Java 程序员眼中的 Linux》仓库中的 SkyWalking-Install-And-Settings.md 为核心，系统梳理 SkyWalking 6.1 的源码构建、IntelliJ IDEA 运行与 Debug、OAP Server 与 UI 启动、Java Agent 探针接入（IDEA / jar / Docker 三种方式）以及部署到服务器等完整链路。读完本文，你将能够独立完成 SkyWalking 从环境准备、编译构建到业务应用无侵入接入的全流程实操，并对 APM 选型背景与探针工作原理有清晰认知。

一、OpenAPM 生态与选型背景

在开始安装之前，先理解 SkyWalking 所处的 APM 生态背景，这有助于明确它的定位与价值。

  • OpenAPM 工具全景：社区维护的 OpenAPM landscape 汇总了市面上绝大多数 APM 相关工具，可作为选型时的横向对比清单。
  • OpenTracing 标准：目前最活跃的分布式链路追踪标准，是一套与具体实现解耦的 API 规范，多数主流 APM 产品都与之兼容。
  • 当下活跃的开源方案：
    • Jaeger：由 CNCF 托管的分布式追踪系统，源于 Uber 开源实践；
    • SkyWalking：Apache 顶级项目，聚焦于服务端 APM，同时支持 Java Agent 无侵入探针与多种存储后端。

SkyWalking 的差异化优势在于其 Java Agent 探针可在不修改业务代码的前提下自动采集调用链、指标与日志关联信息，且内置大量主流框架的自动埋点支持。原文档也明确指出："国内常用的组件目前看来都支持了"，这对 Java 技术栈为主的团队尤其友好。

版本背景说明：本文内容基于原文档撰写时点（2019-05）的SkyWalking 6.1版本。彼时官网推荐通过源码构建出包，并推荐 Docker 镜像方式部署。后续大版本（如 8.x、9.x）在 UI 端口、存储选型、配置项上有所演进，本文保留 6.1 的完整实操细节，同时会在文中标注关键差异点供读者对照。

二、前置环境准备：JDK 8、Maven 3 与 Elasticsearch

根据原文档抽取的核心结论，SkyWalking 6.1 的源码构建与运行依赖如下：

  1. 至少需要 JDK 8 + Maven 3：OAP Server、Agent、Web UI 均为 Java 工程，源码构建必须满足此环境；
  2. 需要 Elasticsearch 作为存储后端：
    • 通过查看源码依赖的 Elasticsearch 客户端包，确认当时支持5.x 和 6.x两个大版本；
    • Elasticsearch 与 SkyWalking 所在服务器的时间必须保持一致，否则会导致时间戳错位、数据聚合异常。建议通过 NTP 等时间同步手段统一集群内时钟（仓库另有 NTP.md 可参考）。

2.1 环境准备可参考的仓库资料

本仓库恰好收录了完整的 JDK、Maven、Elasticsearch 安装资料，可配套使用：

组件仓库文档一键安装脚本
JDK 8JDK-Install.md（含 CentOS 卸载自带 OpenJDK、tar 解压安装、环境变量配置）install_jdk_online.sh、install_jdk_offline_to_bash.sh
Maven 3Maven-Install-And-Settings.mdinstall_maven_offline_to_bash.sh
Elasticsearch 5.x / 6.xElasticsearch-Base.md（Docker 单节点部署、CentOS RPM 安装、系统参数调优）—

其中 Elasticsearch-Base.md 提供了两种典型部署方式，可直接对接 SkyWalking：

  • Docker 方式：文档给出了 5.6.8 与 6.7.2（带 ik 分词）两套docker-compose.yml示例，核心配置为cluster.name=elasticsearch、network.host=0.0.0.0、xpack.security.enabled=false，并将 9200/9300 端口映射到宿主机；
  • RPM 方式（CentOS 7）：文档强调至少 2G 内存、JDK 1.8 起步，并给出fs.file-max=65535、vm.max_map_count=262144（写入/etc/sysctl.conf）以及/etc/security/limits.conf中的nofile、memlock限制调整，这些系统级参数正是 Elasticsearch 生产运行的关键调优项。

实操提示：Elasticsearch 5.x 与 6.x 的索引类型/映射行为有差异，SkyWalking 6.1 内部会针对版本差异做适配，直接使用文档支持的 5.x/6.x 均可；若升级 SkyWalking 到 7.x+，则需按新版要求选用 6.x 及以上版本。

三、从源码构建 SkyWalking

原文档推荐通过源码构建出包（这也是官网当时的主推方式）。构建命令如下：

cd skywalking/ git submodule init git submodule update mvn clean package -DskipTests

要点说明：

  • git submodule 必须初始化：SkyWalking 工程通过 submodule 管理部分第三方依赖与生成的协议代码，跳过这两步会导致编译失败；
  • -DskipTests：跳过测试用例执行，加速构建；若需要验证构建产物完整可用，可去掉该参数（构建时间会显著增加）；
  • 构建完成后，Java Agent 的产物路径为：skywalking/apm-sniffer/apm-agent/target/skywalking-agent.jar，后续探针接入会反复用到。

四、基于 IntelliJ IDEA 直接运行与 Debug

将 SkyWalking 源码导入 IntelliJ IDEA 后，可以直接以源码方式启动 OAP Server 与 UI，便于 Debug 理解其内部运行机制。这是阅读源码、二次开发最推荐的路径。

4.1 将生成代码目录标记为 Sources Root

SkyWalking 依赖 gRPC、ANTLR4、OAL 等代码生成框架，构建后生成的代码需要手工标记为 IDEA 的源码目录（Sources Root），否则 IDE 无法解析相关类。

gRPC 自动生成代码（protobuf 目录），需要标记grpc-java与java两个子目录：

/skywalking/apm-protocol/apm-network/target/generated-sources/protobuf /skywalking/oap-server/server-core/target/generated-sources/protobuf /skywalking/oap-server/server-receiver-plugin/receiver-proto/target/generated-sources/protobuf /skywalking/oap-server/exporter/target/generated-sources/protobuf

ANTLR4 自动生成代码：

/skywalking/oap-server/generate-tool-grammar/target/generated-sources

OAL（Observability Analysis Language）自动生成代码：

/skywalking/oap-server/generated-analysis/target/generated-sources

操作方式：在 IDEA 的 Project 面板中右键对应目录 → Mark Directory as → Sources Root。若目录为空，请先确认已执行mvn clean package -DskipTests完成代码生成。

4.2 启动 OAP Server

OAP Server（Observability Analysis Platform）是 SkyWalking 的后端聚合分析服务，负责接收 Agent 上报的数据、完成指标聚合与链路存储。

  • 编辑配置：/skywalking/oap-server/server-starter/src/main/resources/application.yml
    • 该文件包含 Elasticsearch 连接信息（地址、端口、索引前缀等），按实际环境修改即可；
    • 默认配置中storage部分选定 Elasticsearch 作为存储实现，core部分配置 gRPC/HTTP 接收端口（gRPC 默认 11800、HTTP 默认 12800）。
  • 启动类：/skywalking/oap-server/server-starter/src/main/java/org/apache/skywalking/oap/server/starter/OAPServerStartUp.java
  • 启动观察：第一次启动会自动创建 540 个左右的 Elasticsearch 索引库（按天分片的时间序列索引），因此首次启动耗时明显偏长，属正常现象，耐心等待即可。

4.3 启动 UI 项目

  • 启动类：/skywalking/apm-webapp/src/main/java/org/apache/skywalking/apm/webapp/ApplicationStartUp.java
  • 访问地址：http://127.0.0.1:8080
  • 默认账号：用户名admin，密码admin

UI 启动后即可看到服务拓扑、调用链追踪、指标面板等视图。在接入 Agent 并产生流量之前，界面数据为空属正常现象。

版本差异提示：SkyWalking 8.x 起 UI 与 OAP Server 合并发布，默认 UI 端口调整为 8080 之外的独立端口，且application.yml结构大幅调整；本文的目录结构与 6.1 对应，升级使用时请以对应版本官方文档为准。

五、Java Agent（探针）接入

Java Agent 是 SkyWalking 实现"无侵入埋点"的核心组件。业务服务通过-javaagent参数加载skywalking-agent.jar，在 JVM 启动阶段完成字节码增强，自动采集 HTTP、RPC、数据库、消息队列等调用链数据，并通过 gRPC 上报到 OAP Server。

原文档整理了三种接入方式：IDEA 调试、jar 包运行、Docker 容器。

5.1 引入 apm-toolkit-trace 依赖（可选增强）

探针本身无需修改业务代码即可工作；若希望在代码中手动埋点（自定义 Span、标记业务标签、获取 traceId），需要引入 toolkit 依赖。原文档给出的是 Maven 坐标（以 6.1.0 为例）：

<!--SkyWalking start--> <!-- https://mvnrepository.com/artifact/org.apache.skywalking/apm-toolkit-trace --> <dependency> <groupId>org.apache.skywalking</groupId> <artifactId>apm-toolkit-trace</artifactId> <version>6.1.0</version> </dependency> <!--SkyWalking end-->

5.2 常用注解与 API 示例

原文档给出了一个典型的 Controller 埋点示例，完整展示了@Trace、ActiveSpan.tag、TraceContext.traceId()的配合使用：

@Trace @ApiOperation(tags = {"用户系统管理->用户管理->用户列表"}, value = "查询所有用户列表", notes = "查询所有用户列表") @RequestMapping(value = "/list", method = RequestMethod.GET) @ResponseBody public List<SysUser> list() { List<SysUser> sysUserList = sysUserService.findAll(); ActiveSpan.tag("一共有数据：", sysUserList.size() + "条"); log.info("当前 traceId={}", TraceContext.traceId()); return sysUserList; }

逐行解读：

  • @Trace：将当前方法标记为一个可追踪的 Span（链路中的一个节点）。@Trace支持在任意方法上使用，探针会在方法进入/退出时自动生成 Span 并关联上下文；
  • ActiveSpan.tag(key, value)：向当前 Span 写入自定义标签，用于在链路查询时快速定位业务信息（如上例记录返回数据条数）；
  • TraceContext.traceId()：获取当前调用链的全局 traceId，可写入业务日志，实现"日志 ↔ 链路"关联检索；
  • 更多 toolkit 注解（如@Tag、@Tags、@Span等）可参考官方文档《Application-toolkit-trace》，此处仅保留原文档实战示例。

5.3 方式一：IntelliJ IDEA 项目调试

在 IDEA 中启动 Demo 工程时，于VM options中加入探针参数：

-javaagent:/你自己的路径/skywalking-agent.jar -Dskywalking.agent.application_code=my_app_001 -Dskywalking.collector.backend_service=localhost:11800

参数逐项说明：

参数含义说明
-javaagent:<path>加载探针路径指向构建产物skywalking/apm-sniffer/apm-agent/target/skywalking-agent.jar（或解压目录agent/skywalking-agent.jar）
-Dskywalking.agent.application_code应用编码在 UI 中用于区分不同业务应用，如my_app_001
-Dskywalking.collector.backend_serviceOAP 后端地址默认 11800 是 gRPC 接收接口，Agent 通过该端口上报数据

配置完成后启动应用，请求带有@Trace的 Controller 接口，稍等片刻即可在 UI 界面看到该应用的调用链与指标统计。

5.4 方式二：jar 包方式

Spring Boot 可执行 jar 在服务器上运行时，同样只需在java命令前追加探针参数：

java -javaagent:/你自己的路径/skywalking-agent.jar -Dskywalking.collector.backend_service=localhost:11800 -Dskywalking.agent.application_code=my_app_002 -jar my-project-1.0-SNAPSHOT.jar

对比 IDEA 方式，两者参数完全一致，差别仅在于application_code用于区分不同实例。此方式适合已通过mvn package产出 jar 的常规部署流程。

5.5 方式三：Docker 方式

容器化场景下，将探针目录与业务 jar 一起打进镜像，并通过环境变量注入参数。原文档给出了完整 Dockerfile 与运行命令：

Dockerfile：

FROM openjdk:8-jre-alpine LABEL maintainer="tanjian20150101@gmail.com" ENV SW_AGENT_NAMESPACE=java-agent-demo \ SW_AGENT_COLLECTOR_BACKEND_SERVICES=localhost:11800 COPY skywalking-agent /apache-skywalking-apm-bin/agent COPY target/sky-demo-1.0-SNAPSHOT.jar /demo.jar ENTRYPOINT java -javaagent:/apache-skywalking-apm-bin/agent/skywalking-agent.jar -jar /demo.jar

构建并运行：

docker build -t hello-demo . docker run -p 10101:10101 -e SW_AGENT_NAMESPACE=hello-world-demo-005 -e SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.10.0.2:11800 hello-demo

要点说明：

  • 环境变量与系统属性的对应关系：SkyWalking Agent 支持通过环境变量覆盖同名配置项——SW_AGENT_NAMESPACE对应-Dskywalking.agent.namespace（命名空间隔离），SW_AGENT_COLLECTOR_BACKEND_SERVICES对应-Dskywalking.collector.backend_service（后端地址，示例中为127.10.0.2:11800）。因此docker run时可通过-e动态覆盖镜像内的默认值，实现一套镜像多环境复用；
  • 若 OAP Server 不在本机，请将SW_AGENT_COLLECTOR_BACKEND_SERVICES指向宿主机可达的 OAP 地址（容器内不能直接使用localhost）；
  • 探针目录skywalking-agent应预先解压并置于构建上下文（即agent/skywalking-agent.jar所在目录）。

六、构建 jar 部署在服务器

若目标环境不具备 IDE 或 Docker，可直接构建出可部署的完整包，上传服务器运行。构建命令与第三节一致：

cd skywalking/ git submodule init git submodule update mvn clean package -DskipTests

构建产物位于各模块的target/目录下，部署服务器时只需关注：

  • OAP Server 包：oap-server/server-starter/target/下生成的发行包，内含application.yml与启动脚本；
  • Web UI 包：apm-webapp/target/下生成的 webapp 发行包；
  • Agent 包：apm-sniffer/apm-agent/target/skywalking-agent.jar，连同agent/config、agent/plugins等目录整体分发到业务服务器。

服务器部署的核心是保证 Agent 能通过网络访问 OAP Server 的 gRPC 端口（默认 11800），且 OAP Server 能访问 Elasticsearch（默认 9200）。首次上线建议按"Elasticsearch → OAP Server → UI → Agent"的顺序逐层验证连通性。

七、告警配置

原文档为告警配置提供了官方参考入口（指向 SkyWalking 官方中文博客的《监控微服务》系列文章）。结合 SkyWalking 6.1 的机制，告警功能的核心思路是：在 OAP Server 侧基于告警规则对聚合后的指标进行阈值判断，命中后触发 Webhook/邮件等通知，规则定义在 OAP Server 的告警配置文件（alarm-settings.yml，位于发行包的config/目录）中。

由于告警规则的具体字段（如指标名、比较符、阈值、周期、静默窗口）随版本演进差异较大，且原文档未给出完整示例，这里不展开虚构细节——建议以当前使用版本的官方告警文档为准，先基于默认规则文件改阈值，再逐步增加自定义指标告警。

八、总结

本文完整覆盖了 SkyWalking 6.1 从选型、环境准备、源码构建、IDEA 调试到三种 Agent 接入方式的全部实操路径，核心要点可概括为：

  1. 依赖关系清晰：JDK 8 + Maven 3 构建，Elasticsearch 5.x/6.x 存储，且服务器间时间必须一致；
  2. 调试链路完整：IDEA 中标记 gRPC/ANTLR4/OAL 生成目录为 Sources Root，即可启动OAPServerStartUp与ApplicationStartUp进行断点调试，首次启动约创建 540 个索引库属正常现象；
  3. 接入方式灵活：-javaagent参数 +-Dskywalking.agent.application_code+-Dskywalking.collector.backend_service=localhost:11800三件套，在 IDEA、jar、Docker 三种场景下通用；
  4. 无侵入与手动埋点并存：纯 Agent 即可完成自动采集，apm-toolkit-trace的@Trace/ActiveSpan/TraceContext则提供精细化埋点能力。

本仓库还提供了 TOC.md 与 SUMMARY.md 两份目录索引，以及配套的 JDK-Install.md、Maven-Install-And-Settings.md、Elasticsearch-Base.md、NTP.md 等环境建设文档，可与本文配合构成完整的 SkyWalking 落地工具箱。

  • 文档
  • 教程
  • 技术博客

【免费下载链接】Linux-Tutorial

《Java 程序员眼中的 Linux》

项目地址：https://gitcode.com/gh_mirrors/li/Linux-Tutorial
点击查看免费下载
上一篇：从0到1开发Treemacs扩展：构建个性化Emacs树形视图
下一篇：使用yomotsu/camera-controls实现3D模型自适应视口功能详解

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/10/6 15:46:05

运放全参数仿真自动化：Cadence Virtuoso与Ocean脚本实战

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/10/6 15:42:17

YOLOv8+HCA-Net野生动物实时监测实战指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/10/6 15:40:40

report_timing命令详解：数字后端时序收敛的核心工具

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/10/6 15:39:47

Altium Designer嘉立创工艺规则配置实战指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/10/6 15:36:51

DeepSeek大模型智慧办公落地：从API调用到私有化部署的完整指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/10/6 15:36:48

双脉冲测试：IGBT开关性能验证的核心方法

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华