Sentinel：超详细部署与使用教程

Sentinel 是阿里巴巴开源的面向微服务架构的流量防卫组件，以「流量」为切入点，覆盖限流、流量整形、并发隔离、熔断降级、系统自适应过载保护等领域，是 Spring Cloud Alibaba 生态中与 Hystrix 对标并成为主流的容错组件。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

随着分布式系统的普及，服务间调用的稳定性变得至关重要。Sentinel 以「流量」为切入点，围绕流量控制、流量整形、并发数限制、熔断降级与系统自适应过载保护展开，为微服务提供可靠性与弹性保护。Sentinel 源自阿里巴巴内部，在过去十年的双 11 大促中支撑了几乎全部核心场景——秒杀类突发流量限流、消息削峰填谷、不可靠下游服务熔断、集群限流等，2018 年正式开源后迅速成为 Spring Cloud Alibaba 生态的标配容错组件。

与 Hystrix 相比，Sentinel 的特点是：以资源为中心（Java 方法、HTTP 接口、SQL 等都可以被定义为资源）、规则维度丰富（QPS / 线程数 / 异常比例 / 异常数 / 系统 Load / 热点参数）、有实时监控控制台，并且支持通过 Nacos / Apollo / ZooKeeper 等配置中心持久化和动态推送规则。

1.2 核心功能

• 流量控制（Flow Control）：以资源为单位，按 QPS 或并发线程数限制访问量，支持直接拒绝、Warm Up（冷启动）、匀速排队（排队等待）三种流控效果。
• 熔断降级（Degrade）：当调用链路中某个资源出现不稳定（异常比例、异常数或慢调用比例超过阈值）时，对该资源调用进行熔断，在一段时间内直接快速失败，防止级联故障。
• 系统自适应保护（System Adaptive Protection）：从整体维度（Load1、CPU 使用率、入口 QPS、平均 RT）监控应用，当系统达到预估的高水位时进行限流，保证整体容量不被打垮。
• 热点参数限流（Param Flow Control）：针对热点参数（如商品 ID、用户 ID）做维度限流，例如限制同一个商品 ID 的下单 QPS。
• 集群限流（Cluster Flow Control）：分布式集群统一计数限流，解决单机限流配额不精准的问题。
• 来源访问控制（Authority）：根据调用来源（origin）进行黑白名单控制。
• 实时监控与控制台：单机实时监控，500 台以下规模的集群聚合监控；提供 Sentinel Dashboard 可视化管理。
• 生态集成：开箱即用支持 Spring Cloud、Apache Dubbo、gRPC、Quarkus、Spring WebFlux、Reactor 等框架；多语言支持 Java、Go（sentinel-golang）、C++、Rust；并通过 OpenSergo 规范参与服务网格流量治理标准建设。

1.3 技术架构

下图是 Sentinel 官方给出的功能全景：顶部是 Sentinel Dashboard（实时监控、机器发现、规则管理）；中部是 Sentinel 核心能力矩阵（流量整形、并发隔离、系统自适应保护、调用链、限流、集群限流、熔断、实时指标、热点参数、削峰、来源控制等）；右侧是各开源框架集成（Spring Cloud、gRPC、Apache Dubbo、Reactive、Service Mesh）；底部是动态规则配置中心（ZooKeeper、Redis、Nacos、Apollo）。

工作原理上，应用通过 Sentinel 定义「资源」（SphU.entry("resourceName")），运行时各类规则（FlowRule、DegradeRule、SystemRule、ParamFlowRule）在资源入口处生效统计与拦截；客户端通过 sentinel-transport-simple-http 模块向 Dashboard 上报心跳与指标，Dashboard 支持在线编辑规则并推送回客户端。

二、环境要求

注意：Sentinel 客户端的规则默认保存在内存中，应用重启后丢失；生产环境必须接入动态规则数据源（Nacos / Apollo / ZooKeeper / Redis 等），详见官方 Wiki「Dynamic Rule Configuration」。

三、部署方式

Sentinel 的部署分两部分：① 服务端组件 = Sentinel Dashboard 控制台（独立 JAR）；② 客户端集成 = 在业务应用中引入 SDK 依赖。下面给出三种部署/集成路径：Dashboard JAR 直接启动（最快上手）→ 源码编译 Dashboard → Spring Boot 应用集成客户端并接入 Nacos 规则持久化。

3.1 方式一：下载 Dashboard JAR 直接启动（最快上手）

