建议收藏 | SkyWalking：集群搭建教程

▌ 技术引导
SkyWalking 集群搭建最值钱的是配置多节点穿透式通信与数据聚合，确保全局追踪数据的实时性和一致性。直接用 Docker Compose 搭建时，务必在 agent 配置中设置 agent.id 为唯一标识，且所有节点的 storage 模块要指向同一个 Elasticsearch 集群，否则会出现数据不一致或丢失。我见过很多拉取镜像后直接启动，结果集群无法发现彼此，这时候要检查 agent.config 中的 cluster.name 是否一致。如果使用 Kubernetes，我建议用 DaemonSet 部署 agent，这样每个节点都能拉起一个 agent 实例，避免单点故障。另外，gRPC 代理在跨网络通信时必须配置 TLS，否则会触发协议不匹配的错误。所以，从启动脚本到配置文件，每一步都要踩准细节。

实际部署时，我用的命令是 `docker-compose up -d`，但必须在 docker-compose.yml 文件中将 agent 与 storage、oap 服务的网络策略设置为 bridge，避免容器间无法互相访问。有些人在启动集群时忽略了 agent 的 endpoint 配置，导致监控数据无法上传。还有人用 IP 地址直接连接，结果发现集群内部服务发现机制失效，这时候要确保 agent 与 oap 之间的服务名在 DNS 中正确解析。如果使用外部存储，比如 MinIO，要确认 agent 的 storage.type 配置是否正确，并设置 storage.backend 的具体地址。我之前因为没同步 agent.id 到 storage，导致一些 span 数据无法被正确归因，这时候得在启动脚本中输出 agent.id 并同步到配置中心。

在配置 ensemble 模式时，最简单的方式是用 Elasticsearch 的 cluster.name 做统一标识，所有节点的配置文件要保持一致。我见过有人在 oap 服务启动时没有指定正确的 es 配置，导致数据写入失败。另外，agent 和 oap 的版本必须一致，否则会因为协议不兼容引发异常。如果使用 Kafka 作为传输中间件，要确保 agent.config 中的 collector.backend 配置为 kafka，并指定正确的 topic 名称，否则数据会堆积在 agent 处。还有人问为什么启动后服务无法发现，其实是因为没有设置 service discovery 的地址，这个地址需要通过服务发现组件，比如 Consul 或 etcd，进行注册与解析。

一 安装与初始化
二 服务发现与网络配置
三 数据存储与传输协议
四 集群成员发现机制
五 优化与性能调优

▌ 技术参考
一 安装与初始化
使用 Docker Compose 安装 SkyWalking 集群时，需要先准备三张镜像：agent、oap、storage。镜像版本必须一致，否则 agent 和 oap 之间会因为协议不匹配导致数据无法传输。安装命令通常为 `docker-compose up -d`，但要注意 agent 的配置文件中必须设置 `agent.id=xxx`，确保每个节点识别唯一。初始化脚本可以写成 `echo 'agent.id=skywalking-agent-01' > agent.config`，这样在启动时命令行就能看到正确配置。对于 storage 模块，如果使用 Elasticsearch，需要在启动脚本中配置 `storage.type=elasticsearch`，并指定 `elasticsearch.servers=es-host:9200`。有些人在初始化存储时忘记配置 index 名称，导致数据写入到错误的索引，这时候要检查 `storage.index=skywalking` 的设置。

二 服务发现与网络配置
SkyWalking 集群内部服务发现通常依赖 DNS 解析，比如 Kubernetes 中的 CoreDNS 或者 Docker 的内置 DNS。在 agent 启动时，必须确保能够正确访问 oap 服务的地址。如果使用 Docker 网络，可以在 docker-compose.yml 中设置 `networks: default`，这样 agent 和 oap 服务就能在同一个网络中互通。如果服务部署在不同网络，需要手动配置 agent 的 `collector.backend_service` 为 oap 服务的 DNS 名称，例如 `collector.backend_service=opentelemetry-collector:11800`。对于跨网络的场景，最好使用 gRPC 代理，这样可以集中处理服务发现和负载均衡。
另外，要确保所有 agent 实例的 `agent.config` 文件中 `service_name` 一致，避免监控数据被错误分类。我见过有人因为服务名不一致，导致监控面板上出现多个重复的服务，这时候需要统一配置。如果是本地测试环境，可以使用 `--add-host=opentelemetry-collector:127.0.0.1` 参数直接指定 oap 的 IP 地址，这样避免 DNS 解析错误。

