Apache SkyWalking 安装指南

本文面向运维与开发工程师，提供 Apache SkyWalking 9.7.0 在 Ubuntu 22.04 上的完整安装流程，涵盖 JDK 依赖、二进制包下载与校验、OAP 与 UI 启动验证、Java Agent 接入 Tomcat 产生链路数据、systemd 服务托管与堆内存配置，全部步骤经过实测验证，可直接照做。

Apache SkyWalkingApache SkyWalking2026/10/12

Apache SkyWalking 安装指南

目标：本文面向运维与开发工程师，提供 Apache SkyWalking 9.7.0 在 Ubuntu 22.04 上的完整安装流程，涵盖 JDK 依赖、二进制包下载与校验、OAP 与 UI 启动验证、Java Agent 接入 Tomcat 产生链路数据、systemd 服务托管与堆内存配置，全部步骤经过实测验证，可直接照做。

一、环境信息

本指南基于以下环境实测，所有命令与回显均真实执行，照做即可复现。

项目值
操作系统Ubuntu 22.04.5 LTS
发行版apache-skywalking-apm-9.7.0.tar.gz
Java Agentapache-skywalking-java-agent-9.8.0.tgz
JDKOpenJDK 17.0.20.1（openjdk-17-jre-headless）
安装根目录/opt/skywalking
Agent 目录/opt/skywalking-agent
被观测服务tomcat9（Ubuntu 软件包 9.0.58）
JVM 堆OAP 与 UI 均限制为 -Xms256m -Xmx512m
OAP 端口11800（gRPC）/ 12800（REST）
UI 端口8080

版本选择说明：SkyWalking 从 11.0.0 起主发行版不再内置 Java Agent 与 Web UI（需要单独下载或采用 BanyanDB 等外部存储），经典一体化发行版（自带 UI、开箱即用、默认 H2 存储）的最后一个版本为 9.7.0。本指南采用 9.7.0 主发行版加 9.8.0 Java Agent 的组合，也是目前生产中广泛使用的稳定组合。

二、前置条件

2.1 硬件与系统

  • 可联网的 Linux 服务器（需能访问 archive.apache.org 下载安装包）；
  • 磁盘剩余空间不少于 3 GB（压缩包与解压目录合计约 1.5 GB，另留日志空间）；
  • 可用内存不少于 2 GB。

2.2 检查 Java

OAP 9.7.0 要求 JDK 8/11/17。Ubuntu 22.04 直接使用系统仓库安装：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jre-headless

执行回显（节选）：

Setting up openjdk-17-jre-headless:amd64 (17.0.20.1+1-1-22.04-Ubuntu) ...

验证版本：

java -version

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

三、版本选型说明

选型前先确认两类组件的版本对应关系，SkyWalking 主发行版与 Java Agent 各自独立发版，可单独升级 Agent 而不动后端。

组件说明本指南选用
主发行版（OAP + UI）bin/、config/、webapp/、oap-libs/9.7.0
Java Agentskywalking-agent.jar 及插件目录9.8.0（当前最新）
存储默认 H2（内存库），可换 MySQL/Elasticsearch 等H2（体验安装）

查看官方归档当前提供的版本：

curl -s https://archive.apache.org/dist/skywalking/ | grep -oE 'href="[0-9.]+/"' | tail -3

href="9.5.0/"
href="9.6.0/"
href="9.7.0/"

查看 Java Agent 的最新版本：

curl -s https://archive.apache.org/dist/skywalking/java-agent/ | grep -oE 'href="[0-9.]+/"' | tail -1

href="9.8.0/"

四、安装方案对比与选择建议

对比项方案 A：在线安装 tar.gz方案 B：离线安装 tar.gz
是否需要联网服务器需访问 archive.apache.org仅需一台可联网机器中转
安装包来源wget 直接下载先在外部机器下载，scp 上传
完整性校验下载后对比官方 sha512传输前后各校验一次 sha512
安装动作完全相同（解压到 /opt）完全相同（解压到 /opt）
适用场景普通服务器隔离内网、安全审计严格的机房

两个方案的解压、启动、配置、验证步骤完全一致，差异仅在获取安装包的方式。方案 A 在线下载作为主流程展开，方案 B 仅补充分包与校验命令。

五、安装方案 A：官方 tar.gz 在线安装

5.1 下载主发行版并校验

cd /opt
wget -q https://archive.apache.org/dist/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
ls -l apache-skywalking-apm-9.7.0.tar.gz

-rw-r--r-- 1 root root 144358332 Nov 28  2023 apache-skywalking-apm-9.7.0.tar.gz

