Apache SkyWalking —— 国产开源一体化 APM：无侵入探针 + OAP 分析 + 拓扑/链路/指标/告警

分类：05 APM与链路追踪 适用：Java / Go / Python / Node.js / .NET 等多语言微服务、Service Mesh、K8s 云原生与混合云；单机 PoC 到数百服务大规模集群 一句话：Language Agent 自动埋点 → OAP 接收/聚合 → 可插拔存储 → UI 拓扑/链路/指标与告警，四件事收在一个平台 官方：https://skywalking.apache.org/ ｜ https://github.com/apache/skywalking 授权：Apache License 2.0（Apache 软件基金会顶级项目，开源免费、可商用）

版本说明：官方 main 分支已到 11.x（可查 v11.0.0 Backend setup 文档），新 UI 代号 Horizon；Java/Go/Python/Node.js Agent 为独立仓库、独立发版。本文镜像 tag、发行包版本一律写「以官方最新稳定版为准」，不锁定具体数字。

1. 它解决什么问题

不适合：只需纯链路且已全面 OTel 化（Jaeger/Tempo 更轻）；只要基础设施指标（Prometheus 系）；需闭源商业支持；无法承担 OAP + 有状态存储运维的小团队。OAP 是有状态分析集群，不是无状态采集器。

2. 核心概念与架构

 应用（无侵入）       ┌──────── OAP 集群 ────────┐       存储 / 消费
┌──────────────┐ gRPC │ Receivers(:11800 gRPC) │     ┌─────────────────┐
│ Java Agent    │─────►│ agent/OTLP/Zipkin/ALS │ 写  │ BanyanDB :17912 │
│ Go/Python/Node│ sw8  │ Analyze: OAL/MAL 聚合 │────►│ (默认推荐)      │
│ .NET/PHP/Rust…│─────►│ Alarm: MQE 规则        │     │ ES/OpenSearch   │
│ Rover(eBPF)   │ OTLP │ Query: GraphQL(:12800)│     │ MySQL/PostgreSQL│
└──────────────┘      └───────────┬───────────┘     └────────┬────────┘
                                  ▼                          │ 读
                       ┌──────────────────┐ HTTP ┌───────────────────┐
                       │ UI :8080         │◄─────│ 告警 hooks →      │
                       │ 拓扑/链路/仪表盘  │      │ Webhook/企业微信  │
                       └──────────────────┘      └───────────────────┘

链路：Agent 埋点 → OAP 接收/分析 → Storage 落盘 ← UI 查询 → Alarm 推送。Agent 与 OAP 走 :11800 gRPC（OTLP、Envoy ALS、eBPF、Satellite 共享）；UI/运维查 :12800 GraphQL，二者勿混。OAP 先把 TraceSegment 注册成 Service/Instance/Endpoint 字典再聚合，故首次接入需等 1~2 个采集周期。

探针语言支持（官网 ECOSYSTEM「11 language agents」，各仓库独立发版）

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

# 版本号、镜像 tag 一律以官方最新稳定版为准
export SW_VER=<以官方最新稳定版为准>
export BYDB_VER=<与 OAP 兼容的 BanyanDB Server 版本，见 4.4>
# A. 官方二进制包（物理机/VM）：从 https://skywalking.apache.org/downloads/ 下载 apache-skywalking-apm-<SW_VER>.tar.gz
tar -xzf apache-skywalking-apm-${SW_VER}.tar.gz && cd apache-skywalking-apm-${SW_VER}
ls config/application.yml config/alarm-settings.yml webapp/webapp.yml bin/startup.sh
bin/startup.sh                 # OAP + UI；分开用 bin/oapService.sh / bin/webappService.sh
# B. Docker 独立容器（依次起存储 → OAP → UI）
docker run -d --name banyandb -p 17912:17912 -p 17913:17913 apache/skywalking-banyandb:${BYDB_VER} standalone
docker run -d --name oap -p 11800:11800 -p 12800:12800 \
  -e SW_STORAGE=banyandb -e SW_STORAGE_BANYANDB_TARGETS=<BanyanDB_HOST>:17912 \
  -e SW_CLUSTER=standalone apache/skywalking-oap-server:${SW_VER}
docker run -d --name ui -p 8080:8080 -e SW_OAP_ADDRESS=http://<OAP_HOST>:12800 apache/skywalking-ui:${SW_VER}
# C. K8s Helm（官方 chart，版本以官方最新稳定版为准）
helm install skywalking oci://docker.io/apache/skywalking-helm --version <chart版本> \
  --set oap.image.tag=<SW_VER> --set oap.storageType=banyandb \
  --set elasticsearch.enabled=false --set banyandb.enabled=true \
  --set banyandb.image.tag=<BYDB_VER> --set ui.image.tag=<SW_VER>
