简介面向微服务架构开发与运维人员的 sentinel-dashboard 1.8.6 集成 nacos 资源包聚焦服务发现、流控规则统一管理与 Gateway 网关限流场景。内含 568 个文件覆盖 java 业务源码、编译后 class、js/html 控制台前端、xml/properties 配置以及 jar 依赖等类型既能查看 Sentinel 控制台前后端完整实现也可直接改造部署压缩包整体约 26.25MB。包中重点呈现 application.properties 等配置改动思路可将 Sentinel 控制台对接 Nacos实现流控规则动态下发并针对 Gateway 路由进行限流控制同时附带大量控制器与测试类便于理解网关流控规则的接口设计和二次开发。已有 194 人学习下载适合需要快速搭建 SentinelNacos 生产级治理方案的开发者与运维工程师。 我相信很多人跟我一样把 Sentinel 升级到 1.8.6 之后遇到的第一个坎儿不是限流规则怎么写而是——重启之后规则全没了。再往后做 Gateway 接入时又在 Dashboard 上看到一堆flow类型的数据源网关规则死活不生效。这篇就把我在 1.8.6 上集成 Nacos、对接 Gateway 限流的完整过程和踩坑记录写出来给正在折腾这套东西的同学一个可以直接抄作业的参考。先说结论Sentinel 1.8.6 并不是不能做持久化和网关限流而是很多人还停留在 1.8.0 之前的使用习惯上——以为 Dashboard 改了规则就能自动同步到 Nacos。这个版本开始Dashboard 已经从规则生产者退化成纯粹的规则展示与控制台生产侧的能力被挪到了独立的sentinel-rule-datasource体系中。搞清楚这个变化后续所有配置就都顺了。1. 升级 1.8.6 后规则丢失的根因从一个 Dashboard 的定位转变说起如果你是从 1.7.x 或更早版本直接跳到 1.8.6第一反应大概率是怀疑 Nacos 没配好。不瞒你说我第一次升级后在 Dashboard 上配了三条限流规则服务一重启规则全部消失Nacos 的配置列表里也看不到任何新写入的数据。当时一度以为是 Nacos 客户端版本冲突折腾了半天才发现问题根本不在依赖冲突上。Sentinel Dashboard 从 1.8.0 开始做了一个很关键的功能拆分Dashboard 里的规则管理面板默认只操作内存态规则不再直接向任何外部数据源写入。生产环境的规则推送、存储、变更通知全部交给客户端侧的DataSource扩展机制去完成。这意味着以前那种Dashboard 改规则 - 自动同步到 Nacos - 客户端监听刷新的闭环在 1.8.0 之后默认是不存在的。所以当你使用 1.8.6 的 Dashboard 1.8.6 的客户端时最直观的现象就是Dashboard 上能加规则、能删除规则、能实时看到效果但一旦服务重启或者 Dashboard 重启规则就回到初始状态。这其实是官方有意为之——把规则生产从控制台剥离避免多环境共用 Dashboard 时出现规则互相覆盖的混乱局面。那正确的集成逻辑是什么两条线并行Dashboard 负责查通过 Nacos 数据源读取规则展示到界面上让你能看见当前生效的规则是什么。客户端负责拉应用启动时从 Nacos 拉取规则并加载到内存同时监听 Nacos 配置变更实现热更新。规则变更入口要么直接改 Nacos 配置要么通过 Dashboard 的推送按钮需要额外开发或引入开源的控制台扩展把变更写到 Nacos。理解了这个定位再看后面的配置就不会懵了——我们不是在集成而是在用数据源把 Dashboard 和客户端同时接到 Nacos 上。2. 整体链路拆解两条 Nacos 数据通道分别管什么在动手配置之前我建议先把整个链路在脑子里过一遍不然配置的时候很容易被绕晕。我们的目标场景是Spring Cloud Gateway 作为流量入口Sentinel 为网关维度的路由route和 API 分组API Group提供限流能力规则统一放在 Nacos 上Dashboard 负责可视化查看和管理。这里其实涉及两套独立的 Nacos 数据源通道通道作用部署位置数据格式Dashboard - NacosDashboard 启动时读取规则配置展示在控制台Dashboard 服务内对应规则类型的 JSON 数组Gateway Client - Nacos网关启动时拉取规则、运行期监听变更网关微服务内对应规则类型的 JSON 数组两套通道互不干扰但监听的是同一批 Nacos dataId。如果你只配了 Dashboard 侧的读取网关侧没配数据源那 Dashboard 能看到规则但网关根本不加载——这也是很多人界面有规则但不生效的原因。反过来如果只配了网关侧的数据源规则在生效但 Dashboard 打开一片空白。有人会问为什么不直接让 Dashboard 推送规则到 Nacos 呢官方在 1.8.x 里确实没有内置这个能力但社区里有不少实现方案比如通过改 Dashboard 源码、或者用配置中心作为跳板手动维护规则文件。我的建议是如果团队规模不大、规则变更不频繁直接在 Nacos 控制台改 JSON 是最可控的方式因为可以配合 Nacos 的版本管理和回滚功能。等规则数量上来再考虑引入推送扩展。数据源通道清楚了再看规则类型的区别。Gateway 场景下除了普通的FlowRule流控规则还有一套专门给网关用的GatewayFlowRule。两者的核心差异在于FlowRule针对资源名resource限流比如某个SentinelResource注解标注的方法、某个 Feign 接口、某个 URL。GatewayFlowRule针对网关的路由 ID 或 API 分组限流同时支持根据请求参数、请求头、来源 IP 做更细粒度的控制。在 Nacos 上这两种规则是完全独立的数据源分别用不同的 dataId 和规则类型去加载。这也是网关场景最容易漏掉的地方——很多人只配了FlowRule的数据源网关路由维度自然不生效。3. 落地步骤从 Dashboard 读 Nacos 到 Gateway 适配网关规则3.1 Dashboard 侧的 Nacos 数据源配置Dashboard 本身是一个 Spring Boot 应用官方从 1.8.0 开始提供了sentinel-dashboard-datasource-nacos这样的扩展包不过我没直接用这个因为它的配置项在某些版本里不太直观。我采用的是更常见的做法在 Dashboard 的application.properties里配置 Nacos 数据源同时在代码里注册对应的 DataSource 类。这里直接给出可用的配置# Nacos 连接信息 nacos.addr127.0.0.1:8848 nacos.namespacesentinel nacos.usernamenacos nacos.passwordnacos # 网关流控规则 dataId nacos.gateway.flow.dataIdsentinel-gateway-flow-rules nacos.gateway.flow.groupIdSENTINEL_GROUP需要声明的是不同版本的 Dashboard 对 Nacos 集成的支持程度不一样有的版本自带 Nacos 配置项但默认关闭有的需要自己写配置类。如果你用的 Dashboard 是官方原版 1.8.6我建议直接看源码里nacos相关的类是否存在再决定是走配置项还是写代码注册。不过要注意一个非常隐蔽的坑Dashboard 默认使用 8080 端口而 Nacos 控制台默认也是 8080。如果你在同一台机器上同时启动两者后启动的那个会直接报端口占用。我在本地调试时就遇到过后来把 Dashboard 的端口改成 8858 才解决。这个问题在热搜词里也有体现——很多人被nacos console default port is 8080卡住其实只要改掉其中一个的端口就行。3.2 配置 Dashboard 侧的 RuleDataSource为了把 Nacos 里的规则加载到 Dashboard需要实现一个DataSource并注册到 Dashboard 的规则管理器中。参考官方 Demo 和社区做法核心逻辑是这样的Configuration public class NacosDataSourceConfig { Value(${nacos.addr:127.0.0.1:8848}) private String nacosAddr; Value(${nacos.namespace:sentinel}) private String namespace; Bean public DataSource? gatewayFlowDataSource() { Properties properties new Properties(); properties.setProperty(PropertyKeyConst.SERVER_ADDR, nacosAddr); properties.setProperty(PropertyKeyConst.NAMESPACE, namespace); // 使用 Converter 把 Nacos 配置字符串转成网关规则列表 ConverterString, ListGatewayFlowRule converter source - JSON.parseArray(source, GatewayFlowRule.class); NacosDataSourceListGatewayFlowRule dataSource new NacosDataSource(properties, SENTINEL_GROUP, sentinel-gateway-flow-rules, converter); GatewayFlowRuleManager.loadRules(dataSource.getProperty()); dataSource.setCallback(() - GatewayFlowRuleManager.loadRules(dataSource.getProperty())); return dataSource; } }这段代码做的事很直白从 Nacos 拉取sentinel-gateway-flow-rules配置转成GatewayFlowRule列表加载到网关规则管理器里同时注册回调之后 Nacos 上任何变更都会自动刷新。注意这里的 Nacosnamespace要和你网关侧保持一致。我见过很多人在这里填错 namespace 导致 Dashboard 看不到规则——不是规则没推是 namespace 对不上。Nacos 的 namespace 默认是空字符串public如果你在 Nacos 控制台创建了自己的命名空间这里必须填对应的 namespace ID而不是名称。比如你创建了一个叫sentinel的命名空间Nacos 生成的 ID 是一长串随机字符串你要把那个 ID填进来不是sentinel这个字面值。3.3 Gateway 侧的限流依赖与数据源配置网关侧的配置是整个链路的核心。首先在 Gateway 服务的pom.xml里引入依赖版本必须和 Sentinel 核心版本一致否则会出现类冲突dependency groupIdcom.alibaba.csp/groupId artifactIdsentinel-spring-cloud-gateway-adapter/artifactId version1.8.6/version /dependency dependency groupIdcom.alibaba.csp/groupId artifactIdsentinel-datasource-nacos/artifactId version1.8.6/version /dependency然后是初始化逻辑。在网关启动时通过GatewayFlowRuleManager和GatewayApiDefinitionManager加载规则。我用的是PostConstruct初始化 Nacos 监听的方式Component public class GatewaySentinelInit implements ApplicationRunner { Value(${nacos.addr:127.0.0.1:8848}) private String nacosAddr; Override public void run(ApplicationArguments args) { // 加载网关流控规则 initGatewayFlowRules(); // 加载 API 分组定义如果用到 GatewayApiDefinitionManager initGatewayApiDefinitions(); } private void initGatewayFlowRules() { Properties properties new Properties(); properties.setProperty(PropertyKeyConst.SERVER_ADDR, nacosAddr); properties.setProperty(PropertyKeyConst.NAMESPACE, sentinel); // 注意 groupId 要和 Dashboard 侧一致 NacosDataSourceListGatewayFlowRule dataSource new NacosDataSource(properties, SENTINEL_GROUP, sentinel-gateway-flow-rules, source - JSON.parseArray(source, GatewayFlowRule.class)); GatewayFlowRuleManager.register2Property(dataSource.getProperty()); } }很多网上教程在这里用的是FlowRuleManager.register2Property()这是一个典型的坑——网关规则必须用GatewayFlowRuleManager用FlowRuleManager的话控制台能看到规则但不实际生效。原因就在于两种规则的数据格式和校验逻辑完全不同。3.4 Nacos 上的规则配置示例在 Nacos 配置中心里新建一个 dataId 为sentinel-gateway-flow-rules、group 为SENTINEL_GROUP、配置格式为 JSON 的配置内容示例[ { resource: order-service, resourceMode: 0, grade: 1, count: 5, intervalSec: 1, controlBehavior: 0, burst: 2, maxQueueingTimeoutMs: 500, paramItem: { parseStrategy: 2, fieldName: userId } }, { resource: /api/v1/order/**, resourceMode: 1, grade: 0, count: 50, intervalSec: 1 } ]字段不展开全说挑几个关键的讲resourceMode0 表示按路由 IDrouteId匹配1 表示按 URL 路径匹配。网关场景里如果你想对某个具体路由限流用 0对一组路径限流用 1。grade0 表示按并发线程数限流1 表示按 QPS 限流。日常接口限流绝大多数用 QPS。paramItem.parseStrategy网关独有的参数解析策略。2 表示从请求参数中提取指定字段做维度限流比如按 userId 限流每个用户 5 QPS超过就拒绝。burst允许的突发流量配合controlBehavior使用。如果希望匀速排队把controlBehavior设成 2同时设置maxQueueingTimeoutMs。我实际测试中最常用的是路由维度限流 参数维度限流组合——一个接口整体限制 100 QPS同时每个 userId 最多 5 QPS既防止接口被刷爆也避免单个用户占满配额。4. 排坑实记Gateway 场景最容易翻车的几个环节4.1 #Nacos 命名空间不一致这个坑在热搜词里也出现了nacos命名空间一直为null我一开始在 Dashboard 和网关里都配了namespacesentinel结果 Dashboard 始终读不到规则。排查了很久才发现我在 Nacos 控制台创建命名空间时系统生成的 ID 并不是我填的名字而是一个 UUID 字符串。Nacos 2.x 的控制台默认显示的是命名空间名称但程序里要填的是命名空间 ID。后来我直接在配置文件里把 namespace 改成了 UUID一切正常。建议先到 Nacos 控制台 - 命名空间页面复制真实 ID再填到配置里。不要凭印象填名称。另外两台服务如果 namespace 不一致一个能连上另一个连不上不会报错只会让规则静默失效这点排查周期很长一定要提前检查。4.2 数据源类型不匹配FlowRule vs GatewayFlowRule这是网关场景最高频的隐蔽问题。现象是启动时没有报错Dashboard 上也能看到规则但真实的限流效果完全不符合预期接口随便刷都不拦截。问题出在初始化代码。很多人抄的模板是FlowRuleManager.register2Property()但这个方法是给普通微服务场景用的。网关适配器会去读GatewayFlowRuleManager的规则两套规则管理器互不相通。如果你往FlowRuleManager里注册了数据源那 Nacos 里的网关格式规则根本不会被网关解析器消费。检查方法很简单看一眼规则配置里的字段有没有resourceMode、paramItem这些网关专属字段。如果有那你必须用GatewayFlowRuleManager去加载别用FlowRuleManager。4.3 网关规则在 Dashboard 上不显示另一个常见情况是规则在网关侧已经生效了但 Dashboard 页面看不到任何网关规则。这个问题的根源在于 Dashboard 的网关规则展示模块只读取GatewayFlowRuleManager里的规则。如果你没有在 Dashboard 里注册对应的 Nacos 数据源或者注册的是FlowRule数据源而不是GatewayFlowRule数据源那 Dashboard 上的网关流控规则页面就是空的。我当时在 Dashboard 源码基础上加了一段GatewayFlowRuleManager.register2Property()的逻辑接的是同一个 Nacos dataId界面就正常显示出来了。注意Dashboard 1.8.6 默认只集成了流控规则的 Nacos 对接网关规则的对接有的版本需要自己扩展。这里我给出一个更省事的方案如果不想改 Dashboard 源码可以直接在 Nacos 配置中心维护规则Dashboard 仅作为监控面板查看实时数据。网关规则不显示就不显示只要限流在生效就行。但对于需要可视化运维的团队这个方案可能不够那就得自己动手扩展 Dashboard 了。4.4 端口占用与 502 迷惑现象本地联调时我还遇到过一个特别让人头大的问题——网关某个路由转发到下游服务时偶尔 502排查了好久最后发现跟 Sentinel 完全没关系是 Gateway 的全局过滤器执行顺序导致的Sentinel 网关过滤器的 order 值默认是-1如果你自定义的过滤器 order 比它小就会在限流判断之前把请求转发出去一旦下级服务没起来就会出现 502。这个坑很多人会误以为是 Sentinel 限流配置的锅其实只是过滤器顺序问题。把自定义过滤器的order调整到0或-2之后问题彻底消失。热搜词里那些502 bad gateway的问题大多也是这个层面的原因——网关本身没启动、路由没配对、下游服务异常而不是限流规则写错。4.5 Nacos 客户端与 Spring Cloud Alibaba 版本冲突还有一个容易踩的版本问题。如果你同时使用 Spring Cloud Alibaba 的 Nacos 注册发现又引入 Sentinel 的sentinel-datasource-nacos两个包自带的 Nacos client 版本不一致就会出现各种奇怪的NoSuchMethodError或者ClassNotFoundException。我的做法是统一 Nacos client 版本在dependencyManagement里显式声明dependencyManagement dependencies dependency groupIdcom.alibaba.nacos/groupId artifactIdnacos-client/artifactId version2.2.0/version /dependency /dependencies /dependencyManagement如果你用的是 Nacos 2.x 服务端客户端版本最好也选 2.x避免 1.x 客户端与 2.x 服务端的兼容性问题。别小看这个我见过有人在这里折腾了两三天最后发现是客户端版本太旧导致的连接间歇性失败。5. 规则热更新验证与效果实测配置全部完成后最后一步是验证链路是否真的打通。我的验证步骤很简单但每一步都能暴露问题启动 Nacos、Dashboard、Gateway确认三个服务都正常运行。在 Nacos 控制台手动添加规则配置内容用上面给的sentinel-gateway-flow-rulesJSON。观察 Dashboard 的网关流控规则页面确认规则已经展示出来。用压测工具我用的是 wrk 和 JMeter对网关路由发起请求观察是否触发限流。在 Nacos 里修改 count 值等几秒后重新压测确认新规则生效。我实际测得的效果路由维度 QPS 限制 5并发 10 个请求实际通过 5 个其余全部返回SentinelBlockHandler定义的兜底响应表现符合预期。Nacos 里把 count 改成 10不需要重启任何服务大约 1~2 秒后新规则自动生效。这验证了数据源通道、监听机制、网关适配器三个环节都正常。这里有个小细节网关限流的兜底处理要单独设置否则默认返回 429 状态码加一段默认文本前端体验很差。我是在 Gateway 的全局异常处理里加了对BlockException的捕获统一返回 JSON 格式的错误信息Order(-1) Component public class GatewayBlockExceptionHandler implements WebExceptionHandler { Override public MonoVoid handle(ServerWebExchange exchange, Throwable ex) { if (ex instanceof BlockException) { ServerHttpResponse response exchange.getResponse(); response.setStatusCode(HttpStatus.TOO_MANY_REQUESTS); response.getHeaders().setContentType(MediaType.APPLICATION_JSON); String body {\code\:429,\msg\:\请求太频繁请稍后重试\}; DataBuffer buffer response.bufferFactory().wrap(body.getBytes(StandardCharsets.UTF_8)); return response.writeWith(Mono.just(buffer)); } return Mono.error(ex); } }兜底响应做得好不好直接影响用户感知。限流不可怕可怕的是被限流后返回一个看不懂的白屏或 500。个人实操体会这套 Sentinel 1.8.6 Nacos Gateway 的限流链路我前后搭了大概两天时间中间踩的坑基本都写在上面的排坑章节里了。如果重新来一遍我会先把两个核心概念前置搞清楚一是 1.8.x 之后 Dashboard 不再负责规则生产二是 Gateway 场景必须用GatewayFlowRuleManager而非FlowRuleManager。这两个认知到位了剩下都是配置层面的体力活。最后再分享一个小技巧Nacos 上的规则配置建议把group独立出来统一管理不要用默认的DEFAULT_GROUP。比如我统一用SENTINEL_GROUP这样在 Nacos 控制台上通过 group 过滤一眼就能看到所有 Sentinel 相关配置避免和业务配置混在一起。还有规则文件的 JSON 格式建议先在线校验一遍再保存Nacos 不会帮你检查 JSON 合法性语法错误会导致数据源解析失败而且不会报错——规则悄悄不生效排查起来最难受。本文还有配套的精品资源点击获取