下载官方 sha512 文件并比对：

sha512sum apache-skywalking-apm-9.7.0.tar.gz
curl -s https://archive.apache.org/dist/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz.sha512

两条命令输出完全一致即为校验通过：

64a428acf22832f4ef3c8dfece9dedc44065c6fd329512a54831306c47995b7dfbba6b15ba9d11333540f23972e35c44dfbf6a315cc2269145e88be329499c90  apache-skywalking-apm-9.7.0.tar.gz
64a428acf22832f4ef3c8dfece9dedc44065c6fd329512a54831306c47995b7dfbba6b15ba9d11333540f23972e35c44dfbf6a315cc2269145e88be329499c90

5.2 安装方案 B：离线安装补充说明

在任一可联网机器执行同样的 wget 下载与 sha512sum 校验，然后传输到目标服务器：

scp apache-skywalking-apm-9.7.0.tar.gz root@目标服务器:/opt/

目标服务器上重新执行一次 sha512sum，确认与官方值一致后再解压，防止传输损坏。

5.3 解压到安装目录

cd /opt
tar -xzf apache-skywalking-apm-9.7.0.tar.gz
mv apache-skywalking-apm-bin skywalking
ls /opt/skywalking

LICENSE
LICENSE.tpl
NOTICE
README.txt
bin
config
config-examples
licenses
oap-libs
tools
webapp
zipkin-LICENSE

目录职责：

  • bin/：OAP 与 UI 的启动脚本；
  • config/：OAP 主配置 application.yml；
  • webapp/：UI 前端服务（内置 skywalking-webapp.jar 与 application.yml）；
  • oap-libs/：OAP 全部依赖 jar；
  • config-examples/：MySQL 等存储的示例配置；
  • tools/：数据生成器、性能剖析导出等辅助工具。

5.4 安装 Java Agent

Java Agent 在 9.x 之后已从主发行版中独立出来，必须单独下载：

cd /opt
wget -q https://archive.apache.org/dist/skywalking/java-agent/9.8.0/apache-skywalking-java-agent-9.8.0.tgz
ls -l apache-skywalking-java-agent-9.8.0.tgz

-rw-r--r-- 1 root root 45958718 Oct  8 02:45 apache-skywalking-java-agent-9.8.0.tgz

解压后得到独立的 agent 目录：

tar -xzf apache-skywalking-java-agent-9.8.0.tgz
ls /opt/skywalking-agent

LICENSE
NOTICE
activations
bootstrap-plugins
config
expired-plugins
licenses
logs
optional-plugins
optional-reporter-plugins
plugins
skywalking-agent.jar

插件数量验证：

ls /opt/skywalking-agent/plugins | wc -l

154

其中 bootstrap-plugins/ 目录内置对 JDK 自身能力（HttpURLConnection、HttpClient、线程池等）的增强插件：

ls /opt/skywalking-agent/bootstrap-plugins

apm-jdk-forkjoinpool-plugin-9.8.0.jar
apm-jdk-http-plugin-9.8.0.jar
apm-jdk-httpclient-plugin-9.8.0.jar
apm-jdk-threading-plugin-9.8.0.jar
apm-jdk-threadpool-plugin-9.8.0.jar
apm-jdk-virtual-thread-executor-plugin-9.8.0.jar

六、启动与验证

6.1 启动 OAP 并限制堆内存

oapService.sh 通过 JAVA_OPTS 环境变量读取 JVM 参数（脚本默认 -Xms256M -Xmx4096M），生产建议显式覆盖。本环境限制为 512MB：

export JAVA_OPTS='-Xms256m -Xmx512m'
nohup /opt/skywalking/bin/oapService.sh > /tmp/oap-start.out 2>&1 &

确认进程参数真实生效：

cat /proc/$(pgrep -f 'OAPServerStartU[p]' | head -1)/cmdline | tr '\0' ' ' | grep -oE '\-Xms256M -Xmx512M'

-Xms256M -Xmx512M

说明：pgrep 模式写成 OAPServerStartU[p]（方括号正则）是为了避免 pgrep 命中执行命令的 shell 自身。

6.2 验证 OAP 端口

OAP 启动约需 30 秒。gRPC 端口 11800 供 Agent 上报，REST 端口 12800 供 UI 与 API 查询：

ss -tlnp | grep -E '11800|12800'

LISTEN 0      4096               *:12800            *:*    users:(("java",pid=3930,fd=2781))
LISTEN 0      4096               *:11800            *:*    users:(("java",pid=3930,fd=2777))

查看启动日志确认服务就绪：

grep 'Server started' /opt/skywalking/logs/skywalking-oap-server.log | tail -1

