Apache SkyWalking 配置参数详解

目标：本文逐段解析 Apache SkyWalking 9.7.0 的核心配置文件，覆盖 application.yml 的 cluster、core、storage、receiver 四大段落，webapp 的 UI 配置与 agent.config 的探针参数，给出每个配置项的默认值、环境变量名与实测行为说明，并附生产环境调优建议，可直接对照修改。

一、环境信息

本文基于以下环境实测整理，所有默认值与行为均来自真实运行验证。

SkyWalking 的配置体系分三层，理解层次关系后按层修改即可，不需要通读全部文件：

二、前置条件

1. 已按《Apache SkyWalking 安装指南》完成 9.7.0 安装并能正常启动 OAP 与 UI；
2. 熟悉 YAML 基本语法，修改前建议先备份原文件：

cp /opt/skywalking/config/application.yml /opt/skywalking/config/application.yml.bak

3. 每次修改后重启对应进程（OAP 或 UI）方可生效；Agent 配置修改后需重启被观测服务。

三、配置文件位置与查看方式

确认三个配置文件均存在：

ls -l /opt/skywalking/config/application.yml /opt/skywalking/webapp/application.yml /opt/skywalking-agent/config/agent.config

-rw-r--r-- 1 root root 64753 Nov  1  2023 /opt/skywalking-agent/config/agent.config
-rw-r--r-- 1 root root 42499 Nov  1  2023 /opt/skywalking/config/application.yml
-rw-r--r-- 1 root root   776 Nov  1  2023 /opt/skywalking/webapp/application.yml

定位各配置段落所在行号（段落名顶格书写）：

grep -nE '^(cluster|core|storage|receiver-sharing-server|receiver-cache|telemetry|health-checker|configuration):' /opt/skywalking/config/application.yml

17:cluster:
68:core:
141:storage:
254:receiver-cache:
255:receiver-sharing-server:
339:telemetry:
366:health-checker:
371:configuration:

查看某一段完整内容（以 storage 段为例，行号区间 141 到 254）：

sed -n '141,200p' /opt/skywalking/config/application.yml | grep -vE '^\s*#|^\s*$'

输出即该段生效行，后续章节的默认值均以此方式核对。发行包还附带示例配置目录：

ls /opt/skywalking/config-examples/

alarm-settings.yml
lal.yaml
log-mal.yaml

四、参数体系总览

application.yml 中的配置项普遍写成「键： 冒号加环境变量占位」的形式，占位内含环境变量名与默认值，格式含义为：未设置对应环境变量时使用冒号后的默认值。因此每个配置项都有两个入口：

1. 直接改 YAML 文件中的默认值；
2. 通过 SW_ 前缀环境变量覆盖（不改文件）。

实测验证环境变量覆盖机制最直接的方式是 JVM 参数：oapService.sh 读取 JAVA_OPTS 环境变量（默认 -Xms256M -Xmx4096M），启动前显式导出即可覆盖：

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

五、核心参数分类详解

5.1 cluster 段：集群模式

• 配置项 selector，环境变量 SW_CLUSTER，默认值 standalone。
• 可选值：standalone、kubernetes、consul、etcd、nacos、zookeeper。
• standalone 为单机模式，无集群注册与发现，所有数据在单进程内聚合，适合单服务器部署；多副本生产部署时切换到注册中心实现，对应配置写在 cluster 段同名子块中。

5.2 core 段：核心服务

环境变量前缀 SW_CORE，选择器 selector 默认值 default。本段实测关键参数：

实测行为佐证：TTL 清理任务按 metricsDataTTL 周期执行，日志可见：

grep 'Deleting history' /opt/skywalking/logs/skywalking-oap-server.log | tail -1

2026-10-12 02:55:57,022 - org.apache.skywalking.oap.server.storage.plugin.jdbc.common.dao.JDBCHistoryDeleteDAO - 55 [pool-5-thread-1] INFO  [] - Deleting history data, ttl: 7, now: 1791773757022. Keep [20261005, 20261013]

端口监听实测（core 段修改后需重启 OAP，ss 验证两个端口同时监听）：

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

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

5.3 storage 段：存储

选择器 selector，环境变量 SW_STORAGE，默认值 h2。官方实现包括 h2、mysql、postgresql、elasticsearch、banyandb 等。

h2（默认，实测启用）：

mysql / postgresql（发行包内置 JDBC 实现，关键环境变量）：

切换方式：SW_STORAGE=mysql 或 SW_STORAGE=postgresql，并按上表设置连接信息；JDBC 驱动已包含在 oap-libs 中，无需额外安装。

elasticsearch（生产主流，关键环境变量，取自 storage 段 elasticsearch 子块默认值）：

banyandb（SkyWalking 自研存储，11.x 起为默认方向，关键环境变量）：

选型建议：验证与单机体验用 h2；日均百万级 Span 以下用 mysql 或 postgresql（运维成本最低）；大规模生产用 elasticsearch 或 banyandb。

5.4 receiver-sharing-server 段：共享接收器