步骤 1：下载 Dashboard JAR

从官方 Release 页下载：github.com/alibaba/Sentinel/releases，最新版本为 1.8.10，附件名为 sentinel-dashboard-1.8.10.jar（以实际 release 资产为准）。

cd /opt
wget https://github.com/alibaba/Sentinel/releases/download/1.8.10/sentinel-dashboard-1.8.10.jar

若 GitHub 下载慢，可使用加速镜像或从 Maven 中央仓库搜索 sentinel-dashboard 对应版本下载。

步骤 2：启动 Dashboard

按官方 Wiki 给出的标准启动命令：

java -Dserver.port=8080 \
     -Dcsp.sentinel.dashboard.server=localhost:8080 \
     -Dproject.name=sentinel-dashboard \
     -jar sentinel-dashboard-1.8.10.jar

参数说明：

后台常驻运行可加 nohup ... &，或使用 systemd 托管。

步骤 3：登录控制台

浏览器访问 http://<服务器IP>:8080。1.6.0+ 版本默认开启登录鉴权，默认账号密码为 sentinel / sentinel（可通过 -Dsentinel.dashboard.auth.username=xxx -Dsentinel.dashboard.auth.password=xxx 覆盖，以官方文档为准）。

3.2 方式二：源码编译 Dashboard

需要 JDK 8+ 与 Maven 3.x：

git clone https://github.com/alibaba/Sentinel.git
cd Sentinel/sentinel-dashboard
mvn clean package -DskipTests
# 产物：sentinel-dashboard/target/sentinel-dashboard.jar
java -Dserver.port=8080 -jar target/sentinel-dashboard.jar

英文界面版历史上在 dashboard/en 分支构建（以官方仓库说明为准）。

3.3 方式三：业务应用集成客户端 + Nacos 规则持久化（生产推荐）

步骤 1：引入核心依赖

纯 Java 应用（官方 README Quick Start）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.8.10</version>
</dependency>

需要接入 Dashboard 的应用还需引入 transport 模块（官方 Wiki 要求）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>1.8.10</version>
</dependency>

Spring Boot 应用推荐直接使用 Spring Cloud Alibaba 适配（版本对应关系以 Spring Cloud Alibaba 官方文档为准）：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    <!-- 版本以 Spring Cloud Alibaba BOM 为准 -->
</dependency>

步骤 2：配置 Dashboard 地址

启动应用时通过 JVM 参数指定 Dashboard 地址：

java -Dcsp.sentinel.dashboard.server=127.0.0.1:8080 \
     -Dproject.name=my-demo-app \
     -jar my-demo-app.jar

Spring Boot 应用也可在 application.yml 中配置：

spring:
  cloud:
    sentinel:
      transport:
        dashboard: 127.0.0.1:8080
        # 客户端与 Dashboard 通信的端口（默认 8719，被占用时自动 +1 递增）
        port: 8719

步骤 3：验证上报

首次访问应用的任意接口后，Sentinel 才会初始化并向 Dashboard 上报（懒加载机制）。登录 Dashboard，左侧「机器列表」应出现 my-demo-app 及其机器 IP，「实时监控」中可见入口流量曲线。

步骤 4：接入 Nacos 持久化规则（生产必做）

Dashboard 页面上点击「流控规则」新增的规则默认只存在内存中，重启即丢。生产环境应使用 Nacos 作为规则数据源（官方 Wiki「Dynamic Rule Configuration」给出的标准做法）：

<!-- 额外引入数据源适配 -->
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-nacos</artifactId>
    <version>1.8.10</version>
</dependency>

示例代码（注册 Nacos 数据源，从 Nacos 拉取流控规则并监听变更）：

ReadableDataSource<String, List<FlowRule>> ds = new NacosDataSource<>(
    "127.0.0.1:8848",          // Nacos 地址
    "SENTINEL_GROUP",          // groupId
    "sentinel-flow-rules",      // dataId
    source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {})
);
FlowRuleManager.register2Property(ds.getProperty());

在 Nacos 中维护对应 dataId 的规则 JSON，规则即可实时推送到所有应用节点，重启不丢失。

3.4 验证部署成功（通用）