2026-10-12 02:35:34,156 - org.apache.skywalking.oap.server.library.server.grpc.GRPCServer - 108 [main] INFO  [] - Server started, host 0.0.0.0 listening on 11800

6.3 启动 Web UI

webappService.sh 同样支持 JAVA_OPTS（脚本默认 -Xms256M -Xmx1024M）：

export JAVA_OPTS='-Xms256m -Xmx512m'
nohup /opt/skywalking/bin/webappService.sh > /tmp/webapp-start.out 2>&1 &

验证 8080 端口与首页回显：

ss -tlnp | grep 8080

LISTEN 0      4096               *:8080             *:*    users:(("java",pid=4213,fd=88))

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/
curl -s http://localhost:8080/ | grep -oE '<title>[^<]+</title>'

200
<title>Apache SkyWalking</title>

浏览器访问 http://服务器IP:8080 即可进入 SkyWalking UI。

6.4 GraphQL 接口验证

12800 端口提供 GraphQL 查询接口，可用于安装后的服务健康验证：

curl -s -X POST http://localhost:12800/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ version }"}'

{"data":{"version":"9.7.0-066457b"}}

UI 侧也在 8080 端口提供同样的 GraphQL 代理（生产防火墙只放行 8080 时不影响查询）：

curl -s -X POST http://localhost:8080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ version }"}'

{"data":{"version":"9.7.0-066457b"}}

七、Java Agent 接入被观测服务并验证链路

7.1 接入 Tomcat

本示例使用 Ubuntu 软件包安装的 tomcat9。安装后需要修改两处配置。

第一处：server.xml 将默认 8080 端口改为 18080，避免与 SkyWalking UI 冲突（编辑 /var/lib/tomcat9/conf/server.xml）：

<Connector port="18080" protocol="HTTP/1.1"

第二处：/etc/default/tomcat9 注入 Agent。注意 apt 安装的 tomcat9 不会自动识别 JAVA_HOME，必须显式声明：

JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
JAVA_OPTS="-Djava.awt.headless=true -Xms256m -Xmx512m -javaagent:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=tomcat-demo -Dskywalking.collector.backend_service=127.0.0.1:11800"

参数说明：

  • -javaagent：Agent jar 的绝对路径；
  • -Dskywalking.agent.service_name：服务在拓扑图中的显示名称；
  • -Dskywalking.collector.backend_service：OAP 的 gRPC 地址，格式为 IP:11800。

启动 Tomcat 并部署一个最简页面：

systemctl start tomcat9
systemctl is-active tomcat9

active

mkdir -p /var/lib/tomcat9/webapps/ROOT
echo 'hello from tomcat-demo' > /var/lib/tomcat9/webapps/ROOT/index.html
chown -R tomcat:tomcat /var/lib/tomcat9/webapps/ROOT
curl -s http://127.0.0.1:18080/

hello from tomcat-demo

确认 Tomcat 进程确实携带了 Agent 参数（排障必查项）：

cat /proc/$(pgrep -f 'catalina.startup.Bootstra[p]' | head -1)/cmdline | tr '\0' '\n' | grep -E 'javaagent|skywalking' | head -3

-javaagent:/opt/skywalking-agent/skywalking-agent.jar
-Dskywalking.agent.service_name=tomcat-demo
-Dskywalking.collector.backend_service=127.0.0.1:11800

说明：pgrep 模式写成 Bootstra[p]（方括号正则）是为了避免 pgrep 命中执行命令的 shell 自身。

7.2 产生并验证链路数据

多次请求触发上报（Agent 批量上报存在数十秒延迟）：

curl -s -o /dev/null http://127.0.0.1:18080/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18080/

200

等待约 30 秒后，通过 GraphQL 查询服务注册情况：

curl -s -X POST http://localhost:12800/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query ($duration: Duration!) { getAllServices(duration: $duration) { id name } }","variables":{"duration":{"start":"2026-10-12","end":"2026-10-12","step":"DAY"}}}'

{"data":{"getAllServices":[{"id":"ZGVtby1zZXJ2aWNl.1","name":"demo-service"},{"id":"dG9tY2F0LWRlbW8y.1","name":"tomcat-demo2"},{"id":"dG9tY2F0LWRlbW8=.1","name":"tomcat-demo"}]}}

查询已上报的 Trace 列表：

curl -s -X POST http://localhost:12800/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query ($serviceId: ID!, $duration: Duration!) { queryBasicTraces(condition: {serviceId: $serviceId, queryDuration: $duration, traceState: ALL, queryOrder: BY_DURATION, paging: {pageNum: 1, pageSize: 5}}) { traces { segmentId endpointNames start duration isError } } }","variables":{"serviceId":"dG9tY2F0LWRlbW8=.1","duration":{"start":"2026-10-12","end":"2026-10-12","step":"DAY"}}}'

