Spring Cloud Alibaba 2025.0.0.0 配套搭建 Sentinel Dashboard 1.8.9

发表于 更新于 分类于 ， ， 置顶 精品
阅读次数： 0 本文字数： 6.4k 阅读时长 ≈ 23 分钟

摘要

  • 依据 Spring Cloud Alibaba 版本发布说明，搭建与 Spring Cloud Alibaba 2025.0.0.0 对应的 Sentinel Dashboard 1.8.9。

  • 本文侧重 Dashboard 单机搭建（JAR / Docker / systemd），并补充应用侧接入、OpenFeign / RestTemplate / Gateway 适配，以及 Nacos 规则持久化。

  • 生产推荐：规则持久化到 Nacos（Push 模式）；Dashboard 可选（仅监控时需要），限流生效不依赖控制台。

  • 同版本配套的 Nacos Server 见 Spring Cloud Alibaba 2025.0.0.0 配套搭建 Nacos 3.0.3。

一、版本对照

1. Spring Cloud Alibaba 2025.0.x 适配关系

摘自官方 版本发布说明：

Spring Cloud Alibaba Version Spring Cloud Version Spring Boot Version
2025.0.0.0 2025.0.0 3.5.0

同页「组件版本关系」中，与 2025.0.0.0 对应的 Sentinel 版本为：

Spring Cloud Alibaba Version Sentinel Version
2025.0.0.0 1.8.9

对比：同属 2025.x 的 2025.1.0.0 亦使用 Sentinel 1.8.9，服务端 Dashboard 版本可共用。

2. 环境准备

项目 要求说明
Sentinel Dashboard 1.8.9 JDK 1.8+ 即可（也可直接用 JDK 17）
Docker（可选） Docker 20+

端口规划（与 Nacos 同机时建议错开控制台端口）：

用途 端口 说明
Sentinel Dashboard 8858 本文示例端口；默认官方示例常用 8080，易与 Nacos 3.x 控制台冲突

二、搭建 Sentinel Dashboard 1.8.9

官方发布包：Sentinel v1.8.9 Release（资源文件 sentinel-dashboard-1.8.9.jar）。
控制台说明见 Sentinel Wiki · Dashboard。

1. 方式一：JAR 直接启动（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
mkdir -p /usr/local/sentinel && cd /usr/local/sentinel

# 跟随请求重定向
curl -L https://github.com/alibaba/Sentinel/releases/download/1.8.9/sentinel-dashboard-1.8.9.jar

# 使用 8858，避免与 Nacos 控制台 8080 冲突
nohup java \
  -Dserver.port=8858 \
  -Dcsp.sentinel.dashboard.server=10.10.2.45:8858 \
  -Dproject.name=sentinel-dashboard \
  -jar sentinel-dashboard-1.8.9.jar \
  > sentinel-dashboard.log 2>&1 &

访问：http://127.0.0.1:8858
默认账号 / 密码：sentinel / sentinel（生产务必修改）。

2. 方式二：Docker 启动

官方在 sentinel-dashboard 目录提供 Dockerfile（1.8.9 / 1.8 分支均有）。镜像构建时会从 GitHub Release 再下载 sentinel-dashboard-1.8.9.jar，因此构建机需能访问 GitHub；网络不稳时优先用上文「方式一」官方 JAR。

构建前必读

  1. 基础镜像失效：官方 Dockerfile 的基础镜像 openjdk:8-jre-slim 已在 Docker Hub 上失效，无论用下面（1）（2）（3）哪种方式，都需先修改 Dockerfile 中的 FROM（例如改为 openjdk:8u212-jre-slim），再执行 docker build。具体替换命令与 slim / 非 slim 说明见下文 （3）。
  2. GitHub 下载失败：官方 Dockerfile 在构建阶段会通过 curl 访问 release-assets.githubusercontent.com 拉取 JAR。若出现 curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL，说明 Docker 构建网络无法稳定访问 GitHub Release（国内环境较常见）。此时请改用下文 （3.1）宿主机预下载 JAR，或直接用上文「方式一」JAR 启动。

docker build 的上下文必须是含 Dockerfile 的 sentinel-dashboard 目录，任选下面一种准备源码：

（1）完整克隆（最简单）

1
2
3
4
5
6
7
8
git clone https://github.com/alibaba/Sentinel.git
cd Sentinel
git checkout 1.8.9

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  sentinel-dashboard

（2）稀疏克隆（只取 sentinel-dashboard，省流量）

