Apache SkyWalking Docker Compose 部署指南

目标：本文提供使用 Docker Compose 一键部署 Apache SkyWalking 9.7.0 可观测平台的标准方案，覆盖官方镜像选型、OAP 与 UI 双服务编排、环境变量配置、JVM 堆限制、数据持久化路径、等价 docker run 命令与常用运维命令，全部步骤经真实环境实测验证，可直接照做。

一、环境信息

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

项目	值
操作系统	Ubuntu 22.04
Docker 版本	29.8.0
Compose 版本	v2（docker compose 子命令）
OAP 镜像	apache/skywalking-oap-server:9.7.0
UI 镜像	apache/skywalking-ui:9.7.0
编排目录	/opt/skywalking-compose
JVM 堆	OAP 限制 -Xms256m -Xmx512m
端口	11800（gRPC）、12800（REST）、8080（UI）

版本说明：SkyWalking 从 11.0.0 起官方主发行版不再提供独立 UI 镜像组合的经典形态，且默认存储转向 BanyanDB。9.7.0 是 OAP 镜像与 UI 镜像稳定配套、默认 H2 存储开箱即用的成熟版本，本指南采用 9.7.0。

二、镜像选型说明

官方 Docker Hub 仓库 apache/ 下提供两个核心镜像：

镜像	用途	默认暴露端口
apache/skywalking-oap-server	OAP 后端，接收 Agent 上报并做聚合分析	11800 gRPC、12800 REST
apache/skywalking-ui	Web UI，通过 SW_OAP_ADDRESS 回连 OAP 查询	8080 HTTP

镜像与二进制发行版的配置体系一致：镜像内部使用环境变量覆盖 application.yml，例如 SW_STORAGE 覆盖存储选择器、JAVA_OPTS 覆盖 JVM 参数，与手工安装时修改配置文件等效。镜像内置的 OAP 版本可通过 GraphQL version 查询确认，本环境实测返回 9.7.0-066457b。

拉取镜像（镜像已存在时重复执行会回显 up to date，即无需重复下载）：

docker pull apache/skywalking-oap-server:9.7.0
docker pull apache/skywalking-ui:9.7.0

Status: Image is up to date for apache/skywalking-oap-server:9.7.0
docker.io/apache/skywalking-oap-server:9.7.0
Status: Image is up to date for apache/skywalking-ui:9.7.0
docker.io/apache/skywalking-ui:9.7.0

确认镜像清单与体积：

docker images | grep skywalking

apache/skywalking-oap-server:9.7.0    9af311a030f2   952MB   365MB
apache/skywalking-oap-server:latest   835a0d8de39a   997MB   371MB
apache/skywalking-ui:9.7.0            3c7f7225d051   719MB   267MB
apache/skywalking-ui:latest           bc0fae785f4f   512MB   105MB

镜像摘要可用于固化版本（防止 latest 漂移）：

docker inspect apache/skywalking-oap-server:9.7.0 --format '{{.RepoDigests}}'
docker inspect apache/skywalking-ui:9.7.0 --format '{{.RepoDigests}}'

[apache/skywalking-oap-server@sha256:9af311a030f2a106dceecffddef72038e8a7335b92e2c2bd3a30be5942d663ea]
[apache/skywalking-ui@sha256:3c7f7225d0512fcb8ea96a0e8820e1752b99ee3a651b33fd4a69ead629de3b1d]

三、前置条件

服务器已安装 Docker 与 Compose 插件，并验证可用：

docker version --format 'server={{.Server.Version}}'
docker compose version

server=29.8.0
Docker Compose version v2.40.0

内存不低于 2 GB（OAP 512MB 堆 + UI 512MB 堆 + 系统开销）。
端口 11800、12800、8080 未被占用：

ss -tlnp | grep -E '11800|12800|8080' || echo 'ports free'

ports free

四、部署步骤

4.1 创建编排文件

mkdir -p /opt/skywalking-compose
cat > /opt/skywalking-compose/docker-compose.yml <<'EOF'
version: '3.8'

