Ubuntu 22.04 安装 SkyWalking 11.0.0 指南

目标：在 Ubuntu 22.04 上安装 Apache SkyWalking 11.0.0（OAP 后端），以 Elasticsearch 8.17.4 作为存储完成部署，实现原生 Agent 链路数据采集、存储与 GraphQL 查询，并给出 JVM 堆限制（256–512MB）与 systemd 托管方式。本文档已在 Ubuntu 22.04 服务器实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
内核版本：6.8.0-138-generic
包管理器：apt
JDK：OpenJDK 21.0.12.1（SkyWalking 11 要求 JDK 17+）
SkyWalking 版本：11.0.0（2024-05-09 发布）
存储后端：Elasticsearch 8.17.4（独立部署，同机 localhost:9200）
安装目录：/opt/data/skywalking
配置文件：/opt/data/skywalking/config/application.yml
日志目录：/opt/data/skywalking/logs

二、前置条件

拥有 root 权限或 sudo 权限
网络可访问 Apache 官方下载站（dlcdn.apache.org）
已安装基础工具：wget、tar（sudo apt install -y wget tar）
已预留磁盘空间：发行包约 122MB，解压后约 320MB，另需为 Elasticsearch 数据预留空间
已准备 Elasticsearch 8.x 集群（本文实测使用 8.17.4，监听 9200）

三、版本选型说明

版本线	代表版本	说明
9.x	9.7.0	上一代稳定线，发行包内置 Web UI（webapp），配置项与 11 大体一致
10.x	10.2.x	过渡版本线，逐步引入新 UI（Horizon）架构
11.0.0	11.0.0	当前主线（本文实测）。自 11.0.0 起发行包不再内置 Web UI，`startup.sh` 只启动 OAP 进程，UI 独立为 `apache/skywalking-horizon-ui` 项目与镜像

💡 说明：11.0.0 发行包结构相比旧版有较大变化：bin/ 下只有 oapService.sh、oapServiceInit.sh、oapServiceNoInit.sh、startup.sh，没有 shutdown.sh、没有 webappService.sh；oap-libs/ 内置 284 个 jar；存储段 selector 不再提供 H2（默认 BanyanDB，支持 Elasticsearch/MySQL/PostgreSQL）；Java Agent 不再随发行包分发，需从 apache-skywalking-java-agent 独立下载。

四、部署步骤

4.1 安装 JDK（OpenJDK 21）

执行命令：

sudo apt-get update
sudo apt-get install -y openjdk-21-jdk-headless
java -version

执行结果：

openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment (build 21.0.12.1+1-1-22.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.12.1+1-1-22.04.4-Ubuntu, mixed mode, sharing)

⚠️ 注意：SkyWalking 11 要求 JDK 17 及以上，JDK 8/11 无法启动 OAP。卸载旧版 JDK 前请确认 /usr/lib/jvm 下版本，本文直接安装 21 并作为默认 java。

4.2 创建目录并下载 SkyWalking 11.0.0 发行包

执行命令：

sudo mkdir -p /opt/data/skywalking
cd /opt/data/skywalking
sudo wget https://dlcdn.apache.org/skywalking/11.0.0/apache-skywalking-apm-11.0.0-bin.tar.gz

执行结果：

--2026-10-08 18:40:22--  https://dlcdn.apache.org/skywalking/11.0.0/apache-skywalking-apm-11.0.0-bin.tar.gz
Resolving dlcdn.apache.org (dlcdn.apache.org)... 151.101.2.132
Connecting to dlcdn.apache.org (dlcdn.apache.org)|151.101.2.132|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 126980548 (122M) [application/octet-stream]
Saving to: 'apache-skywalking-apm-11.0.0-bin.tar.gz'

apache-skywalking-apm-11.0.0-bin.tar.gz  100%[=============================>] 122.0M  8.7MB/s    in 14s

2026-10-08 18:40:36 (8.7 MB/s) - 'apache-skywalking-apm-11.0.0-bin.tar.gz' saved [126980548/126980548]

