SkyWalking OAP 后端 IP 与端口配置完全指南：core 模块绑定、gRPC/REST 双服务与各模块独立端口-平芜编程栈

可观测性
APM
链路追踪
指标监控
日志分析
微服务

【免费下载链接】skywalking

APM, Application Performance Monitoring System

项目地址：https://gitcode.com/gh_mirrors/sk/skywalking

导读

SkyWalking OAP（Observability Analysis Platform）后端通过 IP 与端口绑定对外提供服务，其设计允许操作系统上存在多个 IP 的情况下，精确控制每个服务监听哪个地址。本指南基于官方文档与仓库源码，系统讲解core模块中restHost/restPort/gRPCHost/gRPCPort等核心配置的作用、Agent 与 UI 的接入方式，以及 receiver、query 等模块提供者如何额外指定各自的 IP 和端口。读完本文，你将能独立规划 OAP 的对外监听地址、解决跨网段访问与端口冲突问题，并理解各端口背后的源码实现。

一、两个 IP/端口对：gRPC 与 HTTP REST 服务的职责划分

OAP 后端对外提供两套独立的网络服务，分别服务于不同角色的客户端，均由核心模块（core）统一定义默认监听地址：

服务	默认监听	典型端口	主要消费方
gRPC 服务	`0.0.0.0`	`11800`	大多数 Agent、探针（Probe）、部分 Receiver
HTTP REST 服务	`0.0.0.0`	`12800`	UI（SkyWalking UI / Horizon UI）、部分语言 Agent、REST 类 Receiver

两者职责划分的官方说明如下：

大多数 Agent 与探针使用 gRPC 服务，以获得更好的性能和代码可读性；
部分 Agent 使用 REST 服务，因为某些语言环境可能不支持 gRPC；
UI 使用 REST 服务，但传输的数据始终是 GraphQL 格式（即通过 HTTP REST 端口访问 GraphQL 查询 API）。

也就是说，12800端口承载的并非普通 RESTful 接口，而是 GraphQL 端点；11800端口承载的才是 Agent 上报链路数据（Trace、JVM 指标、日志、Profile 快照等）的主要通道。

二、core 模块配置详解

OAP 的默认配置位于 oap-server/server-starter/src/main/resources/application.yml，其中core段是 IP 与端口绑定的权威出处。官方文档给出的最小配置如下：

core: default: restHost: 0.0.0.0 restPort: 12800 restContextPath: / gRPCHost: 0.0.0.0 gRPCPort: 11800

2.1 完整参数表（含默认值与含义）

结合 CoreModuleConfig.java 与application.yml，核心配置项的完整说明如下：

配置项	环境变量	默认值	说明
`restHost`	`SW_CORE_REST_HOST`	`0.0.0.0`	HTTP REST（GraphQL）服务监听地址
`restPort`	`SW_CORE_REST_PORT`	`12800`	HTTP REST（GraphQL）服务监听端口
`restContextPath`	`SW_CORE_REST_CONTEXT_PATH`	`/`	REST 服务的上下文路径（Context Path）
`gRPCHost`	`SW_CORE_GRPC_HOST`	`0.0.0.0`	gRPC 服务监听地址
`gRPCPort`	`SW_CORE_GRPC_PORT`	`11800`	gRPC 服务监听端口

在实际的application.yml中，这些配置以环境变量占位符形式给出，方便容器化部署时通过环境变量覆盖：

core: selector: ${SW_CORE:default} default: role: ${SW_CORE_ROLE:Mixed} # Mixed/Receiver/Aggregator restHost: ${SW_CORE_REST_HOST:0.0.0.0} restPort: ${SW_CORE_REST_PORT:12800} restContextPath: ${SW_CORE_REST_CONTEXT_PATH:/} ... gRPCHost: ${SW_CORE_GRPC_HOST:0.0.0.0} gRPCPort: ${SW_CORE_GRPC_PORT:11800}

从源码角度看，CoreModuleConfig.java 中与监听地址直接相关的字段还包括：