services:
  skywalking-oap:
    image: apache/skywalking-oap-server:9.7.0
    container_name: skywalking-oap
    restart: unless-stopped
    environment:
      JAVA_OPTS: "-Xms256m -Xmx512m"
      SW_STORAGE: h2
    ports:
      - "11800:11800"
      - "12800:12800"
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -s http://localhost:12800/graphql || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 10

  skywalking-ui:
    image: apache/skywalking-ui:9.7.0
    container_name: skywalking-ui
    restart: unless-stopped
    depends_on:
      - skywalking-oap
    environment:
      SW_OAP_ADDRESS: http://skywalking-oap:12800
    ports:
      - "8080:8080"
EOF

关键配置说明：

JAVA_OPTS：将 OAP 堆限制为 512MB，实测镜像内 java 进程 PID 1 参数为 java -Xms256m -Xmx512m；
SW_STORAGE: h2：使用内置 H2 内存库存储，功能验证最简路径，重启后数据清空；
SW_OAP_ADDRESS：UI 通过服务名 skywalking-oap 访问 OAP 的 REST 端口，依赖 Compose 默认网络内置 DNS；
healthcheck：通过 12800 端口 GraphQL 探活，OAP 镜像内自带 curl 命令。

4.2 启动编排栈

cd /opt/skywalking-compose
docker compose up -d

 Container skywalking-oap Started
 Container skywalking-ui Starting
 Container skywalking-ui Started

说明：Compose v2 会对 version: '3.8' 字段输出提示 the attribute version is obsolete, it will be ignored，不影响部署；新写法可直接删除该行。

4.3 查看运行状态

docker compose ps --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'

NAME             STATUS                    PORTS
skywalking-oap   Up 49 seconds (healthy)   0.0.0.0:11800->11800/tcp, [::]:11800->11800/tcp, 1234/tcp, 0.0.0.0:12800->12800/tcp, [::]:12800->12800/tcp
skywalking-ui    Up 48 seconds             0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

OAP 状态为 Up (healthy)，说明 GraphQL 探活已通过。

4.4 验证 OAP 进程堆参数

docker exec skywalking-oap ps -ef | head -2