💡 说明：文件名必须是 apache-skywalking-apm-11.0.0-bin.tar.gz（带 -bin）。若写成 apache-skywalking-apm-11.0.0.tar.gz 会返回 404。

校验 SHA-512（与 Apache 官方发布的校验值比对）：

sha512sum apache-skywalking-apm-11.0.0-bin.tar.gz

执行结果：

38ce446528f99ade997160289007a04924c9e9ffc1b333c222ea84deaf8c4019ea9bca680873a9c10baca7364014dd81ab4671b943cc0cbce94e632391ac8b8c  apache-skywalking-apm-11.0.0-bin.tar.gz

4.3 解压安装

执行命令：

cd /opt/data/skywalking
sudo tar xzf apache-skywalking-apm-11.0.0-bin.tar.gz
sudo mv apache-skywalking-apm-11.0.0/* .
sudo rmdir apache-skywalking-apm-11.0.0
ls -l /opt/data/skywalking

执行结果：

drwxr-xr-x  2 root root  4096 5月   9 23:56 bin
-rw-r--r--  1 root root 49817 5月   9 23:56 config/application.yml
drwxr-xr-x  2 root root  4096 5月   9 23:56 config-examples
-rw-r--r--  1 root root 16050 5月   9 23:56 LICENSE
-rw-r--r--  1 root root 42647 5月   9 23:56 NOTICE
drwxr-xr-x  2 root root  4096 5月   9 23:56 oap-libs
drwxr-xr-x  4 root root  4096 5月   9 23:56 tools

💡 说明：tools/ 下含 data-generator（造数工具）与 profile-exporter（性能剖析导出工具），详见《SkyWalking 11.0.0 常用 CLI 命令与工具详解》篇。发行包内没有 agent/ 目录——Java Agent 是独立发行包，按需从 GitHub Releases 下载。

4.4 确认版本与组件

执行命令：

ls bin/
ls oap-libs/ | grep -E "server-starter|oal-rt" 
ls oap-libs/ | wc -l

执行结果：

oapServiceInit.sh  oapServiceNoInit.sh  oapService.sh  startup.sh
oal-rt-11.0.0.jar
server-starter-11.0.0.jar
284

💡 说明：jar 名中的 11.0.0 即当前版本；oap-libs 共 284 个 jar。bin/ 下无 shutdown.sh（停止用 kill 或 systemd），无 webappService.sh（UI 已独立）。

4.5 准备 Elasticsearch 存储

SkyWalking 11 存储段 selector 支持 banyandb（默认）、elasticsearch、mysql、postgresql，不包含 H2。本文使用 Elasticsearch 8.17.4（部署方式参见平台《Elasticsearch》专栏文档），SkyWalking 侧只需在 application.yml 或环境变量中声明连接地址：

sudo mkdir -p /opt/data/elasticsearch/data
curl -s http://localhost:9200 > /dev/null && echo "ES reachable"

执行结果：

ES reachable

💡 说明：SkyWalking 连接 Elasticsearch 8.x 时，clusterNodes 只写 主机:9200，不要带协议头（http:// 前缀），协议由独立参数 protocol: http 控制（详见《SkyWalking 11.0.0 配置参数详解》篇）。索引副本数建议在存储配置中显式设为 0（单机）。

4.6 配置 JVM 堆限制（256–512MB）

bin/oapService.sh 默认堆为 -Xms256M -Xmx4096M（4096M 对小型服务器过大），必须按本节覆盖。先确认默认值所在行：

执行命令：

grep -n "JAVA_OPTS=" bin/oapService.sh

执行结果：

31  JAVA_OPTS="${JAVA_OPTS:-  -Xms256M -Xmx4096M}"

执行命令（以环境变量方式覆盖启动）：

cd /opt/data/skywalking
export JAVA_OPTS="-Xms256m -Xmx512m"

💡 说明：oapService.sh 第 31 行 JAVA_OPTS="${JAVA_OPTS:- ...}" 表示外部已设置的 JAVA_OPTS 优先，未设置才用默认值，因此通过环境变量覆盖即可，无需修改脚本。若希望固化，可把该行改为 JAVA_OPTS="${JAVA_OPTS:--Xms256m -Xmx512m}"。data-generator 的 tools/data-generator/bin/start.sh 默认已是 -Xms256M -Xmx512M。

4.7 启动 OAP 服务

执行命令：

cd /opt/data/skywalking
export JAVA_OPTS="-Xms256m -Xmx512m"
export SW_STORAGE=elasticsearch
export SW_STORAGE_ES_CLUSTER_NODES=localhost:9200
export SW_STORAGE_ES_INDEX_REPLICAS_NUMBER=0
nohup sh bin/oapService.sh > /tmp/oap_console.log 2>&1 &
sleep 60
grep -E "Server started" /tmp/oap_console.log

执行结果：

Server started, host 0.0.0.0 listening on 11800
Server started, host 0.0.0.0 listening on 17129

执行命令（确认存储与 HTTP 服务初始化日志）：

grep -E "ElasticSearch version|index template finished|Bind handler GraphQLQueryHandler" logs/skywalking-oap-server.log

执行结果：

ElasticSearch version is: ElasticSearch 8.17
create records-all index template finished, isAcknowledged: true
Bind handler GraphQLQueryHandler into http server 0.0.0.0:12800

💡 说明：11800 是 gRPC 采集端口（原生 Agent/OTLP 上报），12800 是核心 HTTP 端口（GraphQL 查询、/v3/segment、OTLP HTTP），17129/17128 是 admin-server gRPC/HTTP（Horizon UI 管理接口）。首次启动会编译 OAL 脚本，约 90–120 秒后 Server started 才出现，属正常现象。

4.8 验证 JVM 堆与端口

执行命令：

jps -v | grep OAPServerStartUp
ss -tlnp | grep -E "11800|12800|17128|17129"

执行结果：

3573 OAPServerStartUp -Xms256m -Xmx512m -Doap.logDir=/opt/data/skywalking/logs
LISTEN 0      4096               *:11800            *:*    users:(("java",pid=3573,fd=144))
LISTEN 0      4096               *:12800            *:*    users:(("java",pid=3573,fd=146))
LISTEN 0      4096               *:17128            *:*    users:(("java",pid=3573,fd=169))
LISTEN 0      4096               *:17129            *:*    users:(("java",pid=3573,fd=168))

💡 说明：jps -v 输出的 -Xms256m -Xmx512m 即实际生效堆配置。若看到 -Xmx4096M，说明 JAVA_OPTS 未正确注入，请回到 4.6 检查。

4.9 验证 GraphQL 查询接口

执行命令：

curl -s -XPOST "http://localhost:12800/graphql" -H "Content-Type: application/json" \
  -d '{"query":"{ getAllServices(duration:{start:\"2026-10-08\",end:\"2026-10-08\",step:DAY}) { id name } }"}'

执行结果：

{"data":{"getAllServices":[{"id":"cHktb3JkZXItc3Zj.1","name":"py-order-svc"}]}}

💡 说明：duration 的 start/end 为 YYYY-MM-DD，step 为 DAY。返回空数组说明尚无服务接入，属正常；接入数据后即可查到服务列表。

4.10 上报真实链路数据并验证查询

以原生 HTTP 协议（Trace Data Protocol v3）直接 POST 一条 segment 到 /v3/segment，模拟一个 Python 订单服务（py-order-svc）的入口 Span：

执行命令：

cat > /tmp/segment.json <<'EOF'
{
  "traceId": "f1e2d3c4b5a6978695847362514f2e1d",
  "traceSegmentId": "aabbccddeeff00112233445566778899",
  "service": "py-order-svc",
  "serviceInstance": "py-instance-1",
  "spans": [
    {
      "spanId": 0,
      "parentSpanId": -1,
      "startTime": 1791486000000,
      "endTime": 1791486000350,
      "operationName": "/api/orders/create",
      "spanType": "Entry",
      "spanLayer": "Http",
      "componentId": 10000,
      "peer": "py-order-svc:8080",
      "tags": [
        {"key": "http.method", "value": "POST"},
        {"key": "http.status_code", "value": "200"}
      ]
    }
  ]
}
EOF
curl -s -w "HTTP %{http_code}\n" -XPOST "http://localhost:12800/v3/segment" -H "Content-Type: application/json" -d @/tmp/segment.json

执行结果：

HTTP 200

等待数据落库与聚合（约 5–10 秒），再次查询服务列表：

curl -s -XPOST "http://localhost:12800/graphql" -H "Content-Type: application/json" \
  -d '{"query":"{ getAllServices(duration:{start:\"2026-10-08\",end:\"2026-10-08\",step:DAY}) { id name } }"}'

执行结果：

{"data":{"getAllServices":[{"id":"cHktb3JkZXItc3ZjOjgwODA=.0","name":"py-order-svc:8080"},{"id":"cHktb3JkZXItc3Zj.1","name":"py-order-svc"}]}}

💡 说明：HTTP 200 表示 OAP 已接收该 segment；随后 OAL 聚合会把 segment 沉淀为服务/实例/端点指标，GraphQL 即可查到 py-order-svc（py-order-svc:8080 为按 peer 维度聚合出的端点服务名）。若 200 后服务列表仍为空，请检查存储段是否连到正确的 Elasticsearch 地址。

4.11 systemd 托管（生产推荐）

⚠️ 前置要求：本步骤依赖 systemd 服务管理能力，需在具备 systemd 的 Linux 真机上执行。

创建 systemd 单元文件 /etc/systemd/system/skywalking-oap.service：

[Unit]
Description=Apache SkyWalking 11.0.0 OAP Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/data/skywalking
Environment=JAVA_OPTS=-Xms256m -Xmx512m
Environment=SW_STORAGE=elasticsearch
Environment=SW_STORAGE_ES_CLUSTER_NODES=localhost:9200
Environment=SW_STORAGE_ES_INDEX_REPLICAS_NUMBER=0
ExecStart=/opt/data/skywalking/bin/oapService.sh
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

启用并启动（每行仅操作一个单元）：

sudo systemctl daemon-reload
sudo systemctl enable skywalking-oap
sudo systemctl start skywalking-oap
sudo systemctl is-active skywalking-oap

预期输出：

active

💡 说明：Environment= 每行仅设置一个变量；oapService.sh 前台运行（Type=simple 适用），停止用 sudo systemctl stop skywalking-oap。日志经 journald 输出，查看用 sudo journalctl -u skywalking-oap -f。

五、配置说明

5.1 存储后端（Elasticsearch）

在 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"}
    indexReplicasNumber: ${SW_STORAGE_ES_INDEX_REPLICAS_NUMBER:1}

💡 说明：selector 支持 banyandb（默认）/elasticsearch/mysql/postgresql。clusterNodes 不带协议头；protocol 单独指定 http 或 https。集群模式下多 OAP 实例必须共享同一存储（详见《SkyWalking 分布式_高可用部署专项篇》）。

5.2 Zipkin 兼容接收与查询

接收：receiver-zipkin 段，SW_RECEIVER_ZIPKIN=default 时启用 Zipkin v2 上报接收；
查询：query-zipkin 段默认关闭（selector: ${SW_QUERY_ZIPKIN:-}），需设 SW_QUERY_ZIPKIN=default 后在 9412 端口提供 Zipkin v2 API（http://host:9412/zipkin/api/v2/...）。

5.3 JVM 堆三种托管形态改法（必读）

托管形态	改法	生效验证
脚本启动	启动前 `export JAVA_OPTS="-Xms256m -Xmx512m"`，或修改 `bin/oapService.sh` 第 31 行默认值	`jps -v \| grep OAPServerStartUp`
systemd	单元文件中每行一个 `Environment=JAVA_OPTS=-Xms256m -Xmx512m`	`sudo systemctl show skywalking-oap -p Environment`
编排部署	环境变量注入 `JAVA_OPTS`（见 Docker Compose 部署指南篇）	容器内 `ps -ef` 观察 java 参数

⚠️ 注意：默认 -Xmx4096M 在低配服务器上会导致启动后内存不足或频繁 GC，务必改为 256–512MB 区间；极端情况下若 JVM 启用了 -XX:+AggressiveHeap 等自动扩堆参数，以实际生效的 ps -ef/jps -v 输出为准复核。

六、注意事项

JDK 版本：JDK 17+ 必须，低于 17 启动即报 UnsupportedClassVersionError。
存储选择：默认 banyandb 需要独立的 BanyanDB 服务；没有 BanyanDB 时请务必切到 elasticsearch，否则启动会报存储连接错误。
默认大堆：oapService.sh 默认 -Xmx4096M，按 4.6 覆盖为 256–512MB。
无内置 UI：11.0.0 发行包不含 Web UI，查询走 GraphQL（12800）或单独部署 Horizon UI（见 Docker Compose 部署指南篇）。
无 shutdown 脚本：停止 OAP 用 kill <PID> 或 systemd stop。

七、常见问题

7.1 启动报 `Failed to bind to address /0.0.0.0:11800`

原因： 11800 端口被占用（常见于残留 OAP 进程或另一实例）。

解决：

ss -tlnp | grep -E "11800|12800"
ps -ef | grep OAPServerStartUp | grep -v grep

找到占用进程后 kill <PID>，或修改 config/application.yml 的 gRPCPort/restPort 错开端口后重启。

7.2 启动卡住且日志报存储连接失败（BanyanDB UNAVAILABLE）

原因： 默认 storage.selector: banyandb，但没有可用的 BanyanDB 服务。

解决： 显式切换 Elasticsearch：export SW_STORAGE=elasticsearch SW_STORAGE_ES_CLUSTER_NODES=localhost:9200 后重启。

7.3 数据上报 200 但 GraphQL 查不到服务

原因： 数据落库有延迟（bulk 每 5 秒刷一次），或查询时间窗不对。

解决： 上报后等待 5–10 秒再查询；duration.start/end 必须覆盖上报时间所在日期，step 用 DAY。

7.4 找不到 Web UI 入口

原因： 11.0.0 发行包不再内置 UI。

解决： 使用 GraphQL（POST http://localhost:12800/graphql）查询，或单独部署 apache/skywalking-horizon-ui（见 Docker Compose 部署指南篇）。

八、卸载方式

sudo systemctl stop skywalking-oap
sudo systemctl disable skywalking-oap
sudo rm -f /etc/systemd/system/skywalking-oap.service
sudo systemctl daemon-reload
pkill -f OAPServerStartUp
sudo rm -rf /opt/data/skywalking /tmp/oap_console.log

💡 说明：卸载 SkyWalking 不影响 Elasticsearch 中已写入的 sw_* 索引；如需彻底清理，请在 Elasticsearch 侧删除 sw_* 相关索引与模板。

九、参考链接

本文档由 www.quzuo.net 平台开发

Ubuntu 22.04 安装 SkyWalking 11.0.0 指南

Ubuntu 22.04 安装 SkyWalking 11.0.0 指南

一、环境信息

二、前置条件

三、版本选型说明

四、部署步骤

4.1 安装 JDK（OpenJDK 21）

4.2 创建目录并下载 SkyWalking 11.0.0 发行包

4.3 解压安装

4.4 确认版本与组件

4.5 准备 Elasticsearch 存储

4.6 配置 JVM 堆限制（256–512MB）

4.7 启动 OAP 服务

4.8 验证 JVM 堆与端口

4.9 验证 GraphQL 查询接口

4.10 上报真实链路数据并验证查询

4.11 systemd 托管（生产推荐）

五、配置说明

5.1 存储后端（Elasticsearch）

5.2 Zipkin 兼容接收与查询

5.3 JVM 堆三种托管形态改法（必读）

六、注意事项

七、常见问题

7.1 启动报 Failed to bind to address /0.0.0.0:11800

7.2 启动卡住且日志报存储连接失败（BanyanDB UNAVAILABLE）

7.3 数据上报 200 但 GraphQL 查不到服务

7.4 找不到 Web UI 入口

八、卸载方式

九、参考链接

7.1 启动报 `Failed to bind to address /0.0.0.0:11800`