简介本资源是一个面向Java后端开发者与微服务监控初学者的Spring Boot集成SkyWalking实战演示项目旨在解决分布式系统中链路追踪、性能分析与故障定位的学习门槛问题。项目完整呈现Trace、Span、Logs、Tags等核心概念的代码级实现与可视化验证适用于微服务架构实践、APM工具入门及可观测性技术教学场景。压缩包共13个文件含2个关键Java启动类体现探针注入与API调用链、2份Markdown文档含环境搭建说明与原理图解、6张架构与UI界面截图直观展示SkyWalking服务端拓扑与追踪详情、1个pom.xml依赖配置、1个application.properties配置文件及LICENSE协议文件整体体积仅537KB轻量易导入。已有189人学习下载读者可直接运行获得可工作的端到端演示环境快速掌握SkyWalking Agent接入、跨服务追踪埋点、UI仪表盘解读及基础告警配置等核心能力。1. 项目概述为什么我们需要一个SkyWalking演示项目如果你正在使用或计划使用Spring Boot构建微服务那么“可观测性”这个词对你来说一定不陌生。当你的服务从一个单体应用拆分成十几个、甚至几十个相互调用的独立服务时一个请求的完整路径就像在城市里玩一场复杂的“接力赛”。如果其中一棒跑慢了、跑丢了或者干脆摔倒了你该如何快速定位问题出在哪条街道、哪个选手身上靠传统的日志那无异于大海捞针。这正是分布式链路追踪工具比如我们今天要拆解的SkyWalking大显身手的地方。这个名为“基于Spring Boot的SkyWalking演示项目 .zip”的压缩包在我看来绝不仅仅是一个简单的“Hello World”示例。它是一个精心设计的、用于学习和验证的“沙箱”。它解决的核心痛点非常明确降低SkyWalking与Spring Boot集成实践的门槛。很多开发者包括我自己在初次接触时都卡在了第一步文档看了概念懂了但代码一跑起来SkyWalking的UI里就是看不到数据或者数据不全。这个演示项目就是为了让你绕过这些“坑”直接看到一个能跑通、能出数据的完整案例从而快速理解链路追踪的核心价值和工作原理。它适合谁呢首先是Spring Boot的初中级开发者尤其是那些项目正从单体向微服务演进急需引入监控手段的团队。其次是运维或SRE工程师他们需要理解应用如何上报数据以便更好地配置和维护SkyWalking服务端。最后它也适合技术决策者或架构师通过这个可运行的Demo可以直观地评估SkyWalking是否能满足团队的监控需求为技术选型提供实践依据。简单说这个项目就是一个“开箱即用”的脚手架帮你把SkyWalking的Agent探针如何嵌入Spring Boot应用、如何上报数据到后端OAPObservability Analysis Platform服务器、以及最终如何在UI上呈现链路和指标这一整套流程给串起来并跑通。接下来我们就深入这个“沙箱”看看它里面到底藏了哪些门道以及如何基于它进行更深入的定制和问题排查。2. 项目核心设计与思路拆解拿到一个演示项目我习惯先不看代码而是思考它的设计意图。一个优秀的演示项目其价值在于用最小的复杂度清晰地展示核心集成路径和关键配置。这个SkyWalking演示项目我认为其设计思路可以拆解为以下几个层次。2.1 技术栈选型与版本锁定从热搜词可以看到Spring Boot的版本众多从2.1、2.6到最新的4.x。SkyWalking本身也在快速迭代。版本不匹配是集成失败最常见的原因之一。因此这个演示项目的首要任务就是锁定一个经过验证的、兼容的技术栈组合。一个合理的选型可能是Spring Boot 2.7.x SkyWalking Java Agent 8.x/9.x SkyWalking OAP/UI 9.x。为什么是这些版本Spring Boot 2.7.x这是一个长期支持LTS版本生态稳定且是Spring Boot 2.x向3.x过渡的一个重要版本用户基数大问题解决方案多。SkyWalking Java Agent 8.x/9.x这两个版本对Spring Boot、Spring Cloud、Dubbo等主流框架的支持已经非常成熟且提供了对JDK 8-17的广泛支持。Agent的“无侵入”特性在这里是关键——它通过Java Agent机制在应用启动时进行字节码增强无需修改业务代码。SkyWalking OAP/UI 9.x服务端与UI的版本需要与Agent大致匹配以保证数据协议和功能的兼容性。这个选型背后的逻辑是求稳而非求新。演示项目的目标是“跑通”和“理解”而不是追逐最新特性。稳定的组合能确保学习者将精力集中在核心原理上而非解决版本冲突问题。2.2 模拟微服务调用场景单一的Spring Boot应用无法展示链路追踪的真正威力。因此这个演示项目极有可能包含了两个或更多个简单的Spring Boot服务模拟一个最基本的微服务调用链。例如service-a提供一个HTTP接口比如/api/a。service-b提供另一个HTTP接口比如/api/b。设计一个调用链用户请求service-a的/api/a在service-a的内部逻辑中它会通过RestTemplate或OpenFeign等HTTP客户端去调用service-b的/api/b然后将两者的结果合并返回。这样一个简单的场景就构成了一个包含两个跨服务Span跨度的Trace追踪。在SkyWalking UI上你就能清晰地看到一次请求先后经过了service-a和service-b每个服务的耗时、状态都一目了然。这比任何文字描述都来得直观。2.3 关键配置的显式化与注释对于初学者SkyWalking的配置是另一个难点。配置文件如agent.config参数繁多且很多配置依赖于部署环境如OAP服务器地址、服务名、采样率等。一个好的演示项目会把这些关键配置从默认的、隐藏的状态中“拉”出来并通过注释进行说明。例如项目可能会包含一个skywalking-agent目录里面有一个配置清晰的config/agent.config文件其中高亮显示了以下配置# 服务在SkyWalking UI中显示的名称 agent.service_name${SW_AGENT_NAME:Your_ApplicationName} # 后端OAP服务器的gRPC地址收集数据用 collector.backend_service${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800} # 日志级别调试时可设为DEBUG logging.level${SW_LOGGING_LEVEL:INFO} # 采样率10000表示100%采样生产环境需调整 agent.sample_n_per_3_secs${SW_AGENT_SAMPLE:10000}同时项目文档或README会明确指出如何通过环境变量如SW_AGENT_NAME或JVM参数来覆盖这些配置以适应不同的启动环境。这种设计让配置变得透明、可管理。2.4 构建与启动脚本的封装“一键启动”是提升演示项目体验的关键。项目可能会提供docker-compose.yml文件来一键启动SkyWalking的后端OAP和UI同时也提供清晰的Shell脚本或Maven/Gradle命令指导你如何将SkyWalking Agent挂载到Spring Boot应用上。例如一个典型的启动命令会被明确写出java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar \ -Dskywalking.agent.service_nameservice-a \ -Dskywalking.collector.backend_servicelocalhost:11800 \ -jar service-a-0.0.1-SNAPSHOT.jar脚本化或文档化这一步能避免新手在“如何挂载Agent”这个第一步就卡住。它传递了一个重要理念SkyWalking Agent的集成是启动时的一次性行为而非编译时依赖。3. 核心细节解析与实操要点理解了整体设计我们深入到骨髓看看那些决定集成成败的“魔鬼细节”。这些细节往往在官方文档中一笔带过但在实际操作中却至关重要。3.1 SkyWalking Agent的三种集成方式与选择这是集成第一步也是困惑最多的一步。演示项目通常会展示最推荐的一种但了解全貌有助于你应对复杂环境。使用JVM参数-javaagent演示项目首选 这是最经典、最灵活的方式。在启动Spring Boot应用的JVM命令中直接指定Agent jar包的路径和配置。优点是完全无侵入适用于任何部署方式IDE、命令行、容器。演示项目必然采用这种方式因为它最通用。注意-javaagent参数的路径必须是绝对路径或者相对于启动目录的可访问路径。在IDE中运行你需要在“Run/Debug Configurations”的VM options里添加这个参数。在Dockerfile中集成 对于容器化部署最佳实践是在构建Docker镜像时将SkyWalking Agent直接打包进镜像并在ENTRYPOINT或CMD中通过-javaagent指定。演示项目如果包含Dockerfile可能会这样写FROM openjdk:11-jre-slim COPY skywalking-agent /usr/local/skywalking-agent COPY app.jar /app.jar ENTRYPOINT [java, -javaagent:/usr/local/skywalking-agent/skywalking-agent.jar, -jar, /app.jar]这种方式将Agent作为应用镜像的一部分部署更一致。通过探针服务网格Service Mesh集成 在更云原生的场景下如果使用了Istio等服务网格链路追踪可以由Sidecar代理如Envoy自动完成无需在应用内集成Agent。但SkyWalking可以通过其Mixer组件接收这些数据并统一展示。这超出了基础演示项目的范围但值得了解。实操心得对于本地开发和学习坚持使用第一种方式。它能让你最清晰地感知Agent的存在和工作机制。在IDE中配置一次VM options之后每次调试运行都会自动挂载Agent非常方便。3.2 Agent配置的优先级与外部化SkyWalking Agent的配置加载遵循一个明确的优先级顺序理解这个顺序能帮你高效地管理不同环境开发、测试、生产的配置。系统属性最高通过-D设置的JVM参数例如-Dskywalking.agent.service_namemy-service。Agent配置文件agent.config文件中的配置项。环境变量例如SW_AGENT_NAME。默认值Agent jar包中内置的默认配置。最佳实践是将动态的、环境相关的配置如服务名、OAP地址通过系统属性或环境变量传入而将静态的、行为相关的配置如采样率、插件开关写在配置文件中。演示项目通常会教你使用系统属性。例如在application.properties或通过启动脚本设置-Dskywalking.agent.service_nameproject.artifactId \ -Dskywalking.collector.backend_service${SKYWALKING_OAP_HOST:localhost}:11800这里用到了Maven属性${project.artifactId}和环境变量${SKYWALKING_OAP_HOST}实现了配置的外部化和自动化。3.3 Spring Boot Actuator与SkyWalking的协作热搜词中提到了“关闭 spring boot actuator后还能访问/actuator”这引出了一个相关话题。Spring Boot Actuator提供了应用的健康检查、度量指标等端点。SkyWalking也能收集JVM指标如CPU、内存、GC和应用层的HTTP指标。它们的关系是互补而非替代Actuator提供的是“自省”视角通过HTTP端点暴露给运维人员或监控系统如Prometheus拉取。SkyWalking Agent提供的是“外部观测”视角主动将指标和链路数据推送到后端的OAP服务器。在演示项目中你可能会发现两者并存。Agent会自动收集许多指标但你也可以同时开启Actuator将/actuator/prometheus端点暴露给另一个监控体系。这并不冲突。重要提示如果你发现SkyWalking UI中缺少JVM或线程指标请检查Agent配置中相关的插件是否开启如jvm-*插件这与Actuator是否开启无关。3.4 追踪上下文在异步编程中的传递这是微服务链路追踪中的一个高级但常见的坑。在Spring Boot中当你使用Async、CompletableFuture或消息队列等进行异步处理时当前线程的追踪上下文Trace Context默认是不会自动传递到新线程的。这会导致一个Trace在异步点“断掉”在UI上看到不连续的链路。演示项目如果设计得比较深入可能会演示如何解决这个问题。SkyWalking通过apm-toolkit-trace依赖提供了工具类。核心解决方案是使用RunnableWrapper或CallableWrapper来包装你的异步任务。例如import org.apache.skywalking.apm.toolkit.trace.RunnableWrapper; import org.apache.skywalking.apm.toolkit.trace.CallableWrapper; // 使用线程池提交任务 executorService.submit(RunnableWrapper.of(() - { // 你的异步业务逻辑 // 在这个新线程中Trace上下文得以延续 })); // 或者使用CompletableFuture CompletableFuture.runAsync(RunnableWrapper.of(() - { // 异步逻辑 }));实操心得在涉及异步编程的地方务必检查链路是否连续。如果发现断链第一个要排查的就是是否使用了RunnableWrapper/CallableWrapper进行包装。这是一个非常容易遗漏但至关重要的步骤。4. 实操过程与核心环节实现现在让我们化身实操者一步步“还原”这个演示项目的搭建和运行过程。我会假设一个最典型的项目结构并填充所有你可能遇到的细节。4.1 环境准备与SkyWalking后端部署在连接应用之前我们需要一个接收和展示数据的“大脑”——SkyWalking后端。步骤1获取SkyWalking发行版前往Apache SkyWalking官网下载最新的发行版例如apache-skywalking-apm-9.7.0.tar.gz。解压后目录结构通常包含bin/启动脚本。config/OAP服务器和UI的配置文件。oap-libs/OAP运行库。webapp/UI前端文件。步骤2快速启动单机模式对于演示和学习使用其内置的H2存储和默认配置是最快的。进入bin目录执行Linux/Mac:./startup.shWindows:startup.bat这个脚本会同时启动OAP服务器和Web UI。启动后你可以通过http://localhost:8080访问SkyWalking UI。OAP服务默认监听gRPC 11800端口用于接收Agent数据和REST 12800端口用于UI查询。注意默认配置将数据存储在内存H2数据库中重启后数据会丢失。仅供测试。步骤3验证后端服务打开浏览器访问http://localhost:8080应该能看到SkyWalking的登录页默认无密码。同时可以检查OAP日志logs/oap.log查看是否有错误。4.2 Spring Boot应用集成Agent假设我们的演示项目包含两个服务demo-order-service和demo-inventory-service。步骤1准备Agent目录将SkyWalking发行版中的/agent文件夹整个复制到你的项目目录下或者一个统一的共享位置。这个文件夹包含了运行Agent所需的所有jar包和配置。步骤2配置应用以demo-order-service为例应用本身不需要引入任何SkyWalking的依赖除非你需要上述的异步工具包。它的pom.xml是干净的Spring Boot项目。核心在于启动命令。步骤3在IDE中配置启动参数以IntelliJ IDEA为例打开Run/Debug Configurations。选择你的Spring Boot应用启动类配置。在VM options栏中添加如下参数请根据你的实际路径修改-javaagent:/ABSOLUTE_PATH_TO_YOUR_PROJECT/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_namedemo-order-service -Dskywalking.collector.backend_service127.0.0.1:11800 -Dskywalking.logging.levelDEBUG-javaagent: 指向你复制的agent目录下的jar文件。service_name: 在UI上显示的服务名。collector.backend_service: 指向你刚启动的OAP服务器地址。logging.level: 设为DEBUG便于首次集成时排查问题。步骤4编写模拟业务代码在demo-order-service中创建一个简单的Controller它会调用demo-inventory-service。RestController RequestMapping(/order) public class OrderController { private final RestTemplate restTemplate; public OrderController(RestTemplateBuilder builder) { this.restTemplate builder.build(); } GetMapping(/{id}) public String createOrder(PathVariable String id) { // 模拟本地处理 log.info(Order service processing order {}, id); // 跨服务调用库存服务 String inventoryResult restTemplate.getForObject( http://localhost:8081/inventory/check/{itemId}, String.class, item_ id); return Order id created. Inventory status: inventoryResult; } }在demo-inventory-service中提供一个对应的接口。RestController RequestMapping(/inventory) public class InventoryController { GetMapping(/check/{itemId}) public String checkInventory(PathVariable String itemId) { log.info(Inventory service checking item {}, itemId); // 模拟数据库查询等操作 return Item itemId is in stock.; } }步骤5启动并验证按上述方式分别配置并启动两个Spring Boot应用注意修改各自的service_name和端口避免冲突如order用8080inventory用8081。使用浏览器或curl访问http://localhost:8080/order/123。打开SkyWalking UI (http://localhost:8080)在左侧导航栏选择“拓扑图”。你应该能看到两个服务节点demo-order-service和demo-inventory-service以及它们之间的调用关系线。选择“追踪”页面设置好时间范围和服务名你应该能查询到刚才那次请求的详细链路包含两个Span分别对应两个服务的处理过程。4.3 关键配置详解与调优建议当基础功能跑通后我们需要关注一些影响性能和功能的配置。演示项目的agent.config里可能已经预设了一些但理解它们很重要。配置项默认值/示例说明与调优建议agent.service_nameYour_ApplicationName必改。生产环境建议通过环境变量注入如-Dskywalking.agent.service_name${APP_NAME}。collector.backend_service127.0.0.1:11800必改。指向OAP集群地址。多节点用逗号分隔如10.0.0.1:11800,10.0.0.2:11800。agent.sample_n_per_3_secs-1(负数表示全采样)生产环境必调。全采样对性能有影响。可设为正整数如1000表示每3秒最多采样1000条链路。也可使用动态采样配置。agent.ignore_suffix.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg忽略对这些后缀的请求进行追踪。可以添加你们公司静态资源的后缀。logging.levelINFO调试时设为DEBUG可以查看Agent详细的增强和上报日志帮助定位问题。生产环境设为INFO或ERROR。plugin.mongodb.trace_paramfalseMongoDB插件是否追踪查询参数。出于安全和性能考虑生产环境建议保持false。plugin.elasticsearch.trace_dslfalseElasticsearch插件是否追踪DSL语句。生产环境建议false。plugin.jdbc.trace_sql_parametersfalseJDBC插件是否追踪SQL参数。强烈建议生产环境保持false避免敏感数据泄露。plugin.springmvc.collect_http_paramsfalseSpringMVC插件是否收集HTTP参数。同上建议false。调优核心原则在满足监控需求的前提下尽量减少不必要的数据收集特别是包含业务数据的参数、语句。这既是出于性能考虑更是安全红线。5. 常见问题与排查技巧实录即使按照演示项目一步步来你也可能会遇到一些“坑”。下面是我在实践中总结的常见问题及其排查思路这可能是比演示代码更有价值的部分。5.1 SkyWalking UI中看不到服务或链路数据这是最典型的问题。请按照以下清单进行排查就像医生问诊一样从最可能的原因开始检查Agent是否成功挂载查看应用启动日志。如果Agent挂载成功日志开头会有明显的SkyWalking Agent启动信息例如INFO org.apache.skywalking.apm.agent.SkyWalkingAgent - SkyWalking agent has been started...。如果没看到说明-javaagent参数未生效。检查IDE的VM options或命令行参数确保路径是绝对路径且jar包存在。检查网络连通性应用所在机器需要能访问OAP服务器的11800(gRPC) 端口。使用telnet oap-host 11800或nc -zv oap-host 11800测试。防火墙或安全组规则可能阻止了通信。检查服务名和OAP地址配置确认agent.service_name和collector.backend_service配置正确。可以通过在应用启动后检查logs/skywalking-api.log文件查看Agent尝试连接的后端地址。服务名不要包含特殊字符或空格建议使用中划线如user-service。检查OAP服务状态与日志访问http://oap-host:12800/如果返回{services:[]}之类的JSON说明OAP的HTTP服务是活的。查看OAP的日志logs/oap.log搜索ERROR或WARN看是否有关于数据接收或存储的错误。验证数据是否产生确保你的应用确实在处理请求。多发几次请求因为默认采样率可能不是100%。在Agent配置中临时将logging.level设为DEBUG然后观察logs/skywalking-api.log看是否有Segment发送的日志。5.2 链路不完整或断链表现为一个请求的Trace在UI上只显示了一部分服务的Span后续的调用消失了。异步调用问题最常见回顾第3.4节。检查在Async、线程池、CompletableFuture、消息监听等方法中是否使用了RunnableWrapper或CallableWrapper包装任务。排查技巧在疑似断链的代码前后手动打印或日志记录当前线程的Trace ID。SkyWalking提供了TraceContext.traceId()方法来获取。对比前后ID是否一致。使用了不支持的客户端或框架SkyWalking通过插件支持主流组件如Dubbo, RocketMQ, Kafka, Redis客户端等。但如果你使用了某个小众的HTTP客户端或RPC框架可能没有对应的插件支持。解决方法检查agent/plugins目录下是否有相关插件jar。也可以查阅SkyWalking官方文档的“支持列表”。如果确实不支持可能需要开发自定义插件或考虑换用受支持的客户端。跨进程上下文传递失败在服务A调用服务B时Trace上下文是通过HTTP头如sw8传递的。如果服务B的框架没有正确解析这些头部链路就会断。排查技巧使用抓包工具如Wireshark或打印HTTP请求的完整Headers检查从服务A发出的请求是否包含了SkyWalking相关的Header如sw8。再检查服务B收到的请求头中是否还有这些信息。5.3 性能开销与资源占用疑虑引入任何Agent都会带来性能损耗SkyWalking的目标是将其控制在可接受的范围内官方宣称是增加约3%-5%的响应时间。采样率是关键全采样agent.sample_n_per_3_secs-1在高并发下对CPU和网络会有压力。生产环境务必调整。可以设置为一个合理的数值如1000或者使用更高级的动态采样配置。关注缓冲区与队列Agent会将数据缓存在内存队列中然后批量发送给OAP。如果网络或OAP出现故障队列积压会导致内存上涨。监控指标可以关注JVM内存使用情况。SkyWalking Agent本身也提供了一些JMX指标可以通过agent.config中的statuscheck.ignored等配置来管理。插件选择性加载agent/plugins目录下的所有插件默认都会被加载。如果你确定某些组件不会用到例如你的应用不用Kafka可以将对应的插件jar文件移出plugins目录或者重命名以.disabled结尾以减少启动时的字节码增强范围和运行开销。5.4 与Spring Boot 3.x / Spring Boot 4.x 的兼容性热搜词中提到了Spring Boot 4.x这是一个前沿话题。截至我知识更新的时间点SkyWalking对Spring Boot 3.x基于Java 17的支持在较新的Agent版本如9.x中已经较好。但需要注意Java版本Spring Boot 3.x要求Java 17。确保你使用的SkyWalking Agent版本支持Java 17。依赖冲突Spring Boot 3.x使用了Jakarta EE 9包名从javax.*变为jakarta.*。SkyWalking的某些插件如果涉及Servlet API等需要兼容Jakarta。务必使用SkyWalking官方声明支持Spring Boot 3.x的Agent版本。测试策略在将SkyWalking Agent升级或与Spring Boot新版本集成前务必在预发布环境中进行充分的性能和兼容性测试。重点关注是否有链路丢失、Span信息错乱、或应用启动失败等问题。这个演示项目就像一张精心绘制的地图带你走通了SkyWalking集成Spring Boot的主干道。但真实的微服务森林远比地图复杂充满了各种意外的小径和沟壑。希望我分享的这些设计思路、实操细节和排查经验能成为你探索这片森林时的一把趁手工具和一份避险指南。记住可观测性建设的核心价值不在于工具本身多强大而在于它是否真的能帮你快速定位和解决问题。从这个演示项目出发不断实践、踩坑、总结你才能真正驾驭它。本文还有配套的精品资源点击获取