restMaxThreads（默认 200）、restIdleTimeOut（默认 30000ms，环境变量SW_CORE_REST_IDLE_TIMEOUT）、restAcceptQueueSize（默认 0，环境变量SW_CORE_REST_QUEUE_SIZE）：HTTP 服务器的线程与连接队列调优参数；
httpMaxRequestHeaderSize（默认 8192 字节，环境变量SW_CORE_HTTP_MAX_REQUEST_HEADER_SIZE）：HTTP 请求头大小上限，设为 -1 可禁用限制；
restSSLEnabled/restSSLKeyPath/restSSLCertChainPath（环境变量SW_CORE_REST_SSL_*）：REST 服务端 TLS 配置，证书与私钥从磁盘读取，轮换时无需重启即可重新加载；
gRPCSslEnabled/gRPCSslKeyPath/gRPCSslCertChainPath/gRPCSslTrustedCAPath（环境变量SW_CORE_GRPC_SSL_*）：gRPC 服务端 TLS/mTLS 配置；
maxConcurrentCallsPerConnection（默认 0，表示不限制）、maxMessageSize（默认 52428800 即 50MB）、gRPCThreadPoolSize（默认 -1）：gRPC 服务器的连接并发、消息体大小与线程池参数。

这些参数与端口配置一起，构成了 OAP 对外网络能力的完整控制面。

2.2 环境变量覆盖方式

在 Docker 或 Kubernetes 场景下，推荐直接通过环境变量覆盖，无需修改application.yml。例如：

# 仅绑定本机回环地址（仅本机可访问） export SW_CORE_REST_HOST=127.0.0.1 export SW_CORE_GRPC_HOST=127.0.0.1 # 修改端口以规避冲突 export SW_CORE_REST_PORT=12880 export SW_CORE_GRPC_PORT=11880

三、源码级原理：core 模块如何创建两个服务器

OAP 的core模块默认实现位于 CoreModuleProvider.java，其prepare()方法中完整展示了两个服务器的创建过程：

gRPC 服务器（CoreModuleProvider.java 第 241-265 行）：根据gRPCSslEnabled决定是否携带证书创建GRPCServer，随后应用maxConcurrentCallsPerConnection、maxMessageSize、gRPCThreadPoolSize等参数，并调用initialize()完成初始化；同时通过setBootingParameter将oap.internal.comm.host/port与oap.external.grpc.host/port写入启动参数——这两组参数分别用于 OAP 集群节点间的内部通信寻址与对外 Agent 通信地址的广播。

HTTP REST 服务器（CoreModuleProvider.java 第 267-284 行）：通过HTTPServerConfig.builder()装配restHost、restPort、restContextPath、restIdleTimeOut、restAcceptQueueSize、httpMaxRequestHeaderSize以及 REST TLS 配置，再创建HTTPServer并初始化。

启动时序：两个服务器并非在prepare()立即对外监听，而是统一推迟到notifyBootCompleted()阶段（第 517-528 行）才调用grpcServer.start()与httpServer.start()。源码注释明确说明这一设计意图："receiver ports open last: every module has finished its boot-time work"，即接收端口最后打开，确保首个请求到达时 OAP 已完整启动。

此外，ConfigService.java 会拷贝gRPCHost/gRPCPort供其他模块读取，作为 Agent 注册、集群协调等逻辑的地址来源。

四、IP 绑定注意事项（官方重点提示）

4.1 IP 绑定的含义

对于不熟悉 IP 绑定的用户，需要注意：一旦 IP 绑定完成，客户端只能使用该 IP 访问服务。例如，若绑定172.09.13.28，即使你就在本机上，也必须使用172.09.13.28访问服务，而不能使用127.0.0.1或localhost。

这一特性的直接后果是：

绑定0.0.0.0（默认值）：监听所有网卡地址，本机、局域网、外网地址均可访问，默认推荐；
绑定具体网卡 IP（如172.09.13.28）：仅该 IP 可达，适合多网卡主机上精确隔离服务暴露面；
绑定127.0.0.1：仅本机回环访问，适合本机调试或不对外暴露的场景（此时 UI 与远端 Agent 将无法连接）。

在多 IP 的宿主机（如云服务器、双网卡容器节点）上部署时，务必根据安全策略明确restHost与gRPCHost的取值，避免"以为绑定了全部网卡，实际只暴露了部分网卡"的认知偏差。

4.2 与 role 的关系

值得补充的是，core模块还支持三种部署角色（CoreModuleConfig.java 第 263-289 行）：

Mixed（默认）：接收 Agent 数据、做 L1 与 L2 两级聚合；
Receiver：只接收 Agent 数据并做 L1 聚合，结果转发给 Mixed/Aggregator 节点；
Aggregator：只接收其他 OAP 节点的数据，做 L2 聚合后落库。

