微服务 - Jul1en

SkyWalking

Mon, 15 Jun 2026 12:06:13 +0800

SkyWalking

相关笔记：Spring Cloud 核心概念

链路追踪

微服务拆分后，一次请求可能经历下面的过程：

用户请求进入 Gateway
Gateway 调用商品服务、订单服务或库存服务
订单服务继续调用支付服务
服务访问 MySQL、Redis 或消息队列
部分调用串行执行，部分调用并行执行

这些服务可能由不同团队开发，部署在不同服务器上，甚至使用不同语言。只看单个服务的日志是很难追溯到问题的，比如

请求具体经过了哪些服务
服务之间是什么依赖关系
各个接口的性能怎么样

这就需要链路追踪。链路追踪会记录一次请求在多个服务之间的流转路径、耗时和状态，把分散在各个服务里的调用信息集中展示。它的核心是通过唯一的 Trace ID 串联跨服务调用，用 Span 表示一次具体处理单元，再通过 Context 传递让链路可以连续下去。

这里用快递包裹的物流追踪来类比链路追踪。看物流轨迹时，我们会关心包裹经过了哪些转运节点、每个节点花了多少时间、派送过程有没有异常。链路追踪也是类似的思路：给复杂的网络请求画一张“流程图”，记录一次操作经过了哪些服务、每个环节耗时多少、是否出现异常。

链路追踪	快递物流
Trace	整个物流链路
Trace ID	快递单号
Span	包裹每经过一个转运中心产生的一条记录，包含到达时间、状态等信息

链路追踪的作用主要有四个：

保障系统可用性：结合 CPU、内存、成功率等指标，提前发现异常并触发告警
优化性能和资源使用：通过完整 Trace 看清每个服务节点耗时，找到慢调用
提升故障排查效率：用 Trace ID 把跨服务日志、错误信息串成统一视图
理解服务依赖与拓扑：自动展示服务间调用关系、调用频率和成功率，辅助架构分析

链路追踪适合找调用关系和慢点，但不完全等同于日志。 Trace 说明“哪一步慢、哪一步错”，日志继续解释“当时的参数和业务状态是什么”。如果还要定位到具体方法和代码行，再进入性能剖析。

常见方案

链路追踪本身是一类问题，不是 SkyWalking 独有的能力。常见方案大概有这些：

Zipkin：Twitter 开源的分布式链路追踪系统，设计思路来自 Google Dapper 论文，常用于请求链路采集、存储和查询
CAT：美团点评开源的分布式实时监控系统，理念来源于 eBay 的 CAL 系统，报表和监控能力比较完整，但通常需要代码埋点
SkyWalking：Apache 顶级项目，面向微服务和分布式架构，支持 Agent 自动采集，UI 功能较完整，也支持插件扩展

简单对比图：

维度	Zipkin	CAT	SkyWalking
接入复杂度	接入相对简单，常和 Spring Cloud 生态集成	需要代码埋点	通过 Java Agent 启动，代码无侵入
数据粒度	接口级	代码级，可细化到具体代码块	方法级，支持 RPC、HTTP
支持语言	Java、C#、Python、Node.js、Go、Ruby、Scala 等	Java、C/C++、Python、Node.js、Go 等	Java、Python、Node.js、PHP、Go、Ruby 等
调用链可视化	支持	支持	支持
聚合报表	较少	很丰富	较丰富
服务依赖图	简单	简单	较好
告警支持	不直接提供	支持	支持
存储机制	内存、Elasticsearch、MySQL 等	MySQL、本地文件、HDFS 等	Elasticsearch、MySQL、BanyanDB、PostgreSQL 等
社区情况	文档丰富，功能迭代相对慢	国内使用多，社区活跃度一般	社区活跃，更新较频繁
主要优势	部署简单，适合快速接入基础 Trace	报表完整，适合综合监控	无侵入、Apache 项目、生态较完整
主要不足	报表能力弱，功能相对单一	代码侵入性高	插件开发门槛较高

选择 SkyWalking 的原因

综合来看，SkyWalking 的能力更完整，无代码侵入接入、多语言、报表、告警和插件体系都比较适合当前 Java Spring 微服务项目。

核心组件

SkyWalking 架构分为三类组件：探针 Agent、后端 Backend 和前端 UI。其中 OAP 是后端的核心部分，负责接收、处理和存储来自探针的数据，并生成聚合指标。

组件	作用	比喻（交通网系统）
Agent	探针，通过字节码增强收集应用运行时数据	摄像头
OAP	接收、分析、聚合数据，并提供查询和告警能力	交通数据处理系统（后端）
UI	展示拓扑、服务指标、Trace、日志、剖析任务和告警	Dashboard 看板（前端）

关键术语

术语	含义
APM	Application Performance Monitor，应用性能监控，通过收集和分析响应时间、吞吐量、错误率等数据来帮助优化系统性能
OAP	Observability Analysis Platform，观测分析平台，是 SkyWalking 后端的核心部分
Agent	探针，通过字节码增强无侵入采集应用运行时数据
Metrics	指标，比如服务响应时间、服务成功率、分钟请求数
Trace	一次完整的分布式请求，由多个 Span 或 Segment 组成
Trace ID	一次 Trace 的全局标识，常用于 Trace 与日志互查
Span	一次具体操作，比如接收 HTTP 请求、执行方法、调用数据库
Endpoint	服务入口，比如 `GET:/orders/{id}` 或一个 RPC 方法
Context Propagation	把 Trace 上下文传到下游服务或异步任务
Sampling	只采集部分请求，控制 Agent、网络和存储开销
Topology	根据调用数据得到的服务依赖关系
Apdex	根据响应时间评估用户体验的指标
OAL	OAP 中用于分析 Trace 和 Mesh 流量的规则语言
MQE	Metrics Query Expression，当前告警规则使用的指标表达式

安装部署

下载包说明

课件里是手动下载安装 SkyWalking，需下载两个包：

SkyWalking APM：服务端包，里面包含 OAP、UI、配置文件和启动脚本，用来启动 SkyWalking 后端与可视化界面
Java Agent：探针包，用来接入 Spring Boot 服务，通过 -javaagent 挂到业务 JVM 上采集 Trace、Metrics 等数据

从 8.8.0 之后，APM 和 Agent 分开安装，所以只下载 Java Agent 不够。需要先准备 SkyWalking APM 服务端，再给业务服务接入 Java Agent。

APM 历史版本：https://archive.apache.org/dist/skywalking
Java Agent 历史版本：https://archive.apache.org/dist/skywalking/java-agent

Docker Compose 部署

目录可以这样放：

skywalking/
├── compose.yaml
└── config/
    └── alarm-settings.yml

compose.yaml：

services:
  banyandb:
    image: apache/skywalking-banyandb:0.10.2
    container_name: skywalking-banyandb
    command:
      - standalone
      - --stream-root-path
      - /data/stream-data
      - --measure-root-path
      - /data/measure-data
    ports:
      - "17912:17912"
      - "17913:17913"
    volumes:
      - banyandb-data:/data
    healthcheck:
      test: ["CMD", "sh", "-c", "nc -nz 127.0.0.1 17912"]
      interval: 5s
      timeout: 5s
      retries: 60

  oap:
    image: apache/skywalking-oap-server:10.4.0
    container_name: skywalking-oap
    depends_on:
      banyandb:
        condition: service_healthy
    environment:
      SW_STORAGE: banyandb
      SW_STORAGE_BANYANDB_TARGETS: banyandb:17912
      SW_HEALTH_CHECKER: default
      JAVA_OPTS: "-Xms1g -Xmx1g"
    ports:
      - "11800:11800"
      - "12800:12800"
    volumes:
      - ./config/alarm-settings.yml:/skywalking/ext-config/alarm-settings.yml:ro
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo >/dev/tcp/127.0.0.1/12800'"]
      interval: 15s
      timeout: 5s
      retries: 20
      start_period: 60s

  ui:
    image: apache/skywalking-ui:10.4.0
    container_name: skywalking-ui
    depends_on:
      oap:
        condition: service_healthy
    environment:
      SW_OAP_ADDRESS: http://oap:12800
    ports:
      - "8080:8080"

volumes:
  banyandb-data:

先创建一个可用的 config/alarm-settings.yml：

rules: {}
hooks: {}

启动：

cd skywalking
docker compose up -d
docker compose ps

检查 OAP：

curl http://localhost:12800/internal/l7check

如果 Spring Boot 运行在宿主机，Agent 连接 127.0.0.1:11800。如果应用也在 Compose 中，地址应写成 oap:11800，不能写 localhost:11800，因为容器内的 localhost 指向应用容器自己。

Spring Boot 服务接入

接入 SkyWalking 前先确认两件事：

SkyWalking OAP 和 UI 已经启动，能访问 http://127.0.0.1:8080，如果改过 UI 端口就换成自己的端口
微服务本身能正常跑通业务请求，否则后面 UI 上即使没有 Trace，也不好判断是业务问题还是 Agent 接入问题

下载与放置 Java Agent

从 SkyWalking 官方 Downloads 页面下载 Java Agent 后，一般先解压 SkyWalking APM 包，再在 APM 目录中新建 agent 文件夹，把 Java Agent 解压后的内容复制进去。这样后面启动业务服务时，就可以指向这个 agent/skywalking-agent.jar，也比较方便。

启动参数接入

以 order-service 为例，通过 -javaagent 参数配置 SkyWalking Agent 来追踪微服务。最直接的启动方式是在 Java 启动参数里增加：

# 换成自己本地的 agent 安装路径
java \
  -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
  -Dskywalking.agent.service_name=order-service \
  -Dskywalking.collector.backend_service=127.0.0.1:11800 \
  -jar order-service.jar

-javaagent 必须放在 -jar 前面。

几个参数含义：

-javaagent：后面换成自己本地的 skywalking-agent.jar 路径
-Dskywalking.agent.service_name：服务名称，比如 order-service
-Dskywalking.collector.backend_service：SkyWalking OAP 的 gRPC 地址，默认是 127.0.0.1:11800（需开放端口号）

启动完成后，打开 SkyWalking UI 左侧的服务页面，就能看到已经接入的服务。其他服务也按同样方式加 Agent 参数，只是 service_name 要改成各自的服务名。

也可以通过环境变量配置：

export SW_AGENT_NAME=order-service
export SW_AGENT_INSTANCE_NAME=order-service-local-01
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.0.0.1:11800

java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
  -jar order-service.jar

常用配置：

Agent 配置	环境变量	说明
`agent.service_name`	`SW_AGENT_NAME`	服务名，同一业务服务的多个实例保持一致
`agent.instance_name`	`SW_AGENT_INSTANCE_NAME`	实例名，同一服务内保持唯一
`agent.namespace`	`SW_AGENT_NAMESPACE`	可用于区分环境或命名空间
`agent.cluster`	`SW_AGENT_CLUSTER`	标记数据中心或集群
`collector.backend_service`	`SW_AGENT_COLLECTOR_BACKEND_SERVICES`	OAP gRPC 地址

服务名建议使用明确且固定的英文名，比如 gateway-service、order-service、inventory-service。不要把 Pod IP 或随机端口放到服务名里，这类信息应该放在实例名中。

Docker 中接入

Spring Boot 镜像可以把 Agent 放进镜像：

FROM eclipse-temurin:21-jre

WORKDIR /app