kubectl get svc,pod -l app=skywalking    # K8s 另可用 SWCK Java Agent Injector 挂 sidecar

D. Docker Compose（推荐，一键全套）

# docker-compose.yaml —— tag 以官方最新稳定版为准
services:
  banyandb:
    image: apache/skywalking-banyandb:${BYDB_VER}
    command: standalone
    ports: ["17912:17912", "17913:17913"]
  oap:
    image: apache/skywalking-oap-server:${SW_VER}
    environment:
      SW_STORAGE: banyandb
      SW_STORAGE_BANYANDB_TARGETS: banyandb:17912
      SW_CLUSTER: standalone
      SW_OTEL_RECEIVER: default
      SW_OTEL_RECEIVER_ENABLED_OC_RULES: vm
    ports: ["11800:11800", "12800:12800"]
    depends_on: [banyandb]
  ui:
    image: apache/skywalking-ui:${SW_VER}
    environment: { SW_OAP_ADDRESS: http://oap:12800 }
    ports: ["8080:8080"]

E. 二进制 + systemd（生产托管）

# /etc/systemd/system/skywalking-oap.service
[Service]
Type=forking
User=skywalking
Environment=SW_STORAGE=banyandb
Environment=SW_STORAGE_BANYANDB_TARGETS=<BanyanDB_HOST>:17912
Environment=SW_CLUSTER=standalone
ExecStart=/opt/skywalking/bin/oapService.sh
Restart=on-failure
[Install]
WantedBy=multi-user.target

docker compose up -d && docker compose ps                       # D 启动
systemctl daemon-reload && systemctl enable --now skywalking-oap # E 启动（UI 另建 unit）
# 官方另有 skywalking-showcase 与 BanyanDB 仓库内 compose 演示栈（含 demo 微服务）

3.3 首次启动与验证

curl -sS -w '\nHTTP %{http_code}\n' http://<OAP_HOST>:12800/healthcheck   # 预期 HTTP 200
curl -sS -X POST http://<OAP_HOST>:12800/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query { version getTimeInfo { timezone currentTimestamp } checkHealth { score details } }"}'
# 预期 {"data":{"version":"<构建串>",...,"checkHealth":{"score":0,...}}}；score=0 为 OK，>0 为 degraded
curl -sS -o /dev/null -w 'UI HTTP %{http_code}\n' http://<UI_HOST>:8080/   # 预期 200，浏览器可见（空）服务列表
grep -E 'Version|module.core.provider|module.storage.provider' logs/skywalking-oap-server.log  # 预期 booting parameters 模块表

4. 配置文件详解

4.1 主配置路径

多数项支持 SW_* 环境变量覆盖（优先级高于文件）；生产用环境变量，不改包内文件便于镜像复用。

4.2 关键项说明表

4.3 完整可运行最小示例：Java Agent agent.config

分发目录 skywalking-agent/：skywalking-agent.jar、config/agent.config、plugins/、optional-plugins/、logs/；插件 jar 移入/移出 plugins/ 即启用/禁用。

# skywalking-agent/config/agent.config —— 最小可用
agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}                          # UI 服务名，全局唯一
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800} # OAP gRPC，非 12800
agent.namespace=${SW_AGENT_NAMESPACE:}                                          # 隔离传播 header
agent.instance_name=${SW_AGENT_INSTANCE_NAME:}                                  # 留空则 UUID@hostname 生成
agent.sample_n_per_3_secs=${SW_AGENT_SAMPLE:-1}                                # 每 3 秒最多 N 段；<=0 关闭
agent.span_limit_per_segment=${SW_AGENT_SPAN_LIMIT:300}                         # 单 Segment 最大 Span
agent.ignore_suffix=${SW_AGENT_IGNORE_SUFFIX:.jpg,.js,.css,.png,/health,/actuator/health}
logging.level=${SW_LOGGING_LEVEL:INFO}
logging.file_name=${SW_LOGGING_FILE_NAME:skywalking-api.log}
logging.dir=${SW_LOGGING_DIR:}

覆盖优先级：-Dskywalking.<key> > SW_AGENT_* 环境变量 > agent.config 文件值；生产推荐只用环境变量。

4.4 OAP 配置片段与「存储后端版本差异」（重要）

application.yml 不建议全量手写，只覆盖 selector 与端口（selector 写法取自官方 storage 文档）：