在不同角色下，gRPC 端口同时承担"Agent 上报"与"OAP 节点间内部通信"两种职责（见 CoreModuleProvider.java 第 451-467 行，Mixed/Aggregator 角色会将自身 gRPC 地址注册到集群协调器）。因此在规划多节点集群时，需要保证各节点gRPCHost/gRPCPort相互可达，且与 Agent 网络联通。

五、模块提供者指定的其他 IP 和端口

官方文档特别指出：core模块中的 IP 和端口是默认值，但许多模块提供者（尤其是各类 receiver 模块）会提供额外的 IP 和端口设置。这是 SkyWalking 可扩展架构的重要体现——每个模块通过自身的ModuleConfig声明独立的监听地址，与core的默认端口并存。

5.1 receiver-sharing-server（共享接收服务器）

多数 receiver 模块（如 trace、jvm、profile、meter、log、browser、otel 等）并不直接创建独立端口，而是把处理器注册到receiver-sharing-server这个共享服务器上。其配置同样位于application.yml：

receiver-sharing-server: selector: ${SW_RECEIVER_SHARING_SERVER:default} default: # For HTTP server restHost: ${SW_RECEIVER_SHARING_REST_HOST:0.0.0.0} restPort: ${SW_RECEIVER_SHARING_REST_PORT:0} restContextPath: ${SW_RECEIVER_SHARING_REST_CONTEXT_PATH:/} restIdleTimeOut: ${SW_RECEIVER_SHARING_REST_IDLE_TIMEOUT:30000} restAcceptQueueSize: ${SW_RECEIVER_SHARING_REST_QUEUE_SIZE:0} httpMaxRequestHeaderSize: ${SW_RECEIVER_SHARING_HTTP_MAX_REQUEST_HEADER_SIZE:8192} # For gRPC server gRPCHost: ${SW_RECEIVER_GRPC_HOST:0.0.0.0} gRPCPort: ${SW_RECEIVER_GRPC_PORT:0} maxConcurrentCallsPerConnection: ${SW_RECEIVER_GRPC_MAX_CONCURRENT_CALL:0} maxMessageSize: ${SW_RECEIVER_GRPC_MAX_MESSAGE_SIZE:52428800} #50MB gRPCThreadPoolSize: ${SW_RECEIVER_GRPC_THREAD_POOL_SIZE:0} gRPCSslEnabled: ${SW_RECEIVER_GRPC_SSL_ENABLED:false} ... authentication: ${SW_AUTHENTICATION:""}

注意其默认端口为0。从 SharingServerConfig.java 的注释可以看到关键约定：只有设置为真实端口（非 0），Armeria/HTTP 服务器与 gRPC 服务器才会真正启动；若为0，则所有 receiver 的处理器会注册到core模块的11800/12800端口上（见 SharingServerModuleProvider.java 第 77-104、110-150 行）。

这是一个非常重要的部署决策点：默认情况下（端口为 0），Agent 数据与 UI 查询都走core的11800/12800；若你希望将 Agent 上报流量与查询流量物理隔离（例如按网段或安全域拆分），可给receiver-sharing-server配置独立的SW_RECEIVER_GRPC_PORT/SW_RECEIVER_SHARING_REST_PORT，此时 OAP 会额外监听新的端口。

5.2 各模块独立端口速查表

从 application.yml 可以整理出当前仓库中所有模块默认监听的端口，方便统一规划防火墙与端口映射：