COPY agent /opt/skywalking-agent
COPY target/order-service.jar /app/app.jar

ENTRYPOINT ["java",
  "-javaagent:/opt/skywalking-agent/skywalking-agent.jar",
  "-jar",
  "/app/app.jar"]

应用服务配置：

order-service:
  image: example/order-service:1.0.0
  environment:
    SW_AGENT_NAME: order-service
    SW_AGENT_INSTANCE_NAME: order-service-01
    SW_AGENT_COLLECTOR_BACKEND_SERVICES: oap:11800
  depends_on:
    oap:
      condition: service_healthy

如果同一个镜像启动多个副本，不要把 SW_AGENT_INSTANCE_NAME 写死。可以不配置，让 Agent 生成实例名，或者由 Kubernetes 使用 Pod 名注入。

自定义追踪

自动插件主要覆盖框架入口和常见中间件。纯业务方法、自研协议、特殊线程模型可能不会自动出现，这时可以使用 Java Agent Toolkit。

Toolkit 依赖

<properties>
    <skywalking.version>9.6.0</skywalking.version>
</properties>

<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-trace</artifactId>
    <version>${skywalking.version}</version>
</dependency>

Toolkit 版本建议和 Java Agent 版本保持一致。

日志关联与上传

要想在 SkyWalking UI 里查看日志，并把日志和 Trace 关联起来，需要分成两件事：

在本地日志中打印 Trace ID，方便从日志跳到 Trace
通过 gRPC 把日志上传到 OAP，在 SkyWalking UI 中统一查询

添加依赖

Spring Boot 默认常用 Logback：

<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-logback-1.x</artifactId>
    <version>9.6.0</version>
</dependency>

编写 xml 文件

在 src/main/resources 下新建 logback-spring.xml。Spring Boot 会优先加载 logback-spring.xml，它比普通 logback.xml 更适合 Spring Boot 项目，也能使用 Spring 的扩展能力。

下面这个配置只负责把 Trace ID 打到本地控制台日志里：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
                <Pattern>
                    %d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} - %msg%n
                </Pattern>
            </layout>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

有 Agent 且当前线程处于 Trace 中时，%X{tid} 会输出 Trace ID；没有可用 Trace 时会显示 TID: N/A。

如果希望写出完整 SkyWalking 上下文，可以把 %X{tid} 换成 %X{sw_ctx}，内容包括：

serviceName, instanceName, traceId, traceSegmentId, spanId

上传日志

只打印 Trace ID 还不等于上传日志。上面的配置只能让应用自己的控制台日志带上 Trace ID，SkyWalking UI 的 Log 页面还看不到这些日志。

如果要把日志上传到 OAP，需要在 logback-spring.xml 里添加 GRPCLogClientAppender：

<appender name="GRPC_LOG"
          class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.log.GRPCLogClientAppender">
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
        <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
            <Pattern>
                %d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} - %msg%n
            </Pattern>
        </layout>
    </encoder>
</appender>

<root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="GRPC_LOG"/>
</root>

这里要注意：GRPCLogClientAppender 上报日志时，会自动附带 Trace ID、Segment ID 和 Span ID。也就是说，layout 控制的是日志正文格式；日志与 Trace 的关联信息由 gRPC reporter 自动带上。等重启服务并发起请求后，就可以在 SkyWalking UI 的 Log 页面查询日志，也可以根据 Trace ID 过滤日志并跳转到对应 Trace。

告警

SkyWalking OAP 的告警规则位于 apm 的 config/alarm-settings.yml。Docker 镜像可以把同名文件挂载到 /skywalking/ext-config 来覆盖默认配置。

可以把告警类比成烟雾报警器：当系统出现响应慢、成功率低这类异常时，就像检测到烟雾一样触发通知，提醒研发或运维尽快处理。

SkyWalking 默认规则主要覆盖这些场景：

服务平均响应时间超过阈值
服务成功率低于阈值
服务响应时间百分位数超过阈值，比如 P50、P75、P90、P95、P99
服务实例平均响应时间超过阈值
Endpoint 平均响应时间超过阈值
数据库访问平均响应时间超过阈值
Endpoint 关系平均响应时间超过阈值

规则字段

简单罗列一些规则字段，用到的时候再查即可。

字段	说明
规则 ID	必须以 `_rule` 结尾
`expression`	MQE 表达式，结果必须是单值布尔结果
`period`	参与判断的分钟窗口
`silence-period`	告警触发后的静默时间
`recovery-observation-period`	条件恢复后连续观察多少个周期再发送恢复通知
`include-names`	只匹配指定实体
`exclude-names`	排除指定实体
`include-names-regex`	用正则匹配实体名
`tags`	附加标签，常用 `level` 标记告警级别
`hooks`	指定本规则调用哪些通知目标
`message`	告警文本，`{name}` 会替换成实体名

Webhook

Webhook 是 OAP 把告警推送给外部系统的一种方式。告警触发后，OAP 会使用 HTTP POST 和 application/json 请求目标地址，请求体是告警消息数组，在编写代码时需要注意用 List<>~

接收方只要提供一个可访问的 HTTP 地址，就可以接收 SkyWalking 推送的告警数据。常见用途包括推送到钉钉、企业微信、飞书、邮箱，或者转给内部告警服务继续处理。

配置

完整的 alarm-settings.yml 可以这样写：

rules:
  service_resp_time_rule:
    expression: sum(service_resp_time > 1000) >= 3
    period: 5
    silence-period: 10
    recovery-observation-period: 2
    message: "服务 {name} 最近 5 分钟内多次超过 1000ms"
    tags:
      level: WARNING
    hooks:
      - webhook.ops

hooks:
  webhook:
    ops:
      urls:
        - http://host.docker.internal:8088/webhooks/skywalking
      recovery-urls:
        - http://host.docker.internal:8088/webhooks/skywalking
      headers:
        Authorization: Bearer replace-with-your-token

排查顺序

实际遇到问题需要排查时可以按这个顺序：

先看服务拓扑，确认调用方向和异常节点
再看 Service、Instance、Endpoint 指标，缩小时间范围
打开慢请求 Trace，查看哪个 Span 占用时间最多
用 Trace ID 查询关联日志，检查参数、异常和业务状态
接口内部仍看不出原因时，创建 Trace Profiling 任务
JVM 出现 CPU、分配或锁问题时，创建 Java App Profiling 任务
确认指标规则后配置告警，再接 Webhook 通知

Seata

Sun, 14 Jun 2026 23:25:19 +0800

Seata

Seata 是 Spring Cloud Alibaba 体系里常用的分布式事务解决方案。它解决的核心问题是：微服务拆分之后，一个业务请求可能跨多个服务、多个数据库，Seata 负责把这些分散的本地事务组织成一个全局事务，让整条业务链路尽量保持一致。

可以先这样记：

Eureka、Nacos、OpenFeign、Gateway 解决服务治理：注册、发现、调用、网关转发。
Sentinel 解决流量治理：限流、熔断、降级、系统保护。
Seata 解决事务治理：跨服务写库后的数据一致性。

学习 Seata 时可以先不展开某个注解或配置，先看这条主线：

微服务把一个业务动作拆成多个本地事务，Seata 再用全局事务把这些本地事务协调起来。

为什么需要 Seata

单体应用里，下单、扣库存、扣余额可能都在一个工程、一个数据库里。此时只要开启一个本地事务，就能保证：

订单创建成功；
库存扣减成功；
账户扣款成功；
中间任一步失败就整体回滚。

拆成微服务后，情况变复杂了：

服务	数据库	本地事务能管什么
订单服务	订单库	只能保证订单表修改成功或失败
库存服务	库存库	只能保证库存表修改成功或失败
账户服务	账户库	只能保证账户表修改成功或失败

问题在于：每个服务只能保证自己的本地事务，没人天然知道整条下单链路应该一起提交，还是一起回滚。

典型异常场景：

订单服务创建订单成功。
库存服务扣减库存成功。
账户服务扣减余额时超时。
最后变成“订单有了，库存少了，钱没扣”。

这就是分布式事务要解决的核心问题：一个业务动作被拆成多个本地事务后，如何避免“部分成功、部分失败”。

这张图可以抓三个角色：TM 发起全局事务，RM 执行各自的本地分支，TC 负责从全局视角决定提交或回滚。

Seata 的三个核心角色

Seata 的模型可以理解为：业务服务继续执行自己的本地操作，但每个本地事务分支都要登记到同一个全局事务里。

角色	全称	作用
TC	Transaction Coordinator	全局事务协调者，通常就是 Seata Server，负责维护全局事务状态。
TM	Transaction Manager	全局事务管理器，通常在入口业务服务里，负责开启、提交、回滚全局事务。
RM	Resource Manager	资源管理器，负责管理本地分支事务，并向 TC 注册和上报状态。

放到下单业务里：

订单服务通常是 TM，因为它是业务入口。
库存服务、账户服务中的数据库资源通常由 RM 管理。
Seata Server 是 TC，负责协调所有分支。

整体流程可以这样看：

sequenceDiagram participant Client as 用户请求 participant Order as 订单服务(TM) participant TC as Seata Server(TC) participant Stock as 库存服务(RM) participant Account as 账户服务(RM) Client->>Order: 下单 Order->>TC: 开启全局事务 Order->>Stock: 扣减库存 Stock->>TC: 注册分支事务 Order->>Account: 扣减余额 Account->>TC: 注册分支事务 alt 全部分支成功 Order->>TC: 提交全局事务 TC->>Stock: 分支提交 TC->>Account: 分支提交 else 任一分支失败 Order->>TC: 回滚全局事务 TC->>Stock: 分支回滚 TC->>Account: 分支回滚 end

CAP 和 BASE

学习 Seata 前，经常会遇到 CAP 和 BASE。这两个概念不用过度抽象，它们主要是在解释：分布式系统为什么很难只追求“绝对强一致”。

CAP

目标	含义
C：Consistency	一致性，多个节点看到的数据结果一致。
A：Availability	可用性，请求能得到正常响应。
P：Partition tolerance	分区容错性，网络异常时系统还能继续运行。

微服务一定会发生远程调用，所以网络问题无法完全避免。也就是说，P 基本是必须接受的。一旦发生网络分区，系统通常要在强一致性和可用性之间做取舍。

BASE

BASE 是工程上的折中思路：

Basically Available：基本可用，系统不要因为局部失败完全瘫痪。
Soft State：软状态，允许短时间中间状态存在。
Eventually Consistent：最终一致，通过补偿、重试、异步修复让数据最终对上。

所以 Seata 的重点不是把分布式系统变得和单机数据库一样，而是在一致性、性能、可用性、业务侵入之间找一个能落地的方案。

两阶段提交（2PC）

2PC 是分布式事务里最经典的提交思想：先询问所有参与者能不能提交，再根据所有人的结果统一提交或回滚。

阶段一：Prepare

第一阶段，协调者先问所有参与者：

能不能提交？
资源是否准备好？
本地操作是否可以进入待提交状态？

参与者准备好后回复“可以”，否则回复“不可以”。

阶段二：Commit or Rollback

如果所有参与者都同意，协调者通知大家提交。
只要有一个参与者不同意，协调者通知大家回滚。

主要问题

协调者故障时，参与者可能不知道该提交还是回滚。
一阶段需要锁定资源，等到二阶段结束才释放，导致事务资源长时间得不到释放，锁定周期长，性能和可用性压力比较大。