1. Dashboard 启动日志无报错，浏览器 http://<IP>:8080 可用 sentinel/sentinel 登录；
2. 业务应用首次调用接口后，Dashboard「机器列表」出现该应用节点；
3. 新增一条流控规则（如资源 HelloWorld QPS=20），用压测工具（如 ab）压测时超过阈值的请求被拦截，应用日志 ~/logs/csp/${appName}-metrics.log.xxx 中 block 列增长。

3.5 关键配置说明

四、使用方法

4.1 基础用法：定义资源与规则（官方 Quick Start）

第一步引入依赖后，用 Sentinel API 包裹业务代码：

import com.alibaba.csp.sentinel.Entry;
import com.alibaba.csp.sentinel.SphU;
import com.alibaba.csp.sentinel.slots.block.BlockException;

public class SentinelDemo {
    public static void main(String[] args) {
        try (Entry entry = SphU.entry("HelloWorld")) {
            // 你的业务逻辑
            System.out.println("hello world");
        } catch (BlockException e) {
            // 被限流/熔断的处理：快速失败、降级提示
            e.printStackTrace();
        }
    }
}

第二步定义规则（示例：资源 HelloWorld 每秒最多通过 20 次）：

import com.alibaba.csp.sentinel.slots.block.RuleConstant;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRule;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRuleManager;

import java.util.ArrayList;
import java.util.List;

List<FlowRule> rules = new ArrayList<>();
FlowRule rule = new FlowRule();
rule.setResource("HelloWorld");
rule.setCount(20);                              // 阈值 20
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);     // 按 QPS 限流
rules.add(rule);
FlowRuleManager.loadRules(rules);

4.2 常用命令/API

注解方式定义资源（Spring 应用常用）

引入 sentinel-annotation-aspectj 后直接注解：

@SentinelResource(value = "queryOrder", blockHandler = "handleBlock", fallback = "handleFallback")
public Order queryOrder(Long orderId) {
    return orderService.selectById(orderId);
}

// 被限流/熔断时的降级方法（签名需与原方法匹配，额外加 BlockException 参数）
public Order handleBlock(Long orderId, BlockException ex) {
    return Order.defaultOrder();
}

查看实时监控日志

按官方 README，运行后指标记录在 ~/logs/csp/${appName}-metrics.log.{日期}：

|--timestamp-|------date time----|-resource-|p |block|s |e|rt  |occupied
1529998905000|2018-06-26 15:41:45|HelloWorld|20|5579 |20|0|728 |0

字段含义：p=入口请求数，block=被规则拦截数，s=成功处理数，e=异常数，rt=平均响应时间(ms)，occupied=预占请求数。

熔断降级规则示例

DegradeRule degradeRule = new DegradeRule();
degradeRule.setResource("queryOrder");
degradeRule.setGrade(CircuitBreakerStrategySLOW_REQUEST_RATIO.getType()); // 慢调用比例
degradeRule.setCount(500);        // 慢调用阈值 500ms
degradeRule.setSlowRatioThreshold(0.5);
degradeRule.setMinRequestAmount(5);
degradeRule.setStatIntervalMs(10000);
DegradeRuleManager.loadRules(Collections.singletonList(degradeRule));

Dashboard 管理规则（HTTP 方式）

Dashboard 页面可直接新增/编辑流控、降级、热点、系统、来源规则；也可通过客户端暴露的 HTTP API 查规则，详见官方 Wiki「How to Use → HTTP commands for rules」。

4.3 进阶功能

• 热点参数限流：对 @SentinelResource 方法的入参做限流，例如 paramFlowItem 指定某个商品 ID 的特殊阈值。
• 集群限流：部署 Token Server（独立应用），各节点作为 Token Client 向其申请配额，实现全集群统一 QPS 上限。
• 系统自适应保护：按 Load1 / CPU / 入口 QPS 整体维度限流，适合大促前整体压舱。
• 规则持久化三模式：原始模式（Dashboard 推内存）、拉模式（客户端定时拉配置中心）、推模式（监听配置中心变更），生产一律用推模式。
• 多语言生态：Go 版 sentinel-golang、C++ 版、Rust 版可用于非 Java 服务。

4.4 适用场景

• 秒杀/抢券类突发流量：按资源 QPS 限流保护后端；
• 不可靠下游服务：配置异常比例/慢调用比例熔断，防止级联雪崩；
• 消息队列消费削峰：匀速排队流控效果；
• 热点数据防护：热点参数维度限流；
• 大促整体容量保护：系统自适应规则；
• Spring Cloud / Dubbo 微服务统一容错治理。