模块	配置项	环境变量	默认端口	用途
`core`	`restPort`	`SW_CORE_REST_PORT`	12800	GraphQL 查询 API（UI 使用）
`core`	`gRPCPort`	`SW_CORE_GRPC_PORT`	11800	Agent 上报 + OAP 集群内部通信
`receiver-sharing-server`	`restPort`/`gRPCPort`	`SW_RECEIVER_SHARING_REST_PORT`/`SW_RECEIVER_GRPC_PORT`	0（不启用）	独立接收通道（可选）
`receiver-zipkin`	`restPort`	`SW_RECEIVER_ZIPKIN_REST_PORT`	9411	接收 Zipkin 格式 trace（HTTP）
`query-zipkin`	`restPort`	`SW_QUERY_ZIPKIN_REST_PORT`	9412	Zipkin 查询 API / zipkin-lens UI
`promql`	`restPort`	`SW_PROMQL_REST_PORT`	9090	PromQL 查询 API
`logql`	`restPort`	`SW_LOGQL_REST_PORT`	3100	LogQL 查询 API
`traceQL`	`restPort`	`SW_TRACEQL_REST_PORT`	3200	TraceQL 查询 API
`telemetry`(prometheus)	`port`	`SW_TELEMETRY_PROMETHEUS_PORT`	1234	OAP 自身指标暴露（Prometheus 格式）
`receiver-zabbix`	`port`	`SW_RECEIVER_ZABBIX_PORT`	10051	接收 Zabbix 告警数据
`aws-firehose`	`port`	`SW_RECEIVER_AWS_FIREHOSE_HTTP_PORT`	12801	AWS Firehose 数据接收
`admin-server`	`port`/`gRPCPort`	`SW_ADMIN_SERVER_PORT`/`SW_ADMIN_SERVER_GRPC_PORT`	17128 / 17129	管理 API（状态、inspect、运行时规则热更新等）

例如query-zipkin的 REST 服务器还支持restContextPath: ${SW_QUERY_ZIPKIN_REST_CONTEXT_PATH:/zipkin}，即默认挂载在/zipkin路径下；receiver-zipkin则同时支持 HTTP（9411）与 Kafka 两种采集方式（enableKafkaCollector，默认关闭）。

5.3 各查询 API 模块的独立配置示例

以 PromQL 与 LogQL 为例，它们各自拥有独立的 REST 服务器，便于与 Grafana 等生态工具对接：

promql: selector: ${SW_PROMQL:default} default: restHost: ${SW_PROMQL_REST_HOST:0.0.0.0} restPort: ${SW_PROMQL_REST_PORT:9090} restContextPath: ${SW_PROMQL_REST_CONTEXT_PATH:/} logql: selector: ${SW_LOGQL:default} default: restHost: ${SW_LOGQL_REST_HOST:0.0.0.0} restPort: ${SW_LOGQL_REST_PORT:3100} restContextPath: ${SW_LOGQL_REST_CONTEXT_PATH:/}

这些模块与core的12800端口共存，均遵循"模块提供者指定独立 IP 和端口"的设计模式——每种能力（Zipkin 兼容、PromQL、LogQL、TraceQL、管理 API）都可以独立启用、独立绑定地址。

六、常见问题与排查建议

Agent 上报成功但 UI 打不开：确认restPort（默认 12800）与gRPCPort（默认 11800）都已在防火墙/安全组放行，且 Agent 配置的 collector 地址指向gRPCHost:gRPCPort，UI 配置指向restHost:restPort。
UI 能打开但看不到数据：检查是否将receiver-sharing-server的 gRPC 端口改成了非 0 值，而 Agent 仍连接core的 11800 端口——此时数据进入了独立通道，需要同步调整 Agent 端地址，或恢复共享服务器端口为 0。
多网卡主机上外部访问不通：回顾本文第 4 节的 IP 绑定规则，确认绑定的是对外网卡 IP 而非127.0.0.1，并避免绑定单一内网 IP 后仍尝试用公网 IP 访问。
端口冲突：各模块默认端口不同（12800/11800/9411/9412/9090/3100/3200/1234/17128/17129 等），若与既有服务冲突，通过对应SW_*_PORT环境变量修改即可，无需改动配置文件。
开启 TLS 后客户端连接失败：若设置了restSSLEnabled/gRPCSslEnabled，需同步在 Agent 或 UI 侧配置证书信任；gRPCSslTrustedCAPath用于 mTLS 场景下的 CA 校验。

总结

SkyWalking OAP 的 IP 与端口体系围绕"core 模块提供默认双服务（gRPC:11800 + REST:12800），各模块提供者可独立扩展端口"这一核心设计展开。理解restHost/restPort/restContextPath/gRPCHost/gRPCPort五个基础配置项、环境变量覆盖方式、IP 绑定的排他性语义，以及receiver-sharing-server端口为 0 时的注册逻辑，即可从容应对单机部署、多网卡隔离、集群通信与生态工具对接等绝大多数网络规划场景。所有配置均可在 application.yml 中查阅，底层实现可进一步阅读 CoreModuleProvider.java 与 SharingServerModuleProvider.java。