所以 2PC 是重要基础，但不一定是所有业务的最佳选择。Seata 的 XA 模式更接近标准 2PC，而 AT 模式是在两阶段思想上做了工程优化。

XA 模式

XA 模式依赖数据库原生对 XA 协议的支持，是基于两阶段提交实现的工作机制原理图

执行逻辑

开启事务：事务管理器（TM）开启一个全局事务，并于事务协调器（TC）建立连接，TC返回一个全局事务 ID（XID）给 TM
分支事务注册与执行：资源管理器（RM）收到业务请求操作后，会向 TC 注册分支事务（可能有多个RM，故称是分支事务），执行事务 SQL，并携带 XID 保证事务一致性
分支事务状态报告：RM 执行完分支事务后，向 TC 报告分支事务的执行状态
TC 决定事务提交或回滚策略：TM 等待 RM 中的所有的分支任务执行完成后，通知 TC 事务结束。TC 接收通知后会检查各个分支事务的执行状态，如果所有的分支事务都成功，则通知所有 RM 提交所有事务；若有其中一个分支事务失败，则通知所有的 RM 回滚事务
RM 接收 TC 通知并执行分支事务提交或回滚：RM 接收 TC 指令后执行对应的 commit 或 rollback 操作

优缺点

优点

事务强一致性：XA 模式能满足 ACID 原则，确保分布式事务的强一致性
实现简单且无代码侵入：常用数据库都支持 XA 协议，使用 Seata 的 XA 模式无需修改业务代码，只需简单配置即可

缺点

依赖关系型数据库、驱动、连接池对 XA 的支持
性能较差：因为是基于两阶段提交，故也保留了两阶段的缺点：一阶段需要锁定资源，等待二阶段结束才释放——资源锁持有时间长

AT 模式

AT 也是基于二阶段提交实现的，但它不会像 XA 一样把数据库事务一直保持到第二阶段。一阶段会提交业务数据和 undo_log，先释放数据库连接与本地锁；全局事务是否结束，则继续由 TC 和全局锁控制。

优缺点

优点

适合支持本地 ACID 事务且被 Seata 数据源代理支持的关系型数据库
无代码侵入
一阶段本地事务先提交，持有资源时间短，不会像 XA 那样长时间持有数据库事务，性能开销小

需要注意

依赖关系型数据库的本地 ACID 事务，并通过数据源代理解析 SQL
全局锁发生冲突时会重试，冲突频繁会增加等待和回滚成本
二阶段回滚前需要校验 After Image，数据被其他操作改动时不能直接覆盖

undo_log

undo_log 可以理解成 Seata 给数据修改准备的“后悔药”。它记录业务 SQL 修改前后的数据状态，方便全局失败时自动生成反向 SQL。

当业务 SQL 修改数据时，Seata 会记录两份数据快照：

Before Image：SQL 执行前记录当前要修改的数据的快照——全局失败时用于回滚
After Image：SQL 执行后的快照——回滚前校验是否发生脏写

比如库存从 100 扣到 99：

Before Image：100
After Image：99
如果全局事务失败，就根据 Before Image 把库存恢复成 100

本地锁与全局锁

AT 会同时使用数据库本地锁和 Seata 全局锁，两者解决的问题不同。

本地锁： 数据库执行 UPDATE、DELETE 或 SELECT FOR UPDATE 时产生的行锁，只在当前数据库本地事务中生效。本地事务提交或回滚后，本地锁就会释放。

全局锁： TC 维护的逻辑锁，通常根据数据源、表名和主键标识被修改的行。分支事务在一阶段提交前必须先获得全局锁；本地事务提交后，全局锁仍由当前全局事务持有，直到二阶段提交或回滚结束。

所以一阶段提交后会出现这样的状态：

数据库本地事务已经提交，本地锁和连接已经释放
业务数据对普通数据库查询已经可见
全局锁仍然存在，其他 AT 全局事务不能提交对同一行的修改

一阶段

AT 一阶段会在同一个本地事务中完成业务数据修改和回滚日志记录：

RM 开启本地事务，业务 SQL 获取数据库本地锁。
数据源代理解析 SQL，确定表名、条件和要修改的数据。
查询修改前的数据，生成 Before Image。
执行业务 SQL，再根据主键查询修改后的数据，生成 After Image。
将 Before Image、After Image、XID、Branch ID 等信息写入 undo_log。
RM 向 TC 注册分支事务，并申请当前数据行的全局锁。
获得全局锁后，在同一个本地事务中提交业务数据和 undo_log，随后释放本地锁与数据库连接。
RM 向 TC 报告一阶段执行结果。

如果全局锁获取失败，当前分支不能提交本地事务。RM 会在超时时间内重试；一直无法获得时，本地事务回滚，同时释放本地锁。

二阶段

全局提交：

TM 通知 TC 提交全局事务，TC 将分支标记为提交并释放对应的全局锁。
RM 收到提交请求后可以快速返回，后续异步批量删除 undo_log。

这里不需要再次提交业务数据，因为业务数据在一阶段已经提交完成。

全局回滚：

RM 收到 TC 的回滚请求后开启新的本地事务，并尝试获取业务数据的本地锁。
根据 XID 和 Branch ID 查询对应的 undo_log。
将数据库当前值与 After Image 比较，检查一阶段之后数据是否又被修改。
数据一致时，根据 Before Image 和原业务 SQL 信息生成反向 SQL，恢复业务数据。
删除对应的 undo_log，提交本地回滚事务并向 TC 报告结果。
TC 确认分支回滚完成后释放全局锁。

如果当前数据与 After Image 不一致，说明发生了脏写或有其他操作修改了这行数据，此时不能直接用 Before Image 覆盖，需要按照异常处理策略处理。

写隔离

写隔离依赖全局锁。两个全局事务修改同一行时，后提交本地事务的分支必须等待前一个全局事务释放全局锁。

图中 tx1 一阶段提交后已经释放本地锁，所以 tx2 可以获得本地锁并更新同一行。但是 tx1 仍持有全局锁，tx2 在提交本地事务前无法获得全局锁，只能重试。tx1 二阶段提交并释放全局锁后，tx2 才能继续提交。

如果 tx1 进入二阶段回滚，它还需要重新获取本地锁执行反向 SQL。此时若本地锁被等待全局锁的 tx2 持有，tx1 会等待；tx2 获取全局锁超时后回滚本地事务并释放本地锁，tx1 才能完成补偿回滚。

读隔离

AT 一阶段会提前提交本地事务，因此普通 SELECT 不参与全局锁竞争，可能读到另一个全局事务尚未完成二阶段提交的数据。从全局事务范围看，默认只能达到读未提交。

如果业务需要全局范围的读已提交，可以使用 SELECT FOR UPDATE。Seata 会代理这类查询并申请全局锁：当锁被 tx1 持有时，tx2 会释放本地锁并重试，直到 tx1 完成二阶段并释放全局锁后再读取数据。

这里的读已提交是全局事务范围的隔离效果。数据库本身仍需要配置为读已提交或更高的本地隔离级别。

AT = 一阶段提交业务数据和 undo_log，用全局锁控制并发写；二阶段提交时异步清理日志，失败时根据数据镜像自动补偿。

TCC 模式

TCC = Try / Confirm / Cancel

它和 AT 最大的区别是：AT 通过数据源代理、undo_log 和全局锁自动管理分支事务，TCC 则要求业务自己实现资源预留、确认和取消逻辑。它不依赖数据库提供特定的分布式事务能力，也可以管理缓存、消息、远程接口等业务资源。

图中两个 Try 分支都成功时进入 Confirm，只要有一个 Try 失败，就进入 Cancel 释放已经预留的资源。Confirm 和 Cancel 是二选一的二阶段操作。

三个阶段

阶段	核心任务	库存例子
Try	检查业务条件并预留资源	可用库存减 1，冻结库存加 1
Confirm	使用 Try 预留的资源完成业务	冻结库存减 1，正式完成扣减
Cancel	释放 Try 预留的资源	冻结库存减 1，可用库存加 1

Try 不能只检查资源而不做预留。比如 Try 只检查库存充足，却没有扣减可用库存，那么进入 Confirm 前库存还可能被其他请求用掉，Confirm 就无法保证成功。比较常见的设计是把资源从“可用”转成“冻结”，让后续 Confirm 只确认结果，Cancel 只释放资源。

执行流程

一个全局事务包含多个 TCC 分支时，流程如下：

TM 开启全局事务，获得 XID。
每个参与服务执行自己的 Try 方法，完成业务检查和资源预留，并向 TC 注册分支事务。
所有 Try 都成功后，TM 通知 TC 提交全局事务，TC 调用各分支的 Confirm。
只要有一个 Try 失败，TM 就通知 TC 回滚全局事务，TC 调用已经注册分支的 Cancel。
Confirm 或 Cancel 执行完成后，RM 向 TC 报告分支结果；执行失败时，TC 会按照策略继续重试。

Try、Confirm 和 Cancel 都是独立的本地事务，不会像 XA 一样长期占用数据库连接和行锁。Try 完成资源预留后就会提交本地事务，所以 TCC 的并发性能通常较好。

业务接口

Seata 使用 @TwoPhaseBusinessAction 标记 Try 方法，并指定 Confirm 和 Cancel 方法。BusinessActionContext 会携带 XID、Branch ID、Action Name 以及 Try 阶段需要传递到二阶段的业务参数。

@LocalTCC
public interface InventoryTccAction {

    @TwoPhaseBusinessAction(
        name = "inventoryTccAction",
        commitMethod = "confirm",
        rollbackMethod = "cancel",
        useTCCFence = true
    )
    boolean tryFreeze(
        BusinessActionContext context,
        @BusinessActionContextParameter(paramName = "productId") Long productId,
        @BusinessActionContextParameter(paramName = "count") Integer count
    );

    boolean confirm(BusinessActionContext context);

    boolean cancel(BusinessActionContext context);
}

@LocalTCC 用于本地 Bean 形式的 TCC 接口。远程服务也可以作为 TCC 资源，关键是三个阶段必须围绕同一份业务资源设计。

设计要求

Try： 完成参数校验、资源检查和资源预留。Try 成功后，必须保证 Confirm 有条件完成。

Confirm： 只处理 Try 已预留的资源，不再执行可能失败的业务检查。Confirm 需要支持重复调用。

Cancel： 释放 Try 预留的资源，并恢复到执行 Try 前可继续使用的状态。Cancel 同样需要支持重复调用。

TCC 的三个常见问题

问题	含义	处理思路
幂等	网络超时或结果未确认时，Confirm、Cancel 可能被重复调用	根据 XID 和 Branch ID 记录分支状态，已经完成的操作直接返回成功
空回滚	Try 请求未到达或执行失败，但 TC 已经调用 Cancel	Cancel 找不到 Try 记录时不修改业务资源，同时记录已回滚状态
悬挂	Cancel 先完成，迟到的 Try 请求之后又开始执行	Try 执行前检查分支是否已经回滚，已经回滚则拒绝执行

Seata 可以通过 TCC Fence 处理这些问题。开启 useTCCFence = true 后，框架会使用 tcc_fence_log 记录分支状态，并让 Fence 记录与业务操作处于同一个本地事务中。

优缺点

优点

不依赖底层数据库，可以管理跨数据库、跨应用的业务资源
Try 提交后不长期持有数据库锁，适合并发量和性能要求较高的核心链路
资源预留粒度由业务控制，可以根据场景进行优化