三 数据存储与传输协议
SkyWalking 的数据存储模块必须统一配置，否则会出现数据不一致的情况。如果使用 Elasticsearch，需要确保每个 agent 都连接到同一个集群，并且 `storage.type=elasticsearch`、`storage.index=skywalking` 的设置正确。在 oap 服务的配置中，需要指定 `elasticsearch.servers=es-host:9200`，并确保 `elasticsearch.cluster.name=skywalking-cluster`，这样所有节点才能识别同一个存储环境。我用过 Kafka 作为传输中间件，这时候 agent 的 `collector.backend_service` 要设置为 Kafka 的地址，并且 `collector.backend=kafka`。如果 Kafka 配置了 TLS，需要额外添加 `kafka.ssl.enabled=true` 和 `kafka.ssl.truststore.location=/path/to/truststore.jks` 等参数。在 Kubernetes 中，建议使用 ConfigMap 来集中管理这些配置，避免镜像版本不一致带来的问题。

四 集群成员发现机制
SkyWalking 集群成员发现通常通过 gRPC 代理实现，这个代理需要配置成所有节点都能访问的地址。在 agent 的配置文件中，必须设置 `collector.backend_service=grpc-agent-01:11800`，这里的地址要确保所有 agent 实例都能解析到对应的 gRPC 服务。如果使用 Consul 作为服务发现，可以在 agent 的启动脚本中添加 `service_discovery.url=consul://consul-host:8500`，并确保 `service_discovery.type=consul`。这样，当 agent 启动时，会自动注册服务到 Consul，同时 oap 服务也能从中获取所有 agent 的地址。在 Kubernetes 中，可以使用 `--service-discovery=K8S` 参数，这样 agent 会自动从 Kubernetes API 获取服务地址，避免手动维护服务列表。

五 优化与性能调优
SkyWalking 集群的性能优化主要集中在 agent 的采集频率和存储压力上。默认情况下，agent 每秒会发送一次追踪数据，如果业务量大，可以适当调高 `agent.max_trace_id=1000000`，减少数据堆积。同时，要配置 `agent.collector.backend_service` 为 gRPC 代理地址，避免 HTTP 长连接带来的资源浪费。如果使用 Elasticsearch，可以调整 `storage.max_data_age=30d`，这样可以控制数据保留时间，减少磁盘压力。在 oap 服务中，可以配置 `oap.log.level=info` 来优化日志输出，避免日志量过大影响性能。对于高并发场景，建议启用 `gRPC.keepalive.time=300s` 和 `gRPC.keepalive.timeout=50s`，这样可以减少连接建立的开销。

六 适用场景与局限性
SkyWalking 集群适用于多节点部署、需要全局追踪的微服务架构。比如在 Kubernetes 上部署多个服务实例，每个实例都需要 agent 收集数据，并通过 oap 节点聚合。如果服务数量较多，可以使用 ensemble 模式来提升可靠性。但集群也存在局限性，比如依赖 DNS 解析，如果网络不稳定，会导致服务发现失败。此外，存储层如果配置不当，比如 Elasticsearch 的副本数过高，会增加写入延迟。在某些边缘计算场景下，如果网络带宽有限，使用 gRPC 代理可能会增加传输开销。因此，需要根据网络环境和业务需求灵活调整配置。

七 替代方案或进阶技巧
如果不想用 SkyWalking 集群，可以选择独立部署 oap 与 storage 模块，这样可以避免服务发现的复杂性。但独立部署时，每个 agent 都需要手动配置 oap 的地址，维护成本较高。另一个替代方案是使用 Prometheus+Grafana 监控，但不具备分布式追踪能力。如果希望提升性能，可以考虑使用 Kafka 作为传输中间件，这样可以缓解 oap 的压力。在进阶技巧方面，可以使用 `--config-file=/path/to/agent.config` 参数指定 agent 配置文件，这样在 Kubernetes 中能方便地通过 ConfigMap 注入配置。另外，可以启用 `agent.max_span_count=5000` 来控制每个请求的最大追踪数，避免资源浪费。

八 配置文件详解
SkyWalking 的 agent 配置文件通常包含 `agent.id`、`service_name`、`collector.backend_service` 等关键参数。其中，`agent.id` 必须唯一，否则会触发 ID 冲突错误。`service_name` 是服务注册的名称，建议使用业务组件名，如 `user-service`。`collector.backend_service` 指定 gRPC 代理地址，例如 `grpc-agent-01:11800`。在 oap 配置中，`storage.type` 用于选择存储类型，支持 elasticsearch、kafka、minio 等多种方案。如果使用 Kafka，需要配置 `storage.backend=kafka` 和 `kafka.servers=broker1:9092,broker2:9092`。同时，`oap.log.level=info` 可以控制日志输出级别，避免日志量过大。在 Kubernetes 中，可以使用 ConfigMap 来管理这些配置，确保每个 agent 实例拿到正确的参数。