# config/application.yml —— 片段，非全量文件
storage:
  selector: ${SW_STORAGE:banyandb}
  banyandb:
    targets: ${SW_STORAGE_BANYANDB_TARGETS:127.0.0.1:17912}
cluster:
  selector: ${SW_CLUSTER:standalone}
  standalone: {}
core:                                  # core.default 另含 restHost/gRPCHost，默认 0.0.0.0
  selector: ${SW_CORE:default}
  default:
    restPort: ${SW_CORE_REST_PORT:12800}
    gRPCPort: ${SW_CORE_GRPC_PORT:11800}

⚠️ 升级顺序：先确认 bydb.yml 兼容 API 版本 → 选匹配 BanyanDB Server → 升 OAP → 升 UI → 升 Agent。只升 OAP 不换 BanyanDB 是常见事故。

4.5 完整可运行最小示例：alarm-settings.yml

# config/alarm-settings.yml —— 规则 id 必须以 _rule 结尾
rules:
  service_resp_time_rule:
    # MQE：根运算必须比较运算，结果 1(true) 即触发
    expression: sum(service_resp_time > 1000) >= 3
    period: 10
    silence-period: 5
    recovery-observation-period: 3
    message: 服务 {name} 在最近 10 分钟内有 3 分钟响应时间超过 1000ms

完整规则集（含 service_sla_rule 与 hooks.webhook / hooks.wechat）见第 6 章。8.x 及更早用 metrics-name/op/threshold/period/count/silence-period；9.x+ 改为 MQE expression。跨大版本升级必须按新版自带 alarm-settings.yml 重写规则，否则旧规则被忽略或启动报错。

5. 核心使用方法

5.1 命令集（编号 122 命令 + 2326 UI 路径 + 指标表，共 ≥26 条）

# --- Java Agent 挂载（无侵入）---
# 1) 标准 Spring Boot：-javaagent 必须在 -jar 之前
java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
     -Dskywalking.agent.service_name=order-service \
     -Dskywalking.collector.backend_service=<OAP_HOST>:11800 -jar order-service.jar
# 2) 纯环境变量（容器推荐）
export SW_AGENT_NAME=order-service SW_AGENT_COLLECTOR_BACKEND_SERVICES=<OAP_HOST>:11800
export JAVA_TOOL_OPTIONS="-javaagent:/opt/skywalking-agent/skywalking-agent.jar"
java -jar order-service.jar
# 3) Tomcat：bin/catalina.sh 首行加
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/skywalking-agent/skywalking-agent.jar"; export CATALINA_OPTS
# 4) 采样与 Span 上限：-Dskywalking.agent.sample_n_per_3_secs=10 -Dskywalking.agent.span_limit_per_segment=300
# 5) 日志输出 TraceID：应用引 apm-toolkit-logback/log4j，pattern 加 %tid（版本以官方为准）
# 6) Docker 只读挂载探针
docker run -v /opt/skywalking-agent:/skywalking-agent:ro \
  -e SW_AGENT_NAME=order-service -e SW_AGENT_COLLECTOR_BACKEND_SERVICES=<OAP_HOST>:11800 \
  -e JAVA_TOOL_OPTIONS=-javaagent:/skywalking-agent/skywalking-agent.jar <业务镜像:tag>
# --- OAP REST :12800 ---
# 7) 健康检查
curl -sS http://<OAP_HOST>:12800/healthcheck
# 8) 版本 + 健康分
curl -sS -X POST http://<OAP_HOST>:12800/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query { version getTimeInfo { timezone currentTimestamp } checkHealth { score details } }"}'
# 9) 服务列表（V1 API 自 9.5.0 deprecated 但短期兼容；Duration 格式 "yyyy-MM-dd HHmm"）
curl -sS -X POST http://<OAP_HOST>:12800/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query ($d: Duration!) { services: getAllServices(duration: $d) { id name normal } }",
       "variables":{"d":{"start":"2026-11-05 0000","end":"2026-11-05 0100","step":"MINUTE"}}}'
# 10) 服务实例 / 11) 指标时序同理：getServiceInstances(duration,serviceId)、readMetricsValues(condition,duration)；或用 swctl 19)
# 12) OTLP 直连 OAP（无需 SkyWalking Agent）
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<OAP_HOST>:11800 OTEL_SERVICE_NAME=payment-service
export OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.1
# --- swctl（SkyWalking CLI）---
# 13) 指定 OAP 地址
export SWCTL_BASE_URL=http://<OAP_HOST>:12800/graphql
swctl service list                                                        # 14) 服务列表
swctl instance list --service-name=order-service                             # 15) 实例列表
swctl endpoint list --service-name=order-service                             # 16) 端点列表
swctl trace list --service-name=order-service                                # 17) 最近 Trace
swctl trace <trace-id>                                                       # 18) 单条 Trace 详情
swctl metrics linear --name=service_resp_time --service-name=order-service   # 19) 指标折线
swctl logs list --service-name=order-service                                 # 20) 关联日志
swctl dashboard global                                                       # 21) 全局仪表盘
swctl --base-url=http://<OAP_HOST>:12800/graphql --display yaml service list # 22) YAML 输出

