1. 为什么在动手之前要先想清楚"搭哪一层"
很多人看到"SkyWalking搭建"这几个字，第一反应就是打开搜索引擎，复制一段docker-compose配置，粘贴，回车，浏览器打开8080端口，看到界面出来了，就觉得"搭好了"。我最早也是这么干的，结果后面接应用的时候各种问题冒出来：探针连不上、数据查不到、拓扑图是空的、告警不触发。回头一查，发现根子上是搭建阶段就没想清楚自己要的是哪一层的东西。
SkyWalking这套东西，从部署形态上大致可以分成三块：存储层、OAP服务层、UI展示层，再加上一个探针采集层（探针是跟着业务应用走的，不算在服务端搭建里，但搭建时必须为它预留好接入条件）。所谓"搭建"，本质上是把前三层跑起来，并且让它们之间能正确对话，同时给第四层留好入口。
为什么强调"先想清楚搭哪一层"？因为不同的使用场景，对这三层的取舍完全不同。我见过几种典型情况：
- 个人学习/本地验证：一台机器，用内置的H2存储，OAP和UI都跑起来，探针接一个本地demo应用，能出数据就行。这种最省事，但H2存储重启就丢数据，绝对不能上生产。
- 小团队内部试用：一台中等配置的服务器，用Elasticsearch做存储，OAP单节点，UI单节点，接几个测试环境的服务。这种要开始考虑存储的持久化和磁盘规划了。
- 生产环境：存储用ES集群或者其它成熟方案，OAP多节点做负载，UI可以多实例，前面挂负载均衡，探针按服务规模配置采样率。这种搭建的重点已经不是"能不能跑起来"，而是"稳不稳、扛不扛得住、数据留多久"。
我下面讲的内容，会以**单机搭建一套完整可用的SkyWalking（OAP + UI + Elasticsearch存储）**为主线，因为这是绝大多数人真正需要的起点——既能验证功能，又足够接近生产形态，不至于学一套"玩具配置"后面全部推倒重来。同时我会把每一步"为什么这么选"讲清楚，这样你后面要扩成集群或者换成别的存储，心里有底。
在正式开始之前，先把版本这件事说清楚。SkyWalking的版本迭代比较快，不同大版本之间配置项、UI、探针协议都有差异。我建议OAP、UI、探针三者版本保持一致，这是最省心的做法。跨版本混用不是不行，但需要查兼容性矩阵，新手很容易在这里翻车。本文的配置思路适用于较新的9.x系列，具体版本号你按官方发布页选一个稳定的即可，思路是通用的。
提示：搭建之前先确认服务器的时间同步是正常的。SkyWalking的链路数据强依赖时间戳，如果OAP所在机器和业务机器时间差了几分钟，你会看到链路时间错乱、拓扑关系诡异，排查起来非常痛苦。这个坑我踩过，后来养成了搭建前先对时的习惯。
2. 存储选型：H2、Elasticsearch还是别的
存储是SkyWalking搭建里第一个必须做的决策，因为它直接决定了OAP的配置文件怎么写、服务器要多少资源、后面数据怎么维护。我把常见的几种选择摆出来对比一下，你就明白为什么我主线选ES。
| 存储类型 | 适用场景 | 优点 | 缺点 | 我的建议 |
|---|---|---|---|---|
| H2 | 本地学习、功能验证 | 零依赖，开箱即用 | 重启丢数据，性能差，不支持大规模 | 只用来跑通流程 |
| Elasticsearch | 小团队到中大型生产 | 成熟、生态好、查询灵活 | 吃内存、需要单独维护 | 主力推荐 |
| MySQL | 数据量小的场景 | 运维熟悉 | 写入性能有限，官方支持一般 | 不推荐做主力 |
| BanyanDB | 官方自研，较新 | 为可观测性场景优化 | 生态和资料相对少 | 愿意尝鲜可试 |
| 对象存储等 | 特定归档场景 | 成本低 | 实时查询弱 | 配合其它存储用 |
为什么ES是主流选择？因为SkyWalking写入的是海量的链路span数据，特点是写多读少、按时间维度查询、数据量大。ES的倒排索引和分片机制天然适合这种负载，而且它本身在运维圈子里普及度高，出问题好找人问。H2虽然简单，但它是嵌入式数据库，OAP一重启数据就没了，你辛苦接的探针数据全白费，学习阶段无所谓，一旦要给别人演示或者做持续观察，就必须换掉。
选ES之后，还有一个绕不开的问题：ES的版本。SkyWalking对ES版本有要求，太老的版本不支持，太新的版本可能还没适配。我的经验是选一个SkyWalking官方文档里明确列出的、经过验证的ES版本，不要盲目追最新。另外ES从7.x开始默认开启了安全认证，而SkyWalking的默认配置里往往是不带认证的，这两者一撞上，OAP就连不上ES，日志里会报认证相关的错误。这个后面在配置环节我会专门讲怎么处理。
资源规划上给个参考：单机跑ES + OAP + UI，内存建议至少8GB起步，其中ES分到4GB左右（通过JVM参数控制），OAP分2GB，剩下的留给系统和UI。如果你机器只有4GB，那ES会跑得很挣扎，查询经常超时，体验很差。磁盘方面，链路数据的体积增长很快，取决于你的采样率和流量，建议先留出50GB以上，并且规划好清理策略——ES的索引是会一直涨的，不清理迟早撑爆磁盘。
注意：ES对文件句柄数和虚拟内存映射有系统级要求，Linux下需要调整
vm.max_map_count，否则ES启动会直接失败。这个不是SkyWalking的问题，是ES自身的硬性要求，但很多人第一次搭会卡在这里，以为是SkyWalking配置错了。
3. 一步步把OAP和UI跑起来
这一节是实操的核心。我按"先存储、再OAP、最后UI"的顺序来，因为OAP启动时会去连存储，存储没准备好OAP会报错退出，顺序反了你会看到一堆吓人的异常日志。
3.1 先把Elasticsearch拉起来并确认健康
不管你用容器还是二进制包，ES起来之后第一件事是确认它真的健康，而不是进程在就算数。访问它的健康检查接口，看到状态是green或者yellow都算可用（单节点通常是yellow，因为副本分片没法分配，这是正常的，不用慌）。如果看到red，说明有主分片没分配成功，这时候OAP连上去也会有问题，得先把ES弄健康。
ES起来后，建议先手动创建一个给SkyWalking用的索引模板或者至少确认默认的索引创建是开的。SkyWalking会在写入时自动按天创建索引，如果ES禁止了自动创建索引，OAP写入就会失败。这个开关在ES的配置里，默认一般是允许的，但有些加固过的环境会关掉，需要留意。
3.2 OAP的配置文件改哪几个地方
OAP的配置文件是核心，里面东西很多，但搭建阶段真正要动的就那么几处。我把它拆成"必改"和"按需改"两类。
必改项：
- 存储指向：把storage的selector改成elasticsearch，然后填上ES的地址、端口。如果是ES集群，多个节点用逗号隔开。
- ES认证：如果你的ES开了认证，这里要填用户名密码；如果没开，就留空或者按无认证配置。这一步是新手最容易漏的，漏了就是连不上。
- 命名空间/集群名：给这套SkyWalking起个名字，后面UI和探针都会用到，多套环境时能区分开。
按需改项：
- 采样率：默认是全采样，生产环境流量大时全采样会把存储写爆，需要调低。学习阶段保持默认即可。
- 数据保留时间：控制链路数据在ES里留多久，默认好像是几天，生产环境按合规和成本要求调整。
- 接收端口：OAP默认监听几个端口，分别对应gRPC和HTTP协议，探针用哪个协议就连哪个端口。默认值一般不用改，但如果端口被占用就得换。
改完配置后启动OAP，不要只看进程在不在，要看日志。OAP启动日志里会明确打印它连上了哪个存储、监听了哪些端口、有没有报错。如果日志里出现连接超时、认证失败、索引创建失败这类字样，说明配置还有问题，别急着往下走。
提示：OAP启动后，可以先用一个简单的健康检查接口确认它活着。SkyWalking的OAP提供了健康检查端点，返回正常就说明服务本身没问题。这一步能帮你把"OAP自身问题"和"探针接入问题"分开，排查时非常有用。
3.3 UI怎么连上OAP
UI是个纯前端加一层轻量后端的东西，它的配置很简单，核心就是告诉它OAP的地址。改完启动，浏览器打开UI端口，如果能看到界面并且右上角没有报错，基本就通了。
这里有个细节：UI连OAP用的地址，如果是容器部署，要注意容器网络里的地址和宿主机地址不是一回事。我见过有人UI和OAP都在容器里，UI配置里写了localhost，结果连不上——因为在UI容器里localhost指的是UI自己，不是OAP。这种问题在容器化部署里非常常见，解决办法是用容器名或者服务名互连，或者干脆用宿主机网络。
UI起来之后，如果还没接探针，界面里是空的，这是正常的。别看到空界面就以为搭失败了，得先接一个应用产生数据，才能验证整条链路是通的。
4. 接一个探针，验证数据真的通了
服务端搭好只是完成了一半，真正证明"搭建成功"的标志是：一个应用接上探针后，UI里能看到它的服务、链路、拓扑和指标。这一步没做，你永远不知道自己的搭建是不是真的可用。
4.1 探针接入的三种常见方式
探针（Agent）是跟着业务应用走的，接入方式取决于你的应用怎么跑：
- Java应用：最常见，通过启动参数挂载agent，指定OAP地址和服务名。这种方式对代码零侵入，改个启动脚本就行。
- 容器化应用：把agent打进镜像，或者通过挂载卷的方式注入，启动参数里带上agent配置。
- 其它语言：SkyWalking对多种语言有探针支持，接入方式各不相同，但核心都是配置OAP地址和服务名。
以Java为例，接入时最关键的两个参数是服务名和OAP地址。服务名决定了UI里这个应用叫什么，OAP地址决定了数据往哪送。服务名建议用有意义的名字，比如按业务模块命名，别用默认的随机名，否则UI里一堆乱码一样的服务名，根本分不清谁是谁。
4.2 为什么探针连不上，先查这三处
探针接不上是最高频的问题，我总结了一个排查顺序，按这个顺序走基本能定位：
- 网络通不通：从应用所在机器，能不能访问到OAP的接收端口。用telnet或者nc测一下，不通就是网络或防火墙问题，跟SkyWalking配置无关。
- 端口对不对：探针配置的端口和OAP实际监听的端口是否一致。OAP有gRPC和HTTP两套端口，探针用哪个协议就要连哪个端口，连错了就是连不上。
- 服务名和认证：如果OAP开了鉴权（较新版本支持），探针要带上对应的token；服务名如果配了非法字符也可能出问题。
我遇到过一次，应用和OAP在同一台机器，探针就是连不上，最后发现是OAP只监听了内网某个地址，而探针配置里写的是另一个地址。这种问题看日志最直接——探针的日志里会明确写它尝试连接哪个地址、失败原因是什么。所以接探针时一定要看探针自己的日志，不要只盯着OAP。
4.3 数据出来了，怎么判断是不是"正常"
探针接上、应用有流量之后，UI里应该能看到东西了。但"看到东西"和"数据正常"是两回事。我一般会检查这几个点：
- 服务列表：能看到你配置的服务名，说明探针注册成功了。
- 链路追踪：随便点一条链路，能看到完整的调用链，每个span有耗时、有状态，说明数据采集是完整的。
- 拓扑图：服务之间的调用关系能画出来，说明跨服务的上下文传递是通的。
- 指标：服务的响应时间、吞吐量等指标有数据，说明指标采集正常。
如果链路有但拓扑是空的，通常是跨进程上下文传递没配好；如果指标有但链路没有，可能是采样或者探针配置的问题。这些细分问题的排查，前提是你先把"数据能出来"这个基线建立起来。
5. 搭建完之后必须做的几件收尾事
很多人搭完看到界面就收工了，结果过几天发现磁盘满了、数据查不到了、重启后配置丢了。搭建的"最后一公里"其实是这些收尾工作，做好了才能长期稳定用。
5.1 数据保留和磁盘清理策略
ES里的链路数据是只增不减的，除非你配置了清理。SkyWalking本身有数据保留时间的配置，到期的索引会被删除。但你要确认这个配置真的生效了，方法是观察几天，看旧索引有没有被清掉。如果没清，要么是配置没生效，要么是OAP没有权限删除索引。
另外，ES本身也有磁盘水位线机制，磁盘用到一定比例会变成只读，那时候OAP就写不进去了。所以磁盘监控是必须的，别等写不进去了才发现。
5.2 配置的持久化和备份
如果你用容器部署，配置文件一定要挂载出来或者用配置管理工具管理，别放在容器内部。容器一重建，配置全没了，你又得重新配一遍。我习惯把OAP和UI的配置文件放在宿主机的固定目录，容器启动时挂载进去，这样升级、迁移都方便。
5.3 给OAP和UI加上进程守护
单机部署时，OAP和UI如果挂了，不会自动起来。生产环境必须用systemd或者容器编排的restart策略做守护。我见过OAP因为内存溢出挂掉，结果一晚上没数据，第二天才发现。加上守护之后，至少进程挂了能自动拉起来，给你争取排查时间。
注意：自动重启只是兜底，不能替代监控。OAP频繁重启本身就是问题，要看日志找根因，而不是靠重启掩盖。
6. 从单机走向集群时，搭建思路要怎么变
单机搭通之后，如果你的服务规模上来了，迟早要考虑集群。集群化不是简单地把单机配置复制几份，有几个点必须提前想清楚。
OAP多节点：多个OAP节点可以同时接收探针数据，它们之间通过存储层共享数据，不需要节点间直接通信。这意味着你可以在OAP前面挂负载均衡，探针连负载均衡地址即可。但要注意，OAP节点之间的配置要一致，尤其是存储配置和集群命名。
UI多实例：UI是无状态的，可以起多个实例，前面挂负载均衡。UI连OAP时，如果OAP是多节点，UI配置里可以填多个OAP地址，它会自动做负载。
存储集群：ES本身要做集群，保证高可用。这时候OAP的存储配置里要填多个ES节点地址。ES集群的运维是另一个话题了，但搭建阶段至少要把节点地址配对。
探针的采样和限流：集群环境下，探针数量多、流量大，采样率必须调，否则存储扛不住。同时OAP层面也可以做限流，防止突发流量打垮服务。
我个人的体会是，单机搭建时就要把配置项的含义搞清楚，这样集群化时你才知道哪些要改、哪些不能动。如果单机阶段就是抄配置、不求甚解，集群化时会非常痛苦，因为你要面对的是成倍的复杂度和成倍的排查难度。
7. 几个我踩过、也见别人踩过的坑
最后分享几个具体的坑，都是搭建阶段高频出现的，提前知道能省不少时间。
坑一：ES起来了但OAP连不上，日志报连接被拒绝。八成是ES的地址或端口配错了，或者ES只监听了localhost而OAP在另一台机器。检查ES的network配置，确认它监听的地址是OAP能访问到的。
坑二：UI界面能打开但一直转圈、没数据。先确认OAP活着，再确认UI配置的OAP地址对不对。容器部署时特别注意localhost的问题。
坑三：探针接上了，服务列表有，但链路是断的。检查跨服务调用时上下文有没有透传，比如HTTP调用要带上特定的header，消息队列要带上特定的属性。这个跟具体框架有关，需要查对应探针的文档。
坑四：跑了一段时间磁盘满了。检查数据保留配置和ES磁盘水位，及时清理或扩容。这个坑的代价最大，因为磁盘满了之后OAP写不进去，整个可观测性就断了。
坑五：升级版本后配置不兼容。升级前一定看官方的升级说明和配置变更，别直接替换二进制包就重启。我习惯升级前先备份配置和数据，出问题能回滚。
搭建这件事，说难不难，说简单也不简单。难的不是敲几条命令，而是理解每一层在干什么、为什么这么配、出问题往哪查。把单机这套跑通、跑稳，你对SkyWalking的理解就已经超过大多数只会复制粘贴的人了。后面无论是扩集群、换存储还是接更多语言的应用，都是在这个基础上的自然延伸。