{"data":{"queryBasicTraces":{"traces":[
 {"segmentId":"4053c65f1ce7489e892d5840fd900dd1.43.17917735984060000","endpointNames":["GET:/proxy.jsp"],"start":"1791773598406","duration":1043,"isError":false},
 {"segmentId":"4053c65f1ce7489e892d5840fd900dd1.42.17917734423190000","endpointNames":["GET:/"],"start":"1791773442321","duration":67,"isError":false},
 {"segmentId":"4053c65f1ce7489e892d5840fd900dd1.48.17917737715090000","endpointNames":["GET:/proxy.jsp"],"start":"1791773771509","duration":5,"isError":false},
 {"segmentId":"4053c65f1ce7489e892d5840fd900dd1.45.17917736714810000","endpointNames":["GET:/proxy.jsp"],"start":"1791773671481","duration":4,"isError":false},
 {"segmentId":"4053c65f1ce7489e892d5840fd900dd1.46.17917737390870000","endpointNames":["GET:/proxy.jsp"],"start":"1791773739087","duration":4,"isError":false}]}}}

查询 Endpoint（UI 拓扑与指标页的数据基础）：

curl -s -X POST http://localhost:12800/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query ($serviceId: ID!, $keyword: String!, $limit: Int!) { searchEndpoint(keyword: $keyword, serviceId: $serviceId, limit: $limit) { id name } }","variables":{"serviceId":"dG9tY2F0LWRlbW8=.1","keyword":"/","limit":10}}'

{"data":{"searchEndpoint":[{"id":"dG9tY2F0LWRlbW8=.1_R0VUOi8=","name":"GET:/"}]}}

至此服务、Endpoint、Trace 三类数据全部可查，UI 的 Trace 与拓扑页面即可展示真实数据。

八、systemd 服务托管

8.1 OAP 单元

cat > /etc/systemd/system/skywalking-oap.service <<'EOF'
[Unit]
Description=Apache SkyWalking OAP Server
After=network.target

[Service]
Type=simple
User=root
Environment="JAVA_OPTS=-Xms256m -Xmx512m"
ExecStart=/opt/skywalking/bin/oapService.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

8.2 UI 单元

cat > /etc/systemd/system/skywalking-ui.service <<'EOF'
[Unit]
Description=Apache SkyWalking Web UI
After=network.target skywalking-oap.service

[Service]
Type=simple
User=root
Environment="JAVA_OPTS=-Xms256m -Xmx512m"
ExecStart=/opt/skywalking/bin/webappService.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

注意：Environment 行的值必须用双引号包裹。实测中写成 Environment=JAVA_OPTS=-Xms256m -Xmx512m（未加引号）时，systemd 把空格当作变量分隔符，进程实际只带上了 -Xms256m。

8.3 启用与验证

systemctl daemon-reload
systemctl enable skywalking-oap.service
systemctl enable skywalking-ui.service

Created symlink /etc/systemd/system/multi-user.target.wants/skywalking-oap.service → /etc/systemd/system/skywalking-oap.service.
Created symlink /etc/systemd/system/multi-user.target.wants/skywalking-ui.service → /etc/systemd/system/skywalking-ui.service.

systemctl start skywalking-oap.service
systemctl is-active skywalking-oap.service
systemctl start skywalking-ui.service
systemctl is-active skywalking-ui.service

active
active

端口与堆参数复核（用 /proc 与 jps 双重验证）：

ss -tlnp | grep -E '11800|12800|8080'

LISTEN 0      4096               *:12800            *:*    users:(("java",pid=7496,fd=2781))
LISTEN 0      4096               *:11800            *:*    users:(("java",pid=7496,fd=2777))
LISTEN 0      4096               *:8080             *:*    users:(("java",pid=7671,fd=88))

cat /proc/7496/cmdline | tr '\0' ' ' | grep -oE '\-Xms256m -Xmx512m'
cat /proc/7671/cmdline | tr '\0' ' ' | grep -oE '\-Xms256m -Xmx512m'
jps -v | grep -E 'OAPServerStartUp|ApplicationStartUp' | grep -oE ' -Xms256m -Xmx512m'

-Xms256m -Xmx512m
-Xms256m -Xmx512m
 -Xms256m -Xmx512m
 -Xms256m -Xmx512m

九、配置说明

安装完成后默认值可直接跑通 standalone 单机模式，以下为与本指南直接相关的默认配置项。