需要注意

三个阶段都需要业务实现，代码侵入和设计成本较高
需要额外维护冻结资源、业务状态或中间表
Confirm、Cancel 必须考虑重试、幂等、空回滚和悬挂

TCC 适合库存、账户、优惠券这类可以明确预留资源的核心业务。若业务资源无法冻结，或者很难设计可靠的 Confirm 和 Cancel，通常不适合直接使用 TCC。

Saga 模式

Saga 主要解决长流程事务。一个业务可能要依次调用订单、库存、支付、积分、物流和第三方系统，如果使用 XA 长时间持有资源，整个流程的性能和可用性压力会很大；有些参与者也无法提供 TCC 所需的三个接口。

Saga 会把长事务拆成多个可以独立提交的本地事务。每个正向服务执行成功后立即提交，不持有全局锁；后续步骤失败时，再按相反顺序调用已经成功步骤对应的补偿服务。

正向动作	补偿动作
创建订单	取消订单
扣减库存	释放库存
发放积分	撤销积分
创建物流单	取消物流单

比如依次执行“创建订单 -> 扣减库存 -> 扣减余额”，如果扣减余额失败，状态机不会撤销一个数据库事务，而是先补偿库存，再取消订单，让业务最终回到可接受的状态。

状态机

Seata 的 Saga 模式基于状态机引擎实现。业务流程通过状态图定义，并生成 JSON 状态语言文件。

状态机中的一个节点可以调用一个正向服务，也可以配置对应的补偿节点。除了普通服务调用，还支持条件分支、并行执行、子流程、参数映射、状态判断和异常捕获。

执行流程如下：

状态机启动全局事务并生成 XID，同时持久化状态机实例。
引擎根据状态图执行正向服务，每个服务在自己的本地事务中提交。
每个节点的开始、结束和执行状态都会写入状态日志，便于故障后恢复。
所有节点成功时，状态机正常结束。
某个节点失败时，引擎根据流程定义决定继续重试、向前恢复，或者触发补偿。
触发补偿后，引擎按照成功节点的相反顺序执行补偿服务，直到流程结束。

补偿

补偿是一个新的业务操作，不等于数据库回滚。比如“发放积分”的补偿可以是“扣回积分”，但如果积分已经被使用，补偿就可能失败。因此正向服务和补偿服务都需要保存业务状态，并明确哪些状态允许继续执行或补偿。

补偿服务需要考虑：

幂等： 正向服务和补偿服务都可能因为超时而重试，同一个业务键不能重复修改数据
空补偿： 正向请求未成功到达，但补偿请求先执行时，应记录补偿状态并返回成功
悬挂： 已经完成空补偿后，迟到的正向请求必须被拒绝

故障恢复

Saga 不一定只能向后补偿。对于某些流程，前面已经完成的动作很难撤销，或者继续完成后续步骤更合理，此时可以恢复状态机上下文并继续向前执行。常见处理方向有两种：

反向补偿： 按相反顺序撤销已经成功的步骤，适合补偿动作明确的流程
正向恢复： 重试失败节点并继续完成后续步骤，适合业务更希望最终成功的流程

状态机日志记录了节点执行结果，因此服务或状态机重启后，可以根据已有状态继续处理，不需要从头执行整个流程。

隔离问题

Saga 的本地事务会立即提交，也没有全局锁，所以不能保证事务隔离。中间状态可能被其他请求读取或继续使用，之后即使触发补偿，也不一定能够完全恢复。

比如先给账户增加余额，再执行后续步骤。如果余额在流程结束前已经被使用，后续失败时就无法直接扣回。因此设计 Saga 时需要限制中间资源的使用，或者调整执行顺序，让难以补偿、风险较高的操作尽量晚执行。

优缺点

优点

每个步骤独立提交本地事务，不长期持有数据库锁，适合长流程
可以调用第三方系统或旧系统，不要求参与者提供 TCC 三阶段接口
状态机支持异步、并行、条件分支和故障恢复，适合复杂服务编排

需要注意

不保证隔离，中间状态可能被其他业务读取和修改
每个正向服务需要设计对应的补偿服务，补偿本身也可能失败
业务状态、幂等、重试和人工处理机制需要提前设计

Saga 适合流程长、参与系统多、允许最终一致的业务。对于金额、库存等不能暴露中间状态，且补偿失败影响较大的场景，需要先评估隔离和补偿是否可以可靠实现。

四种模式怎么选

选择 Seata 模式时需按业务约束往下判断：是否必须强一致，是否只是关系型数据库短事务，能不能在业务上预留资源，失败后能不能补偿。判断有先后关系：越靠前，越偏数据库事务能力；越靠后，越依赖业务自己设计预留、确认、撤销和补偿。

模式	优先选择条件	代价	不适合的场景
XA	所有分支资源支持 XA，业务要求强一致和较高隔离	分支事务和数据库锁会持续到二阶段	长事务、高并发热点资源
AT	关系型数据库、本地 ACID 事务、SQL 可被 Seata 代理	依赖 `undo_log`、全局锁和 SQL 解析，复杂 SQL 要谨慎	非关系型资源、外部系统、无法代理的 SQL
TCC	资源可以预留，业务能实现 Try、Confirm、Cancel	需要处理幂等、空回滚、悬挂，接口改造成本高	资源无法冻结，或业务方不愿维护三阶段接口
Saga	流程长，参与系统多，允许通过补偿达到最终一致	不保证隔离，补偿服务本身也要考虑失败后的再次执行	金额、库存等不能暴露中间状态的核心资源

选择顺序

强一致和隔离优先： 所有参与资源都支持 XA，并且可以接受较长的锁持有时间时，考虑 XA。
普通数据库短事务： 主要是关系型数据库增删改查，希望减少业务改造时，优先考虑 AT。
资源可以预留： 并发压力比较高，又能设计冻结资源和三阶段接口时，考虑 TCC。
长流程和外部系统： 事务持续时间长，参与者无法统一接入 AT 或 TCC，并且业务允许补偿时，考虑 Saga。

如果一个流程既不能接受长时间锁定，又无法自动回滚、预留资源或设计可靠补偿，说明当前事务范围过大，需要先划分清楚业务边界。常见做法是把大事务拆成更小的本地事务，再通过消息、事件表、人工处理或对账流程处理后续状态～

部署方式

Seata 在 Spring Cloud Alibaba 项目中，通常会和注册中心、配置中心、远程调用一起出现。

典型接入步骤：

启动 Seata Server，也就是 TC
业务服务引入 Seata 依赖
配置事务分组、注册中心和配置中心
在每个业务库里创建 undo_log 表
在入口业务方法上使用 @GlobalTransactional

示例：

@GlobalTransactional
public void createOrder(OrderDTO orderDTO) {
    orderService.saveOrder(orderDTO);
    stockClient.deduct(orderDTO.getProductId(), orderDTO.getCount());
    accountClient.deduct(orderDTO.getUserId(), orderDTO.getMoney());
}

由于文档更新较勤，部署步骤会有些差异，最好阅读官方文档进行部署 👉 https://seata.apache.org/zh-cn/docs/user/quickstart

Sentinel

Thu, 21 May 2026 00:00:00 +0800

Sentinel

Sentinel 是微服务里非常典型的一类保护组件。它负责的是流量管控：当流量突然变大、某个下游接口变慢、异常开始扩散时，系统不要被一路拖垮。

如果说 Spring Cloud 核心概念解决的是“服务怎么拆、怎么找、怎么调”，那么 Sentinel 更像是在这些调用链外面再加一层保险。微服务拆开后，请求就不再只经过一个系统，而是会在网关、服务 A、服务 B、数据库、缓存之间层层传递。任何一个点出问题，都有可能变成整条链路的雪崩。

这也是为什么 Sentinel 的知识点看起来很多，既有流控规则，也有热点参数限流、熔断降级、授权规则、FallbackFactory、规则持久化。表面上它们是不同章节，本质上其实都在回答同一个问题：系统变复杂之后，怎么把风险拦在局部，而不是让故障扩散到全局。

主线

先理解为什么微服务需要限流，以及流控规则怎么配。
再区分基于 QPS 和基于并发线程数的两种限流思路。
然后继续往下看流控模式，直接、关联、链路分别适合什么场景。
再往后是流控效果，warm up 和排队等待本质上是在控制“放行的节奏”。
当普通流控还不够精细时，就需要热点参数限流。
如果问题已经不是“流量太大”，而是“服务本身变慢、变脆”，就要进入熔断降级。
熔断之后，调用方不能直接报错给用户，所以又引出了 fallback、FallbackFactory 和自定义异常返回结果。
最后，学习环境里可以靠 Dashboard 临时配规则，但生产环境必须考虑规则持久化，也就是 pull / push 模式。

为什么微服务需要 Sentinel

在微服务里，一个请求可能会先经过网关，再调用订单服务，订单服务再调用户服务、库存服务、支付服务。只要中间有一个节点响应慢了，上游线程就会被占住；如果大量线程一起等待，下游故障很快就会影响到上游。

如果是流量太大，就先做限流。
如果是某个依赖明显不稳定，就做熔断降级。
如果不同来源的请求优先级不同，就做授权控制。
如果请求被拦下来了，就返回一个可控、可读的降级结果。
如果系统已经准备上线，就把这些规则从“内存里的临时配置”变成“可以持久化管理的正式规则”。

一、流量控制

1. 为什么先学流控

Sentinel 最核心的起点就是流量控制。因为很多线上问题，单位时间内进来的请求太多，或者请求处理得太慢，导致系统承受不住。

比如某个查询接口平时每秒只有 20 个请求，数据库完全顶得住。但活动一开始，流量瞬间变成每秒 2000 个请求，这时数据库、线程池、连接池都可能先后被打满。流控做的事，就是在系统快到极限之前，主动拒绝一部分请求，保持系统正常运行。

基于流量控制的算法有木桶算法、漏斗算法和令牌算法。此处不过多展开。

2. 基于 QPS 和基于并发线程数的流控

QPS 是每秒请求数，限流策略是限制“请求进入速度”。比如一个接口每秒最多只希望处理 100 次调用，那么就可以基于 QPS 配规则。
并发线程数的限流策略为关注同一时刻有多少请求正在处理中。它适合保护那些执行时间较长、线程占用明显的接口。因为有些接口虽然每秒请求数不高，但每个请求都很慢，此时就要考虑线程占用限制与释放的问题。

3. 流控规则的核心字段

配置流控规则时，不管是在代码里还是在控制台里配置，有几个核心参数是必须了解的

resource，针对哪个资源生效，通常就是某个接口、某个方法、某个服务调用点。
grade，按什么维度限流，是 QPS 还是并发线程数。
count，规定了 QPS 的阈值。
strategy，三种流控模式——直接、关联、链路。
controlBehavior，超过阈值之后怎么处理，是直接失败、预热还是排队等待。

如果用代码方式理解，一个最基础的流控规则大概长这样：

FlowRule rule = new FlowRule();
rule.setResource("queryGoods");  // 规定资源
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);  // 规定限流规则
rule.setCount(100);  // QPS 设置为 100
FlowRuleManager.loadRules(List.of(rule));

这段代码规定资源名叫 queryGoods 的入口，QPS 超过 100 以后就开始限流。

4. 三种流控模式，直接、关联、链路

直接模式

