SkyWalking使用：Spring Boot场景

Spring Boot 项目接入 SkyWalking 核心逻辑与 Spring Cloud Alibaba 一致（无侵入式 Agent 挂载），但无需适配微服务组件，步骤更简化。以下是基于 SkyWalking 9.x + Spring Boot 2.x/3.x 的完整实操流程，覆盖单机测试、生产部署、日志关联等核心场景。

一、环境准备

组件	版本建议	说明
Spring Boot	2.3.x ~ 3.2.x（主流版本）	兼容所有 SkyWalking 9.x
SkyWalking	9.7.0（最新稳定版）	包含 Agent/OAP/UI
JDK	8+/11+/17+	适配 Spring Boot 版本（3.x 推荐 17+）
存储介质	Elasticsearch 7.17.x（推荐）/ H2（测试）	生产必选 ES，测试可用 H2

二、步骤 1：部署 SkyWalking 服务端（OAP + UI）

1. 下载并解压安装包

bash

运行

复制代码

# 下载 SkyWalking 9.7.0
wget https://archive.apache.org/dist/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
# 解压
tar -zxvf apache-skywalking-apm-9.7.0.tar.gz
cd apache-skywalking-apm-bin

2. 配置存储（测试 / 生产区分）

（1）测试环境（H2 内存库，无需额外部署）

默认配置即可，无需修改 config/application.yml，H2 适合本地测试，重启 OAP 数据会丢失。

（2）生产环境（Elasticsearch 存储）

编辑 config/application.yml，修改存储配置：

yaml

复制代码

storage:
  selector: ${SW_STORAGE:elasticsearch}
  elasticsearch:
    clusterNodes: ${SW_STORAGE_ES_CLUSTER_NODES:192.168.1.100:9200} # 你的ES地址
    protocol: http
    connectTimeout: 3000
    socketTimeout: 30000
    indexShardsNumber: 2
    indexReplicasNumber: 1

3. 启动 OAP 和 UI

bash

运行

复制代码

# 启动 OAP Server（后台运行）
nohup bin/oapService.sh > oap.log 2>&1 &

# 启动 UI 服务（后台运行）
nohup bin/webappService.sh > ui.log 2>&1 &

4. 验证服务端

UI 访问地址：http://{服务器IP}:8080（默认账号 / 密码：admin/admin）
OAP 端口检查：telnet {IP} 11800（Agent 上报端口），通则正常。

三、步骤 2：Spring Boot 应用接入 SkyWalking Agent

核心是给 Spring Boot Jar 包添加 javaagent 启动参数，无需修改任何业务代码。

1. 准备 Agent 包

将解压后的 apache-skywalking-apm-bin/agent 目录拷贝到应用服务器（如 /opt/skywalking/agent），本地测试可直接使用解压后的路径。

2. 本地开发环境接入（IDEA 示例）

（1）配置 VM options

在 IDEA 中打开 Spring Boot 项目，点击「Run/Debug Configurations」→ 选择对应启动类 → 配置 VM options：

plaintext

复制代码

-javaagent:/你的路径/apache-skywalking-apm-bin/agent/skywalking-agent.jar
-Dskywalking.agent.service_name=demo-springboot # 应用名称（自定义）
-Dskywalking.collector.backend_service=127.0.0.1:11800 # OAP 地址

（2）启动应用

启动 Spring Boot 应用，访问任意接口（如 http://localhost:8081/hello），然后打开 SkyWalking UI，在「服务拓扑图」「调用链」中可看到数据。

3. 服务器 Jar 包部署接入

（1）基础启动命令

bash

运行

复制代码

java -javaagent:/opt/skywalking/agent/skywalking-agent.jar \
-Dskywalking.agent.service_name=demo-springboot \
-Dskywalking.collector.backend_service=192.168.1.100:11800 \
-jar demo-springboot-1.0.0.jar

（2）可选参数调优

参数	作用	示例
`skywalking.agent.sample_n_per_3_secs`	采样率（高流量场景降低）	`-Dskywalking.agent.sample_n_per_3_secs=10`（每 3 秒采样 10 个请求）
`skywalking.logging.level`	Agent 日志级别	`-Dskywalking.logging.level=INFO`
`skywalking.agent.instance_name`	实例名（多实例区分）	`-Dskywalking.agent.instance_name=demo-springboot-01`