九 安全与加密配置
SkyWalking 的安全配置主要集中在 gRPC 代理和存储层的加密上。如果使用 TLS，可以在 agent 配置中添加 `gRPC.ssl.enabled=true`，并指定 `gRPC.ssl.truststore.location=/path/to/truststore.jks`。同时，`gRPC.ssl.truststore.password=yourpassword` 必须正确设置，否则连接会失败。在 oap 服务中，需要配置 `storage.ssl.enabled=true` 和 `storage.ssl.client.truststore.location=/path/to/client-truststore.jks`，确保与 storage 之间的通信安全。如果 storage 配置了授权，还需要在 agent 的 `storage.auth.username` 和 `storage.auth.password` 中填写相应的凭据。在 Kubernetes 中，可以使用 Secret 类型来管理这些敏感信息，避免明文暴露在配置文件中。

十 常见踩坑场景与避坑方案
在部署 SkyWalking 集群时，最常见的坑是节点无法互相发现。我见过有人在启动时没有设置 `agent.id`，导致多个 agent 使用相同 ID，这时候监控面板会显示错误的追踪数据。另一个常见问题是存储配置错误，比如 Elasticsearch 的地址写错，或者索引名称不一致，这时候数据会丢失。还有人在使用 Kafka 时忘记配置 `kafka.servers`，导致 agent 无法发送数据。针对这些情况，可以在启动脚本中添加日志输出，比如 `--log.level=debug`，这样可以更快定位问题。此外，要确保防火墙规则允许 gRPC 代理和存储层的端口互通，比如 11800 和 9200。

十一 集群节点数量与性能关系
SkyWalking 集群的性能与节点数量密切相关。通常情况下，3-5 个 oap 节点能有效处理中等规模的追踪数据。如果节点数量太少，比如只有 1 个 oap，会增加单点故障的风险，且数据处理压力较大。当节点数量增加到 10 个以上时，可以考虑使用 Kafka 作为传输层，减少 oap 的负载。在存储层，Elasticsearch 的副本数建议设置为 1，这样既能保证数据可用性，又不会带来过多的写入延迟。如果业务量极大，可以考虑使用 MinIO 作为冷存储，这样能够降低成本，同时不影响实时监控。

十二 容器网络与服务发现
在容器环境下，SkyWalking 的服务发现必须通过 DNS 或服务注册机制实现。比如在 Docker 中，可以使用 `--add-host` 参数将 oap 的地址映射为 `opentelemetry-collector:127.0.0.1`，这样 agent 就能正确连接。在 Kubernetes 中，可以使用 `--service-discovery=K8S` 参数，这样 agent 会自动从 Kubernetes API 获取 oap 服务的地址。如果使用 Consul，需要在 agent 的配置中添加 `service_discovery.url=consul://consul-host:8500`，并确保 Consul 中注册了正确的服务。另外，要确保所有 agent 实例的 `agent.id` 是唯一的，这样可以避免数据冲突。

十三 网络策略与端口配置
SkyWalking 集群的网络策略必须开放所有相关端口，尤其是 gRPC 代理和存储层的端口。gRPC 代理默认使用 11800 端口，存储层如 Elasticsearch 使用 9200，Kafka 使用 9092。在 Kubernetes 中，可以通过 Service 资源暴露这些端口，例如 `type: ClusterIP` 或 `type: LoadBalancer`。如果部署在云环境中，建议使用 `type: LoadBalancer`，这样外部可以访问到服务。同时，要确保所有节点之间可以通过 DNS 解析找到彼此，比如 `opentelemetry-collector` 或 `elasticsearch`，否则 agent 无法连接到 oap 或存储层。

十四 多节点配置与负载均衡
在多节点部署中，SkyWalking 需要配置负载均衡策略，以保证数据均匀分布。通常，gRPC 代理会自动处理负载均衡，但需要确保所有 agent 实例的 `collector.backend_service` 指向同一个 gRPC 代理地址。如果使用 Kubernetes，可以将 gRPC 代理部署为 DaemonSet，这样每个节点都有一个代理实例，避免单点故障。此外，可以在 oap 服务中配置 `oap.max_connections=1000`，这样可以限制连接数，提升稳定性。如果发现某个节点负载过高，可以手动增加 oap 实例，或者在 agent 配置中调整 `agent.max_trace_id`，降低单次发送的数据量。

十五 日志与调试技巧
SkyWalking 的日志调试是排查问题的关键。在 agent 启动时，可以通过 `--log.level=debug` 查看详细的连接日志，确认 agent 是否能正确连接到 oap 服务。如果发现数据丢失，可以检查 `storage.max_data_age` 的配置，确保数据没有被过早删除。同时，可以使用 `--config-file=/path/to/agent.config` 参数指定配置文件，这样在 Kubernetes 中能方便地通过 ConfigMap 管理配置。此外，可以使用 `--config-file=/path/to/agent.config --log.file=/path/to/agent.log` 来指定日志输出路径，方便后续分析。在 oap 服务中，日志级别也可以设置为 `info`，这样能减少不必要的输出，同时保留关键信息。