1
2
3
4
5
6
7
8
9
10
git clone --filter=blob:none --sparse \
  https://github.com/alibaba/Sentinel.git
cd Sentinel
git sparse-checkout set sentinel-dashboard
git checkout 1.8.9

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  sentinel-dashboard

（3）不克隆仓库，只下载 Dockerfile

官方 Dockerfile 本质是拉取 Release JAR，也可单独下载该文件后构建。

注意：官方 Dockerfile 的基础镜像为 openjdk:8-jre-slim，该标签在 Docker Hub 上已不可用（docker pull 会报 not found）。下载后需改为仍可拉取的标签，例如 openjdk:8u212-jre-slim（与本节开头「构建前必读」一致）。

1
2
3
4
5
6
7
8
9
10
11
12
mkdir -p sentinel-dashboard && cd sentinel-dashboard
curl -fsSL -o Dockerfile \
  https://raw.githubusercontent.com/alibaba/Sentinel/1.8.9/sentinel-dashboard/Dockerfile

# 将已失效的 openjdk:8-jre-slim 替换为可用镜像
sed -i.bak 's|FROM openjdk:8-jre-slim|FROM openjdk:8u212-jre-slim|' Dockerfile
# macOS / Linux 通用；也可用编辑器手动改 FROM 那一行

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  .

修改后的关键行应类似：

1
FROM openjdk:8u212-jre-slim

PS：openjdk:8-*-slim 与不带 slim 的镜像区别

  • 带 slim：基于 Debian slim 精简根文件系统，体积更小、攻击面更小，适合只跑 JRE 的生产镜像；但预装工具更少（如部分调试命令、额外字体/locale 可能缺失）。
  • 不带 slim（如 openjdk:8u212-jre）：完整 Debian 基础层，体积更大，调试与兼容性通常更好，一般用于开发排查或对系统库有额外依赖的场景。
    Sentinel Dashboard 仅依赖 JRE 跑 JAR，优先用 slim 即可；若构建或运行时缺库，再改用不带 slim 的同版本标签。

（4）构建阶段 GitHub 下载失败（SSL_ERROR_SYSCALL）

若 docker build 在 installer 阶段报错类似：

1
curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to release-assets.githubusercontent.com:443

说明官方多阶段 Dockerfile 在 容器内 拉取 GitHub Release 失败。可在 宿主机 先下载 JAR，再改用本地 COPY，避免构建时再访问 GitHub：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
mkdir -p sentinel-dashboard && cd sentinel-dashboard

# 在宿主机下载 JAR（可用代理、镜像站，或从内网机器 scp 过来）
wget https://github.com/alibaba/Sentinel/releases/download/1.8.9/sentinel-dashboard-1.8.9.jar

cat > Dockerfile <<'EOF'
FROM openjdk:8u212-jre-slim

COPY sentinel-dashboard-1.8.9.jar /home/sentinel-dashboard.jar

ENV JAVA_OPTS '-Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080'

RUN chmod -R +x /home/sentinel-dashboard.jar

EXPOSE 8080

CMD java ${JAVA_OPTS} -jar /home/sentinel-dashboard.jar
EOF

docker build -t sentinel-dashboard:1.8.9 .

若宿主机同样无法访问 GitHub，可在一台能下载的机器上取回 sentinel-dashboard-1.8.9.jar 后拷贝到构建目录，再执行 docker build。若不需要容器化，直接用上文「方式一」JAR 启动更简单。

（5）运行容器

1
2
3
4
5
docker run -d \
  --name sentinel-dashboard \
  -p 8858:8080 \
  -e JAVA_OPTS='-Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080' \
  sentinel-dashboard:1.8.9

访问宿主机：http://127.0.0.1:8858。

社区也有第三方镜像（如 bladex/sentinel-dashboard:1.8.9），使用前请确认来源可信；本文优先官方 JAR。

3. systemd 托管示例（可选）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# /etc/systemd/system/sentinel-dashboard.service
[Unit]
Description=Sentinel Dashboard 1.8.9
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/usr/local/sentinel
ExecStart=/usr/bin/java -Dserver.port=8858 -Dcsp.sentinel.dashboard.server=127.0.0.1:8858 -Dproject.name=sentinel-dashboard -jar /usr/local/sentinel/sentinel-dashboard-1.8.9.jar
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
1
2
3
systemctl daemon-reload
systemctl enable --now sentinel-dashboard
systemctl status sentinel-dashboard

