可观测性后端微服务云原生【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sky/skywalking点击查看免费下载SkyWalking OAP 的大部分配置通过application.yml与操作系统环境变量下发而其中的部分配置支持由上游管理系统动态下发。本文聚焦于其中基于Nacos 2.x的动态配置中心Dynamic Configuration CenterDCC实现从application.yml的启用配置、Nacos 中的存储模型Single / Group 两种配置形态到configuration-nacos模块的源码级同步与监听原理并给出集成测试验证方式。读完本文你将掌握如何把 OAP 的agent-analyzer.default.slowDBAccessThreshold、core.default.endpoint-name-grouping-openapi等配置项迁入 Nacos实现不停机热更新。一、动态配置机制与 Nacos 接入前提SkyWalking 的配置体系以 application.yml 和系统环境变量为主同时支持「Single单值」与「Group组」两种动态配置形态详见 动态配置总览。由于该能力依赖上游配置中心服务因此默认处于关闭状态selector默认指向none需要显式启用。Nacos 2.x 是 SkyWalking 支持的 DCC 实现之一其余还包括 Zookeeper、Etcd、Consul、Apollo、Kubernetes Configmap、gRPC DCS 等见 dynamic-config.md 中的实现清单。接入 Nacos 后OAP 会在后台周期性拉取并监听 Nacos 上的配置变更将变化实时同步到内存中的配置注册表从而驱动采样阈值、告警规则、端点分组规则等配置的动态调整。二、在 application.yml 中启用 Nacos 动态配置在 OAP 的application.yml即 oap-server/server-starter/src/main/resources/application.yml中将configuration.selector切换为nacos并填写 Nacos 服务端连接参数configuration: selector: ${SW_CONFIGURATION:nacos} nacos: # Nacos Server Host serverAddr: ${SW_CONFIG_NACOS_SERVER_ADDR:127.0.0.1} # Nacos Server Port port: ${SW_CONFIG_NACOS_SERVER_PORT:8848} # Nacos Configuration Group group: ${SW_CONFIG_NACOS_SERVER_GROUP:skywalking} # Nacos Configuration namespace namespace: ${SW_CONFIG_NACOS_SERVER_NAMESPACE:} # Unit seconds, sync period. Default fetch every 60 seconds. period: ${SW_CONFIG_NACOS_PERIOD:60} # the name of current cluster, set the name if you want to upstream system known. clusterName: ${SW_CONFIG_NACOS_CLUSTER_NAME:default}其中selector: ${SW_CONFIGURATION:nacos}表示可通过环境变量SW_CONFIGURATION覆盖默认值默认nacos例如在容器/编排环境中设置SW_CONFIGURATIONnacos即可切换。各参数含义与默认值如下参数环境变量覆盖默认值说明serverAddrSW_CONFIG_NACOS_SERVER_ADDR127.0.0.1Nacos Server 主机地址portSW_CONFIG_NACOS_SERVER_PORT8848Nacos Server 端口groupSW_CONFIG_NACOS_SERVER_GROUPskywalking配置所属 GroupOAP 读写配置时统一使用该 GroupnamespaceSW_CONFIG_NACOS_SERVER_NAMESPACE空配置所属 Namespace留空时使用 Nacos 默认public命名空间periodSW_CONFIG_NACOS_PERIOD60周期同步间隔单位秒默认每 60 秒全量拉取一次clusterNameSW_CONFIG_NACOS_CLUSTER_NAMEdefault当前集群名称原文档列出供上游系统识别需要特别说明的是原文档dynamic-config-nacos.md中仅列出上述 6 项而当前仓库源码中的配置模型 NacosServerSettings.java 与application.yml还额外提供了 Nacos 认证相关的四个字段参数环境变量覆盖默认值说明usernameSW_CONFIG_NACOS_USERNAME空Nacos 认证用户名passwordSW_CONFIG_NACOS_PASSWORD空Nacos 认证密码accessKeySW_CONFIG_NACOS_ACCESSKEY空阿里云 ACM / 鉴权 AccessKeysecretKeySW_CONFIG_NACOS_SECRETKEY空与 AccessKey 配套的 SecretKey在启动阶段NacosConfigurationProvider.java 会对配置做合法性校验serverAddr为空或 null → 抛出ModuleStartException(Nacos serverAddr cannot be null or empty.)port 0→ 抛出ModuleStartException(Nacos port must be positive integer.)group为空 → 抛出ModuleStartException(Nacos group cannot be null or empty.)username与accessKey同时非空→ 抛出ModuleStartException(Nacos Auth method should choose either username or accessKey, not both)即两种认证方式只能二选一。校验通过后initConfigReader()构造NacosConfigWatcherRegister并交由模块框架启动该模块依赖com.alibaba.nacos:nacos-client见 configuration-nacos/pom.xml。三、Nacos 中的配置存储模型启用后OAP 会以Data Id 配置键configKey、Group 上面配置的group的方式读写 Nacos 配置。依据配置类型的不同分为 Single 与 Group 两种存储形态。3.1 Single 单值配置Single 配置是一个配置键对应一个配置值逻辑结构为{configKey}:{configValue}在 Nacos 中的存储结构为Data IdGroupConfig ValueconfigKey{group}configValue例如动态配置为{agent-analyzer.default.slowDBAccessThreshold}:{default:200,mongodb:50}当group skywalking时Nacos 中的实际配置为Data IdGroupConfig Valueagent-analyzer.default.slowDBAccessThresholdskywalkingdefault:200,mongodb:50在 Nacos 控制台的「配置管理 → 配置列表」中新建一条配置Data ID 填agent-analyzer.default.slowDBAccessThresholdGroup 填skywalking配置内容填default:200,mongodb:50即可完成下发该配置将覆盖application.yml中agent-analyzer/default/slowDBAccessThreshold的值。3.2 Group 组配置Group 配置是一个配置键对应一组「子键-子值」在 Nacos 中的存储结构为Data IdGroupConfig ValueConfig TypeconfigKey{group}subItemkey1subItemkey2...TEXTsubItemkey1{group}subItemValue1subItemkey2{group}subItemValue2.........即主配置项Data Id 为 configKey的内容是一个子键清单每个子键又各自是一条独立的配置Data Id 为 subItemkey。若需新增/删除某个子项必须同步更新主配置项里的子键清单。子键之间的分隔规则为通过Nacos UI设置时每个子键独占一行行与行之间以\n分隔前后空白会被自动 trimsubItemValue1 subItemValue2 ...通过Nacos Open API / SDK发布时子键以\n或\r\n分隔例如configService.publishConfig(test-module.default.testKeyGroup, skywalking, subItemkey1\n subItemkey2));这与源码中 NacosConfigWatcherRegister.java 的解析逻辑一致readGroupConfig对主配置内容执行config.split(\\n|\\r\\n)后对每个子键做String::trim再逐一getConfig(itemName, group, 1000)拉取子键的值。例如动态配置为{core.default.endpoint-name-grouping-openapi}:|{customerAPI-v1}:{value of customerAPI-v1} |{productAPI-v1}:{value of productAPI-v1} |{productAPI-v2}:{value of productAPI-v2}当group skywalking时Nacos 中的实际配置为Data IdGroupConfig ValueConfig Typecore.default.endpoint-name-grouping-openapiskywalkingcustomerAPI-v1productAPI-v1productAPI-v2TEXTcustomerAPI-v1skywalkingvalue of customerAPI-v1productAPI-v1skywalkingvalue of productAPI-v1productAPI-v2skywalkingvalue of productAPI-v2core.default.endpoint-name-grouping-openapi用于为不同服务下发 OpenAPI 定义文件YAML 内容子键按serviceName.文件名组织从而生成端点名分组规则参见 endpoint-grouping-rules.md。四、同步与监听configuration-nacos 模块源码解析Nacos 动态配置的核心实现位于 NacosConfigWatcherRegister.java它继承自FetchingConfigWatcherRegisterconfiguration-api 模块整体运行机制分三层1. 连接建立构造阶段构造函数将serverAddr:port、namespace以及可选的username/password或accessKey/secretKey写入Properties并通过NacosFactory.createConfigService(properties)创建 NacosConfigService客户端PropertyKeyConst.SERVER_ADDR、PropertyKeyConst.NAMESPACE、PropertyKeyConst.USERNAME/PASSWORD、PropertyKeyConst.ACCESS_KEY/SECRET_KEY。2. 周期全量同步FetchingFetchingConfigWatcherRegister.start()会启动一个单线程调度器以syncPeriod即配置项period默认 60 秒为周期执行configSync()内部依次调用singleConfigsSync()与groupConfigsSync()前者对每个已注册的WatchType.SINGLE监听器调用readConfig(keys)后者对WatchType.GROUP监听器调用readGroupConfig(keys)并将拉取结果写入ConfigTable/GroupConfigTable最终回调各ConfigChangeWatcher完成值更新详见 FetchingConfigWatcherRegister.java。3. Nacos 实时监听PushreadConfig内部先通过removeUninterestedKeys(keys)移除已失效的监听再对每个 Data Id 调用configService.addListener(dataId, group, listener)注册监听器监听器触发时执行onDataIdValueChanged(dataId, configInfo)把新值写入configItemKeyedByName缓存并打印Nacos config changed日志。对于新注册的键还会立即getConfig(dataId, group, 1000)拉取一次初值从而兼顾「实时推送」与「启动即生效」两条路径registerKeyListeners。五、支持动态化的配置项速览并非所有 OAP 配置都支持动态下发可动态化的键由各模块在启动时注册到ConfigWatcherRegister。以下为当前支持的核心键详见 dynamic-config.mdSingle 单值配置Config Key值说明值格式示例agent-analyzer.default.slowDBAccessThreshold慢数据库语句阈值覆盖application.yml中agent-analyzer/default/slowDBAccessThresholddefault:200,mongodb:50agent-analyzer.default.uninstrumentedGateways未插桩网关配置覆盖gateways.yml同 uninstrumented-gateways.mdalarm.default.alarm-settings告警规则覆盖alarm-settings.yml同 backend-alarm.mdcore.default.apdexThresholdApdex 阈值覆盖service-apdex-threshold.yml同 apdex-threshold.mdcore.default.endpoint-name-grouping端点名分组规则覆盖endpoint-name-grouping.yml同 endpoint-grouping-rules.mdcore.default.log4j-xmllog4j 日志配置覆盖log4j2.xml同 dynamical-logging.mdcore.default.searchableTracesTags可检索的 Trace Tag 列表覆盖application.yml中core/default/searchableTracesTagshttp.method,http.status_code,rpc.status_code,db.type,db.instance,mq.queue,mq.topic,mq.brokeragent-analyzer.default.traceSamplingPolicy默认与按服务维度的采样策略覆盖trace-sampling-policy-settings.yml同 trace-sampling.mdconfiguration-discovery.default.agentConfigurationsConfigurationDiscovery 配置见 Java Agent 的 configuration-discovery 说明Group 组配置Config Key子键说明值说明core.default.endpoint-name-grouping-openapi与 OpenAPI 定义文件相关的服务名如serviceA一个服务对应多个文件时子键用serviceName.文件名拆分如serviceA.API-file1、serviceA.API-file2OpenAPI 定义文件内容YAML 格式用于生成端点名分组规则格式同 endpoint-grouping-rules.md以 Nacos 下发agent-analyzer.default.slowDBAccessThreshold为例在 Nacos 控制台发布后OAP 无需重启即可在下一个同步周期或通过监听实时感知变更动态调整慢 SQL 统计阈值同理可动态下发告警规则与端点分组规则。六、集成测试验证NacosConfigurationIT仓库为 Nacos 动态配置提供了基于 Testcontainers 的集成测试 NacosConfigurationIT.java可直接作为功能验证的参考测试环境nacos/nacos-server:v2.3.2-slim容器MODEstandalone暴露8848HTTP与9848gRPC 端口测试中通过nacos.server.grpc.port.offset设置偏移Single 验证向test-module.default.testKeyGroupskywalking发布值500等待provider.watcher.value()变为500随后removeConfig删除该键验证值恢复为 null —— 覆盖「新增生效、删除失效」两条路径Group 验证向test-module.default.testKeyGroup发布item1\n item2并分别发布item1100、item2200验证组内各子项被正确解析加载随后依次删除item1、修改item1300、删除主键testKeyGroup验证组配置的增、删、改全流程与主键清单的联动shouldReadUpdatedGroup。此外单元测试 NacosConfigWatcherRegisterTest.java 与测试模块NacosConfigurationTestModule/NacosConfigurationTestProvider共同构成了对该实现的回归保障。七、使用注意事项默认关闭动态配置依赖外部配置中心configuration.selector默认是none未显式切换到nacos前不会建立 Nacos 连接同步周期与实时性period默认 60 秒控制周期全量同步频率同时 Nacos 监听器提供实时推送实际生效速度通常远快于一个周期缩短period可加速兜底同步但会增加对 Nacos 的轮询压力Group 子键维护新增/删除子项时务必同步更新主配置项configKey中的子键清单否则子项不会被加载子键之间以换行分隔前后空白会被 trim主配置项文本末尾的空行可忽略认证方式互斥username/password与accessKey/secretKey只能选择其一同时配置会导致 OAP 启动失败Data Id 与 Group 强绑定所有读写均使用configuration.nacos.group指定的 Group默认skywalking在 Nacos 控制台新建配置时 Group 必须与此一致否则无法命中。赞分享可观测性后端微服务云原生【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sky/skywalking点击查看免费下载相关推荐Apache SkyWalking 动态配置Dynamic Configuration机制详解从 application.yml 开关到 ZooKeeper/Etcd/Nacos 多实现Apache SkyWalking 动态配置Dynamic Configuration机制详解从 application.yml 开关到 ZooKeepe可观测性后端微服务云原生RuoYi-Vue-fast配置中心实现Nacos集成与动态配置RuoYi Vue fast配置中心实现Nacos集成与动态配置 你是否还在为项目配置修改需要重启服务而烦恼是否希望实现配置的实时更新而不影响系统运行本文告别配置地狱SeaTunnel集成动态配置中心实战指南告别配置地狱SeaTunnel集成动态配置中心实战指南 你是否还在为数据同步任务中的配置变更焦头烂额每次修改配置文件后重启集群的操作不仅繁琐还可能导致数据数据工程大数据批处理流处理上一篇yuzu Early Access 4026性能对比与Citra及官方Switch运行效率测试下一篇2025 AI安全新范式Qwen3Guard-Gen-8B重新定义大模型防护标准创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考