目录
一、环境准备
二、步骤 1：部署 SkyWalking 服务端（OAP + UI）
1. 下载并解压安装包
2. 配置存储（测试 / 生产区分）
（1）测试环境（H2 内存库，无需额外部署）
（2）生产环境（Elasticsearch 存储）
3. 启动 OAP 和 UI
4. 验证服务端
三、步骤 2：Spring Boot 应用接入 SkyWalking Agent
1. 准备 Agent 包
2. 本地开发环境接入（IDEA 示例）
（1）配置 VM options
（2）启动应用
3. 服务器 Jar 包部署接入
（1）基础启动命令
（2）可选参数调优
4. Docker 部署接入（Dockerfile 示例）
四、步骤 3：日志与 TraceID 关联（关键扩展）
1. 引入依赖
2. 修改 logback-spring.xml 配置
五、常见问题与解决方案
六、生产环境最佳实践
七、Spring Boot 3.x 适配注意事项
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-bin2. 配置存储（测试 / 生产区分）
（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: 13. 启动 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，实现全链路追踪、性能指标监控、日志关联，无需侵入业务代码，是生产环境故障定位的核心工具。
