Sentinel Dashboard：客户端保护、规则发布与运行维护
Sentinel 在应用内部对受保护的资源执行限流、并发控制和熔断。一次请求是否放行，由当前实例里的规则与统计状态决定。Dashboard 用来查看实例、资源和指标，并管理规则；普通业务请求不经过 Dashboard。
部署时先把这三件事分开：应用有没有定义资源，客户端加载了什么规则，规则从哪里保存和发布。控制台页面能打开，只完成了管理入口这一部分。
资源、统计和规则怎样参与请求
一个资源对应哪段工作
资源可以是一段 Java 方法、HTTP 路由、RPC 调用或访问下游的操作。名称应稳定，例如 orders 或 payment-call；把订单号直接拼入资源名，会产生大量不同的统计对象，也难以用一条规则覆盖。
HTTP /orders
└─ SphU.entry("orders")
├─ 被规则拒绝 → BlockException → 由应用转换为 429 等响应
└─ 放行 → 执行业务 → 记录耗时/异常 → entry.exit()
Dashboard ← 心跳、指标与管理通信 → 客户端管理端口
业务请求 ────────────────────→ 应用业务端口Sentinel API 不预先规定 HTTP 返回体。限流时返回什么状态码、是否带重试提示、哪些降级结果可以被调用方接受，由接口契约决定。熔断下游后若返回旧缓存，也应让调用方知道数据的新鲜度。资源与基本 API 见 How to Use。
QPS 与并发数处理不同负载
QPS 限流控制单位时间内进入资源的请求数量；并发控制限制同时执行这段资源的线程数。下游变慢后，即使 QPS 没有增加，请求也会占用更久，活跃线程和连接可能逐渐耗尽，因此两种限制常常需要一起考虑。
默认单机规则作用于每个实例。三个实例各自配置 QPS=100，整体上限会受流量分布影响，不能解释成服务总共只允许 100。扩缩容之后也要重新看资源预算。
流控的直接模式判断当前资源；关联模式根据另一个资源的负载限制当前资源；链路模式按指定调用入口区分同名资源。链路模式需要实际调用上下文支持，不能只在控制台填写入口名。快速失败、Warm Up 和匀速排队分别处理直接拒绝、冷启动流量爬升和流量整形，具体参数见 Flow Control。
排队会增加请求等待时间，应给等待上限，并与 HTTP、数据库和上游超时匹配。下游已经完全不可用时，继续把请求排进更长的队列通常只会扩大积压。
启动控制台并验证真实限流
版本、文件和身份
使用 Linux、Bash、Docker Engine、Compose v2、OpenSSL、curl 7.76 或更新版本。下载 控制组件实验源码，解压后进入 control-lab。若已经在该目录做过其他实验，保留已有 .env。
固定 Sentinel Core、Transport 和 Dashboard 为 1.8.10，发行文件从 官方 Release获取。客户端源码目标 Java 17，构建用 Maven 3.9.12/JDK 25，运行客户端用 JRE 25，Dashboard 使用固定 JDK 17。不同组件的运行时分别记录，不用单一的“Java 版本”掩盖差异。
bash prepare.sh
mkdir -p .m2 dashboard
curl -q --fail --location --connect-timeout 10 --max-time 180 \
https://github.com/alibaba/Sentinel/releases/download/1.8.10/sentinel-dashboard-1.8.10.jar \
--output dashboard/sentinel-dashboard.jar
sha256sum dashboard/sentinel-dashboard.jar
docker run --rm --user "$(id -u):$(id -g)" \
-e MAVEN_CONFIG=/tmp/.m2 \
-v "$PWD:/work" -v "$PWD/.m2:/m2" -w /work \
maven:3.9.12-eclipse-temurin-25 \
mvn -B -ntp -Dmaven.repo.local=/m2 -Duser.home=/tmp \
-pl sentinel-client -am package
docker compose up -d dashboard sentinel-app
docker compose logs --tail 40 dashboard sentinel-app下载后记录本地 SHA-256，离线交付时和已审核的制品清单比对；现场计算一个摘要本身不提供来源认证。首次下载使用官方 HTTPS 发布入口，并遵守团队制品校验流程。
构建容器以宿主 UID/GID 运行，Maven 缓存可写。应用和 Dashboard 都使用 UID 10001、只读根文件系统和可写临时目录。宿主操作者需要 Docker 权限；镜像构建和运行权限不能混为一谈。
Compose 在回环地址发布业务端口 18082、控制台端口 18881。客户端管理端口 8719 只在实验 Docker 网络内开放。控制台账号为 operator，随机密码从 .env 的 SENTINEL_PASSWORD 读取，启动时映射到 Dashboard 的认证配置，不使用默认公开凭据。
资源代码与启动规则
示例依赖 sentinel-core 和 sentinel-transport-simple-http。启动时读取 sentinel-client/qps 文件，默认内容为 2，校验范围 1～100，然后加载对应流控规则：
FlowRule rule = new FlowRule("orders");
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
rule.setCount(count);
rule.setLimitApp("default");
FlowRuleManager.loadRules(List.of(rule));这个文件只在启动时读取，不会自动监视修改。非法值会让应用启动失败，避免带着缺失规则对外服务。HTTP 处理器中的关键顺序为：
Entry entry = null;
try {
entry = SphU.entry("orders", EntryType.IN);
body = "accepted=" + accepted.incrementAndGet();
} catch (BlockException blocked) {
status = 429;
body = "blocked";
} catch (Exception failure) {
Tracer.trace(failure);
status = 500;
body = "failed";
} finally {
if (entry != null) entry.exit();
}计数器位于 entry 成功之后，被拒绝的请求不会增加它。这里用简单计数隔离流控行为，没有把返回 accepted 包装成真实订单提交。业务异常在 exit 前统计，BlockException 则单独处理，不混入下游业务失败比例。
对照放行与拒绝
先访问一次资源触发客户端初始化：
curl -q --noproxy '*' --fail-with-body \
--connect-timeout 2 --max-time 10 \
http://127.0.0.1:18082/orders预期得到 accepted 计数。随后连续请求，统计状态码。由于 429 是预期结果，这个循环不使用 --fail-with-body，但会拒绝传输错误和其他状态：
accepted=0
blocked=0
for i in $(seq 1 30); do
code=$(curl -q --noproxy '*' --silent --show-error \
--connect-timeout 2 --max-time 10 \
-o /dev/null -w '%{http_code}' http://127.0.0.1:18082/orders) || break
case "$code" in
200) accepted=$((accepted + 1));;
429) blocked=$((blocked + 1));;
*) printf 'unexpected HTTP %s\n' "$code"; break;;
esac
done
printf 'accepted=%s blocked=%s\n' "$accepted" "$blocked"
test "$((accepted + blocked))" -eq 30
test "$accepted" -gt 0 && test "$blocked" -gt 0快速执行时应同时出现 200 和 429；放行数量受统计窗口、执行速度和已有请求影响，不要把它写成永远恰好等于 2。若客户端本身发送得很慢，先确认请求速率确实超过阈值。
检查控制台的双向通信
浏览器打开宿主回环 18881，登录后查看 ops4-orders。第一次资源调用之后等待心跳出现，机器列表应显示容器 IP 与管理端口 8719，簇点链路中应出现 orders。
客户端使用 csp.sentinel.dashboard.server=dashboard:8080 发送心跳。Dashboard 随后要反向连接客户端上报的 IP:8719，查询资源和推送规则。跨 NAT 时尤其要检查上报地址；1.8.10 的心跳接口要求 IP 字面值，不能把 Docker 服务名直接填进 csp.sentinel.heartbeat.client.ip。同网络实验采用自动检测的容器 IP。协议与校验见 Dashboard 文档及 心跳接口实现。
在流控规则页将 orders 阈值临时改为 5，再发送同样请求，观察客户端规则和放行数量变化。修改的是运行中客户端内存，下一节会处理它的持久化问题。先验证控制台退出对现有保护的影响：
docker compose stop dashboard
# 再执行上面的状态码统计循环
docker compose start dashboard客户端仍应执行已加载规则。控制台停机影响管理和观测，普通单机流控不会因此停止；采用额外的集群令牌服务时，还要单独判断那个服务是否可用。
熔断、热点和系统规则各自保护什么
熔断依据已完成调用的统计
熔断关注一段时间内的慢调用比例、异常比例或异常数。规则需要一起设置资源、统计窗口、最小请求数、触发阈值和熔断时长。样本不足时，不能只凭一次慢请求推断熔断应当打开。
CLOSED：正常执行并统计
└─ 达到样本量且触发阈值 → OPEN：拒绝新调用
└─ 熔断时长结束
→ HALF_OPEN：放入探测调用
├─ 探测成功 → CLOSED
└─ 探测失败 → OPEN熔断不会终止已经运行的数据库或 HTTP 请求，下游调用仍需要自己的超时和取消策略。对于手工 entry 接入，业务异常要通过 Tracer 记录；返回一个错误对象而不抛异常、不记录失败时，异常比例统计未必知道调用失败。策略说明见 Circuit Breaking。
下载工程中的 CircuitProbe 用真实 Sentinel 规则执行五次受控失败，触发 OPEN，再验证拒绝和半开恢复：
docker compose run --rm --no-deps sentinel-app \
java -Duser.home=/tmp -Dcsp.sentinel.log.dir=/tmp/sentinel \
-cp '/app/classes:/app/dependency/*' lab.CircuitProbe应依次输出 CLOSED → OPEN、OPEN → HALF_OPEN、HALF_OPEN → CLOSED，以及 PASS。该探针使用 1 秒统计窗口、最小 5 次请求、0.5 异常比例和 1 秒熔断时长，只用于快速观察状态机；生产阈值要根据下游容量、正常延迟分布和误触发成本确定。
热点参数、系统保护与来源限制
热点规则限制同一资源内某个参数值的访问，例如单个商品 ID。需要额外的 sentinel-parameter-flow-control 模块，并在 entry 时把参数传入；退出时带回对应 count 和参数。paramIdx=0 指的是传入参数数组的第一个位置，不是随意挑选一个 HTTP 参数名。示例和完整字段见 热点参数限流。
系统规则观察入口流量与进程负载，例如入口 QPS、并发线程、平均响应时间、CPU 或系统 load。入口应标为 EntryType.IN，负载指标还受操作系统和容器资源识别影响。系统保护适合避免实例整体过载，业务下游的专属限制仍应落在对应资源上。见 Adaptive System Protection。
来源访问规则按 origin 区分调用方。origin 应由可信网关、认证结果或内部调用身份生成；直接信任外部请求随意填写的 Header，会让调用者伪装来源。Sentinel 黑白名单不承担完整用户认证和对象权限检查，配置方法见 来源访问控制。
集群限流增加了哪些依赖
需要服务级总量约束时，可采用集群流控，由 Token Client 向 Token Server 请求配额。需要稳定规则 ID、客户端到令牌服务的路由、容量和故障策略，不能仅把同一条单机规则复制给全部实例。
令牌服务异常时，是否回退本地限流、拒绝还是采用其他行为，要按具体规则配置和业务风险测试。Dashboard、Nacos 和 Token Server 是不同组件：前两个正常，也不能证明令牌分配正常。部署方式和字段见 Cluster Flow Control。
接入 Spring 时确定资源和异常职责
Spring 项目可使用对应适配器自动建立 Web/RPC 资源，也可以用 @SentinelResource 声明方法资源。自动路由资源和手工方法资源可能同时存在，配置规则前先看实际资源名、HTTP 方法前缀以及 URL 归一化结果。
blockHandler 处理被 Sentinel 拒绝的调用；fallback 处理指定业务异常的替代返回，两者签名与触发条件分别配置。代理未生效、类内自调用、返回类型不匹配或把异常捕获在注解方法内部，都可能改变结果。所需模块和框架适配见 官方适配说明；Spring Cloud Alibaba 的依赖组合与工程接入见 生态开发接入。
规则保存、发布和回退怎样形成完整链路
默认控制台修改只存在于运行时
默认 Dashboard 将规则推送给客户端，并在自己的内存中维护相应信息。客户端重启后，需要重新从配置的来源加载；控制台磁盘上存在 JAR 或日志，并不意味着规则已经持久化。默认行为和扩展方式见 Dynamic Rule Configuration。
本实验从 qps 文件建立启动规则，因此重启 sentinel-app 后会重新加载文件中的 2，覆盖控制台先前对运行时做的临时修改：
cat sentinel-client/qps
docker compose restart sentinel-app
docker compose logs --tail 15 sentinel-app看到 startupQps=2 后重新发送请求，观察放行与拒绝。这个结果验证了启动规则来源；运行中修改文件不会热更新。
使用 Nacos 等外部规则源
生产常把规则文本放在配置中心，客户端数据源订阅后将其转换为对应规则列表，再更新 RuleManager。流控规则文本例如：
[
{
"resource": "orders",
"limitApp": "default",
"grade": 1,
"count": 5,
"strategy": 0,
"controlBehavior": 0
}
]Nacos 数据源需要相应 sentinel-datasource-nacos 依赖、serverAddr、Namespace、Group、Data ID、只读凭据及转换器。FlowRule、DegradeRule、ParamFlowRule、SystemRule、AuthorityRule 使用不同模型和管理器，应分开数据标识或明确定义文档结构。转换器要校验资源名、阈值单位和范围，不能对任意 JSON 解析异常直接返回空列表。
空数组通常表示明确移除该来源下的规则；格式错误应该拒绝采用并报警。已运行实例可保留最后有效规则，首次启动没有有效规则时则按业务决定启动失败或使用受审查的基线。该行为需要数据源和应用实现支持，不能假定所有配置中心插件都以同一策略处理。
默认 Dashboard 不会因为客户端接了 Nacos 数据源，就自动把页面修改写回 Nacos。若保留控制台作为编辑入口，需要改造 DynamicRuleProvider / DynamicRulePublisher 等扩展，让控制台读写同一个外部来源；另一种方式是统一通过配置发布系统变更规则，控制台只观测。实现入口见 动态规则扩展。
同时启用控制台直推、启动文件和远程数据源时，规则可能相互覆盖。应确定每类规则的唯一发布来源，列清启动加载、订阅更新和应急修改的优先关系。Nacos 的保存与应用采用验证见 Nacos 运维。
发布验证与权限
保留上一份有效规则和变更原因，先在少量实例应用新版本，核对客户端实际加载值、通过/拒绝数量、下游负载及业务结果。过低阈值会扩大拒绝，过高阈值可能压垮下游，二者都需要恢复条件。
回退时重新发布上一份有效内容，并逐实例确认采用。单纯在 Dashboard 改回页面值，可能没有覆盖外部来源；客户端下一次收到订阅又会恢复错误规则。
控制台与客户端管理端口只向管理网络开放，生产入口使用受控身份与加密访问。开放 8719 等管理端口会允许外部读取或修改规则，不能只给 Dashboard 配密码而忽略客户端端口。规则发布身份与业务应用只读身份分开，审计中保留变更对象和结果，避免记录访问令牌。
从缺失的环节定位运行问题
| 现象 | 定位路径 | 修复后的验证 |
|---|---|---|
| 控制台没有应用 | 客户端依赖、首次资源调用、dashboard 地址、心跳日志 | 机器列表出现正确 IP 和端口 |
| 有机器但读不到资源 | Dashboard 反向访问、上报地址、8719 是否实际绑定 | 簇点链路出现 orders，能读取规则 |
| 规则存在但不拒绝 | 资源名、阈值、实际 QPS、调用上下文、来源覆盖 | 同时观察请求状态与客户端实际规则 |
| 所有请求都被拒绝 | 多类规则叠加、错误阈值、系统负载、熔断状态 | 找到具体规则后受控回退，确认下游没有再过载 |
| 下游一直失败却不熔断 | 最小样本量、窗口、Tracer、适配器异常统计 | 用受控失败观察 OPEN 与半开恢复 |
| 重启后规则消失 | 启动来源、数据源连接与解析、运行账号权限 | 启动即加载有效规则，再验证请求结果 |
客户端运行日志用于定位心跳、规则加载和统计异常；长期监控则应进入指标平台。控制台显示的短期曲线不承担完整历史审计或容量趋势存储。日志与指标字段分别见 Logs和 Metrics。
升级前在隔离环境验证现有规则的序列化字段、资源名和适配器行为，尤其是 HTTP 方法前缀与默认上下文变化。更新客户端后先核对实际资源，再放开新规则。停止实验时可用 docker compose stop sentinel-app dashboard，保留启动规则文件；同一 Compose 中其他实验的数据卷不需要删除。
权威资料与规范地址
资源与保护规则
| 查阅内容 | 官方地址 |
|---|---|
| 资源与 API | How to Use |
| 流控策略与效果 | Flow Control |
| 熔断状态 | Circuit Breaking |
| 参数规则 | 热点参数限流 |
| 系统保护 | Adaptive System Protection |
| 来源规则 | 来源访问控制 |
| 令牌服务 | Cluster Flow Control |
控制台与框架接入
| 查阅内容 | 官方地址 |
|---|---|
| 固定版本制品 | 1.8.10 Release |
| 控制台与通信 | Dashboard |
| 心跳地址校验 | MachineRegistryController |
| 框架接入 | Adapters |
规则保存与运行观察
| 查阅内容 | 官方地址 |
|---|---|
| 规则持久化 | Dynamic Rule Configuration |
| 客户端日志 | Logs |
| 指标数据 | Metrics |