三、应用侧快速接入（SCA 2025.0.0.0）

官方指南：SCA · Sentinel 快速开始。

1. BOM 与依赖

父 POM / 依赖管理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2025.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>com.alibaba.cloud</groupId>
      <artifactId>spring-cloud-alibaba-dependencies</artifactId>
      <version>2025.0.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

业务模块引入：

1
2
3
4
<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

Starter 会传递依赖 sentinel-* :1.8.9，与上文 Dashboard 版本对齐。

2. application.yml 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
server:
  port: 18082

spring:
  application:
    name: demo-provider
  cloud:
    sentinel:
      transport:
        dashboard: 127.0.0.1:8858
        # 客户端供 Dashboard 回调的本地端口，默认 8719，冲突时可改
        # port: 8719
      eager: true

3. 代码最小示例

1
2
3
4
5
6
7
8
9
@RestController
public class TestController {

    @GetMapping("/hello")
    @SentinelResource("hello")
    public String hello() {
        return "Hello Sentinel";
    }
}

应用启动并访问一次受保护接口后，打开 Sentinel 控制台，应能看到应用名 demo-provider 及资源 hello，随后可在控制台配置流控规则验证限流。

仅在控制台「新增流控规则」时，规则默认只推到客户端内存。应用重启或 Dashboard 重启后规则会丢。生产请接下文 「五、单台 Dashboard + Nacos 规则持久化」；本地联调可先用手写控制台规则快速验证。

四、客户端组件适配（OpenFeign / RestTemplate / Gateway）

spring-cloud-starter-alibaba-sentinel 对 Spring Cloud 生态常见 HTTP 客户端做了适配。完整说明见 SCA · Sentinel 进阶指南 · 客户端支持。

Servlet 侧的 spring.cloud.sentinel.filter.*、servlet.block-page 等配置对 OpenFeign / RestTemplate 不生效，需按下面各自方式配置限流与降级处理。

1. OpenFeign

依赖：Sentinel Starter + OpenFeign（版本由 BOM 管理）：

1
2
3
4
5
6
7
8
<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

需显式打开开关：

1
2
3
feign:
  sentinel:
    enabled: true

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
@FeignClient(
    name = "service-provider",
    fallback = EchoServiceFallback.class,
    configuration = FeignConfiguration.class
)
public interface EchoService {

    @GetMapping("/echo/{str}")
    String echo(@PathVariable("str") String str);
}

class FeignConfiguration {
    @Bean
    public EchoServiceFallback echoServiceFallback() {
        return new EchoServiceFallback();
    }
}

class EchoServiceFallback implements EchoService {
    @Override
    public String echo(@PathVariable("str") String str) {
        return "echo fallback";
    }
}

要点：

项 说明
开关 默认不启用，必须 feign.sentinel.enabled=true
资源名 httpmethod:protocol://requesturl；上例 echo 为 GET:http://service-provider/echo/{str}
@FeignClient 注解属性（含 fallback / fallbackFactory 等）Sentinel 均兼容
规则配置 对上述资源名配 flow / degrade 即可（可写在 Nacos，见第五节）

2. RestTemplate

对 RestTemplate Bean 加 @SentinelRestTemplate：

1
2
3
4
5
6
7
8
@Bean
@SentinelRestTemplate(
    blockHandler = "handleException",
    blockHandlerClass = ExceptionUtil.class
)
public RestTemplate restTemplate() {
    return new RestTemplate();
}

blockHandler / fallback 对应方法必须是 blockHandlerClass / fallbackClass 中的 静态方法；参数、返回值与 ClientHttpRequestInterceptor#intercept 一致，并多一个 BlockException：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import com.alibaba.cloud.sentinel.rest.SentinelClientHttpResponse;
import com.alibaba.csp.sentinel.slots.block.BlockException;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpResponse;

public class ExceptionUtil {

    public static ClientHttpResponse handleException(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution,
            BlockException exception) {
        return new SentinelClientHttpResponse("blocked by sentinel");
    }
}

要点：

项 说明
注解属性 blockHandler + blockHandlerClass（限流）；fallback + fallbackClass（降级）；均可选
启动校验 声明了 handler 但方法不存在时，应用启动直接失败
未配 handler 被限流 / 熔断时默认返回类似 RestTemplate request block by sentinel
资源名粒度 ① GET:https://host:port/path（含路径）② GET:https://host:port（仅主机端口）

例：GET https://www.taobao.com/test 对应资源名可为 GET:https://www.taobao.com/test 或 GET:https://www.taobao.com。