直接模式最好理解，就是“谁超了就限谁”。比如 /goods/list 接口访问量过大，就直接对 /goods/list 做限流。这种模式适合最常见的单接口保护场景。

关联模式

关联模式的是限制与重要接口相关联的资源例如订单创建接口和商品查询接口都要访问数据库，秒杀时商品查询量暴增，可能会把数据库资源占满，影响到下单。这时就可以设置，当“商品查询”资源压力过大时，限制“商品查询”，把资源留给“下单”这种更重要的业务。

链路模式

链路模式关注的是，同一个资源可能从不同调用入口进入，但这些入口的优先级不一样。比如一个 queryUser() 方法，既会被普通查询页面调用，也会被下单流程调用。虽然最终访问的是同一个方法，但“下单链路里的 queryUser()”和“普通查询链路里的 queryUser()”业务价值不同。链路模式就能针对某一条调用路径单独限流。这说明 Sentinel 的资源观念不只是“接口名”，而是“接口在整条调用链里扮演什么角色”。

5. 流控效果：快速失败、warm up、排队等待

阈值一旦超了，系统并不一定只有“直接拒绝”这一种做法。 warm up 和排队等待，就是在讨论“限流之后的处理节奏”。

快速失败

快速失败是最直接的方式。超过阈值后，后续请求立刻被拒绝。这种方式实现简单，保护性最强，适合大多数接口。

warm up

warm up 适合服务冷启动的情况，如：资源正在初始化、数据库连接也刚建立，假设这个服务的 QPS 为 100，刚启动时请求就达到阈值，此时服务器的资源还未完全初始化，也有可能服务器的崩溃。所以 warm up 的思路不是一开始就放开全部流量，而是先给一个较低的通过阈值，然后随着时间逐步升高，线性地升到设定的目标阈值。

排队等待

排队等待适合对“匀速处理”有要求的场景。比如某些写库操作，这时可以让请求先处于队列排队，按稳定节奏通过。

6. 热点参数限流

资源的接口的访问量是不一样的，有些接口访问的频繁，我们称之为热点接口例如商品详情接口 /goods/{id} 平时很稳，但某个爆款商品 id=1001 突然被全网抢购。这时接口本身不一定超限，真正热点的是参数 1001。如果仍然按接口整体限流，就会误伤所有其他商品请求。热点参数限流能做到：

同一个接口，不同参数值分开统计。
对高频热点参数单独限流。
必要时还能给某些特定参数配置例外阈值。

也就是说，普通流控解决的是“这个门太多人进”，热点参数限流解决的是“门本身没问题，但总有一小撮人疯狂挤同一个窗口”。

7. 限流算法的理解重点

常见限流算法通常有下面几类：

固定窗口 / 滑动窗口

漏桶 / 令牌桶

二、熔断降级

1. 熔断的三种触发条件

慢调用比例

当一个资源的响应时间持续很长，而且慢请求所占比例超过阈值时，就可以触发熔断。这个规则适合处理接口请求过慢的场景。

异常比例

如果在一个统计窗口内，请求中的异常占比明显超过阈值，就说明这个资源已经处于高风险状态，可以暂时熔断。这个规则强调的是接口请求失败的比例。

异常数

如果在统计窗口内，异常总数超过阈值时触发熔断。

2. 熔断状态机

状态机用于监控接口

CLOSED 表示正常放行，请求可以正常通过。
OPEN 表示熔断打开，这段时间内请求不会继续请求目标资源，而是直接走降级逻辑，可能会请求到另外的备用接口。
HALF_OPEN 表示半开，也就是给系统一次“试着恢复”的机会。它不会一次性把流量全放开，而是先用少量探测请求看看下游是否真的恢复了。如果恢复了，就回到 CLOSED；如果还是不行，就重新进入 OPEN。

三、授权规则与自定义异常返回

1. 授权规则

授权规则关注的是“谁可以访问我”，对请求来源进行白名单放行 / 黑名单拦截。在微服务里，不同来源的请求优先级可能不同。比如某个接口只允许内部服务调用，不允许外部来源直接访问；或者同一个资源，对某些来源放行，对另一些来源拦截。 Sentinel 的授权规则一般会基于 origin 来做判断。你可以把 origin 理解成请求来源标识。规则的本质就是，对资源设置白名单或黑名单，让不同来源得到不同处理。

2. 自定义异常返回结果

当请求被 Sentinel 拦住时，如果直接把原始异常栈丢给前端，用户体验会很差，前端也很难统一处理。所以实际项目里，通常会把“被限流”“被降级”“被授权拦截”这些情况包装成统一的业务返回。在 Spring MVC 项目中，常见做法是实现 BlockExceptionHandler：

@Component
public class CustomBlockExceptionHandler implements BlockExceptionHandler {
    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response, 
					String resourceName, BlockException e) throws Exception {
        response.setStatus(429);
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write("{\"code\":429,\"msg\":\"当前请求被限流或降级，请稍后再试\"}");
    }
}

四、Fallback 行为与封装接口 FallbackFactory

1. 为什么熔断后还需要 fallback 行为

熔断之后还需要降级逻辑，也就是 fallback。降级逻辑的目标不是把功能完整替代掉，而是在主流程不可用时，提供一个能接受的兜底结果。

2. FallbackFactory

Spring 为我们封装了 FallbackFactory 接口，此实例将在出现任何类型的错误时被调用，任何关于 fallback 的错误降级都可实现这个接口，捕获异常。它可以拿到触发降级的异常对象 Throwable，这样在写兜底逻辑时就有更多上下文。

实现栗子🌰

@FeignClient(name = "user-service", fallbackFactory = UserClientFallbackFactory.class)  // 需声明 fallbackFactory
public interface UserClient {
    @GetMapping("/users/{id}")
    String queryUserName(@PathVariable("id") Long id);
}

@Component
public class UserClientFallbackFactory implements FallbackFactory<UserClient> {
    @Override
    public UserClient create(Throwable cause) {
        return id -> "用户服务暂时不可用，执行了降级逻辑，原因：" + cause.getMessage();
    }
}

五、规则管理与持久化

1. 规则配置

当前的配置文件都是存放于内存中的，重启服务器后规则就没了，且微服务中多台示例部署，每个实例都规则可能都不同，管理配置会非常困难，我们需要平台将规则配置统一管理起来，方便修改同步。

2. pull / push 模式

pull 模式

应用会主动从某个外部规则源读取配置，比如 Nacos、Apollo、ZooKeeper、文件或数据库。应用更像是规则的消费者，规则中心保存正式配置，应用自己去拉取。

push 模式

控制台或配置中心把规则配置主动推送到已经注册的实例中，实例（服务器）收到后会立刻更新 它的好处是实时性更好，规则修改后生效更快，也更接近真正的集中治理模式。生产环境里都会建议将 Sentinel 规则配置台注册到服务中心如 nacos 上，然后再由 nacos 推送，方便统一管理。

SpringCloud Config

Thu, 14 May 2026 16:38:45 +0000

SpringCloud Config

Spring Cloud Config 解决的是微服务项目中“配置分散、环境复杂、修改成本高”的问题。单体项目里，配置通常写在本地 application.yml 中，应用启动时直接读取即可。但微服务项目会拆出多个服务，每个服务又会区分开发、测试、生产等环境。如果每个服务都自己维护一份配置，时间久了就会出现配置重复、版本混乱、修改困难的问题。

配置中心的思路就是把配置从服务代码里抽出来，交给一个统一的服务管理。Spring Cloud Config 中，承担统一管理角色的是 Config Server，真正使用配置的业务服务是 Config Client。Config Server 从 Git、本地文件系统、Vault、JDBC 等后端读取配置，再通过 HTTP 接口提供给各个客户端。Config Client 启动时访问 Config Server，拉取属于自己的配置并加载到 Spring Environment 中。

为什么需要 Spring Cloud Config

微服务拆分之后，配置数量会快速增加。比如一个电商系统可能有用户服务、订单服务、商品服务、网关服务，每个服务又可能有 dev、test、prod 三套环境。如果所有配置都放在各自服务内部，修改数据库地址、缓存地址、开关配置时，就需要分别进入多个服务修改，甚至重新打包发布。

Spring Cloud Config 把配置统一放到远程配置仓库中，服务本身只保留“我是谁、我要去哪里拉配置”这类最基础的信息。这样一来，配置的维护位置就从“每个微服务内部”变成了“统一配置仓库”，配置读取入口也从“服务本地文件”变成了“Config Server”。

这种变化带来两个直接好处。第一，配置可以集中管理，避免同一个配置在多个服务中重复维护。第二，配置可以通过 Git 追踪历史，谁改了什么、什么时候改的，都有记录。对于团队协作和多环境管理来说，这比散落在各个服务里的配置更可靠。

Config Server 与 Config Client 的关系

Config Server 是配置中心服务端，它不一定直接保存配置文件，而是连接一个配置后端。入门阶段最常见的是 Git 仓库。Git 仓库中可以存放类似 user-service-dev.yml、order-service-prod.yml 这样的配置文件。Config Server 启动后，会读取这些配置，并通过 HTTP 接口提供给客户端。

Config Client 是具体业务服务，例如 user-service、order-service、gateway-service。这些服务启动时会主动访问 Config Server。访问时，客户端会告诉服务端三个关键信息：应用名、环境和配置版本。Config Server 根据这三个信息找到对应配置，再返回给客户端。

这里的三个信息非常重要。application 表示应用名，通常来自 spring.application.name。profile 表示环境，例如 dev、test、prod。label 通常表示 Git 分支或标签，例如 main、master、v1.0。所以 Config Server 本质上是在回答一个问题：某个应用在某个环境下，需要读取哪个版本的配置。

如果 user-service 启动时指定了应用名为 user-service，环境为 dev，配置仓库分支为 main，那么它访问 Config Server 时，Config Server 就会尝试查找和 user-service-dev 相关的配置，并把结果组合成 Spring 可以识别的 PropertySource 返回给客户端。

Config Server 简单部署

搭建 Config Server 的第一步是创建一个普通 Spring Boot 服务，并添加 Config Server 依赖。这个依赖让当前服务具备从配置仓库读取配置并对外暴露配置接口的能力。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

然后在启动类上添加 @EnableConfigServer。这个注解的作用是开启 Config Server 功能，让这个 Spring Boot 应用不再只是普通服务，而是可以作为配置中心服务端工作。

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

接下来需要告诉 Config Server 配置仓库在哪里。最常见的是配置 Git 仓库地址。

server:
  port: 8888

spring:
  application:
    name: config-server
  cloud:
    config:
      server:
        git:
          uri: https://example.com/config-repo.git
          default-label: main

server.port 决定 Config Server 的访问端口，常见示例端口是 8888。spring.cloud.config.server.git.uri 指向远程配置仓库地址。default-label 表示默认读取哪个分支或标签。

启动 Config Server 后，如果配置仓库中存在 user-service-dev.yml，客户端或浏览器可以通过类似 http://localhost:8888/user-service/dev/main 的路径访问配置。这个路径中的 user-service 对应应用名，dev 对应环境，main 对应 Git 分支。

本地学习时也可以使用 native 模式，把配置仓库放在本地目录中。它的好处是简单，不需要先准备远程 Git 仓库，但真实项目中更常用 Git，因为 Git 更适合团队协作、版本回退和变更审计。

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
          search-locations: file:///D:/config-repo

Config Client 简单部署