UID          PID    PPID  C STIME TTY          TIME CMD
root           1       0 99 03:15 ?        00:01:32 java -Xms256m -Xmx512m -classpath /skywalking/ext-libs/*.jar:oap-libs/... org.apache.skywalking.oap.server.starter.OAPServerStartUp

4.5 查看启动日志

docker compose logs skywalking-oap | grep 'Server started'

skywalking-oap  | 2026-10-12 03:15:12,260 org.apache.skywalking.oap.server.library.server.grpc.GRPCServer 108 [main] INFO  [] - Server started, host 0.0.0.0 listening on 11800

4.6 服务可用性验证

在宿主机（或部署机）验证 UI 与 GraphQL：

curl -s -o /dev/null -w 'UI http: %{http_code}\n' http://localhost:8080/
curl -s -X POST http://localhost:12800/graphql -H 'Content-Type: application/json' -d '{"query":"{ version }"}'

UI http: 200
{"data":{"version":"9.7.0-066457b"}}

浏览器访问 http://部署机IP:8080 即可打开 SkyWalking UI。Agent 侧将 backend_service 指向部署机IP:11800 即可上报链路数据。

4.7 查看镜像元信息

docker inspect skywalking-oap --format 'image={{.Config.Image}}'
docker inspect skywalking-ui --format 'image={{.Config.Image}}'

image=apache/skywalking-oap-server:9.7.0
image=apache/skywalking-ui:9.7.0

五、数据持久化说明

默认 SW_STORAGE 为 h2 时，OAP 使用内存 JDBC（application.yml 默认 JDBC URL 为 jdbc:h2:mem:skywalking-oap-db），数据保存在 OAP 进程内存中，存在以下行为：

容器重启、OAP 进程退出即清空全部 Trace 与指标；
数据量受堆内存约束，512MB 堆下仅适合短期功能验证；
迁移成本为零，验证完成后随时可切换外部存储。

生产持久化路径是切换存储选择器，官方支持的外部存储包括 MySQL、PostgreSQL、Elasticsearch、BanyanDB。以 Elasticsearch 为例，在 skywalking-oap 服务的 environment 中声明即可（变量名与默认值取自发行包 application.yml 的 elasticsearch 配置段，本文未做多服务编排实测，按官方文档核对后使用）：

环境变量	示例值	说明
SW_STORAGE	elasticsearch	切换存储选择器
SW_STORAGE_ES_CLUSTER_NODES	elasticsearch:9200	ES 集群地址
SW_ES_USER / SW_ES_PASSWORD	elastic / 变更后密码	ES 开启认证时填写

同时在 services 下补充 elasticsearch 服务并把 skywalking-oap 的 depends_on 指向它。MySQL 持久化对应 SW_STORAGE=mysql，配合 SW_JDBC_URL、SW_DATA_SOURCE_USER、SW_DATA_SOURCE_PASSWORD 三个变量（默认值分别为 jdbc:mysql://localhost:3306/swtest、root、root@1234，需按实际库调整）。

六、常用环境变量表

环境变量	默认值	作用
JAVA_OPTS	-Xms256M -Xmx4096M（脚本内置）	OAP 的 JVM 参数，堆大小、GC 策略在此覆盖
SW_STORAGE	h2	存储选择器：h2/mysql/postgresql/elasticsearch/banyandb
SW_CLUSTER	standalone	集群模式选择器，多副本用 nacos/zookeeper 等
SW_CORE_GRPC_HOST / SW_CORE_GRPC_PORT	0.0.0.0 / 11800	Agent 上报的 gRPC 监听
SW_CORE_REST_HOST / SW_CORE_REST_PORT	0.0.0.0 / 12800	REST 与 GraphQL 监听
SW_TELEMETRY	prometheus	自身指标遥测选择器
SW_OAP_ADDRESS	http://localhost:12800	UI 镜像专用，回连 OAP 地址
SW_HEALTH_CHECKER	无	健康检查组件地址，standalone 下默认无

变量与 application.yml 中形如 SW_ 前缀的占位定义一一对应，镜像启动时注入环境变量即可生效，无需进入容器改文件。

七、常用配置参数说明

配置项	位置	默认值	说明
storage selector	application.yml	h2	与 SW_STORAGE 对应
core gRPCPort	application.yml	11800	Agent 上报端口
core restPort	application.yml	12800	GraphQL/REST 端口
core persistentPeriod	application.yml	25	落库周期（秒）
core metricsDataTTL	application.yml	7	指标数据保留天数
core recordDataTTL	application.yml	3	记录数据保留天数
storage h2 maxSizeOfBatchSql	application.yml	100	H2 批量写入 SQL 条数
webapp serverPort	webapp/application.yml	8080	UI 端口
webapp oapServices	webapp/application.yml	http://localhost:12800	UI 回连 OAP

UI 镜像的 SW_OAP_ADDRESS 环境变量即覆盖 webapp application.yml 中的 oapServices 项；OAP 镜像的其余 SW_ 变量覆盖 config/application.yml 中同名占位。完整参数语义见《Apache SkyWalking 配置参数详解》。

八、配置文件持久化（挂载）

需要精细调整 application.yml 而不通过环境变量时，用卷挂载替换镜像内配置：

    volumes:
      - ./application.yml:/skywalking/config/application.yml:ro

OAP 镜像内工作目录为 /skywalking，config 子目录即主配置。挂载前先取出镜像内原始文件做底稿：

docker cp skywalking-oap:/skywalking/config/application.yml ./application.yml

修改后重建服务生效：

cd /opt/skywalking-compose
docker compose up -d --force-recreate skywalking-oap

注意：挂载的 application.yml 中 SW_ 占位仍会被环境变量覆盖，同一项不要在文件与环境变量中各写一套值，避免排障困扰。

九、等价 docker run 运行方式

不使用编排文件时，两条 docker run 可以达到相同效果。先创建专用网络：

docker network create skywalking-net

启动 OAP：

docker run -d --name skywalking-oap \
  --network skywalking-net \
  -e JAVA_OPTS="-Xms256m -Xmx512m" \
  -e SW_STORAGE=h2 \
  -p 11800:11800 -p 12800:12800 \
  --restart unless-stopped \
  apache/skywalking-oap-server:9.7.0

启动 UI：

docker run -d --name skywalking-ui \
  --network skywalking-net \
  -e SW_OAP_ADDRESS=http://skywalking-oap:12800 \
  -p 8080:8080 \
  --restart unless-stopped \
  apache/skywalking-ui:9.7.0

两个容器通过 skywalking-net 网络按服务名互访，验证方式与 4.6 节一致（UI 首页 200、GraphQL 返回 9.7.0-066457b）。

十、常用运维命令

命令	用途
docker compose up -d	后台启动全部服务
docker compose ps	查看服务状态与健康检查结果
docker compose logs -f skywalking-oap	跟踪 OAP 日志
docker compose restart skywalking-ui	重启单个服务
docker compose stop / start	停止/启动整栈（保留网络与容器定义）
docker compose down	删除容器与网络（H2 数据随之清空）
docker compose up -d --force-recreate	配置变更后强制重建
docker compose config	校验并展开最终编排配置
docker exec -it skywalking-oap bash	进入 OAP 排障

标准巡检组合：

cd /opt/skywalking-compose
docker compose ps --format 'table {{.Name}}\t{{.Status}}'
curl -s -X POST http://localhost:12800/graphql -H 'Content-Type: application/json' -d '{"query":"{ version }"}'

NAME             STATUS
skywalking-oap   Up 49 seconds (healthy)
skywalking-ui    Up 48 seconds
{"data":{"version":"9.7.0-066457b"}}

十一、常见问题（FAQ）

11.1 OAP 容器反复重启

先用 docker compose logs skywalking-oap 看根因。常见两类：一是堆参数过大导致 JVM 申请内存失败，把 JAVA_OPTS 调小（本指南 -Xms256m -Xmx512m 在 2GB 内存服务器实测通过）；二是端口被宿主机其他进程占用，ss -tlnp 排查后修改 ports 映射。

11.2 UI 打开空白或报无法连接后端

UI 通过 SW_OAP_ADDRESS 回连 OAP。自查三点：变量值必须是 http://服务名:12800（用服务名而非 localhost）；两个服务在同一 Compose 网络（默认同编排文件即同网络）；OAP 已完成启动（compose ps 显示 healthy 需要约 1 分钟）。

11.3 Agent 已上报但 UI 查不到数据

数据链路为 Agent 批量上报（约 30 秒）加 OAP 落库（persistentPeriod 25 秒），上报告地址必须是 OAP 的 gRPC 端口 11800 而非 12800。Agent 侧排查方法见《Apache SkyWalking 常用 CLI 命令与工具详解》。

11.4 重启后数据全部消失

默认 SW_STORAGE=h2 为内存库，属预期行为。需要持久化按第五节切换 MySQL、PostgreSQL、Elasticsearch 或 BanyanDB 存储。

11.5 up 时提示 version 属性已废弃

Compose v2 输出 the attribute version is obsolete, it will be ignored, please remove it to avoid potential confusion，仅提示不阻断，可删除 version 行消除告警。

11.6 想看 OAP 实际生效的 JVM 参数

进入容器查看 PID 1 的命令行：

docker exec skywalking-oap ps -ef | grep java

输出首行 java 进程即携带 -Xms256m -Xmx512m 等参数，与 environment 声明一致即为生效。

十二、参考链接

官方镜像仓库：https://hub.docker.com/u/apache
OAP 镜像说明：https://hub.docker.com/r/apache/skywalking-oap-server
UI 镜像说明：https://hub.docker.com/r/apache/skywalking-ui
官方文档主页：https://skywalking.apache.org/docs/
GitHub 仓库：https://github.com/apache/skywalking