• 配置项 selector，环境变量 SW_RECEIVER_SHARING_SERVER，默认值 default。
• 该段为各类 HTTP/gRPC 上报协议（链路、指标、日志、事件、JVM 等）提供共享监听，与 core 段共用 11800 端口，一般保持默认不动。
• 关联段 receiver-cache 负责接收侧缓存，默认 default，无需调整。

5.5 webapp/application.yml：UI 配置

文件很短，实测全文关键项：

OAP 与 UI 分机部署时，必须把 oapServices 改为 OAP 实际地址。UI 的 JVM 参数同样由 webappService.sh 的 JAVA_OPTS 控制（脚本默认 -Xms256M -Xmx1024M），实测覆盖为 512MB 后进程参数如下（UI 进程 ID 用 pgrep -f 'ApplicationStartU[p]' 获取）：

cat /proc/$(pgrep -f 'ApplicationStartU[p]' | head -1)/cmdline | tr '\0' ' ' | grep -oE '\-Xms256m -Xmx512m'

-Xms256m -Xmx512m

5.6 agent.config：探针配置

Java Agent 的属性风格配置文件，关键项（行号来自 9.8.0 发行包）：

核对默认值：

grep -n 'agent.service_name\|collector.backend_service' /opt/skywalking-agent/config/agent.config

20:agent.service_name=Your_ApplicationName
100:collector.backend_service=127.0.0.1:11800

三种覆盖方式按优先级：启动参数 -D（如 -Dskywalking.agent.service_name=demo-service，实测生效）、系统环境变量、直接修改 agent.config。Agent 启动方式与参数覆盖的实测过程见《Apache SkyWalking 常用 CLI 命令与工具详解》。

六、环境变量覆盖总表

常用 SW_ 前缀变量按段落归类（默认值均为发行包实测核对值）：

使用规则：环境变量与文件内占位同名时，环境变量优先生效；OAP 镜像化部署（见《Apache SkyWalking Docker Compose 部署指南》）正是依赖该机制实现免改文件配置。

七、生产配置模板

单机小规模生产（日均 Span 百万级以内）推荐起步配置，全部经实测确认可启动：

1. 堆内存：OAP 与 UI 分别 -Xms1g -Xmx4g（本实测环境为 512MB，仅因服务器内存受限；生产按 Span 量扩容）。
2. 存储：切换 mysql 或 elasticsearch，切勿沿用 H2 内存库（重启清空数据）。
3. 数据保留：按磁盘预算调整 SW_CORE_METRICS_DATA_TTL 与 SW_CORE_RECORD_DATA_TTL。
4. 端口收敛：restHost/gRPCHost 按需绑定内网地址，UI 走反向代理对外。
5. UI 回连地址：oapServices 指向 OAP 内网地址。

配置生效验证三板斧（每次改完必做）：

ss -tlnp | grep -E '11800|12800|8080'
curl -s -X POST http://localhost:12800/graphql -H 'Content-Type: application/json' -d '{"query":"{ version }"}'
systemctl is-active skywalking-oap.service
systemctl is-active skywalking-ui.service

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))
{"data":{"version":"9.7.0-066457b"}}
active
active

八、常见问题

8.1 改了 application.yml 不生效

三种可能：一是没有重启对应进程；二是同名配置被环境变量覆盖（环境变量优先于文件默认值）；三是改错了文件（webapp 的配置在 webapp/application.yml，不在 config/ 下）。

8.2 H2 模式重启后数据丢失

默认 JDBC URL 为内存库（h2:mem），这是发行包设计行为，属预期。生产按 5.3 节切换外部存储。

8.3 systemd 托管时堆参数只生效一半

单元文件中 Environment=JAVA_OPTS=-Xms256m -Xmx512m 未加引号时，systemd 把空格解析为变量分隔符，实测进程只剩 -Xms256m。必须写成 Environment="JAVA_OPTS=-Xms256m -Xmx512m"，并用 cat /proc/进程PID/cmdline 复核。

8.4 切换存储后 OAP 启动失败

按日志区分：连接被拒（SW_JDBC_URL 或 ES 地址写错、网络不通）、认证失败（SW_ES_USER/SW_ES_PASSWORD 错误）、驱动缺失（JDBC 方式一般不会发生，驱动已内置）。先用 ss 或 curl 在 OAP 服务器上验证目标存储端口连通性再启动。

8.5 TTL 到期数据没有立刻消失

TTL 清理由 dataKeeperExecutePeriod（默认 5 分钟）驱动的周期任务执行，且按天粒度删除，当天数据不受影响，属正常延迟。

九、参考链接

• 后端配置官方文档：https://skywalking.apache.org/docs/main/latest/en/backend/backend-setup/
• 存储选型官方文档：https://skywalking.apache.org/docs/main/latest/en/backend/backend-storage/
• Java Agent 配置官方文档：https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configuration/
• UI 设置官方文档：https://skywalking.apache.org/docs/main/latest/en/ui/readme/