五、常见问题排查（FAQ）

Q1：Dashboard 登录页进不去，或应用上报后控制台看不到任何应用 - 原因：① Dashboard 未启动或 8080 端口被占用；② 应用没有发过任何请求（Sentinel 懒加载，首次请求才初始化）；③ 客户端未配置 -Dcsp.sentinel.dashboard.server。 - 解决：确认 Dashboard 可访问；先用 curl/浏览器访问一次业务接口；检查启动参数与 spring.cloud.sentinel.transport.dashboard 配置。

Q2：Dashboard「机器列表」有机器，但「实时监控/簇点链路」为空 - 原因：尚未访问任何被 Sentinel 定义的资源；或资源访问未经过 Sentinel 规则链。 - 解决：访问对应接口后等待 1~2 秒；确认资源被 SphU.entry 或 @SentinelResource 定义。

Q3：Dashboard 新增规则后，应用重启规则丢失 - 原因：规则默认存内存，这是设计行为，不是 bug。 - 解决：接入 Nacos / Apollo / ZooKeeper 等动态规则数据源（见 3.3 步骤 4），规则以配置中心为准。

Q4：应用启动报 Ignoring BailOutReason 或连接 Dashboard 超时 - 原因：客户端与 Dashboard 通信端口（默认 8719）被占用，或网络不通。 - 解决：在启动日志 record.log / metricStat.log.pid<pid>.<日期> 中定位；通过 -Dcsp.sentinel.api.port 指定空闲端口，或放行防火墙。

Q5：被限流后返回的是默认 BlockException，前端体验差 - 解决：使用 @SentinelResource 的 blockHandler / fallback 属性自定义降级返回（如返回友好提示或兜底数据），不要直接抛异常给调用方。

Q6：block 计数很高但业务量没涨多少 - 原因：规则阈值配置过低，或流控效果配置成了「匀速排队」但超时设置不合理。 - 解决：先看监控中真实通过 QPS，再合理调整阈值；区分「直接拒绝」与「排队等待」的使用场景。

Q7：Dashboard 监控数据只保留 5 分钟 - 原因：Dashboard 内存监控窗口默认 5 分钟。 - 解决：历史指标需自行持久化——参考官方 Wiki「Metrics → History Resource Metrics」，将客户端 metrics 日志落库。

六、部署注意事项与最佳实践

1. 生产必须持久化规则：Dashboard 页面规则不落地，接入 Nacos/Apollo，规则以配置中心为唯一事实源。
2. 修改默认登录凭据：生产环境 -Dsentinel.dashboard.auth.username/password 修改 sentinel/sentinel 默认账号，Dashboard 不暴露公网，只在内网/VPN 开放。
3. 端口规划：Dashboard 8080；客户端通信端口 8719（被占用自动递增，注意观察日志确认实际端口）。
4. 阈值先测后调：先在压测环境摸清单机真实容量，再配置 QPS/RT 阈值，避免拍脑袋。
5. 熔断与限流组合使用：入口限流 + 下游熔断，二者互补；核心链路配置系统自适应规则做兜底。
6. 关注日志目录：客户端 ~/logs/csp/ 下有 record.log、metricStat、block 等日志，排查问题先看这里。
7. 版本对齐：客户端 sentinel-core、sentinel-transport-simple-http、Dashboard 尽量保持同一大版本（如均为 1.8.x）。
8. 集群限流谨慎用：Token Server 本身是关键节点，需高可用部署，否则成为新的单点。

七、参考资料

• GitHub 仓库：https://github.com/alibaba/Sentinel
• 官方文档（中文）：https://sentinelguard.io/zh-cn/docs/introduction.html
• 官方 Wiki（含 Dashboard、动态规则配置、日志说明）：https://github.com/alibaba/Sentinel/wiki
• Dashboard 使用说明：https://github.com/alibaba/Sentinel/wiki/Dashboard
• 快速开始（How To Use）：https://sentinelguard.io/zh-cn/docs/basic-api-resource-rule.html
• 工作原理（How It Works）：https://sentinelguard.io/zh-cn/docs/basic-implementation.html
• Release 下载：https://github.com/alibaba/Sentinel/releases
• Spring Cloud Alibaba Sentinel 集成：https://github.com/alibaba/spring-cloud-alibaba
• Go 多语言版：https://github.com/alibaba/sentinel-golang
• OpenSergo 流量治理规范：https://opensergo.io/