文件配置项默认值说明
config/application.ymlcluster selectorstandalone单机模式，无集群注册
config/application.ymlstorage selectorh2内置 H2 内存库，重启即清空
config/application.ymlcore gRPCPort11800Agent 上报端口
config/application.ymlcore restPort12800REST/GraphQL 端口
webapp/application.ymlserverPort8080UI 访问端口
webapp/application.ymloapServiceshttp://localhost:12800UI 回连 OAP 地址
agent/config/agent.configagent.service_nameYour_ApplicationName服务名，接入时必须覆盖
agent/config/agent.configcollector.backend_service127.0.0.1:11800OAP gRPC 地址

修改配置后需重启对应进程。配置项的完整含义与生产化调整见《Apache SkyWalking 配置参数详解》。

十、注意事项

  1. 默认 H2 存储为内存库（JDBC URL 为 jdbc:h2:mem:skywalking-oap-db），OAP 重启后历史 Trace 与指标清空，仅适用于体验与功能验证，生产必须切换 Elasticsearch、MySQL 或 BanyanDB 存储。
  2. Agent 与 OAP 之间走 11800 端口 gRPC 长连接，被观测服务器与 OAP 非同机部署时，agent 的 backend_service 要写成 OAP 服务器地址，防火墙放行 11800。
  3. 服务名 agent.service_name 一经大量数据上报后不建议再改，改名会在拓扑中生成新服务节点。
  4. JAVA_OPTS 覆盖堆参数时注意脚本默认值是 4096M，小内存服务器必须显式设置，否则 OAP 可能因申请不到内存启动失败。
  5. Trace 批量上报存在延迟，Agent 侧默认约 30 秒一批，OAP 侧落库周期 25 秒（persistentPeriod），验证时请等待 1 分钟再查询。
  6. OAP 默认监听 0.0.0.0，公网服务器务必用防火墙限制 11800/12800/8080 的来源，避免链路数据与接口暴露。

十一、常见问题

11.1 服务已注册但没有 Trace

实测确认：被观测程序里仅作为 HTTP 客户端发起调用（没有任何服务端入口请求被增强）时，客户端 Span 不产生独立 Trace。用 curl 直接请求接入的服务（触发服务端入口 Span）即可看到数据。另需确认 OAP 与 Agent 时间一致，时间偏差会导致查询窗口错位。

11.2 tomcat9 启动报 No JDK or JRE found

apt 安装的 tomcat9 找不到 JVM，在 /etc/default/tomcat9 中显式添加：

JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

然后 systemctl restart tomcat9。

11.3 systemd 启动后堆参数只生效一半

Environment=JAVA_OPTS=-Xms256m -Xmx512m 未加引号时，systemd 将空格解析为变量边界，实际只有 -Xms256m 生效。用 cat /proc/OAP进程ID/cmdline 核查实际参数（进程 ID 用 pgrep -f 'OAPServerStartU[p]' 获取），并将单元文件改为 Environment="JAVA_OPTS=-Xms256m -Xmx512m"。

11.4 GraphQL 查询报 Invalid format

Duration 参数格式必须与 step 匹配：step 为 DAY 时写 2026-10-12，step 为 MINUTE 时写 2026-10-12 0240（HHmm 四位）。实测用 DAY 步长却传 2026-10-12 0000 会直接报错。

11.5 checkHealth 返回 health-checker missing

standalone 单机模式未注册健康检查组件，接口返回 Exception while fetching data (/checkHealth) : health-checker missing.，属预期行为。验证服务可用性改用 version 查询或直接请求 UI 首页。

11.6 新版本 11.0.0 解压后没有 webapp 和 agent 目录

SkyWalking 11.0.0 起主发行版只包含 OAP 后端，Web UI 与 Java Agent 需按官方文档单独获取，且默认存储改为 BanyanDB。需要开箱即用一体化安装时选择 9.7.0。

十二、卸载方式

停止并移除 systemd 单元：

systemctl stop skywalking-ui.service
systemctl stop skywalking-oap.service
systemctl disable skywalking-ui.service
systemctl disable skywalking-oap.service
rm -f /etc/systemd/system/skywalking-oap.service /etc/systemd/system/skywalking-ui.service
systemctl daemon-reload

删除安装目录与临时文件：

rm -rf /opt/skywalking /opt/skywalking-agent
rm -f /opt/apache-skywalking-apm-9.7.0.tar.gz /opt/apache-skywalking-java-agent-9.8.0.tgz

被观测服务按需移除 -javaagent 参数并重启，即可脱离链路追踪。

十三、参考链接