3. Spring Cloud Gateway（简述）

网关限流需额外依赖（与普通业务服务的 Starter 组合使用）：

1
2
3
4
5
6
7
8
9
10
11
12
<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

规则类型使用 gw-flow / gw-api-group（见第五节对照表）。熔断后的响应可通过 spring.cloud.sentinel.scg.fallback.* 配置（mode=redirect | response 等），详见 进阶指南 与 Sentinel 网关限流。

五、单台 Dashboard + Nacos 规则持久化

官方 Dashboard 不提供集群，生产更务实的做法是：把规则落到 Nacos 配置中心（Push 模式）。应用启动后从 Nacos 拉取规则并监听变更，重启不丢。单台 Dashboard 仅作可选监控面板。动态数据源说明见 SCA · Sentinel 进阶指南。

前提：已按 Spring Cloud Alibaba 2025.0.0.0 配套搭建 Nacos 3.0.3 跑通 Nacos 3.0.3（含鉴权账号密码）。

1. 架构说明

1
2
3
4
5
6
7
                  推送 / 监听（自动）
Nacos Config  ─────────────────────►  业务应用（Sentinel Client 内存）
（规则真源）                                   │
     ▲                                         │ 控制台打开规则页时查询客户端（可选）
     │ 人工维护配置（推荐）                      ▼
Nacos 控制台                        Sentinel Dashboard（单台，可选）
                                        监控、看板；开箱不写回 Nacos
角色 职责
Nacos 规则持久化与多实例一致下发（真源）
业务应用 通过 sentinel-datasource-nacos 订阅规则并写入本地内存生效
Sentinel Dashboard 可选；集群拓扑、实时监控；打开规则页时向客户端拉取展示；开箱不写回 Nacos

同步方向（务必分清）

方向 是否自动 实际链路
改 Nacos → 业务应用 会 Nacos 推送 / 监听 → 客户端内存，限流立刻生效
改 Nacos → Sentinel 控制台 不是直推 Nacos → 应用内存 →（控制台查客户端）→ 页面展示。控制台没有单独一份从 Nacos 同步来的规则库
改控制台 → Nacos 不会 开箱 Dashboard 只推到应用内存，不写回 Nacos
改控制台 → 业务应用 会（临时） 写入客户端内存；重启后仍以 Nacos 为准，或下次 Nacos 发布后被覆盖

一句话：真源永远是 Nacos，不是控制台。
Nacos 改了会自动到应用，控制台打开规则页时通常也能查到；控制台改了不会进 Nacos。两边一起改容易互相覆盖，持久化启用后请统一在 Nacos 维护。

Dashboard 是否必须启动？

不必须。 只保证限流 / 熔断生效时，可以不启 Sentinel Dashboard：

  • sentinel-datasource-nacos 在应用启动时从 Nacos 拉规则并监听变更，与 Dashboard 无关

  • 不配 / 不启控制台时，流控、熔断照常工作

  • spring.cloud.sentinel.transport.dashboard 也可去掉或先注释掉

Dashboard 只是可选运维面板（实时 QPS、机器列表、簇点链路等）。需要临时看监控时再启一台，把 transport.dashboard 指过去即可；规则仍以 Nacos 为准。

% note tip %
若强依赖「控制台点几下就落库」，需二次开发 Dashboard（源码自带 Nacos 推拉示例，社区亦有改版包），本文不展开，优先 Nacos 直配。
% endnote %

2. 应用依赖

在已有 spring-cloud-starter-alibaba-sentinel 之外，再引入 Nacos 数据源（版本由 SCA BOM 管理）：

1
2
3
4
<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

不必单独声明 nacos-client 版本；与同体系 Nacos 3.0.3 对齐即可。若项目已引入 spring-cloud-starter-alibaba-nacos-discovery / config，账号密码等可复用。

3. application.yml 示例

在第三节配置基础上增加 datasource（可并存多种 rule-type，每种对应一个 Nacos DataId）。下面一次挂上常用五类，按需删减即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
server:
  port: 18082

spring:
  application:
    name: demo-provider
  cloud:
    sentinel:
      # 仅做监控时需要；纯 Nacos 规则持久化可不配 / 不启 Dashboard
      transport:
        dashboard: 127.0.0.1:8858
      eager: true
      datasource:
        flow:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            namespace:                   # 留空即 public；与 Nacos 控制台所选命名空间一致
            data-id: ${spring.application.name}-flow-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: flow
        degrade:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-degrade-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: degrade
        authority:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-authority-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: authority
        system:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-system-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: system
        param-flow:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-param-flow-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: param-flow