Config Client 是业务服务。它的目标不是管理配置，而是在启动时从 Config Server 拿到自己的配置。客户端需要添加 spring-cloud-starter-config 依赖。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

新版本更推荐使用 spring.config.import 的方式导入远程配置。这样写的含义很明确：当前应用启动时，除了读取本地配置，也会从 Config Server 导入配置。

spring:
  application:
    name: user-service
  profiles:
    active: dev
  config:
    import: optional:configserver:http://localhost:8888

这里的因果关系要理解清楚。spring.application.name 决定应用名，所以它影响 Config Server 查找哪个服务的配置。spring.profiles.active 决定当前环境，所以它影响读取 dev、test 还是 prod 配置。spring.config.import 决定配置来源，所以它告诉 Spring Boot：请到这个 Config Server 地址拉取远程配置。

如果配置仓库中有 user-service-dev.yml，内容如下：

user:
  level: vip

那么 user-service 启动后，就可以像读取本地配置一样读取到 user.level。从业务代码角度看，它不需要关心这个配置原本来自 Git 还是本地文件，因为配置最终都会进入 Environment。

@RestController
public class UserController {

    @Value("${user.level:normal}")
    private String userLevel;

    @GetMapping("/level")
    public String level() {
        return userLevel;
    }
}

到这里，Spring Cloud Config 的第一条主线就完整了：配置放在 Git 中，Config Server 读取 Git，Config Client 启动时从 Config Server 拉取配置。

刷新机制

Config Client 启动时会拉取配置，但服务启动完成后，它不会自动每秒去检查配置仓库有没有变化。也就是说，如果你修改了 Git 仓库中的配置，已经运行中的服务通常不会立即感知。

这就产生了一个新问题：配置中心解决了“配置放在哪里、启动时怎么读取”的问题，但还没有完全解决“运行时配置变化后怎么生效”的问题。

最基础的方式是手动刷新。比如通过 Actuator 的 /actuator/refresh 端点让某个服务重新加载配置。这个方式在单个服务、单个实例时还能接受，但在真实微服务场景中很快会变得麻烦。

假设系统有 5 个服务，每个服务部署 3 个实例，那么一次配置变化可能需要处理 15 个实例。如果人工逐个调用刷新接口，不仅低效，还容易漏掉某个实例。为了让配置变更自动传播，就需要 Webhook 和 Spring Cloud Bus 配合。

Webhook 的概念

Webhook 是一种事件回调机制。它和轮询正好相反。轮询是服务不断去问配置仓库有没有变化；Webhook 是配置仓库发生变化后，主动通知指定地址。

以 Git 仓库为例，当开发者修改配置并 push 到 GitHub、GitLab 或 Gitee 后，仓库平台可以向 Config Server 的某个接口发送 HTTP POST 请求。这个请求的意义不是传输完整配置，而是告诉 Config Server：配置仓库已经发生变化，你需要处理刷新。

在 Spring Cloud Config 中，Config Server 引入 spring-cloud-config-monitor 后，可以开启 /monitor 端点。Webhook 通常就配置到这个 /monitor 端点上。于是配置变化后的链路变成：开发者修改配置，push 到仓库，仓库触发 Webhook，Webhook 请求 Config Server 的 /monitor，Config Server 获知配置变化。

Webhook 只解决了“谁来告诉 Config Server 仓库变了”的问题。但 Config Server 知道配置变了以后，还要通知所有相关微服务实例刷新。这个广播能力就是 Spring Cloud Bus 要解决的问题。

Spring Cloud Bus 自动刷新机制

Spring Cloud Bus 可以理解为分布式系统中的消息总线。它把多个微服务实例通过消息代理连接起来，例如 RabbitMQ 或 Kafka。Config Server 收到配置变化通知后，可以把刷新事件发送到 Bus 上，再由 Bus 广播给相关的 Config Client 实例。

有了 Spring Cloud Bus，配置刷新链路就从“人工逐个刷新实例”变成了“触发一次事件，消息总线自动广播”。这个变化的关键价值是降低运维成本，并减少遗漏实例的风险。

完整流程可以按因果顺序理解。首先，配置仓库发生变化。然后，Webhook 把变化通知给 Config Server 的 /monitor。Config Server 收到通知后，不直接逐个调用服务，而是发布一个 RefreshRemoteApplicationEvent。接着，Spring Cloud Bus 通过 RabbitMQ 或 Kafka 把这个事件广播出去。最后，Config Client 收到事件后刷新本地 Environment，并重新创建或刷新带有 @RefreshScope 的 Bean。

@RefreshScope 很关键。配置刷新不是让所有对象都自动变成新值。只有那些被纳入刷新范围的 Bean，才会在刷新事件到来后重新读取配置。因此，运行时可能变化的配置类，通常会配合 @RefreshScope 使用。

Webhook + Bus 简单配置

Config Server 侧需要具备两个能力：接收仓库变更通知，以及把刷新事件发布到消息总线。因此需要添加 monitor 和 bus 相关依赖。以 RabbitMQ 为例：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-monitor</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bus-amqp</artifactId>
</dependency>

Config Client 侧也需要接入 Bus，因为客户端要能从消息总线接收刷新事件。同时还需要 Actuator 参与刷新相关能力。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bus-amqp</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Config Server 和 Config Client 要连接同一个消息代理。如果使用 RabbitMQ，可以配置连接信息。

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest

如果某个配置类需要运行时刷新，可以使用 @RefreshScope。

@Component
@RefreshScope
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

配置仓库的 Webhook 地址通常指向 Config Server 的 /monitor。本地测试时，也可以手动向 /monitor 发送请求，模拟仓库触发通知。

curl -X POST http://localhost:8888/monitor \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "path=user-service"

这里的 path=user-service 表示和 user-service 相关的配置发生变化，Config Server 会尝试将刷新事件发送给匹配的应用。

加密环境

配置中心集中管理配置后，新的问题出现了：敏感配置也会集中起来。数据库密码、Redis 密码、第三方接口密钥如果直接以明文形式存入 Git 仓库，一旦仓库权限配置不当、人员误操作、日志暴露或历史提交泄露，就可能造成安全问题。

所以，配置中心不仅要解决“配置统一管理”，还要解决“敏感配置如何安全存储”。Spring Cloud Config 的加密机制就是为这个问题服务的。

它的基本思路是：Git 仓库里不直接保存明文密码，而是保存以 {cipher} 开头的密文。Config Server 读取配置时识别到 {cipher} 前缀，就在返回给 Config Client 前完成解密。这样，仓库里是密文，业务服务拿到的是正常可用的明文配置。

加密与解密端点

Config Server 提供 /encrypt 和 /decrypt 两个端点。/encrypt 用来把明文变成密文，/decrypt 用来验证密文是否可以正确还原。

例如，把一个明文密码加密：

curl localhost:8888/encrypt -s -d mysecret

返回的密文需要加上 {cipher} 前缀后写入配置文件。

spring:
  datasource:
    username: appuser
    password: '{cipher}682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda'

如果使用 .properties 文件，加密值不要再额外加引号，否则可能影响解密。

spring.datasource.password={cipher}682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda

/decrypt 常用于本地验证密文是否正确。

curl localhost:8888/decrypt -s -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda

如果 Config Server 解密失败，它不会简单地把错误密文当成密码继续使用，而是可能生成带 invalid 前缀的属性。这种设计是为了避免密文被误当成真实密码传给客户端。

对称加密

对称加密的特点是加密和解密使用同一个密钥。它的优点是配置简单，非常适合学习和本地 demo。Config Server 只需要知道这个共享密钥，就能完成 /encrypt 和 /decrypt。

encrypt:
  key: mysecretkey

也可以用环境变量保存密钥，避免把密钥写死在配置文件中。

ENCRYPT_KEY=mysecretkey

对称加密的风险也来自这个“同一个密钥”。因为加密和解密都依赖它，一旦密钥泄露，别人就可以解密所有使用这个密钥生成的配置密文。所以对称加密虽然方便，但在生产环境中要非常重视密钥的存放和权限控制。

非对称加密

非对称加密使用一对密钥：公钥和私钥。通常可以用公钥加密，用私钥解密。它比对称加密更适合正式环境，因为加密能力和解密能力可以分离，密钥管理也更规范。

在 Spring Cloud Config 中，非对称加密通常通过 keystore 配置。可以用 JDK 自带的 keytool 创建测试密钥库。

keytool -genkeypair -alias mytestkey -keyalg RSA \
  -keystore server.jks

更完整的测试命令可以包含密码和证书信息。

keytool -genkeypair -alias mytestkey -keyalg RSA \
  -dname "CN=Web Server,OU=Unit,O=Organization,L=City,S=State,C=US" \
  -keypass changeme -keystore server.jks -storepass letmein

把生成的 server.jks 放到 Config Server 的 classpath 下，然后配置 keystore 信息。

encrypt:
  keyStore:
    location: classpath:/server.jks
    password: letmein
    alias: mytestkey
    secret: changeme

这里的 location 指向密钥库位置，password 用于打开密钥库，alias 指定使用哪个密钥，secret 是密钥自身的密码。相比对称加密，非对称加密配置更复杂，但安全边界更清晰。

复习总结

Spring Cloud Config 的知识链路可以从“配置管理”一路推到“自动刷新”和“安全加密”。

最开始的问题是微服务配置太分散，所以引入 Config Server 和 Config Client。Config Server 统一读取配置，Config Client 启动时拉取配置。配置集中之后，又会遇到运行时变更不生效的问题，所以引入刷新机制。手动刷新在多实例场景下成本高，于是使用 Webhook 发现配置仓库变化，再通过 Spring Cloud Bus 把刷新事件广播给所有相关客户端。配置集中管理后，敏感信息也被集中存储，因此还需要加密机制。Config Server 通过 {cipher}、/encrypt、/decrypt、对称密钥或非对称密钥库来保护敏感配置。

简化记忆如下：

Config Server 解决“配置统一放在哪里、怎么对外提供”。
Config Client 解决“业务服务启动时怎么拿配置”。
Webhook 解决“配置仓库变化后怎么通知 Config Server”。
Spring Cloud Bus 解决“Config Server 怎么把刷新事件广播给所有实例”。
@RefreshScope 解决“哪些 Bean 能在运行时重新加载配置”。
{cipher} 解决“敏感配置如何以密文形式保存在 Git 中”。
对称加密适合快速配置，非对称加密适合更正式的安全场景。

‍

Spring Cloud 核心概念

Sun, 10 May 2026 13:00:35 +0000

Spring Cloud 核心概念

Spring Cloud 简单概念笔记：Eureka、Nacos、OpenFeign 与 Gateway

版本说明：本文以 Spring Boot 3 / Spring Cloud 新版本思路为主。很多旧教程会使用 bootstrap.yml、Ribbon 等写法，学习时可以看，但自己写新项目时更建议优先使用 Spring Cloud LoadBalancer、spring.config.import 等新写法。

微服务里的几个核心问题

单体项目里，前端请求通常直接打到一个后端服务：

flowchart LR A[浏览器/客户端] --> B[单体后端应用] B --> C[(数据库)]

微服务项目拆分后，系统可能变成这样：

flowchart LR A[浏览器/客户端] --> G[Gateway 网关] G --> U[用户服务 user-service] G --> O[订单服务 order-service] G --> P[商品服务 product-service] O --> U O --> P U --> DB1[(用户库)] O --> DB2[(订单库)] P --> DB3[(商品库)]