5.2 Web UI 路径（23~26）与常用指标

告警规则入口 config/alarm-settings.yml（4.5、第 6 章）：常用 service_resp_time_rule、service_sla_rule、service_resp_time_percentile_rule、service_instance_resp_time_rule、database_access_resp_time_rule。

6. 告警与通知

噪声控制：period（评估窗口分钟）、silence-period（触发后静默，抑制风暴）、recovery-observation-period（连续 N 周期不触发才判恢复，消除抖动）、sum(<metric> <op> <阈值>) >= <次数>（N 分钟内 M 次异常才告警）。

# config/alarm-settings.yml：分层规则 + 多通道通知
rules:
  endpoint_slow_rule:
    expression: sum(endpoint_resp_time > 3000) >= 3
    period: 10
    silence-period: 10
    recovery-observation-period: 5
    message: 端点 {name} 连续慢响应
hooks:
  webhook:                                  # 通用 Webhook（可转发钉钉/飞书/邮件网关）
    default:
      is-default: true
      urls: [http://<告警网关_HOST>:<PORT>/skywalking/alarm]
  wechat:                                  # 企业微信（官方模板内置 wechat hook）
    text-template: |-
      {"msgtype":"text","text":{"content":"Apache SkyWalking 告警：\n %s."}}
    webhooks:
      - https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<企业微信机器人key>

# 告警体 JSON（scope/name/ruleName/alarmMessage/startTime）由网关格式化转发；邮件则交 SMTP Relay 发送
# 钉钉
curl -sS -X POST 'https://<钉钉机器人Webhook URL>' -H 'Content-Type: application/json' -d '{"msgtype":"text","text":{"content":"SkyWalking 告警：<alarmMessage>"}}'

其他 hook（gRPCHook、Slack、飞书、DingTalk、邮件等）以所用版本 alarm-settings.yml 注释模板与官方告警文档为准，不同大版本支持的 hook 名不完全一致。降噪：按服务分层设阈值；silence-period ≥ period；网关按 ruleName + name 去重与认领；夜间非 P0 走聚合摘要。

7. 实战场景

7.1 接入一个 Java 服务（无侵入 Agent）

• 目标：不改一行业务代码，让 order-service 出现在 UI 并产生链路。步骤：准备 agent 目录 → 设服务名与 OAP 地址 → 挂载启动 → 造流量。

export SW_AGENT_NAME=order-service SW_AGENT_COLLECTOR_BACKEND_SERVICES=<OAP_HOST>:11800 SW_AGENT_SAMPLE=-1
java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
     -Dskywalking.logging.file_name=skywalking-api.log -jar /app/order-service.jar
for i in $(seq 1 50); do curl -sS http://localhost:8081/api/orders/1 -o /dev/null; done

• 验证：swctl service list 出现 order-service；UI General → Service 有 CPM/RT；Trace 有瀑布图。
• 回滚：去掉 -javaagent 与 SW_AGENT_* 重启应用即可，探针不写业务数据、无残留；⚠️ JAVA_TOOL_OPTIONS 是全局环境变量，回滚时务必一并清理，否则所有 JVM 都会被挂探针。

7.2 定位一次慢调用

• 目标：下单接口偶发 >2s，定位到具体服务/端点/SQL。步骤：缩时间窗 → Trace 按耗时排序 → 看 Span 瀑布 → 下钻指标 → 加告警。

# 1) 近 1 小时 RT 时序
swctl --base-url=http://<OAP_HOST>:12800/graphql --display yaml \
  metrics linear --name=service_resp_time --service-name=order-service
# 2) GraphQL 查 p99，判断长尾还是整体变慢
curl -sS -X POST http://<OAP_HOST>:12800/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query ($d: Duration!) { readMetricsValues(condition: {name: \"service_percentile\", entity: {scope: Service, serviceName: \"order-service\", normal: true}}, duration: $d) { label values { values { value } } } }",
       "variables":{"d":{"start":"2026-11-05 1000","end":"2026-11-05 1100","step":"MINUTE"}}}'
