SkyWalking 9.4.0 安装与Java Agent实战：从部署到验证的完整指南

SkyWalking 9.4.0 这套东西我第一次接触是在一个跨服务的调用链排查场景里——十几个服务互相调日志散落在不同机器上出了问题只能靠时间戳猜。后来把 Agent 挂上去调用链一下子从黑盒变成了地图哪个环节慢、哪次请求在哪个服务里卡住一眼就能看到。这次要聊的是 9.4.0 这个版本的安装包和 Java Agent 的获取与落地重点不在下载这个动作本身而在于拿到包之后怎么把它跑起来、Agent 怎么挂、挂完怎么验证、以及那些官方文档里不会写的坑。如果你手上正好有一套 Java 服务需要做链路观测或者你之前装过老版本想升级到 9.4.0这篇内容可以直接照着走。1. 先搞清楚 SkyWalking 9.4.0 到底由哪几块拼起来很多人拿到安装包第一反应是解压完找启动脚本结果发现目录里东西一大堆不知道哪个该先动。SkyWalking 的整体结构其实很清晰它不是一个单体应用而是后端 前端 Agent 存储四件套的组合。9.4.0 这个版本在目录组织上延续了 8.x 后期的风格但有几个细节变化值得单独拎出来说。1.1 后端 OAP 服务真正干活的核心OAPObservability Analysis Platform是整个 SkyWalking 的大脑。它负责接收 Agent 上报的数据、做聚合分析、写入存储、再对外提供查询接口。安装包里bin/目录下的oapService.shLinux/macOS和oapService.batWindows就是它的启动入口。9.4.0 的 OAP 默认走的是 H2 内存数据库这个设计对先跑起来看看效果非常友好——不用额外装数据库解压即用。但你要清楚H2 是内存模式进程一停数据就没了只适合验证和演示生产环境必须换掉。OAP 启动时会占用 11800 端口gRPC 数据上报和 12800 端口HTTP 查询这两个端口是 Agent 和 UI 通信的生命线。我见过不少人启动完发现 UI 打不开排查半天结果是 12800 被别的进程占了。所以启动前先netstat -tlnp | grep -E 11800|12800看一眼能省掉很多无谓的折腾。1.2 UI 前端你实际看到的那个界面UI 在webapp/目录下启动脚本是webappService.sh。它默认监听 8080 端口通过配置里的collector.path指向 OAP 的 12800 端口来取数据。这里有个容易忽略的点UI 和后端是分开启动的两个进程都要起来界面才能正常显示。只启动 OAP 不启动 UI你打开浏览器就是一片空白只启动 UI 不启动 OAP界面能打开但所有图表都是空的还会在控制台报连接失败。9.4.0 的 UI 在图表渲染上比早期版本流畅不少尤其是服务拓扑图那块节点多了之后不会像老版本那样卡顿。这个体验差异在服务数量超过二十个之后会非常明显。1.3 Java Agent挂到你的应用上才有数据Agent 是agent/目录下的那一坨 jar 包和配置文件。它的作用是通过字节码增强的方式在不改你业务代码的前提下把方法调用、数据库访问、HTTP 请求这些信息采集出来然后通过 gRPC 上报给 OAP。Agent 的核心配置在agent/config/agent.config里最关键的三个参数是agent.service_name你的服务叫啥、collector.backend_serviceOAP 在哪、agent.sample_n_per_3_secs采样率。Agent 的挂载方式是在 JVM 启动参数里加-javaagent:指向skywalking-agent.jar。这个动作看起来简单但挂载时机、路径写法、和现有 JVM 参数的兼容性都是容易出问题的地方后面会单独展开。1.4 存储层H2 只是起点不是终点前面说了默认是 H2但 9.4.0 支持的存储后端其实挺全Elasticsearch、MySQL、TiDB、PostgreSQL、BanyanDB 都在列。选哪个不是拍脑袋决定的得看你的数据量和查询需求。下面这张表是我根据实际使用经验整理的对照参数是常见场景下的经验值不是官方硬性指标存储类型适用数据量级部署复杂度查询性能典型场景H2演示/单机验证极低一般本地跑通流程MySQL中小规模中中等已有 MySQL 运维体系Elasticsearch大规模高高生产环境主力选择BanyanDB大规模中高高9.x 新推的专用存储选型逻辑很简单如果你只是想在本地验证 Agent 能不能正常上报H2 足够如果是要上生产Elasticsearch 或 BanyanDB 是更稳妥的选择MySQL 适合数据量不大但已经有现成运维能力的团队。这个判断依据来自一个很朴素的道理——链路数据的写入是持续高频的存储层的写入吞吐和索引能力直接决定了后端会不会成为瓶颈。2. 安装包获取与解压后的第一轮检查2.1 拿到包之后别急着启动安装包通常是一个 tar.gz 压缩包解压命令很常规tar -zxvf apache-skywalking-apm-9.4.0.tar.gz。解压完会得到一个apache-skywalking-apm-bin目录。我建议解压后先别急着跑脚本花两分钟做一轮目录体检这一步能提前发现很多问题。先看bin/下有没有可执行权限。有些环境下压缩包解压后脚本权限会丢失直接执行会报Permission denied。一条命令解决chmod x bin/*.sh。再看config/目录OAP 的配置文件application.yml就在这里存储选型、端口、集群配置全在这个文件里改。最后确认agent/目录完整里面应该有skywalking-agent.jar以及plugins/、config/、optional-plugins/这几个子目录。提示optional-plugins目录里的插件默认不生效需要手动复制到plugins/才会被加载。这个设计是为了控制 Agent 的启动开销别以为解压完所有插件就都激活了。2.2 版本对齐这件事比想象中重要9.4.0 的 OAP 和 Agent 是配套的理论上同版本之间兼容性最好。但实际场景里经常出现后端是 9.4.0Agent 还是 8.x的混搭情况。这种混搭不是绝对不行协议层有一定的向后兼容但新版本的一些特性比如某些指标维度在旧 Agent 上采集不到会导致 UI 上部分图表缺数据。我的做法是后端和 Agent 尽量保持同一大版本。如果确实要混搭先在测试环境验证一遍重点看服务列表、调用链、指标三个页面数据是否完整。判断依据是——Agent 上报的协议字段和后端解析的字段是一一对应的版本错位时字段缺失不会报错只会静默丢数据这种看起来正常但数据不全的情况最难排查。2.3 端口冲突的预检清单启动前把端口占用情况摸清楚比启动后抓瞎强。9.4.0 默认涉及的端口有这么几个11800OAP 的 gRPC 端口Agent 上报数据走这里12800OAP 的 HTTP 端口UI 查询走这里8080UI 的 Web 端口H2 的 TCP 端口如果开了远程访问默认 9092用ss -tlnp或netstat -tlnp逐个确认。如果 8080 被占改webapp/webapp.yml里的server.port如果 11800/12800 被占改config/application.yml里core/gRPC和core/rest对应的端口同时记得把 Agent 配置里的collector.backend_service和 UI 配置里的collector.path同步改掉。这三个地方的端口是联动的改一处不改另一处数据链路就断了。3. 后端启动从 H2 跑通到切换存储3.1 用 H2 先把链路跑通第一次接触这套系统我强烈建议先用默认的 H2 配置把整条链路跑通确认 Agent 能上报、UI 能展示再去折腾存储切换。启动命令就一句bin/oapService.sh start。启动过程会往logs/目录写日志用tail -f logs/skywalking-oap-server.log盯着看到类似 OAP starts successfully 的字样就说明起来了。这里有个细节OAP 启动时如果 H2 初始化失败日志里会有一串异常堆栈但进程可能不会立刻退出表现为启动了但端口没监听。判断方法是启动后等十秒左右用curl http://localhost:12800/internal/l7check探一下返回正常就说明 HTTP 服务真的活了。这个探活接口是我常用的一个土办法比看日志猜状态靠谱。3.2 切换到 Elasticsearch 的关键配置生产环境切 ES改动集中在config/application.yml的storage段。核心是这几行storage: selector: ${SW_STORAGE:elasticsearch} elasticsearch: namespace: ${SW_NAMESPACE:} clusterNodes: ${SW_STORAGE_ES_CLUSTER_NODES:localhost:9200} protocol: ${SW_STORAGE_ES_HTTP_PROTOCOL:http} user: ${SW_ES_USER:} password: ${SW_ES_PASSWORD:} indexShardsNumber: ${SW_STORAGE_ES_INDEX_SHARDS_NUMBER:2} indexReplicasNumber: ${SW_STORAGE_ES_INDEX_REPLICAS_NUMBER:0}clusterNodes填 ES 的地址多个节点用逗号分隔。indexShardsNumber和indexReplicasNumber这两个参数值得说道说道——分片数决定了索引的并行写入能力副本数决定了数据冗余。单机 ES 副本数设 0因为副本没法分配到不同节点上设了也是黄灯集群环境副本数至少 1。分片数不是越大越好分片过多会增加 ES 的集群管理开销中小规模数据量 2 到 3 个分片是比较稳的起点。改完配置重启 OAP第一次启动会自动创建索引模板和索引。这时候去 ES 里GET _cat/indices?v能看到一堆以sw_开头的索引说明存储层对接成功了。3.3 启动脚本背后的进程管理逻辑oapService.sh这个脚本本质上是调用了oapServiceInit.sh和oapServiceNoInit.sh的组合前者负责初始化比如检查 JAVA_HOME、准备目录后者负责真正拉起 Java 进程。它用的是nohup方式后台运行PID 会写到logs/下的某个文件里。停止用bin/oapService.sh stop这个命令会去读 PID 文件然后 kill 进程。踩过的坑如果进程被kill -9强杀PID 文件可能残留下次start时脚本检测到 PID 文件存在会误判已在运行而拒绝启动。解决办法是手动删掉残留的 PID 文件再启动。这个问题的根因是脚本的进程存活检测逻辑比较简单只看 PID 文件在不在不校验进程是否真的活着。4. Java Agent 挂载三种姿势和它们的适用边界4.1 命令行 -javaagent 方式最直接也最容易出错最基础的挂载方式是在启动命令里加参数java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar \ -Dskywalking.agent.service_namemy-service \ -Dskywalking.collector.backend_service127.0.0.1:11800 \ -jar my-app.jar这里有几个必须注意的点。第一-javaagent参数必须放在-jar之前JVM 参数的位置是有讲究的放错位置会被当成应用参数传给 main 方法而不是被 JVM 识别。第二skywalking-agent.jar的路径建议用绝对路径相对路径在不同工作目录下启动时容易找不到。第三-Dskywalking.xxx这种系统属性方式的配置优先级高于agent.config文件里的配置适合在启动命令里做差异化覆盖。我见过最典型的问题是把-javaagent写在了-jar后面结果 Agent 根本没加载应用正常启动但 SkyWalking 里看不到任何数据。排查这种问题的方法是启动时加-Dskywalking.agent.is_open_debugging_classtrueAgent 会在日志里打印类增强的详细信息有没有加载一目了然。4.2 环境变量方式容器化场景的优选在容器环境里改启动命令不如注入环境变量方便。Agent 支持通过SW_AGENT_NAME、SW_AGENT_COLLECTOR_BACKEND_SERVICES这类环境变量来配置export SW_AGENT_NAMEmy-service export SW_AGENT_COLLECTOR_BACKEND_SERVICESoap-host:11800 java -javaagent:/opt/skywalking/skywalking-agent.jar -jar my-app.jar环境变量的命名规则是把agent.config里的配置项转成大写、点换下划线、加SW_前缀。比如agent.service_name对应SW_AGENT_NAMEcollector.backend_service对应SW_AGENT_COLLECTOR_BACKEND_SERVICES。这个映射关系不是完全机械的个别配置项有特殊命名用之前最好翻一下官方文档的配置表确认。容器场景还有个细节Agent 目录要打进镜像里-javaagent路径指向镜像内的路径。如果用的是基础镜像加挂载的方式注意挂载的目录权限Agent 需要对 jar 包有读权限。4.3 配置文件方式适合统一管理直接改agent/config/agent.config文件是最静态的方式适合一批服务用同一套配置的场景。改完之后所有用这个 Agent 目录启动的应用都生效。缺点是灵活性差不同服务要不同配置就得复制多份 Agent 目录。实际项目里我通常采用配置文件打底 启动参数覆盖的组合agent.config里配好collector.backend_service这种全局一致的项service_name这种每个服务不同的项用-D参数在启动时覆盖。这样既减少了重复配置又保留了差异化能力。4.4 三种方式的选择逻辑挂载方式配置灵活性运维成本适用场景命令行 -javaagent高低单机部署、启动脚本可控环境变量高中容器化、K8s 部署配置文件低低批量服务统一配置选择的核心判断是配置差异化的粒度。如果每个服务的service_name都不同但后端地址一致配置文件打底加参数覆盖最省事如果整个环境都是容器化的环境变量方式跟现有的配置注入体系最契合。5. 挂载后的验证链路从有没有数据到数据对不对5.1 第一层验证Agent 有没有连上 OAPAgent 启动后最直接的验证是看 OAP 日志里有没有收到注册请求。logs/skywalking-oap-server.log里出现类似 Service instance registered 的记录说明 Agent 和后端握手成功了。另一个办法是看 Agent 自己的日志Agent 默认会把日志写到应用工作目录下的logs/skywalking-api.log里面有连接状态和上报情况的记录。如果两边日志都没有动静先查网络连通性telnet oap-host 11800或者nc -zv oap-host 11800。gRPC 端口不通的话Agent 会静默重试不会让应用报错所以从应用侧完全感知不到问题必须主动去查。5.2 第二层验证UI 上能不能看到服务打开http://ui-host:8080进服务页面正常情况下几秒到几十秒内就能看到你的服务名出现在列表里。如果服务列表是空的按这个顺序排查UI 的collector.path是否指向正确的 OAP 地址、OAP 的存储是否正常写入H2 模式下重启会丢数据如果刚重启过服务列表清空是正常的、Agent 的service_name是否配置正确。这里有个反直觉的点服务列表的刷新有延迟不是实时的。SkyWalking 的数据是分钟级聚合的刚挂上 Agent 后等一到两分钟再刷新页面比反复点刷新有用。5.3 第三层验证调用链数据是否完整服务能看到之后进追踪页面看具体的调用链。一条完整的链路应该能看到入口 span、中间的服务间调用 span、数据库访问 span、HTTP 客户端 span 等。如果链路只有入口没有下游通常是下游服务的 Agent 没挂或者service_name配错了导致跨服务上下文传递断了。跨服务上下文传递依赖 Agent 在 HTTP 头或 RPC 框架的元数据里注入追踪信息。如果用的是自定义的 RPC 框架可能需要额外的插件支持。9.4.0 的optional-plugins里有一批针对特定框架的插件用之前确认一下你的框架在不在支持列表里。5.4 采样率的取舍agent.sample_n_per_3_secs这个参数控制每 3 秒采样的请求数默认是 -1全采样。全采样在低流量服务上没问题但高 QPS 服务全采样会给后端带来很大压力也会让 Agent 自身的开销变明显。我的经验值是核心服务设 500 到 1000非核心服务设 100 到 300具体看后端存储的写入能力。采样率调低之后UI 上的调用链是抽样展示的但指标数据QPS、响应时间、错误率仍然是全量统计的因为指标聚合和链路采样是两条独立的路径。这个区别很多人不清楚以为采样了指标就不准了其实不是。6. 那些文档里不会写的实操坑6.1 JDK 版本与 Agent 的兼容性9.4.0 的 Agent 对 JDK 8 到 JDK 17 都有支持但不同 JDK 版本下字节码增强的行为有差异。JDK 8 上一切正常换到 JDK 17 之后如果应用用了模块化JPMSAgent 的类加载可能受模块访问限制影响表现为部分插件不生效。遇到这种情况检查启动参数里有没有--add-opens相关的配置必要时给 Agent 涉及的包加上模块开放。另一个常见问题是应用本身用了字节码增强框架比如某些 ORM 框架的动态代理和 Agent 的增强逻辑叠加后出现类冲突。排查方法是临时关掉 Agent 的某个插件把plugins/下对应的 jar 移到别处看问题是否消失以此定位是哪个插件引起的。6.2 日志目录权限与磁盘占用Agent 和 OAP 都会往logs/写日志如果运行用户对日志目录没有写权限进程可能启动失败或者日志静默丢失。部署时确认运行用户对安装目录有读写权限这个在容器里用非 root 用户运行时尤其要注意。磁盘占用方面OAP 的日志默认会滚动但 Agent 的日志在某些配置下增长较快。建议给logs/目录配一个定期清理策略或者调整日志级别到 WARN减少 INFO 级别的输出量。我见过一个案例是 Agent 日志一天涨了几个 G最后发现是调试开关忘了关。6.3 服务名命名规范带来的连锁反应service_name不只是个标签它直接决定了 UI 上服务的分组和拓扑图的节点。命名建议用应用名-模块名的格式比如order-service、user-service避免用带特殊字符或空格的名字。一旦服务名定下来后续改名会导致历史数据和新增数据分成两个服务展示拓扑图上出现断点。如果确实需要改名比较稳妥的做法是新旧名字并行一段时间等历史数据自然过期取决于存储的 TTL 配置后再下线旧名字。这个操作的成本不低所以一开始就把命名规范定好比事后补救划算得多。6.4 时区问题导致的时间错位Agent 上报的数据带时间戳OAP 存储和 UI 展示都依赖时区一致性。如果 Agent 所在机器和 OAP 所在机器时区不同UI 上的调用链时间可能和实际时间对不上排查问题时会被误导。统一时区是最简单的办法或者在 Agent 配置里显式指定时区。这个坑不常遇到但一旦遇到排查方向很容易跑偏到数据丢失上去。7. 从验证环境到生产环境的过渡清单把 H2 换成正式存储只是第一步生产环境还有几件事要做。第一是 OAP 的高可用单节点 OAP 挂了整个观测链路就断了多节点部署时要注意集群配置里节点间的通信端口和存储层的共享。第二是 Agent 的版本管理服务多了之后 Agent 目录散落在各个机器上升级时容易漏建议把 Agent 目录做成统一的基础设施通过配置中心或启动脚本统一注入。第三是数据保留策略链路数据的 TTL 要根据存储容量和排查需求来定太长占空间太短查不到历史问题一般核心服务保留 7 到 15 天是个平衡点。我在实际使用中的体会是SkyWalking 这类观测系统的价值不在于装上了而在于数据可信。数据可信的前提是 Agent 挂载正确、采样率合理、存储稳定、时区一致这几个环节任何一个出问题UI 上看到的图表都可能是误导性的。所以每次新环境部署我都会按Agent 连上没、服务看到没、链路完整没、指标对得上没这四步走一遍确认无误再交给业务方使用。这套流程看起来繁琐但比事后被错误数据带偏方向要省事得多。