拆分之后会出现几个新问题：

服务越来越多，调用方怎么知道某个服务现在在哪台机器、哪个端口？
同一个服务可能部署多个实例，请求应该打到哪一个实例？
服务上线、下线、宕机后，调用方如何及时感知？
公共认证、日志、限流、跨域等逻辑放在哪里更合适？
多个服务的配置如何统一管理、动态刷新？

对应到 Spring Cloud 生态中，常见组件分工如下：

问题	典型组件	作用
服务在哪里	Eureka / Nacos Discovery	服务注册与服务发现
多实例怎么选	Spring Cloud LoadBalancer / Nacos 权重	客户端负载均衡
服务之间怎么调用	OpenFeign	声明式 HTTP 远程调用
外部请求从哪里进	Spring Cloud Gateway	API 网关、统一入口
配置怎么统一管	Nacos Config / Spring Cloud Config	配置中心、动态配置

服务启动后注册到注册中心；调用方从注册中心发现目标服务实例；负载均衡器从多个实例中选一个；OpenFeign 发起服务间调用；Gateway 负责外部入口和公共过滤逻辑；Nacos 还可以统一管理配置。

Eureka：注册中心、服务注册与服务发现

Eureka 是什么

Eureka 是 Netflix OSS 体系里的服务注册与发现组件。它主要分成两类角色：

Eureka Server：注册中心，负责保存服务实例信息。
Eureka Client：微服务应用，启动后把自己注册到 Eureka Server，也可以从 Eureka Server 获取其他服务列表。

可以把 Eureka Server 理解成一个“服务通讯录”其他服务调用 user-service 时，不需要写死 IP 和端口，只需要通过服务名去查。

服务注册

服务注册指的是：服务启动后，把自己的服务名、IP、端口、健康状态等信息上报给注册中心。

以 user-service 为例，它启动时会把自己注册进去：

server:
  port: 8081

spring:
  application:
    name: user-service

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

spring.application.name 很关键，它就是服务名。服务之间一般不是通过 localhost:8081 调用，而是通过 user-service 这个逻辑名称调用。

服务发现

服务发现指的是：调用方根据服务名，从注册中心拿到目标服务的实例列表。

例如 order-service 想调用 user-service，它不需要知道 user-service 部署在哪，只需要知道服务名：

order-service -> 注册中心 -> 查询 user-service -> 得到实例列表 -> 选择一个实例调用

如果 user-service 有多个实例：

user-service
├── 192.168.1.10:8081
├── 192.168.1.11:8081
└── 192.168.1.12:8081

注册中心会保存这些实例，调用方再结合负载均衡策略选择一个。

Eureka 简单部署流程

第一步：创建 Eureka Server

依赖示例：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
</dependency>

启动类：

@SpringBootApplication
@EnableEurekaServer
public class EurekaServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApplication.class, args);
    }
}

配置文件：

server:
  port: 8761

spring:
  application:
    name: eureka-server

eureka:
  client:
    register-with-eureka: false
    fetch-registry: false
    service-url:
      defaultZone: http://localhost:8761/eureka/

这里的两个配置需要注意：

register-with-eureka: false：Eureka Server 不把自己当作普通服务注册。
fetch-registry: false：Eureka Server 不需要从自己这里拉取服务列表。

启动后访问：

http://localhost:8761

可以看到 Eureka 控制台。

第二步：创建服务提供者 user-service

依赖示例：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

配置文件：

server:
  port: 8081

spring:
  application:
    name: user-service

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

简单接口：

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return "user id = " + id;
    }
}

启动后，Eureka 控制台中会出现 USER-SERVICE。

第三步：创建服务消费者 order-service

server:
  port: 8082

spring:
  application:
    name: order-service

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

后面可以通过 OpenFeign 或 RestTemplate 调用 user-service。

负载均衡：为什么不能只调用一个实例

负载均衡解决什么问题

当一个服务部署多个实例时，请求不能永远打到同一个实例，否则会导致：

某台机器压力过大；
其他实例空闲浪费；
单个实例宕机后请求失败；
系统整体吞吐量上不去。

负载均衡就是在多个实例中选择一个实例来处理请求。

服务名调用与负载均衡

以前很多教程会讲 Ribbon，现在新版本更推荐 Spring Cloud LoadBalancer。

服务调用时通常不是这样写：

http://localhost:8081/users/1

而是这样写：

http://user-service/users/1

这里的 user-service 不是域名，而是注册中心中的服务名。调用流程大致是：

先根据 user-service 去注册中心拉取实例列表；
负载均衡器从列表里选一个实例；
把 http://user-service/users/1 转成类似 http://192.168.1.10:8081/users/1；
最后发起真正的 HTTP 请求。

常见负载均衡策略

常见策略包括：

轮询：第 1 次打实例 A，第 2 次打实例 B，第 3 次打实例 C，然后循环。
随机：随机选择一个实例。
权重：权重越高，被选中的概率越大。
同集群优先：消费者优先调用同一个集群或同一个机房内的服务实例。

Nacos：注册中心 + 配置中心

Nacos

Nacos 是阿里开源的动态服务发现、配置管理和服务管理平台。在 Spring Cloud Alibaba 体系中，Nacos 通常承担两个角色：

Nacos Discovery：服务注册与发现，类似 Eureka。
Nacos Config：配置中心，集中管理应用配置，支持动态刷新。

所以 Nacos 比 Eureka 的能力更综合。Eureka 主要关注服务注册发现，而 Nacos 同时可以做注册中心和配置中心。

Nacos 服务注册与发现

服务启动后，将自己注册到 Nacos：

server:
  port: 8081

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

启动多个服务后，可以在 Nacos 控制台看到服务列表。

Nacos 控制台默认地址通常是：

http://localhost:8848/nacos

常见默认账号密码是：

nacos / nacos

具体以你本地安装版本为准。

服务下线

服务下线有两种理解：

一种是应用真正停止。例如你关闭了某个 user-service 实例。注册中心会通过心跳或健康检查发现它不可用，然后把它从可用列表中剔除或标记异常。

另一种是手动下线实例。在 Nacos 控制台中可以把某个实例临时下线。这样它虽然进程还在，但消费者不会再优先调用它。

典型使用场景：

服务要灰度发布，先下线旧实例；
某台机器异常，先摘掉流量；
临时维护，不希望继续接收请求。

理解重点：

下线不是删除服务，而是让该实例暂时不参与调用。

权重配置

Nacos 支持给实例设置权重。权重越高，被调用的概率越大。

例如：

user-service 实例 A：权重 1
user-service 实例 B：权重 5

如果负载均衡策略使用权重，实例 B 大约会获得更多流量。

配置示例：

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        weight: 5

权重常用于：

新版本灰度发布：新版本先给较小权重，观察稳定后再逐步提高；
机器性能不同：高配置机器设置更高权重；
临时降流量：把某个实例权重调低。

flowchart LR C[consumer] --> LB[Nacos + LoadBalancer] LB -->|少量流量| A[user-service v1 / weight=1] LB -->|更多流量| B[user-service v2 / weight=5]

同集群优先

同集群优先的意思是：消费者优先调用与自己处在同一集群、同一机房或同一区域的服务实例。

例如：

上海集群：user-service A、order-service A
北京集群：user-service B、order-service B

上海的 order-service 优先调用上海的 user-service，北京的 order-service 优先调用北京的 user-service。

这个做的好处是网络延迟更低、跨机房调用更少，速度更加快。还有就是一个集群故障时，可以再考虑降级调用其他集群。

配置示例：

spring:
  cloud:
    nacos:
      discovery:
        cluster-name: SHANGHAI

如果要让 Spring Cloud LoadBalancer 更好地结合 Nacos 的集群信息，需要根据项目版本启用对应的 Nacos LoadBalancer 集成配置，例如：

spring:
  cloud:
    loadbalancer:
      nacos:
        enabled: true

权重解决“谁多接一点流量”，集群优先解决“尽量调用离我近的服务”。

环境隔离：Namespace、Group、DataId

Nacos 里常见的隔离概念有三个：

概念	用途	类比
Namespace	环境级隔离	dev、test、prod 三个空间
Group	分组隔离	同一环境下按业务线或项目分组
DataId	配置文件标识	`user-service-dev.yml`

最常用的是 Namespace。比如你可以创建三个命名空间：

dev      开发环境
test     测试环境
prod     生产环境

这样开发环境的服务和配置不会误连到生产环境。

示例：

spring:
  cloud:
    nacos:
      discovery:
        namespace: dev-namespace-id
      config:
        namespace: dev-namespace-id

注意：namespace 配的通常不是命名空间名称，而是命名空间 ID。

Nacos 配置中心

配置中心的价值是：把配置从代码包里抽出来，集中放到 Nacos 管理。

以前配置可能写在每个服务自己的 application.yml 中：

用了 Nacos Config 后，可以把这些配置放在 Nacos 控制台中。应用启动时从 Nacos 拉取配置，运行中还可以监听配置变化。

sequenceDiagram participant App as user-service participant Nacos as Nacos Config App->>Nacos: 启动时拉取 user-service-dev.yml Nacos-->>App: 返回配置内容 App->>App: 使用配置启动 Nacos-->>App: 配置变化通知 App->>App: 动态刷新部分配置

现代写法示例：

spring:
  application:
    name: user-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        group: DEFAULT_GROUP
        file-extension: yaml
  config:
    import:
      - optional:nacos:user-service-dev.yaml

如果使用动态刷新，可以配合 @RefreshScope，这就支持不用重新启动服务即可更改配置：

@RestController
@RefreshScope
public class ConfigController {

    @Value("${user.level:normal}")
    private String userLevel;

    @GetMapping("/config/user-level")
    public String getUserLevel() {
        return userLevel;
    }
}

在 Nacos 控制台修改配置后，接口返回值可以随配置变化而变化。

Nacos 简单部署流程

第一步：启动 Nacos Server

学习环境可以直接本地启动 Nacos 单机版，常见端口是8848

启动成功后访问：

http://localhost:8848/nacos

第二步：服务接入 Nacos Discovery

添加依赖：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

配置：

server:
  port: 8081

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

启动后在控制台查看服务列表。

第三步：服务接入 Nacos Config

添加依赖：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

配置：

spring:
  application:
    name: user-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
  config:
    import:
      - optional:nacos:user-service-dev.yaml

然后在 Nacos 控制台新建配置：

Data ID: user-service-dev.yaml
Group: DEFAULT_GROUP
配置格式: YAML

配置内容示例：

user:
  level: vip

第四步：多环境隔离

创建命名空间：

dev
prod

然后在服务配置中指定命名空间 ID：

spring:
  cloud:
    nacos:
      discovery:
        namespace: dev-namespace-id
      config:
        namespace: dev-namespace-id

这样开发环境服务只注册到开发环境空间，开发环境配置也只从开发空间读取。

Eureka 与 Nacos 的区别

对比项	Eureka	Nacos
定位	服务注册与发现	服务注册发现 + 配置中心 + 服务管理
生态	Netflix OSS / Spring Cloud Netflix	Spring Cloud Alibaba / Nacos 生态
配置中心	不提供，需要搭配其他组件	原生支持配置中心
控制台能力	相对简单，主要查看服务实例	更丰富，可管理服务、实例、权重、配置、命名空间等
权重配置	原生能力弱，通常依赖负载均衡策略扩展	原生支持实例权重
环境隔离	通常靠不同注册中心或配置区分	支持 Namespace、Group 等隔离方式
服务下线	更多依赖心跳和实例状态	控制台可更方便地下线实例、调整权重
适合场景	学习注册中心原理、传统 Spring Cloud 项目	国内项目常见，适合注册中心和配置中心统一管理

