这一篇是真正手把手级别的。文章会按实际部署顺序推进先讲清楚SkyWalking解决什么问题再带你完成版本选型、存储规划、OAP和Web UI搭建、Java服务接入最后用控制台实操几个核心功能并把我在本地和生产环境里踩过的高频坑一并整理出来。无论是第一次接触APM还是已经装过但没跑通按这篇顺序走一遍应该能少走很多弯路。1. 安装SkyWalking之前先把“它到底解决什么问题”讲透1.1 分布式监控的三个传统老大难很多团队在做微服务化改造前监控基本靠“日志平台基础资源监控”硬撑。这套组合在单体阶段还能用服务一拆马上暴露三个痛点。第一个痛点是跨服务链路没有关联。同一个用户请求在A服务、B服务、C服务各留了一段日志日志系统之间没有全局TraceID串联。线上出问题的时候你要从几万条日志里按时间戳人工拼凑完整调用链稍微复杂一点的请求排查半小时都是常态。第二个痛点是服务间调用关系不透明。十几个服务互相调用谁依赖谁、调用频率多高、哪个环节最容易成为瓶颈没有人能准确说清楚。等出了问题再手动画依赖图往往已经来不及。第三个痛点是性能问题定位太慢。资源监控只能告诉你“某个服务CPU高了、响应慢了”但没法告诉你“慢的是哪个接口、调用链路上哪一个环节耗时最多”。这两者的差距在故障处理时是几分钟和几个小时的差别。1.2 四大组件如何分工一句话讲清整套架构SkyWalking的架构不复杂核心就是四个角色Agent探针、OAP Server分析引擎、Web UI可视化控制台、Storage存储后端。用交通系统来类比Agent是装在每辆车上的GPS终端负责采集位置和速度然后上报OAP是交通指挥中心负责汇总、分析、研判UI是指挥中心的大屏把分析结果画出来给交警看Storage就是指挥中心的档案库。每一层只管自己的事所以各组件可以独立升级、独立扩缩容。在API层面Agent采集的数据通过gRPC协议上报给OAP的11800端口UI通过HTTP协议从OAP的12800端口读取数据。这个通信路径很关键后面排查问题会反复用到。1.3 服务、实例、端点UI里绕不开的三个基础概念用SkyWalking之前建议先把三个基础概念搞清楚因为后面看拓扑图、配告警规则、查Trace都离不开它们。服务Service指的是一个独立部署的应用比如order-service、user-service拓扑图上的每个节点基本对应一个服务。实例Instance是一个服务的具体运行进程同一个服务起了两个副本就是两个实例。端点Endpoint是服务对外暴露的具体接口比如HTTP接口的/order/create或者一个RPC方法。三者的层级关系是服务包含实例实例提供端点。理解这个模型之后你在界面上看到的所有指标和链路数据最终都可以归到这三层中的某一层。2. 版本、存储和端口三个决策在装之前就要敲定2.1 版本选型9.x还是8.xAgent怎么配我见过不少团队装SkyWalking很顺利但跑了一两个月开始头疼追根溯源都是在安装前没做好版本决策。所以这一步值得花点时间想清楚。目前主线版本是9.xOAP服务端的JVM基线从JDK 8提升到了JDK 11存储接口也做了重构。如果是新项目直接上9.x最新稳定版即可如果团队是老环境且已经稳定运行在8.x也没有新特性需求没必要盲目升级。这里有一条血泪经验Agent版本和OAP版本要尽量保持大版本一致最理想是同一个小版本。新版Agent连接旧版OAP通常没问题反过来旧版Agent连新版OAP就很容易出现协议不兼容表现是数据采集不上、UI页面一片空白。我在生产环境吃过一次亏OAP是9.0Agent误装了8.15结果所有接入服务的Trace全部消失排查了一整天才定位到版本不匹配上。2.2 存储后端H2能玩生产环境请上ElasticsearchSkyWalking默认存储后端是H2一个纯Java的内存数据库好处是零配置、解压即用适合本地演示和跑通流程坏处是数据无法大规模持久化、不支持集群。生产环境我建议直接上Elasticsearch以下简称ES。SkyWalking 9.x同时支持ES 7.x和8.x其中8.x需要SkyWalking 9.5.0以上版本。如果你的团队已经有ES集群直接复用就好如果没有起一个单节点ES 7.17版本也够用。除了ESSkyWalking还支持OpenSearch、MySQL、PostgreSQL、BanyanDB等存储。这里不展开等确实需要时再按官方文档选型。对绝大多数中小团队来说最优解就是ES。2.3 端口、JDK和防火墙最容易忽视的前置检查部署前先确认三件事。一是端口占用情况。OAP默认使用11800gRPC和12800HTTP两个端口UI默认使用8080。如果机器上已经有程序占用提前改端口或者换机器。二是防火墙和安全组。云服务器尤其要注意11800是Agent上报数据的通道12800是UI查询数据的通道这两个端口必须对需要访问的主机开放。我之前在云环境踩过坑本地测试一切正常一接到测试环境就全是超时最后发现是安全组没放行11800。三是JDK版本。SkyWalking 9.x的OAP服务端要求JDK 11以上建议直接用JDK 17避免版本兼容上的麻烦。3. 从解压到跑通OAP服务端和UI的完整搭建记录3.1 下载、解压、认清目录结构我的演示环境是LinuxmacOS操作完全一致Windows用户把shell命令换成对应的.bat脚本即可。建议准备一台至少4核8G的机器磁盘留20G以上因为ES索引和Agent采集数据都会占空间。下载用命令行即可cd /opt wget https://archive.apache.org/dist/skywalking/9.6.0/apache-skywalking-apm-9.6.0.tar.gz tar -zxvf apache-skywalking-apm-9.6.0.tar.gz mv apache-skywalking-apm-bin skywalking解压后目录结构如下bin启停脚本OAP和UI的入口都在这里configOAP核心配置application.yml就在这个目录oap-libsOAP依赖的第三方类库webappUI应用及配置webapp/webapp.yml是UI关键配置agent内置的Java Agent探针包后面接入业务服务会直接用这里讲的是一次性把OAP和UI都装好。官方也提供单独webapp包但没必要去拆一个发布包全部搞定。3.2 修改OAP配置从H2切换到Elasticsearch打开config/application.yml。如果只是本地演示用默认H2存储什么都不用改。我建议先让H2跑通验证整体流程后再切换。切到ES的配置方式如下storage: selector: ${SW_STORAGE:elasticsearch} elasticsearch: clusterNodes: ${SW_STORAGE_ES_CLUSTER_NODES:localhost:9200} namespace: ${SW_STORAGE_ES_NAMESPACE:skywalking} indexShardsNumber: ${SW_STORAGE_ES_INDEX_SHARDS_NUMBER:2} indexReplicasNumber: ${SW_STORAGE_ES_INDEX_REPLICAS_NUMBER:0}一个特别提醒生产环境建议给ES索引设置namespace这样SkyWalking创建的索引会统一带前缀不会跟ES里其他业务索引混在一起。namespace一旦确定了就不要随意改否则历史数据全对不上。3.3 启动OAP与UI、用curl验证服务状态切到bin目录先后启动OAP和UIcd /opt/skywalking/bin ./oapService.sh第一次启动会初始化存储稍等几十秒。看到日志里的Server started on port: 11800基本就说明OAP起来了。然后开另一个终端./webappService.shUI启动后默认监听8080端口浏览器访问http://localhost:8080就能打开SkyWalking控制台。如果页面能打开但提示连接OAP超时检查webapp.yml里的OAP地址配置server: port: 8080 collector: path: /graphql ribbon: listOfServers: 127.0.0.1:12800OAP和UI不在同一台机器时listOfServers里的IP要改成OAP所在机器的内网或公网IP。改完配置文件后必须重启UI进程才会生效。想确认OAP接口是否真的能用可以发一个GraphQL请求curl -s -X POST http://127.0.0.1:12800/graphql \ -H Content-Type: application/json \ -d {query:query p($i: ID!){service(input:{serviceId:$i}){id name}},variables:{i:1}}能返回JSON就说明OAP链路是通的。3.4 Docker一键体验另一种快速上手方式如果你只是想先看个效果不想折腾二进制包可以用Docker Compose。官方有现成镜像version: 3.8 services: oap: image: apache/skywalking-oap-server:9.6.0 ports: - 11800:11800 - 12800:12800 environment: SW_STORAGE: h2 ui: image: apache/skywalking-ui:9.6.0 ports: - 8080:8080 environment: SW_OAP_ADDRESS: http://oap:12800 depends_on: - oap不过我还是建议你至少按二进制方式完整装一遍只有亲手改过配置文件、看过目录结构后续排查问题才有体感。Docker方式适合快速验证不适合学习原理。4. 把业务服务接进来Java Agent的安装与配置全解4.1 零侵入背后的字节码增强原理Java Agent能实现“零侵入”靠的是JDK的Instrumentation机制。在类加载过程中Agent会在目标类的方法入口、出口、异常路径上注入埋点逻辑自动采集Trace和指标数据。对于业务代码本身没有任何感知。SkyWalking的Agent内置了大量插件覆盖Spring MVC、Tomcat、Netty、Dubbo、gRPC、JDBC、MyBatis、Kafka、RocketMQ等常见组件。这也是它开箱即用的原因——你甚至不需要为某个特定框架写额外配置引入Agent后插件会自动生效。插件目录在agent/plugins下默认全部激活。4.2 一行javaagent参数接入Spring Boot服务Agent就在SkyWalking安装包的agent目录下。可以把它原样拷贝到业务服务器上比如放在/opt/skywalking-agent/然后启动命令变成这样java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \ -Dskywalking.agent.service_nameorder-service \ -Dskywalking.collector.backend_service192.168.1.10:11800 \ -jar app.jar三个关键参数逐一说清-javaagentJVM参数指定Agent jar包路径。-Dskywalking.agent.service_name服务名称。建议跟注册中心或应用名保持一致后面拓扑图和告警都靠这个名字区分服务。-Dskywalking.collector.backend_serviceOAP地址格式是IP:11800。如果有多个OAP用英文逗号分隔。如果不想把参数写死在启动脚本里也可以改agent/config/agent.configagent.service_name${SW_AGENT_NAME:order-service} collector.backend_service${SW_AGENT_COLLECTOR_BACKEND_SERVICES:192.168.1.10:11800}配置文件的优先级低于启动参数启动参数又低于环境变量。在容器化部署场景下用环境变量注入最方便export SW_AGENT_NAMEorder-service export SW_AGENT_COLLECTOR_BACKEND_SERVICES192.168.1.10:118004.3 多服务接入、配置管理、以及如何确认接入成功接入多个服务时每个进程都要带上对应的javaagent参数服务名不要重复。接入后立刻去UI确认拓扑页应该能看到新服务节点出现“服务”列表能看到服务对应的实例信息请求几次业务接口后链路追踪页才能查到Trace数据。如果某个服务接入后UI不出现优先排查三处第一agent/logs/skywalking-agent.log有没有报错第二服务名是否跟其他服务重名第三业务服务器到OAP的11800端口是否可达。这里有两点建议一是Agent日志文件平时不起眼排查问题却最有用我在生产排查时基本都先打开它二是如果多个服务共用同一台机器每个服务进程的Agent内存会叠加服务数量多的时候要注意机器内存水位。5. 打开控制台看数据拓扑、Trace、指标与告警实战5.1 拓扑图的使用思路UI首页默认就是拓扑视图。它会根据采集到的统计数据自动把服务画成节点节点之间连线代表调用关系线的颜色和粗细反映流量大小与健康状态。这里有个很容易产生的误区刚接入完Agent拓扑图可能是空的。因为只有产生了实际调用SkyWalking才会生成拓扑关系。所以接入后记得去访问几次业务接口让Agent采集到真实流量。拓扑图的核心用法不是“看”而是“找”。线上反馈某个服务异常时先看拓扑图上相关节点的连接是否异常往往几秒钟就能定位是谁在调用谁、哪个环节出了问题。5.2 链路追踪定位慢接口当一个接口变慢最常规的排查路径是进入“追踪”页面按入口服务名过滤设置时间范围搜索找到响应时间异常的Trace点击进入详情详情以树状结构展示该请求经过的所有Span每一个Span包含服务名、端点、耗时、开始时间、异常堆栈等信息哪个Span耗时最长瓶颈大概率就在那个服务节点上。举例来说一次下单请求跨了网关、订单服务、库存服务、支付服务四个节点四个Span耗时分别是20ms、800ms、30ms、60ms那么瓶颈一眼锁定在订单服务内部再结合该服务的日志或数据库指标进一步定位到具体代码。界面上的“火焰图”和“树形图”是两种查看方式火焰图更适合看耗时分布占比树形图更适合理解调用逻辑。两者切换使用效率会高很多。5.3 指标看板如何解读在“服务”页面可以查看每个服务和实例的指标面板核心指标有指标含义平均响应时间一段时间内请求耗时均值TP99响应时间99%的请求耗时在多少毫秒以内吞吐量CPM每分钟请求数活跃线程数服务实例的线程活跃情况我个人更关注TP99而不是平均响应时间。平均值容易被长尾请求拉高而TP99能真实反映绝大多数用户的体验。曾经有个服务平均RT看起来正常但TP99持续超3秒顺着Trace查到最后是一个慢SQL在起作用。5.4 告警规则配置和Webhook推送SkyWalking内置告警规则在OAP的config/alarm-settings.yml中。修改后需要重启OAP才会生效。举一个实际可用的配置服务平均响应时间超过1000ms、连续触发3次、沉默期5分钟通过Webhook推送到外部系统。rules: service_resp_time_rule: metrics-name: service_resp_time op: threshold: 1000 period: 10 count: 3 silence-period: 5 message: 服务 {name} 平均响应时间超过 1000ms请检查。 webhooks: - http://your-alert-system:8080/notify告警Webhook发送的payload是一段JSON里面包含服务名、指标值、消息、触发时间等信息。你可以用这个地址接收再转发到钉钉、企业微信或者自建平台。这个文件踩坑概率很高。YAML缩进非常严格冒号后必须有空格如果缩进错导致OAP启动失败报错信息还不一定直观。建议改完配置后先找个YAML校验工具过一遍再重启。6. 排障工具箱我经历过的高频问题和解决方式6.1 连接超时与端口不通这是最高频的问题。现象是UI能打开但服务页面空白或者Agent日志里大量连接超时。排查方法是先测端口telnet 192.168.1.10 11800不通就看云安全组、iptables、firewalld。注意11800和12800应该只对业务网段开放不要暴露公网。6.2 版本兼容性引发的沉默故障Agent和OAP版本不匹配的表现形式很迷惑人——服务正常启动、业务无异常、UI也不报错就是没有数据。我在生产环境遇到过的版本兼容坑就是OAP是9.0、Agent是8.15所有Trace消失。规避办法很简单Agent和OAP用同一个发布版本的安装包升级时同步升级。6.3 配置缩进与热加载的静态判断application.yml和alarm-settings.yml都是静态配置文件修改后必须重启对应进程。好多朋友改完配置等待自动生效最后白等半天。建议每次改配置后按“改配置-校验YAML-重启进程-查看日志”的顺序操作。6.4 存储索引与namespace冲突ES存储下SkyWalking会自动创建大量以索引前缀开头的索引。如果和其他业务共用ES集群且没设namespace后期清理数据、管理索引模板都会很被动。设置namespace之后所有索引都会有统一前缀。要清理历史数据时直接按前缀操作即可风险更低。6.5 采样率与内存调优默认情况下Agent会对所有请求做全量采样。线上大流量场景全量采样会带来不小的网络和存储开销。可以通过agent.config里的采样率参数调整agent.sample_n_per_3_secs${SW_AGENT_SAMPLE_PER_3_SECS:1}这个参数含义是每3秒采样多少条请求。设置合理采样率可以在成本和链路完整度之间做平衡。我的做法是核心服务保持适当采样率排查低频问题时临时调高问题解决后恢复。内存方面OAP的堆内存默认由oapService.sh里的JVM参数控制。大流量场景下建议手动调大export OAP_JAVA_OPTS-Xmx4096m -Xms4096m6.6 时区、时间窗口、缓存等日常小坑数据不刷新不一定都是大问题小坑也会让人卡半天时区UI默认按浏览器本地时间展示服务器如果是UTC日志时间戳和界面时间对不上。时间窗口UI默认查最近15分钟刚接入的服务如果没流量自然看不到数据。先手动请求几次。缓存Agent配置或OAP配置修改后不会热加载必须重启进程。服务名重复多个接入服务配了同一个service_nameSkyWalking会当成一个服务实例下混在一起看起来就特别乱。6.7 安全加固SkyWalking的UI和OAP端口不建议直接在公网暴露。至少做到几点UI用Nginx反向代理并加基本认证11800端口监听在内网IP如果必须对外在网关上做IP白名单。这虽然不是功能性配置但对生产环境至关重要。最后用自己的真实体感收个尾。SkyWalking搭好以后我最大的感受不是“监控图变多了”而是排查思路被重塑了。以前是先查告警、再翻日志、再靠猜现在变成打开拓扑图和Trace页面先定位瓶颈服务和接口再拿日志做二次确认。这套流程稳定以后处理线上性能问题的时间基本能缩短一半以上。如果你正在为分布式系统的性能问题头疼花半天时间把SkyWalking搭起来这笔投入非常值得。