常用 rule-type 与文档对照（Nacos 中均为对应实体的 JSON 数组；下一节给出五类示例）：

rule-type 含义 字段说明（Wiki） 实体类（1.8.9 源码，属性名即 JSON key）
flow 流控 如何使用 · 流量控制 FlowRule
degrade 熔断降级 如何使用 · 熔断降级 DegradeRule
authority 来源黑白名单 如何使用 · 黑白名单控制 AuthorityRule
system 系统自适应保护 如何使用 · 系统自适应保护 SystemRule
param-flow 热点参数限流 热点参数限流 ParamFlowRule
gw-flow / gw-api-group 网关流控 / API 分组 网关限流 需配合 spring-cloud-alibaba-sentinel-gateway，示例从略

SCA 的 进阶指南 说明 datasource 怎么挂；字段有疑问时再对照上表 *Rule.java。

4. 在 Nacos 中创建规则配置

统一在 Nacos 控制台 → 配置管理 → 配置列表 新建，Group 均为 SENTINEL_GROUP，配置格式 为 JSON：

Data ID 对应 rule-type
demo-provider-flow-rules flow
demo-provider-degrade-rules degrade
demo-provider-authority-rules authority
demo-provider-system-rules system
demo-provider-param-flow-rules param-flow

4.1 流控 flow（demo-provider-flow-rules）

对资源 hello 限流 QPS = 2：

1
2
3
4
5
6
7
8
9
10
11
[
  {
    "resource": "hello",
    "limitApp": "default",
    "grade": 1,
    "count": 2,
    "strategy": 0,
    "controlBehavior": 0,
    "clusterMode": false
  }
]
字段 含义
resource 资源名，与 @SentinelResource("hello") 或 URL 资源一致
grade 1 = QPS，0 = 线程数
count 阈值
strategy 0 直接；1 关联；2 链路
controlBehavior 0 快速失败；1 预热；2 排队
clusterMode 单机流控保持 false

4.2 熔断 degrade（demo-provider-degrade-rules）

异常比例熔断（grade: 1，count 为 0~1）：

1
2
3
4
5
6
7
8
9
10
[
  {
    "resource": "hello",
    "grade": 1,
    "count": 0.5,
    "timeWindow": 10,
    "minRequestAmount": 5,
    "statIntervalMs": 1000
  }
]
字段 含义
grade 0 慢调用比例；1 异常比例；2 异常数
count 阈值（慢调用时表示最大 RT 毫秒；异常比例为 0~1）
timeWindow 熔断时长（秒）
minRequestAmount 熔断触发的最小请求数
statIntervalMs 统计窗口（毫秒）
slowRatioThreshold 仅 grade: 0 时使用，慢调用比例阈值

4.3 授权 authority（demo-provider-authority-rules）

仅允许来源 appA、appB 访问资源 hello（白名单，strategy: 0）：

1
2
3
4
5
6
7
[
  {
    "resource": "hello",
    "limitApp": "appA,appB",
    "strategy": 0
  }
]
字段 含义
limitApp 来源名，多个用英文逗号分隔
strategy 0 白名单；1 黑名单

% note tip %
授权规则依赖请求「来源」标识。Web 场景需实现 RequestOriginParser（解析 Header / 参数等为 origin），否则 limitApp 对不上，规则不按预期生效。
% endnote %

4.4 系统保护 system（demo-provider-system-rules）

入口级自适应保护（对全部入口生效，无单独 resource；未用到的指标保持 -1 表示不启用）：

1
2
3
4
5
6
7
8
9
[
  {
    "highestSystemLoad": 5.0,
    "highestCpuUsage": 0.8,
    "avgRt": 200,
    "maxThread": 100,
    "qps": 1000
  }
]
字段 含义
highestSystemLoad 系统 Load1 阈值（主要 Linux 有效）
highestCpuUsage CPU 使用率阈值，范围 [0, 1]
avgRt 所有入口平均 RT 阈值（毫秒）
maxThread 入口最大并发线程数
qps 所有入口总 QPS 阈值

4.5 热点参数 param-flow（demo-provider-param-flow-rules）