# 3) 列最近 Trace 找耗时最大的 TraceID；4) 看 Span 明细定位 DB 还是下游 RPC
swctl trace list --service-name=order-service && swctl trace <trace-id>
# 5) UI 交叉验证：Trace → 过滤 minDuration=2000 → 瀑布图；6) 查 database_access_resp_time 是否吻合

• 验证：瀑布图中单个 Span 占总耗时 >80%；database_access_resp_time 与慢调用时段吻合。
• 回滚：仅新增 endpoint_slow_rule，删除该 rule 并重启 OAP 即回滚；⚠️ 重启 OAP 会短暂中断 :12800 查询，选非高峰执行。

7.3 接入一个 Go 服务（OTLP 路径）

• 目标：不想改 Go 构建命令时，用 OTel SDK 经 OTLP 上报。步骤：启用 OAP OTLP receiver → 应用设标准 OTel 环境变量 → 重启。

# OAP 侧（与 3.2 方式 D 一致的 Docker 环境变量）
SW_OTEL_RECEIVER=default
SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES=vm
# 应用侧：OTel SDK 支持环境变量自动配置，无需 SkyWalking 专用 Agent
export OTEL_SERVICE_NAME=payment-service OTEL_EXPORTER_OTLP_ENDPOINT=http://<OAP_HOST>:11800
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.1
./payment-service

若用原生 Go Agent（apache/skywalking-go），需按该仓库用 go build -toolexec 改写构建命令，版本/用法以官方 README 为准。

• 验证：swctl service list 出现 payment-service；UI 拓扑出现与 order-service 的调用边。
• 回滚：清空 OTEL_* 并重启应用；OAP 侧 SW_OTEL_RECEIVER 保留不影响既有 Agent 接入。

7.4 告警推送到企业微信

• 目标/步骤：慢调用告警直达值班群 → 写 hooks.wechat（第 6 章）→ 重启 OAP → 压测触发阈值。
• 验证：群内收到 text-template 渲染消息，OAP 日志无 Send webhook failed。回滚：注释 hooks 段并重启 OAP；⚠️ 机器人 key 属敏感信息，勿提交进 Git。

8. 日常运维与故障排查

bin/startup.sh            # OAP + UI                 bin/oapService.sh   # 只起 OAP
bin/webappService.sh      # 只起 UI                 tail -f logs/skywalking-oap-server.log
tail -f logs/webapp.log   tail -f <agent目录>/logs/skywalking-api.log
curl -sS http://<OAP_HOST>:12800/healthcheck       # 健康检查
curl -sS http://<OAP_HOST>:1234/metrics            # OAP 自监控（SW_TELEMETRY=prometheus）
systemctl status skywalking-oap

9. 性能、容量与高可用

10. 安全加固、备份与升级

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选 SkyWalking：需要 Trace/Metrics/Log/告警一体、多语言无侵入（尤其 Java 为主）、看重中文文档与国产化生态、不想自己拼 Prometheus+Alertmanager。 何时不选：已全面标准化 OTel 且只要链路（Jaeger/Tempo/Grafana 更贴合）；团队小、无法维护 OAP + BanyanDB/ES 有状态集群；只要容器/主机指标；强需求闭源商业支持。 与 Jaeger 组合：应用统一用 OTel SDK 上报，OTLP 同时送 SkyWalking（APM 与告警）和 Jaeger/Tempo（纯 Trace 归档），避免双探针。

14. 参考链接

• 官网与下载：https://skywalking.apache.org/ ｜ https://skywalking.apache.org/downloads/
• 主仓库：https://github.com/apache/skywalking
• Java Agent / CLI：https://github.com/apache/skywalking-java ｜ https://github.com/apache/skywalking-cli
• Helm / 查询协议 / 演示栈：https://github.com/apache/skywalking-helm ｜ https://github.com/apache/skywalking-query-protocol ｜ https://github.com/apache/skywalking-showcase
• OAP 后端安装：https://skywalking.apache.org/docs/main/v11.0.0/en/setup/backend/backend-setup/
• 存储后端与 selector：https://skywalking.apache.org/docs/main/next/en/setup/backend/backend-storage/
• 查询协议（含废弃 V1 元数据 API 说明）：https://skywalking.apache.org/docs/main/next/en/api/query-protocol-deprecated
• BanyanDB 快速上手：https://skywalking.apache.org/docs/skywalking-banyandb/next/guides/quick-start/quick-start
• Helm OAP 端口 / 官方告警规则模板：https://skywalking.apache.org/docs/skywalking-helm/next/expose/oap-endpoints ｜ https://github.com/apache/skywalking/blob/master/dist-material/alarm-settings.yml
• Java Agent 配置项表 / OTel：https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/ ｜ https://opentelemetry.io/