OpenFeign：声明式服务调用

OpenFeign 是什么

OpenFeign 是一个声明式 HTTP 客户端。所谓声明式，就是你不用手写完整的 HTTP 请求过程，只需要定义一个接口，Spring Cloud 会帮你生成代理对象去调用远程服务。

没有 Feign 时，你可能要写：

restTemplate.getForObject("http://user-service/users/1", String.class);

用了 Feign 后，你可以写成接口，服务类只需要实现这个接口功能即可。

@FeignClient(name = "user-service")
public interface UserClient {

    @GetMapping("/users/{id}")
    String getUser(@PathVariable("id") Long id);
}

在业务代码里像调用本地方法一样调用：

@Service
public class OrderService {

    private final UserClient userClient;

    public OrderService(UserClient userClient) {
        this.userClient = userClient;
    }

    public String getOrderUser(Long userId) {
        return userClient.getUser(userId);
    }
}

OpenFeign 调用流程

sequenceDiagram participant O as order-service participant F as OpenFeign 代理对象 participant R as 注册中心 Eureka/Nacos participant LB as LoadBalancer participant U as user-service O->>F: userClient.getUser(1) F->>R: 根据 user-service 查询实例 R-->>F: 返回实例列表 F->>LB: 选择一个实例 LB-->>F: 返回目标地址 F->>U: 发起 HTTP 请求 /users/1 U-->>F: 返回用户信息 F-->>O: 返回方法结果

OpenFeign 主要负责服务内部之间的远程调用， Gateway 是网关，是外部请求进入系统的统一入口。这两个很容易搞混

OpenFeign 简单部署流程

第一步：消费者服务添加依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

第二步：启动类开启 Feign

@SpringBootApplication
@EnableFeignClients
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

第三步：定义 Feign 接口

@FeignClient(name = "user-service")
public interface UserClient {

    @GetMapping("/users/{id}")
    String getUser(@PathVariable("id") Long id);
}

第四步：注入并调用

@RestController
@RequestMapping("/orders")
public class OrderController {

    private final UserClient userClient;

    public OrderController(UserClient userClient) {
        this.userClient = userClient;
    }

    @GetMapping("/{id}")
    public String getOrder(@PathVariable Long id) {
        String user = userClient.getUser(1L);
        return "order id = " + id + ", " + user;
    }
}

6.4 OpenFeign 常见注意点

@FeignClient(name = "user-service") 中的 name 一般写注册中心里的服务名。
@PathVariable 建议明确写变量名，例如 @PathVariable("id")。
OpenFeign 默认适合服务间 HTTP 调用，不适合传输特别大的文件。

Gateway：网关服务

Gateway

Spring Cloud Gateway 是微服务系统的 API 网关。它通常位于客户端和后端服务之间，作为统一入口。

flowchart LR A[前端/客户端] --> G[Spring Cloud Gateway] G --> U[user-service] G --> O[order-service] G --> P[product-service]

Gateway 常见职责：

路由转发：根据路径把请求转发到不同服务；
统一认证：判断用户是否登录、Token 是否有效；
日志记录：记录请求耗时、IP、路径；
跨域处理：统一配置 CORS；
限流降级：保护后端服务；
请求/响应改写：添加请求头、修改路径等。

Gateway 的三个核心概念

概念	作用	举例
Route 路由	定义请求转发到哪里	`/api/users/**`转发到`user-service`
Predicate 断言	判断请求是否匹配这条路由	Path、Method、Header、Host
Filter 过滤器	在请求前后做增强处理	鉴权、加请求头、日志、限流

一个请求进入 Gateway 后，大致流程如下：

sequenceDiagram participant C as Client participant G as Gateway participant P as Predicate participant F as Filter Chain participant S as Service C->>G: 发送请求 /api/users/1 G->>P: 判断匹配哪条 Route P-->>G: 匹配 user-service 路由 G->>F: 执行 pre 过滤器 F->>S: 转发到 user-service S-->>F: 返回响应 F->>G: 执行 post 过滤器 G-->>C: 返回结果

Gateway 简单部署流程

第一步：添加依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

如果要通过注册中心用服务名转发，还需要接入 Eureka 或 Nacos Discovery。

第二步：配置路由

以 Nacos 为例：

server:
  port: 10010

spring:
  application:
    name: gateway-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
    gateway:
      routes:
        - id: user-service-route
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1

        - id: order-service-route
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1

这里要理解几个点：

uri: lb://user-service 表示通过负载均衡调用注册中心里的 user-service。
Path=/api/users/** 表示路径匹配时才走这条路由。
StripPrefix=1 表示转发前去掉第一层路径，例如 /api/users/1 转成 /users/1。

请求链路：

客户端请求：/api/users/1
Gateway 匹配：Path=/api/users/**
StripPrefix=1 后：/users/1
转发目标：lb://user-service/users/1

GatewayFilter、GlobalFilter 与自定义 Filter

GatewayFilter

GatewayFilter 是路由级过滤器，只对某一条或某几条路由生效。

例如：

spring:
  cloud:
    gateway:
      routes:
        - id: user-service-route
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - AddRequestHeader=X-Source, gateway
            - StripPrefix=1

这个过滤器只对 user-service-route 生效。它会给转发到后端服务的请求添加请求头：

X-Source: gateway

常见内置 GatewayFilter：

Filter	作用
AddRequestHeader	添加请求头
AddResponseHeader	添加响应头
StripPrefix	去掉路径前缀
PrefixPath	添加路径前缀
RewritePath	重写路径
RequestRateLimiter	请求限流
Retry	请求失败重试

GlobalFilter

GlobalFilter 是全局过滤器，会对所有匹配到路由的请求生效。

它适合处理公共逻辑：

登录校验；
Token 解析；
请求日志；
灰度标记；
统一添加请求头；
统计请求耗时。

举一个简单实现栗子

@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");

        if (token == null || token.isBlank()) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }

        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -1;
    }
}

getOrder() 用来控制过滤器顺序。数值越小，优先级越高。

pre 与 post 过滤逻辑

Gateway 的过滤器通常可以分成两个阶段：

pre 阶段：请求转发到后端服务之前执行。
post 阶段：后端服务返回响应之后执行。

flowchart LR A[请求进入 Gateway] --> B[pre 过滤器：鉴权/日志/加请求头] B --> C[转发到后端服务] C --> D[post 过滤器：统计耗时/改响应头] D --> E[返回客户端]

pre 适合做：鉴权、参数校验、添加请求头、路径改写、限流。

post 适合做：响应日志、统计耗时、添加响应头、统一包装响应。

自定义 GatewayFilterFactory

如果你想写一个只在某些路由上生效的自定义过滤器，可以写自定义 GatewayFilterFactory。

示例：

@Component
public class CheckHeaderGatewayFilterFactory
        extends AbstractGatewayFilterFactory<CheckHeaderGatewayFilterFactory.Config> {

    public CheckHeaderGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            String value = exchange.getRequest().getHeaders().getFirst(config.headerName);

            if (value == null || value.isBlank()) {
                exchange.getResponse().setStatusCode(HttpStatus.BAD_REQUEST);
                return exchange.getResponse().setComplete();
            }

            return chain.filter(exchange);
        };
    }

    public static class Config {
        private String headerName;

        public String getHeaderName() {
            return headerName;
        }

        public void setHeaderName(String headerName) {
            this.headerName = headerName;
        }
    }
}

配置中使用：

spring:
  cloud:
    gateway:
      routes:
        - id: user-service-route
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - name: CheckHeader
              args:
                headerName: X-Token

命名规则要注意：

CheckHeaderGatewayFilterFactory -> 配置中写 CheckHeader

也就是说，类名一般以 GatewayFilterFactory 结尾，配置时去掉这个后缀。

8.5 自定义 GlobalFilter

如果逻辑对所有路由都生效，比如统一日志，可以写 GlobalFilter。

@Component
public class LogGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        long start = System.currentTimeMillis();
        String path = exchange.getRequest().getURI().getPath();

        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            long cost = System.currentTimeMillis() - start;
            System.out.println("path=" + path + ", cost=" + cost + "ms");
        }));
    }

    @Override
    public int getOrder() {
        return 0;
    }
}

理解重点：

GatewayFilter 更像“某条路由的局部增强”，GlobalFilter 更像“整个网关的全局拦截器”。

请求链路串联

学了这么多概念，在这里做一个简单的知识串联吧~

假设用户访问订单详情：

GET /api/orders/1001

完整流程如下：

sequenceDiagram participant C as Client participant G as Gateway participant N as Nacos/Eureka participant O as order-service participant F as OpenFeign participant U as user-service C->>G: GET /api/orders/1001 G->>G: GlobalFilter 鉴权、日志 G->>G: Predicate 匹配 /api/orders/** G->>N: 根据 order-service 查询实例 N-->>G: 返回 order-service 实例列表 G->>O: 负载均衡转发请求 O->>F: 调用 UserClient.getUser(userId) F->>N: 根据 user-service 查询实例 N-->>F: 返回 user-service 实例列表 F->>U: 负载均衡调用 user-service U-->>F: 返回用户信息 F-->>O: 返回结果 O-->>G: 返回订单详情 G->>G: post 过滤器记录耗时 G-->>C: 返回响应

Gateway：负责外部入口、路由、过滤器；
Nacos/Eureka：负责服务注册与发现；
LoadBalancer：负责从多个实例中选一个；
OpenFeign：负责服务内部之间的声明式 HTTP 调用；
Nacos Config：虽然不在请求链路中，但负责服务启动和运行时读取配置。

‍

微服务 - Jul1en

SkyWalking

SkyWalking

链路追踪

常见方案

选择 SkyWalking 的原因

核心组件

关键术语

安装部署

下载包说明

Docker Compose 部署

Spring Boot 服务接入

下载与放置 Java Agent

启动参数接入

Docker 中接入

自定义追踪

Toolkit 依赖

相关注解

日志关联与上传

添加依赖

编写 xml 文件

上传日志

告警

规则字段

Webhook

配置

排查顺序

Seata

Seata

为什么需要 Seata

Seata 的三个核心角色

CAP 和 BASE

CAP

BASE

两阶段提交（2PC）

阶段一：Prepare

阶段二：Commit or Rollback

主要问题

XA 模式

优缺点

AT 模式

优缺点

undo_log

本地锁与全局锁

一阶段

二阶段

写隔离

读隔离

TCC 模式

三个阶段

执行流程

业务接口

设计要求

TCC 的三个常见问题

优缺点

Saga 模式

状态机

补偿

故障恢复

隔离问题

四种模式怎么选

选择顺序

部署方式

Sentinel

Sentinel

主线

为什么微服务需要 Sentinel

一、流量控制

1. 为什么先学流控

2. 基于 QPS 和基于并发线程数的流控

3. 流控规则的核心字段

4. 三种流控模式，直接、关联、链路

直接模式

关联模式

链路模式

5. 流控效果：快速失败、warm up、排队等待

快速失败

warm up

排队等待

6. 热点参数限流