对资源 hello 的第 0 个参数默认 QPS = 5；参数值 1001 单独放开到 QPS = 10：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "resource": "hello",
    "grade": 1,
    "paramIdx": 0,
    "count": 5,
    "controlBehavior": 0,
    "durationInSec": 1,
    "clusterMode": false,
    "paramFlowItemList": [
      {
        "object": "1001",
        "classType": "int",
        "count": 10
      }
    ]
  }
]
字段 含义
paramIdx 热点参数在 args 中的下标，从 0 起
count 该参数维度的默认阈值
grade 1 = QPS，0 = 线程数
paramFlowItemList 例外项：某具体参数值使用单独阈值
object / classType 例外参数值及其类型（如 int、long、java.lang.String）

% note tip %
热点规则必须把参数传入 Sentinel 埋点，例如 SphU.entry("hello", EntryType.IN, 1, userId)，paramIdx: 0 即对应第一个 args。仅写 @SentinelResource("hello")、调用时不传参，热点规则不会按参数生效。
% endnote %

5. 验证步骤

步骤 操作 预期
1 发布 Nacos 配置后启动（或已启动）应用 日志无 datasource 加载失败；可压测 /hello 被限流（无需 Dashboard）
2 （可选）打开 Sentinel Dashboard 可见应用与资源；规则列表可能因数据源来源显示为「动态规则」侧生效
3 修改 Nacos 中 count 并发布 客户端秒级感知（监听推送），无需重启
4 重启应用（任意是否启 Dashboard） 规则仍从 Nacos 加载，限流行为不变

若同时在 Dashboard 里手改规则 又在 Nacos 里改规则，客户端终态以最后一次写入内存的规则为准，容易踩坑。持久化启用后，请统一在 Nacos 维护。

6. 可选：Dashboard 侧双向推送（源码改造）

开箱 Dashboard 不会把控制台改动写回 Nacos。下文 6.2～6.4 按推荐路线介绍 Dashboard 侧改造（V2 + Nacos Provider/Publisher）；若在网上看到「客户端 WritableDataSource 反写 Nacos」的做法，见本章末尾 6.5 作对照了解即可。

官方在 1.8.9 源码里只放了一套 流控规则 的 Dashboard 改造示例（不是完整生产方案），且位于 src/test，发布包 JAR 里看不到。

6.1 代码到底在哪（为何在仓库里不好找）

克隆并切到 tag 后路径为（浏览器可直接打开）：

文件 GitHub 路径（tag 1.8.9）
DataId / Group 常量 .../rule/nacos/NacosConfigUtil.java
Nacos ConfigService Bean .../rule/nacos/NacosConfig.java
从 Nacos 拉流控 .../rule/nacos/FlowRuleNacosProvider.java
写回流控到 Nacos .../rule/nacos/FlowRuleNacosPublisher.java

对应本地目录：

1
2
3
4
5
sentinel-dashboard/src/test/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/
├── NacosConfig.java
├── NacosConfigUtil.java
├── FlowRuleNacosProvider.java
└── FlowRuleNacosPublisher.java

找不到时常见原因：

  1. 只下了 sentinel-dashboard-1.8.9.jar（不含 src/test）

  2. 在 src/main 里搜（示例默认不在 main）

  3. 看了错误分支 / 未切到 1.8.9

  4. 以为还有 degrade / authority 等示例——没有；官方 test 样例 只有 flow，其它规则类型需自行照抄扩展

官方样例约定与本文一致性较好：

  • Group：SENTINEL_GROUP（见 NacosConfigUtil.GROUP_ID）

  • DataId：{app}-flow-rules（见 FLOW_DATA_ID_POSTFIX = "-flow-rules"），与上文 demo-provider-flow-rules 一致

6.2 改造步骤（以流控双向同步为例）

1
2
3
4
git clone https://github.com/alibaba/Sentinel.git
cd Sentinel
git checkout 1.8.9
cd sentinel-dashboard

步骤 1：放开 Nacos 依赖（去掉 test scope）

编辑 sentinel-dashboard/pom.xml，将：

1
2
3
4
5
<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
  <scope>test</scope>
</dependency>

改为（删除 <scope>test</scope>，必要时升到与 Nacos 3.x 兼容的客户端版本）：

1
2
3
4
<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

步骤 2：把 test 样例拷到 main