4. Docker 部署接入（Dockerfile 示例）

dockerfile

复制代码

# 基础镜像（适配Spring Boot版本）
FROM openjdk:17-jre-slim
# 拷贝 SkyWalking Agent 到镜像
COPY skywalking-agent /opt/skywalking/agent
# 拷贝 Spring Boot Jar 包
COPY target/demo-springboot-1.0.0.jar /app.jar
# 启动命令（挂载Agent）
ENTRYPOINT ["java", \
"-javaagent:/opt/skywalking/agent/skywalking-agent.jar", \
"-Dskywalking.agent.service_name=demo-springboot", \
"-Dskywalking.collector.backend_service=oap-server:11800", \
"-jar", "/app.jar"]

注：oap-server 需替换为 Docker 网络中 OAP 服务的地址 / 别名。

四、步骤 3：日志与 TraceID 关联（关键扩展）

SkyWalking 可将日志与链路 TraceID 绑定，通过 TraceID 一键定位问题日志，以 Spring Boot 主流的 Logback 为例：

1. 引入依赖

在 pom.xml 中添加 SkyWalking 日志工具包（版本与 Agent 一致）：

xml

复制代码

<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-logback-1.x</artifactId>
    <version>9.7.0</version>
</dependency>

若使用 Log4j2，替换为 apm-toolkit-log4j2-2.x；使用 Log4j 1.x 替换为 apm-toolkit-log4j-1.x。

2. 修改 logback-spring.xml 配置

添加 SkyWalking 日志转换器，输出 TraceID：

xml

复制代码

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 控制台输出 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <!-- SkyWalking 日志布局，%tid 自动填充 TraceID -->
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{50} - %msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

    <!-- 文件输出（可选） -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/demo-springboot.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/demo-springboot.%d{yyyy-MM-dd}.log</fileNamePattern>
        </rollingPolicy>
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{50} - %msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
    </root>
</configuration>

重启应用后，日志中会显示 TraceID（无链路时为 N/A），例如：

plaintext

复制代码

2025-01-15 10:20:30.123 [4f8a7d9e12345678] [http-nio-8081-exec-1] INFO  com.demo.controller.HelloController - 接收到请求：/hello

在 SkyWalking UI 中通过 4f8a7d9e12345678 可直接检索关联日志。

五、常见问题与解决方案

问题现象	排查方向
UI 无应用数据	1. Agent 配置的 OAP 地址是否正确；2. 11800 端口是否开放；3. 应用名是否配置（`service_name` 不能为空）
TraceID 显示 N/A	1. 接口是否被调用（无请求则无 TraceID）；2. Agent 版本与 Spring Boot 版本是否兼容（3.x 需 SkyWalking 9.x+）
启动应用报 `javaagent` 找不到	检查 `-javaagent` 后的路径是否绝对路径，且 `skywalking-agent.jar` 存在
应用性能下降	1. 调低采样率（`sample_n_per_3_secs`）；2. 开启 Agent 异步上报（默认已开启）
日志无 TraceID	1. 日志依赖是否引入；2. logback 配置是否使用 `TraceIdPatternLogbackLayout`

六、生产环境最佳实践

Agent 目录固化 ：将 Agent 包部署到固定路径（如 /opt/skywalking/agent），避免每次部署拷贝；
OAP 集群部署 ：多节点部署 OAP Server，通过 backend_service 配置多个地址（如 192.168.1.100:11800,192.168.1.101:11800）实现负载均衡；
采样率调优 ：QPS > 5000 时，采样率设为 5~20（每 3 秒采样 5~20 个），平衡监控粒度与性能；
数据清理：配置 ES 索引生命周期（ILM），定期清理 7~30 天前的监控数据；
告警配置：在 SkyWalking UI 中配置「响应时间 > 500ms」「错误率 > 1%」等告警规则，对接钉钉 / 邮件。

七、Spring Boot 3.x 适配注意事项

JDK 需使用 17+，避免兼容性问题；
Agent 无需额外配置，SkyWalking 9.x 原生支持 Spring Boot 3.x；
若使用 Spring Boot 3.x 的虚拟线程，SkyWalking 9.7.0+ 已适配，无需修改代码。

通过以上步骤，Spring Boot 项目可快速接入 SkyWalking，实现全链路追踪、性能指标监控、日志关联，无需侵入业务代码，是生产环境故障定位的核心工具。