1
2
3
mkdir -p src/main/java/com/alibaba/csp/sentinel/dashboard/rule/nacos
cp src/test/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/*.java \
   src/main/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/

步骤 3：改 NacosConfig，接上 Nacos 3.x 地址与鉴权

官方默认是 ConfigFactory.createConfigService("localhost")，对 Nacos 3.x（含鉴权、端口 8848）不够用。建议改成可配置，例如：

1
2
3
4
5
6
7
8
9
@Bean
public ConfigService nacosConfigService() throws Exception {
    Properties properties = new Properties();
    properties.put("serverAddr", "127.0.0.1:8848");
    properties.put("namespace", "");          // public 留空；其它命名空间填 namespaceId
    properties.put("username", "nacos");
    properties.put("password", "YourStrongPassword");
    return ConfigFactory.createConfigService(properties);
}

（也可用 application.properties + @Value 注入，避免把密码写死在代码里。）

步骤 4（建议）：发布时转成客户端可直接消费的 FlowRule JSON

官方 encoder 直接 JSON.toJSONString(List<FlowRuleEntity>)，会带上 app / gmtCreate 等控制台字段。客户端 rule-type: flow 一般能忽略多余字段，但更干净的做法是发布前 toRule()：

1
2
3
4
5
6
@Bean
public Converter<List<FlowRuleEntity>, String> flowRuleEntityEncoder() {
    return list -> JSON.toJSONString(
        list.stream().map(FlowRuleEntity::toRule).collect(Collectors.toList())
    );
}

decoder 仍可 JSON.parseArray(s, FlowRuleEntity.class)（字段重合部分能填上；打开规则页时 Controller 还会补 app）。

步骤 5：让 FlowControllerV2 使用 Nacos 的 Provider / Publisher

编辑 com.alibaba.csp.sentinel.dashboard.controller.v2.FlowControllerV2.java。该类通过 @Qualifier 注入规则读写 Bean；默认走内存实现，需 只改两个 Qualifier 名，指向步骤 2 拷到 main 的 Nacos 实现（@Component("flowRuleNacosProvider") / @Component("flowRuleNacosPublisher")）：

修改前（默认，读写内存，不写 Nacos）：

1
2
3
4
5
6
@Autowired
@Qualifier("flowRuleDefaultProvider")
private DynamicRuleProvider<List<FlowRuleEntity>> ruleProvider;
@Autowired
@Qualifier("flowRuleDefaultPublisher")
private DynamicRulePublisher<List<FlowRuleEntity>> rulePublisher;

修改后（读写 Nacos）——仅替换 Qualifier 中的 Bean 名：

1
2
3
4
5
6
@Autowired
@Qualifier("flowRuleNacosProvider")      // default → nacos
private DynamicRuleProvider<List<FlowRuleEntity>> ruleProvider;
@Autowired
@Qualifier("flowRuleNacosPublisher")     // default → nacos
private DynamicRulePublisher<List<FlowRuleEntity>> rulePublisher;

即：flowRuleDefaultProvider → flowRuleNacosProvider，flowRuleDefaultPublisher → flowRuleNacosPublisher。字段类型与其它代码不用动。

必须走 V2 接口（/v2/flow/**）。V1（/v1/flow/**）仍是推客户端内存，改完 Provider 也不写 Nacos。

步骤 6：前端菜单切到 V2 流控页

1.8.9 默认侧边栏「流控规则」指向 V1：

1
2
<!-- sidebar.html -->
<a ui-sref="dashboard.flowV1({app: entry.app})">流控规则</a>

改为（注意：V2 的 state 名是 dashboard.flow，URL 为 /v2/flow/:app）：

1
<a ui-sref="dashboard.flow({app: entry.app})">流控规则</a>

文件：src/main/webapp/resources/app/scripts/directives/sidebar/sidebar.html。

簇点链路里「加流控」走的是 identity.js + FlowServiceV1，同样要改：

  • FlowServiceV1 → FlowServiceV2

  • 跳转路径 /dashboard/flow/ → /dashboard/v2/flow/

文件：src/main/webapp/resources/app/scripts/controllers/identity.js。

步骤 7：打包替换官方 JAR

1
2
3
4
# 在仓库根目录或 dashboard 模块按官方方式打包
mvn -pl sentinel-dashboard -am clean package -DskipTests
# 产物一般在 sentinel-dashboard/target/sentinel-dashboard.jar
java -Dserver.port=8858 -jar target/sentinel-dashboard.jar

6.3 改造后如何验证

步骤 预期
控制台打开应用 →「流控规则」（V2）新增规则并保存 Nacos 出现 / 更新 demo-provider-flow-rules（Group=SENTINEL_GROUP）
应用已配置 rule-type: flow 数据源 客户端自动收到新规则并限流
在 Nacos 改 count 后刷新控制台 V2 流控页 能读到最新配置

6.4 能力边界

  • 官方样例 只覆盖 flow；熔断 / 授权 / 系统 / 热点需自行增加成对的 Provider/Publisher，并改对应 Controller（它们默认也不是 V2 + DynamicRule 模式）。

  • 运维成本明显高于「应用直连 Nacos、控制台只做监控」。中小型环境通常 不必 做本节改造。

7. 附录：客户端 WritableDataSource 写回 Nacos（了解即可）

网上另一种常见做法是 不改 Dashboard，而在客户端注册 写数据源：Dashboard（默认 V1）把规则推到客户端内存后，Sentinel transport 模块回调 WritableDataSource.write()，由客户端把规则 反写 到 Nacos。

1
2
3
4
5
6
7
Dashboard（V1 默认）
    │  API 推送到客户端内存
    ▼
WritableDataSource.write()  →  Nacos publishConfig
    ▲
    │  Nacos 监听（spring.cloud.sentinel.datasource）
客户端内存 ←────────────────┘

官方 FileDataSourceInit 演示的就是这个钩子——只不过写的是 本地文件，不是 Nacos：

1
2
3
4
5
6
7
// 读：注册到 RuleManager（Push 模式常规做法）
ReadableDataSource<String, List<FlowRule>> ds = new NacosDataSource<>(serverAddr, groupId, dataId, parser);
FlowRuleManager.register2Property(ds.getProperty());

// 写：Dashboard 推送后回调；社区常自实现 NacosWritableDataSource
WritableDataSource<List<FlowRule>> wds = new NacosWritableDataSource<>(serverAddr, groupId, dataId, JSON::toJSONString);
WritableDataSourceRegistry.registerFlowDataSource(wds);

注意：sentinel-datasource-nacos 1.8.9 官方只有 NacosDataSource（只读），没有 NacosWritableDataSource；网上教程里的写 Nacos 实现多为 社区自写（在 write() 里调 configService.publishConfig()），或通过 InitFunc / @PostConstruct 注册到 WritableDataSourceRegistry。

与上文 6.2 Dashboard 改造 对比：

客户端 WritableDataSource 反写 Dashboard V2 + Nacos Provider/Publisher
改动范围 每个业务应用 只改 Dashboard
能否用默认 V1 控制台 能 需切 V2 页面 + 改后端
官方 Push 模式态度 不推荐 客户端反写配置中心 推荐
规则维度 V1 按 机器（ip:port）推送 V2 按 应用（app）读写
多实例 每台实例各写一次 Nacos，易覆盖/冲突 Dashboard 统一写一份 {app}-flow-rules

官方 在生产环境中使用 Sentinel 明确：Push 模式正确链路是 控制台 → 配置中心 → 客户端读数据源 → 内存，而不是客户端收到 Dashboard 推送后再写 Nacos（客户端已监听同一 DataId 时，可能 重复更新；多实例还会 争抢写）。WritableDataSourceRegistry 的设计场景是 Pull 模式 + 本地文件 持久化。

适用场景：单机联调、不想改 Dashboard 源码 时可了解此路；生产多实例仍建议走 6.2 Dashboard 改造，或更简单——只在 Nacos 维护规则（上文第五节 Push 模式），Dashboard 仅做监控。

六、联调检查清单

检查项 预期结果
Nacos 规则配置 对应 DataId / Group 已发布且 JSON 合法
规则持久化 / 生效 改 Nacos 后限流生效；重启应用后仍在（可不启 Dashboard）
Sentinel Dashboard（可选） 若已启动：http://127.0.0.1:8858 可登录；触发流量后可见应用
客户端版本 sentinel 1.8.9（由 SCA BOM 引入）

常见问题：

  1. 控制台无应用：需真实流量触发一次资源；检查 spring.cloud.sentinel.transport.dashboard 指向与 Dashboard 实际端口一致。

  2. 端口冲突：与 Nacos 3.x 同机时，勿再占用 8080；本文默认使用 8858。

  3. Nacos 规则不生效：核对 data-id / group-id / namespace / 账号密码；rule-type 与配置内容类型一致；看应用日志是否有 datasource 转换失败。

  4. 控制台改了规则，重启又没了：未接 Nacos，或未把 Dashboard 改成写回 Nacos；请以 Nacos 为准。

  5. 版本混用：按 SCA 官方矩阵固定 Sentinel 1.8.9 最省事。

七、参考链接