Java微服务 on Liangweidong's blog

异地多活：Java Web 微服务的高可用终极形态

Tue, 09 Jun 2026 00:00:00 +0000

异地多活：Java Web 微服务的高可用终极形态

Java Web 微服务系列 · 第 1 篇 · 异地多活阅读时长：约 28 分钟本文写于 2026 年 6 月

引子：机房炸了的那一夜

2018 年某日凌晨，杭州某互联网公司的主数据中心核心交换机突发故障，所有线上服务瞬间不可用。从用户端看：APP 加载失败、支付接口超时、客服电话被打爆、商家无法接单。技术团队用了 45 分钟完成故障切换，业务勉强恢复，但已经损失了数百万 GMV 和大量用户信任。

事后复盘：这次故障只是"机房级"——交换机坏了，换一台就好。

但如果是"城市级“灾难呢？地震、台风、洪水、光纤被施工队挖断、变电站爆炸……机房级灾备在这种场景下完全失效。你需要把整套系统分散到不同的城市，让任意一个城市"消失"时，其他城市依然能继续服务。

这就是异地多活。

但异地多活不是"建几个机房 + 同步数据"那么简单。跨城市的光纤延迟 30-100ms，是机内调用的 60 倍，直接照搬同城双活的架构会让系统慢到用户无法接受。这就是为什么业界演化出"单元化"这套精巧的设计。

一、核心概念：把术语先掰开

在正式进入架构演化史之前，先把几个核心术语定义清楚——很多文章混用"灾备/双活/多活"的概念，导致读者越看越糊涂。

1.1 什么是异地多活

异地多活（Geo-Distributed Active-Active）指在地理上分散的多个机房同时对外提供服务（读写流量），任意机房故障时其他机房可快速接管全部业务。

三个关键词：

地理分散：通常跨城市（北京-上海），距离 1000 公里以上
同时对外服务：所有机房都在线，不是主备关系
快速接管：故障时无需人工切换，其他机房自动承接流量

💡 原理：异地 vs 同城的本质区别

同城机房之间距离 < 100 公里，光纤往返延迟 < 1ms，可以"当一个机房用”。异地机房之间距离 1000+ 公里，光纤往返延迟 30-100ms，不能再当一个机房用——同步要异步化、调用要避免跨机房、状态要"单元化"。

1.2 高可用的衡量标准

可用性有明确的量化公式：

1

可用性 = MTBF / (MTBF + MTTR) × 100%

MTBF（Mean Time Between Failures）：平均故障间隔时间
MTTR（Mean Time To Repair）：平均恢复时间

业内用"N 个 9"描述：

可用性	年累计停机时间	日均停机
99.9%（3 个 9）	8.76 小时	1.44 分钟
99.99%（4 个 9）	52.6 分钟	8.6 秒
99.999%（5 个 9）	5.26 分钟	0.86 秒

异地多活是实现 4 个 9 以上可用性的必经之路。仅靠单机或主从架构，3 个 9 已经是极限。

📌 实践：4 个 9 是什么概念

假设你每天用某 APP 下单 1000 万次：

3 个 9：每天约有 14.4 分钟无法下单 → 约 1 万次失败

4 个 9：每天约有 8.6 秒无法下单 → 约 100 次失败

5 个 9：每天约有 0.86 秒无法下单 → 约 10 次失败

4 个 9 对应"一年内最多停机 52 分钟"，这已经是绝大多数大型互联网公司的目标。

1.3 两个关键指标：RTO 与 RPO

异地多活的效果要落到两个具体指标上：

RTO（Recovery Time Objective）：故障到恢复的时间——系统能停多久
RPO（Recovery Point Objective）：数据丢失的窗口——系统能丢多少数据

异地多活的理想目标：RTO ≈ 0（无感知切换）、RPO ≈ 0（不丢数据）。

方案	RTO	RPO
单机	不可恢复	全部丢失
主从副本	分钟级	秒级
同城双活	秒级	接近 0
异地双活	秒级	秒级（异步同步）
异地多活	秒级	接近 0

📌 实践：RTO/RPO 是和老板谈预算的最佳语言

别只说"系统要做异地多活"，要说"业务每年可接受的停机时间是 X 分钟，每次故障可接受的数据丢失是 Y 条"。这两个数字决定了架构选型。

老板们听不懂"高可用"和"灾备"，但听得懂"我一年最多能接受亏多少钱"。

二、架构演化史：从单机到异地多活

从单机到异地多活，业界走过了一段漫长的路。核心思想始终是"冗余"——用多份资源换取可用性。

2.1 七阶段演进时间线

graph LR
 A[单机] --> B[主从副本]
 B --> C[同城灾备]
 C --> D[同城双活]
 D --> E[两地三中心]
 E --> F[异地双活]
 F --> G[异地多活]
 
 style A fill:#e0e0e0
 style B fill:#b8d8d8
 style C fill:#a5d5d5
 style D fill:#92d2d2
 style E fill:#7fcfcf
 style F fill:#6ccccc
 style G fill:#457b9d,color:#fff

2.2 各阶段对比

阶段	抵御风险	恢复速度	复杂度	跨机房延迟	典型应用
单机	无	-	最低	-	内部工具、Demo
主从副本	服务器级	快	低	-	小型 SaaS
同城灾备（冷备）	机房级	慢（小时级）	中	1-5ms	传统企业 IT
同城灾备（热备）	机房级	较快（分钟级）	中	1-5ms	中型电商
同城双活	机房级	极快（秒级）	中	1-5ms	大型电商
两地三中心	城市级	较慢（人工决策）	较高	30-100ms	银行、金融
异地双活	城市级	极快（秒级）	高	30-100ms	大型互联网
异地多活	城市级 + 规模压力	极快（秒级）	最高	30-100ms	阿里、美团、字节

2.3 关键阶段详解

单机：一台机器打天下

所有服务和数据都在一台机器上。任何硬件故障 = 业务中断。这在 2000 年前的很多小公司很常见，今天只剩 demo 项目还在用。

主从副本：最基础的冗余

数据库主库 + 从库，主库写、从库读。服务器硬件故障时，从库可提升为主库。

优点：实现简单，MySQL 原生支持
缺点：故障切换需人工/脚本介入；切换延迟通常分钟级
典型场景：内部 OA、测试环境

同城灾备：机房级容灾

同城（< 100 公里）再建一个机房，实时同步数据。

冷备：仅做数据备份，不提供服务。故障时需要冷启动所有服务，小时级恢复
热备：实时同步数据 + 提前部署好所有服务，故障时可手动切流量，分钟级恢复

💡 原理：冷备 vs 热备的成本差

冷备只备份数据，成本是"一份存储 + 一点点带宽"。热备要部署完整服务栈，成本是"完整机房 + 完整运维"。很多公司为了省钱做冷备，结果故障时恢复 4 小时，损失 200 万——省小钱亏大钱。

同城双活：机房都承担流量

两个机房都接入流量，但写流量只走主机房，读可走任意机房。逻辑上仍视为一个机房。

优点：资源利用率高，机房级故障可自动切换
缺点：写流量仍是单点（主机房故障时切换仍需决策）

两地三中心：跨城市的折中

2 个城市 + 3 个机房：同城 2 机房双活 + 异地 1 机房灾备。常见于银行、金融、政企。

优点：兼顾机房级和城市级容灾
缺点：异地机房仍是冷/热备状态，资源浪费严重

🎯 避坑点：两地三中心 ≠ 异地双活

很多文章把"两地三中心"和"异地双活"混为一谈，其实完全不同：

两地三中心：异地机房是灾备（平时不接流量），故障时切

异地双活：异地机房平时也接流量，故障时对方接管

监管要求"两地三中心"是最低标准，异地双活是更高标准。

异地双活：迈向真正的多活

两个城市各建一个机房，都承担读写流量。任意城市故障时，另一个城市接管全部业务。

优点：真正解决城市级故障
难点：跨机房数据同步、调用延迟、状态一致性

异地多活：终态

3 个及以上城市部署机房，每个机房都是"主"。新增城市时无需重构同步链路。

优点：容量大、地域覆盖广、单机房故障影响小
难点：复杂度极高，运维成本巨大

💡 原理：演进的内在动力

业务量 ↑ → 故障域要求 ↑ → 单机房容量上限突破 → 必须分散到多机房业务连续性要求 ↑ → 城市级故障不可接受 → 必须跨城市资金可承受 → 多活成为合理选择

演进的本质是"成本 ↔ 可用性"的权衡，不是技术炫技。

三、为什么需要异地多活

3.1 城市级故障是真实存在的

来自云厂商的公开故障记录（不完全统计）：

2019 年 3 月：阿里云华北 2 地域可用区 C 因光缆中断服务异常
2022 年 12 月：腾讯云广州区域部分服务控制台异常
2023 年 8 月：多个云厂商海外 Region 因海底光缆故障网络抖动

自然灾害（地震、洪水、台风）、运营商故障（光缆挖断）、人为误操作（配置错误、误删数据）——城市级故障每年都在发生。

📌 实践：业务连续性分级

业务系统应按中断影响分级，决定采用哪种灾备方案：

等级业务类型 RTO RPO 推荐方案

P0 核心交易 < 5 分钟 < 1 分钟 异地多活

P1 重要业务 < 30 分钟 < 5 分钟同城双活 + 异地灾备

P2 一般业务 < 数小时 < 1 小时同城灾备（热备）

P3 后台系统 < 1 天 < 1 天主从副本即可

3.2 业务中断的代价

故障成本远不止"少卖几单"那么简单：

直接损失：交易系统每分钟损失数百万 GMV（双 11 期间可达千万级）
品牌损失：用户信任度下降，监管关注，媒体曝光
用户流失：一次大故障可能流失 5-10% 活跃用户
员工成本：全员熬夜处理，工时损失巨大
法律风险：金融、医疗行业有合规要求，故障可能引发监管处罚

🛑 误区警示

“我们小公司不会遇到城市级故障"——这是最常见的误判。即便你不用云厂商，你的云厂商会。2023 年某中型电商因云厂商 Region 故障停业 6 小时，直接损失过千万。

3.3 合规与出海

强监管行业：金融、证券、医疗——监管明确要求"两地三中心”
出海业务：海外 Region 故障率高于国内，且跨国专线更脆弱
上市/融资需求：投资人尽调会问"你们的灾备能力如何"

异地多活已经从"加分项"变成"必选项"。

四、具体怎么操作

这是本文最核心的部分。异地多活的实施分五大块：存储双向同步 → 单元化 → 兜底机制 → 全局数据例外 → 故障演练与监控。

4.1 存储层：双向同步

异地多活的前提是两个机房都能写。这要求数据层做双向同步。

主流存储的双向同步方案

存储	双向同步方案	工具 / 中间件	同步延迟	冲突解决
MySQL	双主模式 + binlog 同步	MySQL 原生双主、阿里 Canal、Otter	秒级	字段合并 / 业务回避
Redis	主从双向 + 冲突解决	RedisShake、自研中间件	毫秒级	LWW / 业务回避
MongoDB	Replica Set + Oplog	MongoShake、自研	秒级	版本号 / 业务回避
消息队列	双向 Topic + 幂等消费	Kafka MirrorMaker、RocketMQ	毫秒级	幂等去重
Elasticsearch	CCR 双向	ES CCR	秒级	版本号

MySQL 双主同步的两个坑

坑 1：自增 ID 冲突 双主都从 1 开始自增会重复写入。解决方案：

奇偶分片：A 库 auto_increment_increment=2, offset=1（1, 3, 5…）；B 库 offset=2（2, 4, 6…）
全局序列：用 Snowflake（机房号段区分）或 Redis incr 生成

坑 2：循环同步 A 同步给 B，B 同步给 A，会形成死循环。

🎯 避坑点：循环同步

MySQL 双主同步必须配置 replicate-wild-ignore-table 过滤掉"自己产生的 binlog"，否则会导致：

A 写一条记录 → 同步给 B

B 接收到后写入自己的 binlog → 又同步给 A

无限循环，主从延迟飙升

解决方案：使用 GTID 模式（MySQL 5.7+），每个事务有全局唯一 ID，已同步过的不再同步。

阿里 Canal 实战

Canal 是阿里开源的 MySQL binlog 订阅组件，常用于异地多活的增量同步：

1

MySQL Master → Canal Server（伪装成从库）→ Kafka → 消费端写入目标库

Canal 的优势：

伪装成 MySQL Slave，对主库零侵入
支持多种下游（Kafka、RocketMQ、RabbitMQ）
配合 Otter 可以做到全自动化同步 + 反向校验

Canal 部署架构

完整的 Canal 异地同步架构通常包含三层：

Canal Server 集群：每个机房部署 3-5 个 Canal Server 实例，负责订阅本机房 MySQL 的 binlog
Kafka 集群：作为 Canal Server 和消费端之间的消息缓冲，应对消费端故障或回溯
消费端集群：订阅 Kafka 消息，按顺序应用到目标机房

关键参数：

canal.instance.parser.parallel：是否并行解析 binlog（默认 true）
canal.instance.tsdb.enable：是否启用时间戳库（用于断点续传，必开）
kafka.batch.size：批量发送大小（建议 1000-5000）

📌 实践：增量同步 + 全量校验

异地多活的数据同步不能只做增量。还需要定期全量校验：

增量同步 Canal 负责（秒级延迟）

全量校验用 pt-table-checksum（小时级发现不一致）

不一致数据用 pt-table-sync 修复

增量只能保证"目前一致"，全量校验才能保证"历史一致"。

建议校验频率：核心表每小时一次，非核心表每天一次。漏掉校验的那一天，可能就是数据漂移的开始。

4.2 数据冲突：必须解决的根本问题

当同一数据被两个机房同时修改时，无法判定先后。

举例：用户在机房 A 修改了自己的昵称"张三"，同一秒在机房 B 登录并改成了"李四"。两个机房互相同步时，谁覆盖谁？

两种解决思路：

方案 1：中间件自动合并 依赖时钟排序，最后写入获胜（LWW, Last-Write-Wins）。问题是分布式时钟不准——NTP 同步误差可达 100ms，跨城市误差更大。

方案 2：从源头避免冲突——单元化（业界主流）

💡 原理：避免冲突 > 解决冲突

分布式系统有一句名言："不要试图用软件解决所有问题，要用业务设计避免问题"。单元化就是这种思路——从架构上保证同一数据只在一个机房被修改，冲突从根本上不存在。

4.3 单元化：异地多活的核心

在接入层之上加路由层，按规则把用户分流到固定机房，同一用户的所有业务在同一机房内闭环，根除跨机房调用。

graph TD
 U[用户请求] --> LB[负载均衡 SLB]
 LB --> R{路由层
用户ID mod N}
 R -->|余数 = 0| DC1[机房A]
 R -->|余数 = 1| DC2[机房B]
 R -->|余数 = 2| DC3[机房C]
 
 DC1 --> S1[本地服务A]
 DC2 --> S2[本地服务B]
 DC3 --> S3[本地服务C]
 
 S1 -.禁止跨机房.-> S2
 S2 -.禁止跨机房.-> S3
 
 style S1 fill:#a8dadc
 style S2 fill:#a8dadc
 style S3 fill:#a8dadc

三种分片规则

分片方式	适用场景	优点	缺点
按业务类型	业务边界清晰	实施简单	不适合通用业务
直接哈希分片	通用业务（电商、社交）	均衡分布	机房扩容需数据迁移
按地理位置	O2O（外卖、打车）	用户延迟低	用户跨地区会"漂移"

直接哈希分片示例

假设机房 A、B：

用户 ID % 2 == 0 → 机房 A
用户 ID % 2 == 1 → 机房 B

同一用户的所有读写都路由到固定机房，业务闭环。两个机房独立运行，不互相调用。

单元化的 3 大原则

入口唯一：每个用户从入口就被打上"属于哪个机房"的标签，后续所有调用都基于这个标签
数据本地化：用户数据只存在自己所属的机房，跨机房读通过异步同步
调用收敛：禁止跨机房 RPC 调用，必须通过数据复制或中转层

单元化的代价

单元化不是免费的：

业务改造：所有 RPC 调用要标注"是否跨机房"，跨机房调用要被显式禁止或转发
数据迁移：机房扩容时（如 2 机房变 3 机房）要重新计算哈希，迁移用户
全链路追踪：要能监控每个请求走的是哪个机房，否则出问题无法排查
全局服务特殊处理：支付、库存、配置等"全局服务"无法单元化，需要单独设计

4.4 兜底机制

路由规则理论上保证用户不漂移，但实际会有边界情况：

跨机房调用（如支付、库存等全局服务）
机房切换时的请求路由
用户的"漂移"（如出差、出国）

解决方案：在写存储时检测数据归属。

写入前判断"这条数据属于哪个机房"
如果不属于本机房，报错或转发到正确机房

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// 伪代码：写存储前的归属检测
public void saveOrder(Long userId, Order order) {
 String targetDC = router.getDCByUserId(userId); // 计算用户归属机房
 String currentDC = DataCenterContext.current(); // 当前机房
 if (!targetDC.equals(currentDC)) {
 // 通过 RPC 转发到正确机房
 rpcClient.to(targetDC).saveOrder(userId, order);
 return;
 }
 // 本机房写库
 orderRepository.save(order);
}

📌 实践：兜底是单元化的"安全网"

单元化路由 + 兜底检测 = 双保险。

路由层：99.99% 的请求路由到正确机房

兜底层：剩下 0.01% 的异常请求被拦截或转发

缺一不可。没有兜底的单元化，出一次事故就要全量排查。

4.5 全局数据例外

不是所有数据都要双活。

强一致数据（系统配置、商品库存、汇率、订单号生成器）仍采用"写主机房、读从机房“方案：

这类数据写入频率低，强一致要求高
跨机房写入延迟反而更糟

策略：

数据类型	同步方案	一致性保障	典型工具
配置中心	单点写 + 多点读	ZK/Consul/Nacos 推 + 定时拉	Nacos
全局 ID	机房号段隔离	Snowflake 41 位时间戳 + 5 位机房号	美团 Leaf
库存系统	单点写 + 异步同步	异步消息 + 失败重试	RocketMQ
订单流水	双活单元化	同用户订单落在同机房	-
支付清算	单点写 + 多点读	T+1 同步 + 实时对账	-

🛑 误区警示

盲目追求"全部双活"是常见错误。

全局数据双活得不偿失：成本 3-5 倍，但收益仅"机房级容灾”

同城双活 + 异地灾备已能满足 P1 业务

只对 P0 业务做异地多活即可

4.6 故障演练：必须做的事

异地多活的最大风险是"平时一切正常，故障时不会切"。

Chaos Engineering（混沌工程）：主动制造故障，验证切换流程。

演练清单

单机房断网（拔网线模拟）
单机房电源中断
数据库主从切换
跨机房专线中断
DNS 污染
CDN 故障
整机房故障（最严酷场景）

演练频率

新机房上线前：必须通过完整演练
日常：每月一次小规模演练
大版本上线前：必须做一次全链路演练
年度：至少一次"整机房故障"演练

🎯 避坑点：演练 ≠ 文档

很多团队写了"故障切换手册"就以为高枕无忧。手册没演练过 = 不存在。真正打过几次"实战"，你才知道手册哪些步骤是错的、哪些是过时的、哪些根本没有可执行性。

某互联网公司在 2020 年做第一次真实整机房演练时发现，切换脚本里的目标机房 ID 写错了 3 年没人发现——因为从没真正切过。

Netflix Chaos Monkey 的启发

Netflix 是混沌工程的鼻祖，开源了 Chaos Monkey 系列工具：

Chaos Monkey：随机杀掉生产环境的 EC2 实例
Latency Monkey：注入网络延迟
Conformity Monkey：找不符合最佳实践的实例并关掉

Netflix 的哲学："在生产环境演练，而不是在测试环境"。只有真实流量下的故障切换才有意义。

4.7 监控告警：异地多活的"心跳"

异地多活的监控比传统架构复杂得多——要同时监控"业务指标“和”基础设施指标"。

三层监控

层级	监控指标	告警阈值	工具
基础设施	CPU、内存、磁盘、网络、专线延迟	标准运维阈值	Prometheus + Grafana
中间件	DB 主从延迟、MQ 积压、缓存命中率	按业务定制	Prometheus + 自研 Exporter
业务侧	机房分流比例、跨机房调用比例、错误率	偏离基线 > 5%	SkyWalking + 自研监控

拨测：业务侧的"心跳"

从公网模拟用户请求，每分钟拨测各机房关键接口：

拨测失败率 > 1% → 告警
拨测延迟 > 基线 2 倍 → 告警

📌 实践：拨测是异地多活的"生命线"

基础设施监控正常 ≠ 业务可用。唯一可靠的判断是"从公网调用业务接口是否成功"。

拨测要在公网多个地域部署，不能只部署在机房内—— 否则你连"机房和公网之间的网络"出故障都不知道。

推荐拨测点：北京、上海、广州、深圳 + 海外 1-2 个城市（AWS 东京/新加坡）。

业务侧的关键指标

除了技术指标，异地多活还有几个业务侧专属指标必须监控：

机房分流比例：A 机房 50%、B 机房 50% 是健康态。漂移到 70/30 说明有 bug
跨机房调用比例：理论上接近 0。突然飙升说明单元化规则被破坏
异地同步延迟：MySQL 同步延迟、消息同步延迟。超过 5 秒要告警
用户漂移率：同一用户多次访问落到不同机房的比例。> 1% 就要排查

五、真实案例

5.1 阿里：三地五中心

阿里在 2015 年完成"三地五中心“架构：

3 个城市：杭州、北京、深圳
5 个机房：每城市 1-2 个
每个单元都独立支撑全量业务

关键技术：

单元化 + 异地多活
OceanBase 分布式数据库（保障数据一致性）
异地专线 + 自研流量调度系统

阿里的核心思想：”异地多活不是分布式系统的子集，而是全新的架构范式"——业务设计要按"单元"组织，数据存储要按"单元"分布，流量调度要按"单元"分发。

5.2 美团：两地三中心

美团采用"两地三中心“架构（北京 + 上海）：

北京 2 机房 + 上海 1 机房
单元化按用户 ID 分片
金融级业务做异地双活，O2O 业务做同城双活

美团的特点：

业务分级：金融级（支付、贷款）= 异地双活；O2O（外卖、到店）= 同城双活
自研中间件：自研 OCTO 服务框架 + 自研同步组件
业务容错：单元化失败时，降级到同城双活 而不是直接挂掉

5.3 字节跳动：单元化 + 异地

字节的多活架构特点：

国内多个 Region，海外多个 Region
单元化粒度更细（按服务级别）
自研 Service Mesh 治理跨机房调用

字节的核心创新：

Service Mesh 跨机房治理：跨机房调用通过 Mesh 自动处理（限流、重试、降级）
全链路单元化：从入口网关到数据库，全部带"机房标签”
多语言统一：Go/Java/Python 服务都能融入单元化框架

💡 原理：单元化是异地多活的"第一性原理"

不论叫"三地五中心"还是"两地三中心"，核心都是：

业务单元化划分（让用户绑死在某个机房）

存储层双向同步（让机房之间数据可写）

最上层分片逻辑（决定请求去哪）

任何异地多活方案，缺一不可。

六、总结

6.1 异地多活的 3 大核心要素

业务单元化划分——让同一用户的所有请求在同一机房完成
存储层双向同步——让两个机房都能写
最上层分片逻辑——决定请求去哪

6.2 实施成本

异地多活不是"装个软件就完事"，需要配套建设：

业务层：微服务部署、依赖拆分、SDK、Web 框架
基础设施：服务发现、流量调度、CI/CD、同步中间件
数据保障：数据分类、一致性保障、机房切换一致性
运维：监控体系、异常处理、故障演练

6.3 何时不该上异地多活

业务特征	推荐方案
用户量 < 100 万	同城双活
强监管（金融）	两地三中心
O2O 业务	同城双活 + 异地灾备
业务中断可接受数小时	同城灾备（热备）

异地多活的 ROI 拐点在"日活 1000 万 + 业务连续性要求 4 个 9"。低于这个规模做了也是浪费。

6.4 异地多活的常见陷阱

🛑 误区警示：这些坑别踩

盲目上异地双活：业务量没到，成本先到

忽视单元化改造：直接照搬同城双活，性能差 60 倍

不做故障演练：手册写了等于零，必须真打实战

过度追求强一致：所有数据都双活，成本爆炸

忽视运维成本：复杂度是同城的 5 倍，团队要相应扩

异地多活是"用钱换命"的工程，不是技术炫技。

📌 工程实践：异地多活的成本对比

成本对比（同业务量级）：

单机：1x

同城双活：2-3x

异地双活：5-8x

异地多活：10-15x

决策前先问：

业务真的需要 4 个 9 吗？

城市级故障的发生概率是多少？

一次大故障的最大损失是多少？

异地多活的成本，多久能通过"避免的损失"回本？

6.5 系列预告

这是 Java Web 微服务系列 的开篇。后续计划覆盖：

服务治理：服务发现、配置中心、熔断降级
网关与限流：Spring Cloud Gateway、Sentinel
分布式事务：Seata、Saga、TCC 模式对比
链路追踪：SkyWalking、Jaeger
Spring Cloud Alibaba 实战：Nacos + Sentinel + Seata 三件套

七、异地多活实施清单

如果你决定启动异地多活项目，按以下清单逐项检查，可以少踩很多坑。

7.1 业务层 Checklist

业务分级：明确 P0/P1/P2/P3 业务，确定哪些要异地多活
用户标识：确定分片键（用户 ID / 租户 ID / 业务 ID）
单元化拆分：按分片键拆分服务调用链，画出"业务-数据-机房"映射图
全局服务识别：识别无法单元化的服务（支付、库存、配置中心），单独设计
跨机房调用禁止：通过 Service Mesh 或代码规范禁止跨机房 RPC
数据归属检测：所有写操作前检测数据归属机房

7.2 数据层 Checklist

数据库选型：MySQL 用双主 + GTID；Redis 用 RedisShake；MQ 用 MirrorMaker
同步中间件：部署 Canal + Kafka 集群，保证 binlog 不丢失
全量校验：pt-table-checksum 定期跑，pt-table-sync 修复
ID 方案：改用 Snowflake / Leaf 分布式 ID，不用自增
数据分类：明确"双活数据"和"全局数据"的边界
冲突解决策略：每个表写明冲突解决方式（LWW / 业务回避 / 人工合并）

7.3 流量层 Checklist

入口打标：在负载均衡 / 网关层就打上"用户属于哪个机房"的标签
路由层高可用：路由层本身要异地多活（最关键，不能单点）
健康检查：实时探测机房健康度，自动剔除故障机房
DNS 切流：准备好 DNS 切流脚本，故障时一键切换
灰度切流：先切 1% 流量观察，再切 10%、50%、100%

7.4 运维层 Checklist

监控大盘：业务侧 + 中间件 + 基础设施三层监控
拨测系统：公网多地域拨测，覆盖核心接口
告警分级：P0 故障 5 分钟内电话告警到负责人
故障演练：每月小演练、季度大演练、年度整机房演练
Runbook：每个故障场景有对应 Runbook，且 至少演练过一次
复盘机制：每次故障 24 小时内复盘，输出 Action Item 跟踪

7.5 团队层 Checklist

架构师：至少 2 名资深架构师能讲清楚单元化路由
DBA：有异地多活 MySQL 双主运维经验
SRE：能做混沌工程演练
值班：7×24 小时值班，异地多活的故障不分昼夜
跨团队协作：业务 / 后端 / 数据 / SRE / 安全团队对齐

🎯 避坑点：清单的 80/20 法则

上面 30+ 项检查，80% 的项目栽在前 10 项：

业务分级不清晰

全局服务识别不全

跨机房调用没禁住

ID 方案没换

入口没打标

路由层单点

没有全量校验

没做故障演练

Runbook 是摆设

团队没准备好

先把前 10 项做好，再考虑剩下的。

八、实战案例：同城双活生产落地方案（A 主 B 备，A 挂 B 自动接管）

真实场景：自建同城双机房，域名 + GTM 用阿里云，应用跑在自建 k8s，MySQL/Redis 自建。目标：A、B 机房同时承担流量（A 主 B 备），A 挂了 B 自动接管，A 恢复后自动回稳。

8.1 需求清单

需求	说明
同城双活	自建机房，< 1ms 延迟
A 主 B 备	A 是 MySQL 主库，B 是备库
平时 AB 同时分担流量	写 100% 走 A，读 50% A + 50% B
A 挂了 B 接管全部流量	20-30 秒全自动
A 恢复后自动回稳	Orchestrator 自动切回 A
B 挂了不影响业务	A 独立承担全部

8.2 架构总览

 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


 用户
 │
 ▼
 ┌──────────────────┐
 │ 阿里云 GTM │
 │ api.example.com │
 │ A:100 / B:0 │ ← 平时
 │ A:0 / B:100 │ ← A 挂时
 └────────┬─────────┘
 │ DNS 解析
 ┌──────────────┴──────────────┐
 ▼ ▼
 ┌──────────────────┐ ┌──────────────────┐
 │ 机房 A │ │ 机房 B │
 │ 10.0.0.0/24 │ │ 10.0.1.0/24 │
 │ │ │ │
 │ ┌────────────┐ │ │ ┌────────────┐ │
 │ │ k8s 集群 │ │ │ │ k8s 集群 │ │
 │ │ 3-100 副本 │ │ │ │ 3-100 副本 │ │
 │ └─────┬──────┘ │ │ └─────┬──────┘ │
 │ │ │ │ │ │
 │ ┌─────▼──────┐ │ │ ┌─────▼──────┐ │
 │ │ ProxySQL-A │ │ │ │ ProxySQL-B │ │
 │ │ 10.0.0.50 │ │ │ │ 10.0.1.50 │ │
 │ └─────┬──────┘ │ │ └─────┬──────┘ │
 │ │ │ │ │ │
 │ ┌─────▼──────┐ │ 半同步 │ ┌─────▼──────┐ │
 │ │ MySQL-A │──│──binlog─►│ │ MySQL-B │ │
 │ │ (主→备) │ │ < 1ms │ │ (备→主) │ │
 │ │ 10.0.0.1 │ │ │ │ 10.0.1.1 │ │
 │ │ VIP: │ │ │ │ VIP: │ │
 │ │10.0.0.100 │ │ │ │10.0.1.100 │ │
 │ └────────────┘ │ │ └────────────┘ │
 │ │ │ │
 │ ┌────────────┐ │ │ ┌────────────┐ │
 │ │ Redis-A │──│─Sentinel│─►│ Redis-B │ │
 │ └────────────┘ │ 多数派 │ └────────────┘ │
 └──────────────────┘ └──────────────────┘
 │ │
 └─────────────┬───────────────┘
 │
 ┌───────▼────────┐
 │ Orchestrator │ 部署在 B 机房
 │ 10.0.1.100:3000│
 └────────────────┘

8.3 关键组件选型

组件	选型	理由
DNS 流量调度	阿里云 GTM	机房级流量切换
MySQL HA	Orchestrator	GitHub 在维护、Web UI、A 恢复后自动切回
流量代理	ProxySQL	读写分离 + 应用层透明
VIP 漂移	keepalived	同子网标准玩法
Redis HA	Sentinel	官方方案，3 节点跨机房
k8s	kubespray 自建双集群	Ansible 部署生产级
监控	Prometheus + Grafana + AlertManager	CNCF 标准栈

💡 原理：为什么 Orchestrator 部署在 B 机房

关键洞察：B 平时是备库，挂了不影响主业务。

A 挂了 → Orchestrator 在 B，能自动切 B 为主

A 恢复 → Orchestrator 在 B，能自动把 A 加回集群、自动切回 A

B 挂了 → Orchestrator 也没了，但 A 还是主，业务不受影响（只是失去自动切换能力）

这是用业务容错换运维简化——A 挂了能切，A 恢复能切回，B 挂了业务无感。不需要 Raft 3 节点那么复杂。

8.4 MySQL HA 配置

主库 `/etc/my.cnf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


[mysqld]
server-id = 1
log-bin = mysql-bin
binlog-format = ROW
gtid-mode = ON
enforce-gtid-consistency = ON
log-slave-updates = ON

# ⚠️ 半同步（核心）
plugin-load = "rpl_semi_sync_master=semisync_master.so"
rpl_semi_sync_master_enabled = 1
rpl_semi_sync_master_timeout = 1000
rpl_semi_sync_master_wait_for_slave_count = 1

innodb_flush_log_at_trx_commit = 1
sync_binlog = 1
character-set-server = utf8mb4
report-host = 10.0.0.1

备库：server-id=2、report-host=10.0.1.1，加 plugin-load = "rpl_semi_sync_slave=semisync_slave.so"、rpl_semi_sync_slave_enabled=1。

创建用户（主库执行）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- 半同步复制用户
CREATE USER 'repl'@'10.0.%' IDENTIFIED BY 'ReplPass@123Str0ng';
GRANT REPLICATION SLAVE ON *.* TO 'repl'@'10.0.%';

-- Orchestrator 监控用户
CREATE USER 'orchestrator'@'10.0.%' IDENTIFIED BY 'OrchPass@123';
GRANT SUPER, PROCESS, REPLICATION SLAVE, RELOAD ON *.* TO 'orchestrator'@'10.0.%';
GRANT SELECT ON mysql.* TO 'orchestrator'@'10.0.%';

-- ProxySQL 监控用户
CREATE USER 'proxysql'@'10.0.%' IDENTIFIED BY 'ProxySQL@123';
GRANT REPLICATION CLIENT ON *.* TO 'proxysql'@'10.0.%';

备库指向主库

1
2
3
4
5
6
7
8


CHANGE MASTER TO
 MASTER_HOST='10.0.0.1',
 MASTER_USER='repl',
 MASTER_PASSWORD='ReplPass@123Str0ng',
 MASTER_AUTO_POSITION=1;
START SLAVE;
SHOW SLAVE STATUS\G
-- 验证 Slave_IO_Running: Yes, Slave_SQL_Running: Yes, Seconds_Behind_Master: 0

8.5 keepalived VIP（同子网内）

A 机器 /etc/keepalived/keepalived.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


vrrp_script check_mysql {
 script "/usr/bin/mysqladmin ping -h 127.0.0.1 -uorchestrator -pOrchPass@123"
 interval 2
 weight -30
 fall 3
}

vrrp_instance VI_1 {
 state MASTER
 interface eth0
 virtual_router_id 51
 priority 100
 advert_int 1
 unicast_src_ip 10.0.0.1
 unicast_peer { 10.0.1.1 }
 authentication { auth_type PASS, auth_pass YourVrrpPass }
 virtual_ipaddress { 10.0.0.100/24 }
 track_script { check_mysql }
}

B 机器：state BACKUP、priority 90、unicast_src_ip 10.0.1.1，VIP 改为 10.0.1.100/24。

🎯 避坑点：VIP 不能跨机房飘

VIP 只能在同子网内飘，跨子网 ARP 广播不生效。两个机房各一个 VIP 独立飘，不互相干扰。

8.6 Orchestrator 部署（B 机房）

/etc/orchestrator.conf.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
 "MySQLTopologyUser": "orchestrator",
 "MySQLTopologyPassword": "OrchPass@123",
 "MySQLReplicaUser": "repl",
 "MySQLReplicaPassword": "ReplPass@123Str0ng",

 "RecoverMasterPrimary": true,
 "RecoverIntermediatePrimary": true,
 "FailMasterPromotionOnLagMinutes": 1,
 "RecoveryPeriodBlockSeconds": 30,
 "ApplyMySQLPromotionAfterMasterFailover": true,

 "InstancePollSeconds": 2,
 "BackendDB": "sqlite://var/lib/orchestrator/orchestrator.db",
 "HttpPort": 3000,
 "ListenAddress": "0.0.0.0:3000",

 "PostFailoverProcesses": ["/usr/local/bin/post-failover.sh"],

 "RecoveryHostnameAlias": {
 "10.0.0.1": "mysql-a",
 "10.0.1.1": "mysql-b"
 }
}

post-failover.sh 自动钩子

 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


#!/bin/bash
set -e
LOG=/var/log/orchestrator/post-failover.log
echo "$(date '+%Y-%m-%d %H:%M:%S') PostFailover triggered" >> $LOG

NEW_MASTER=$(orchestrator-client -c which-instance-is-master 2>/dev/null | awk '{print $2}')
NEW_MASTER_IP=$(echo $NEW_MASTER | cut -d: -f1)

# 改两个 ProxySQL 的 hostgroup
for PROXYSQL_HOST in 10.0.0.50 10.0.1.50; do
 mysql -uadmin -padmin -h$PROXYSQL_HOST -P6032 <<EOSQL
UPDATE mysql_servers SET hostgroup=0 WHERE hostname='${NEW_MASTER_IP}' AND port=3306;
UPDATE mysql_servers SET hostgroup=1 WHERE hostgroup=0;
LOAD MYSQL SERVERS TO RUNTIME;
SAVE MYSQL SERVERS TO DISK;
EOSQL
done

# 激活新主 VIP
ssh root@$NEW_MASTER_IP "/usr/bin/systemctl restart keepalived"
sleep 3

# 告警
curl -X POST "https://oapi.dingtalk.com/robot/send?access_token=xxx" \
 -H 'Content-Type: application/json' \
 -d "{\"msgtype\":\"text\",\"text\":{\"content\":\"⚠️ 自动切换完成，新主: $NEW_MASTER_IP\"}}"

echo "PostFailover done" >> $LOG

📌 实践：ApplyMySQLPromotionAfterMasterFailover: true 是关键

这一个配置实现"A 恢复后自动切回 A"——Orchestrator 看到 A 重新可达，自动把 A 加回集群，A 追平数据后自动 promote A 为主。全程 0 人工。

8.7 ProxySQL 部署（每个机房一个）

 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


# /etc/proxysql.cnf
datadir="/var/lib/proxysql"

admin_variables=
{
 admin_credentials="admin:admin"
 mysql_ifaces="0.0.0.0:6032"
}

mysql_variables=
{
 threads=4
 max_connections=2048
 interfaces="0.0.0.0:6033"
 monitor_username="proxysql"
 monitor_password="ProxySQL@123"
}

mysql_servers =
(
 { address="10.0.0.1", port=3306, hostgroup=0, max_connections=500 },
 { address="10.0.1.1", port=3306, hostgroup=1, max_connections=500 }
)

mysql_replication_hostgroups =
(
 { writer_hostgroup=0, reader_hostgroup=1 }
)

mysql_query_rules =
(
 { rule_id=1, match_pattern="^SELECT .* FOR UPDATE$", destination_hostgroup=0 },
 { rule_id=2, match_pattern="^SELECT", destination_hostgroup=1 },
 { rule_id=3, match_pattern=".*", destination_hostgroup=0 }
)

mysql_users =
(
 { username="app_user", password="AppUser@123", default_hostgroup=0, max_connections=500 }
)

应用配置：

1
2
3
4
5


spring:
 datasource:
 # A 机房应用连 A 的 ProxySQL
 # B 机房应用连 B 的 ProxySQL
 url: jdbc:mysql://10.0.0.50:6033/order

平时：写走 hostgroup 0（A），读走 hostgroup 1（B）。 A 挂时：post-failover 钩子改 hostgroup，B 升 hostgroup 0，写读都走 B。

8.8 Redis Sentinel

3 个 Sentinel 节点跨机房分布（A 2 + B 1，避免脑裂）：

1
2
3
4
5
6
7


# /etc/redis-sentinel.conf
port 26379
daemonize yes
sentinel monitor mymaster 10.0.0.60 6379 2
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel auth-pass mymaster YourRedisPass@123

应用配置：

1
2
3
4
5
6


spring:
 redis:
 sentinel:
 master: mymaster
 nodes: 10.0.0.61:26379,10.0.0.62:26379,10.0.1.61:26379
 password: YourRedisPass@123

🎯 避坑点：Sentinel 节点不要都放 A 机房

3 个 Sentinel 如果都放 A，A 挂了 3 个全死，无法决策。A 2 + B 1 分布确保 A 挂了仍能 2 票决策。

8.9 k8s 双集群

机房 A 集群：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


apiVersion: apps/v1
kind: Deployment
metadata: { name: order-service }
spec:
 replicas: 3
 template:
 spec:
 containers:
 - name: app
 env:
 - { name: DATACENTER, value: "dc-a" }
 - { name: DB_URL, value: "jdbc:mysql://10.0.0.50:6033/order" }
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: order-service-hpa }
spec:
 minReplicas: 3
 maxReplicas: 100
 metrics:
 - type: Resource
 resource: { name: cpu, target: { type: Utilization, averageUtilization: 60 } }

机房 B 集群：replicas: 3，DB_URL 改为 B 的 ProxySQL。

📌 实践：机房 B 平时为什么不是 0 副本

有些方案建议"机房 B 平时 0 副本，A 挂了扩到 100"——这是错的：

“AB 同时分担流量"需要 B 也有应用实例承担读流量

0 副本意味着 B 平时不接流量，违反"双活"语义

A 挂了扩到 100 副本要 30-60 秒（启动慢）

B 平时 3 副本：承担读流量 + A 挂了 30 秒内扩到 100

8.10 故障切换全流程

场景 1：A 挂了 → B 升主

1
2
3
4
5
6
7
8


T+0s A 失联
T+2s B 机房 Orchestrator 探测 A 失联
T+5s 二次确认
T+15s promote B 为新主
T+15s post-failover.sh 钩子自动：
 ├─ 改两个 ProxySQL hostgroup
 └─ 激活 B VIP
T+20s 业务全自动恢复 ✅

场景 2：A 恢复 → 自动切回 A

1
2
3
4
5
6
7
8


T+30min A 恢复
T+30min Orchestrator 自动把 A 加回集群
 - A 执行 CHANGE MASTER TO B
 - A 应用 B 的 binlog
T+1h A 追平数据
T+1h Orchestrator 自动切回 A 为主 ← ⚠️ ApplyMySQLPromotionAfterMasterFailover
 - post-failover.sh 再次触发
T+1h+ 稳态恢复

关键：A 追平 B 的时间

核心公式：

1

追平时间 = B 期间写的数据量 ÷ MySQL 复制速度

MySQL 复制速度（ROW 格式半同步）：

硬件配置	复制速度	1 GB 追平时间
高配（NVMe SSD + 万兆网）	500-1000 MB/s	1-2 秒
中配（SSD + 千兆网）	100-200 MB/s	5-10 秒
普通（SATA SSD）	50-100 MB/s	10-20 秒

追平时间估算表：

A 失联时间	中等业务追平量	追平时间（高配）
秒级	< 1 MB	0 秒
1 小时	~100 MB	几秒
半天	~500 MB - 5 GB	几秒 - 1 分钟
1 天	~1-50 GB	几秒 - 几分钟
1 周	~10-500 GB	几秒 - 1 小时
1 个月	~50 GB - 5 TB	几小时 - 1 天

判断追平进度（A 机器执行）：

1
2
3


SHOW SLAVE STATUS\G
-- 重点看 Seconds_Behind_Master: 0 (已追平)
-- Read_Master_Log_Pos == Exec_Master_Log_Pos (binlog 应用完毕)

Orchestrator 的保护：

1
2
3
4


{
 "FailMasterPromotionOnLagMinutes": 1, // 延迟 > 1 分钟不切
 "ApplyMySQLPromotionAfterMasterFailover": true // 自动切回 A
}

Orchestrator 切回 A 的逻辑：

A 加回集群，开始追 B 的 binlog
持续监控 Seconds_Behind_Master
等 Seconds_Behind_Master = 0 才切
A 数据没追平时不会切回，不会丢数据

🎯 避坑点：特殊场景——大库追平

A 失联超过 1 周（B 写了 100+ GB 数据）：单纯 binlog 复制太慢，用 xtrabackup 物理备份：

B 上做物理备份（xtrabackup --backup）

拷贝到 A

A 替换数据目录（xtrabackup --copy-back）

A 接 binlog 追最后一段增量

切回 A

总耗时 2-4 小时。

💡 原理：A 失联 1 天内的真实场景

中等业务 A 失联 1 天，B 期间写 ~1-10 GB：

追平时间：分钟级

Orchestrator 等追平后自动切回 A

业务感知：完全无感，0 人工

这正是 ApplyMySQLPromotionAfterMasterFailover: true 的价值——全自动，不需要 DBA 守在屏幕前。

场景 3：B 挂了

1
2
3
4
5
6


T+0s B 失联
 - A 还是主，业务无影响
 - Orchestrator 也挂了（但不影响业务）
T+30min B 恢复
T+30min Orchestrator 自动重启（systemd 拉起）
T+30min Orchestrator 接管监控

场景 4：备库 B 短暂失联 → 自动追 A

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


T+0s B 失联（B 机器死 / 网络断 / 重启）
 ├─ A 还是主，业务无影响
 ├─ Orchestrator 探测 B 失联（但不切——B 是备）
 └─ ProxySQL 探测 B 不可用，自动剔除 B
 读流量全部回 A

T+X min B 恢复（B 机器 / MySQL 重新启动）
 ├─ B 自动启动 SLAVE
 ├─ B 用 GTID 协议自动定位 A 当前 binlog 位置
 ├─ B 自动拉取并应用 binlog
 └─ B 持续追平

T+X min + 追平时间 B 追平
 ├─ Seconds_Behind_Master = 0
 ├─ ProxySQL 自动把 B 加回 hostgroup 1
 └─ 读流量恢复 A + B 分担

关键：B 失联期间 A 还在主位，业务完全无感。B 恢复后 MySQL GTID 复制原生自动追——0 人工、0 配置。

追平时间估算（B 失联时间 → 追平耗时）：

B 失联时间	中等业务追平量	追平时间（高配）	追平时间（普通）
1 分钟	< 10 MB	< 1 秒	< 1 秒
1 小时	~100 MB - 1 GB	几秒	几秒 - 1 分钟
1 天	~10-100 GB	几秒 - 几分钟	几分钟 - 半小时
1 周	~50 GB - 500 GB	几秒 - 半小时	半小时 - 1 小时

判断追平进度（B 机器执行）：

1
2
3
4
5


SHOW SLAVE STATUS\G
-- 重点看：
-- Slave_IO_Running: Yes
-- Slave_SQL_Running: Yes
-- Seconds_Behind_Master: 0 ← 0 = 追平

💡 原理：B 追 A 是 MySQL 自己的事

A 追 B（A 失联恢复）→ 涉及主从角色切换，需要 Orchestrator 协调

B 追 A（B 失联恢复）→ 备库追上主库，MySQL GTID 复制原生自动

这是 MySQL 主从复制的核心能力，不需要任何额外配置。

🎯 避坑点：大库追平（> 100 GB）

B 失联超过 1 周（A 写了 100+ GB）时，单纯 binlog 复制太慢：

用 xtrabackup 物理备份：A 备份 → 拷贝到 B → B 替换数据目录 → 接 binlog 追增量

总耗时 2-4 小时

但这种场景罕见——B 失联 1 天内追平都是分钟级，完全可接受。

RTO 总结

阶段	耗时	谁做
A 失联 → Orchestrator 探测	2-5s	自动
Orchestrator 二次确认	5-10s	自动
promote B + 切流量	15-20s	自动
数据库层 RTO	20-30s	全自动
k8s B 副本扩容	30-60s	自动
GTM 切流 + DNS TTL 过期	1-5min	半自动
完整 RTO（A 挂）	1-5min
备库 B 失联恢复（追平 A）	分钟级（B 失联 1 天内）	全自动（MySQL GTID 复制）

8.11 落地 Checklist

阶段 1：基础设施（1-2 周）

同城专线开通（< 1ms 延迟）
机房之间防火墙放通（3306/6379/6033/26379/3000/9090/6443/443）
时间同步（chrony，机房间 < 1ms 偏差）
SSH 免密（所有机器之间互信）

阶段 2：MySQL HA（1 周）

MySQL 8.0 安装（主 + 备）
半同步 + GTID 配置
keepalived 部署（同子网 VIP 验证）
Orchestrator 部署（B 机房）
演练 1：kill A mysqld → 30s B 升主

阶段 3：ProxySQL（3 天）

每个机房部署 ProxySQL
应用连接本地 ProxySQL
验证读写分离

阶段 4：Redis HA（3 天）

Redis 主从 + Sentinel 3 节点
演练 2：kill A Redis → 15s 切 B

阶段 5：k8s（1-2 周）

kubespray 部署机房 A 集群
kubespray 部署机房 B 集群
应用部署（A 3 副本 + B 3 副本）
HPA 配置
演练 3：杀光 A Pod → B HPA 扩容

阶段 6：监控告警（1 周）

Prometheus + Grafana + AlertManager
mysqld_exporter / redis_exporter / node_exporter
blackbox_exporter 多地域拨测
告警规则（半同步降级必须电话级）

阶段 7：GTM（2 天）

阿里云 GTM 配置
健康检查 URL 指向 /health
DNS TTL = 60 秒
演练 4：摘 A → GTM 切 B

阶段 8：端到端演练（1 周）

演练 5：拔 A 网线 → 整套自动恢复
演练 6：A 恢复 → 自动切回 A
演练 7：kill A mysqld → 整套自动恢复
Runbook 完善
DBA 培训

阶段 9：灰度上线（1 周）

1% 流量灰度 → 1 周
10% → 3 天
50% → 3 天
100% 上线

🎯 避坑点：演练是核心

写好的脚本不演练等于不存在：

演练必须包含全部场景：A 挂、A 恢复、B 挂、双机房挂

每次演练都验数据一致性：SHOW SLAVE STATUS + 业务对账

演练失败要修脚本：不要凑合"差不多”

月度常态化演练：保持肌肉记忆

8.12 风险与缓解

风险	影响	缓解
DNS TTL 是 RTO 瓶颈	切流后老用户等 1-5min	TTL 60 秒 + 切流前调小
半同步降级为异步	RPO 突然变差	半同步状态告警必须电话级
Orchestrator 误切	数据丢失	`FailMasterPromotionOnLagMinutes: 1` 保护
post-failover.sh bug	切换后 ProxySQL 没切	必须演练 5+ 次，第一次发现 bug 很正常
机房 B k8s 启动慢	A 挂时 B 扩到 100 慢	镜像预热 + 应用启动优化
A 恢复后追数据慢	切回 A 延迟	大库用 `mysqldump` + 物理备份恢复

🛑 误区警示：Orchestrator 部署位置

不要部署在 A 机房——A 挂了 Orchestrator 也挂，没人能自动切

不要以为 B 机房就完美——B 挂了 Orchestrator 也没了，但 A 还是主，业务不受影响，只是失去自动切换能力

正确：Orchestrator 部署在 B 机房，接受 B 挂了失去自动切换能力（业务不受影响），B 恢复后自动起来接管

这是用业务容错换运维简化的最优解——比 Raft 3 节点简单一个数量级。

8.13 成本估算

自建方案年成本约 ¥24 万（含 30 台服务器 5 年折旧、同城专线、阿里云 GTM + 域名 + 拨测公网 IP、机房机柜电力）。对比阿里云托管方案（PolarDB + Tair + ACK）约 ¥60-80 万/年，自建节省 60-70%。

九、常见问题 FAQ

Q1：异地多活和微服务是什么关系？

A：微服务是架构风格，异地多活是部署形态。两者正交：

微服务可以单机部署（最简单）
微服务可以同城双活部署（最常见）
微服务可以异地多活部署（最高级）
单体应用也可以做异地多活（少见但可行）

微服务让"单元化"更容易实施（服务粒度细，可以独立切分），但异地多活不强制要求微服务。

Q2：异地多活和分布式事务是什么关系？

A：强烈不建议在异地多活架构上用分布式事务。

分布式事务（2PC / 3PC / TCC）依赖"事务协调者"在多个机房之间协调，跨机房延迟 30-100ms 会让事务延迟飙升到秒级。用户无法接受秒级的下单响应。

异地多活的正确做法：通过单元化避免跨机房事务。如果实在无法避免（全局服务），用最终一致性（异步消息 + 幂等消费）替代强一致事务。

Q3：异地多活一定要用云厂商吗？

A：不一定。自建机房也可以做异地多活，但成本更高：

自建机房要买地、买设备、招运维
云厂商提供现成的 Region + 专线 + 中间件

多数公司选择公有云 + 多 Region 部署。少数大厂（阿里、字节）会自建机房 + 私有云。

Q4：异地多活最大的坑是什么？

A：根据多家公司公开复盘，最大的坑是"故障时不会切"。

具体表现：

切换脚本 3 年没演练过，目标机房 ID 是错的
切换流程依赖某个离职员工的个人经验
监控系统告警了但没人知道该做什么
切过去后业务不通，又切回来，来回切几次

异地多活不是"建好就完事"，没有持续演练的异地多活形同虚设。

Q5：异地多活的成本能降下来吗？

A：能，但有上限。

降成本的方向：

复用云厂商资源：用公有云 + 容器化，资源按需扩缩
共享存储：用云数据库（RDS / PolarDB）替代自建 MySQL，运维成本降 50%
自动化运维：用 K8s + Operator 自动化部署和切换
共享中间件：用 Nacos / Sentinel / Seata 等开源组件替代自研

但底线是：异地多活的硬件成本不会低于同城的 3-5 倍。这是物理规律（要买双倍资源），不是软件能省的。

Q6：异地多活和 Service Mesh 是什么关系？

A：Service Mesh 是异地多活的"好搭档"。

异地多活要求"禁止跨机房调用"，Service Mesh 可以在 Sidecar 层面自动拦截所有跨机房调用：

标记请求属于哪个机房
拦截违规的跨机房调用
自动重试 + 限流
统一的灰度切流

没有 Service Mesh 也能做异地多活（靠代码规范 + 人工 Review），但有 Service Mesh 会轻松很多。Istio / Linkerd / 自研 Mesh 都是常见选择。

Q7：异地多活会影响性能吗？

A：会，但可控。

性能影响来源：

入口打标 + 路由：每次请求多 1-3ms（路由层查询）
同步复制：写入延迟可能增加（等同步完成）
跨机房调用：理论上 0，违规时可能 30-100ms

通过单元化设计，可以把跨机房调用控制在 0.01% 以下。剩下的性能开销 ≈ 3-5ms，用户几乎感知不到。

十、推荐阅读

如果想深入异地多活的工程实践，以下资料值得一读：

书籍：

《数据密集型应用系统设计》（DDIA, Martin Kleppmann）—— 分布式系统圣经，第 5、6 章讲复制与分区
《大型网站技术架构：核心原理与案例分析》（李智慧）—— 阿里技术专家作品，前几章讲架构演化

公开技术博客：

阿里中间件团队博客：异地多活、双 11 备战系列
美团技术团队博客：OCTO 框架、单元化实践
字节跳动技术博客：Service Mesh 与多活架构

开源组件：

Canal：阿里开源 MySQL binlog 订阅
Otter：阿里开源数据库同步工具
RedisShake：Redis 数据同步
MongoShake：MongoDB 数据同步
Nacos：阿里开源服务发现 + 配置中心
Sentinel：阿里开源流量治理

💡 学习路径建议

入门：本文 + DDIA 第 5 章，理解复制模型

进阶：阿里中间件博客 + 美团 OCTO 系列，理解工业实践

实战：研究 Canal / Sentinel / Seata 源码，理解组件原理

深潜：动手做小规模双活 PoC，体验真实延迟与同步问题

理论 + 实践 + 源码，缺一不可。

参考文章

腾讯云开发者社区 - 异地多活架构

从 Nginx 到 LVS：流量调度在异地多活中的角色与实操

Tue, 09 Jun 2026 00:00:00 +0000

Java Web 微服务系列 · 第 2 篇 · 流量调度阅读时长：约 38 分钟本文写于 2026 年 6 月前置阅读：《异地多活：Java Web 微服务的高可用终极形态》（系列第 1 篇）

引子：流量调度是异地多活的"前哨班"

系列第 1 篇《异地多活：Java Web 微服务的高可用终极形态》我们讲清楚了"业务单元化 + 存储双向同步 + 流量层分片"是异地多活的三大支柱，并画了完整的架构图。但那张图里最顶上的"用户请求"到"机房入口"之间，其实藏着一层很多人会忽略的细节——流量调度层。

本文约定：本篇是系列第 2 篇，专攻"流量调度"这一层。读完你会知道：阿里、美团、字节这些大厂的异地多活架构，流量入口不是单一组件，而是"公网 LB → LVS → Nginx → 应用网关“四级串联的"前哨班”。

我们用一个真实场景开场：

2021 年某电商双 11 零点，入口流量是平时的 30 倍。第一道前哨——DNS 解析——把用户路由到最近的 CDN 边缘节点，扛掉了 80% 的静态请求。剩下 20% 的动态请求进入机房后，第二道前哨——LVS——在内核态做四层负载，把 50 万 QPS 均匀分给后方的 8 台 Nginx。第三道前哨——Nginx——做七层路由（按 Host 头、URL 路径分流到不同微服务）。三层前哨环环相扣，任意一层挂掉，下一层都能自动承接。

这就是流量调度的全部奥秘——冗余 + 分流 + 自动故障切换。本篇按"单机 → 双机 → 集群 → 跨城"的演进顺序，把这条前哨班完整搭一遍。实操部分会给你完整可复制粘贴的命令清单，2 台虚拟机就能跑通整套 LVS + Keepalived + Nginx 链路。

一、流量调度的本质：4 层 / 7 层 / 高可用

异地多活架构里，“流量调度"听起来抽象，本质就是回答三个问题：

用户的请求先到谁？（入口选择）
到达入口后怎么分给后端？（负载均衡）
后端某台机器挂了怎么办？（高可用）

1.1 三层位置：流量调度在异地多活中的定位

先把流量调度放到异地多活的整体架构里看：

graph TD
 U[用户请求] --> DNS[DNS
GSLB全局负载]
 DNS --> CDN[CDN边缘
静态请求]
 CDN -.未命中.-> LB[公网LB
机房入口]
 LB --> LVS[LVS四层
内核态]
 LVS --> NG[Nginx七层
应用路由]
 NG --> GW[Spring Cloud Gateway
微服务路由]
 GW --> APP[微服务集群
异地多活单元化]

 style DNS fill:#457b9d,color:#fff
 style LB fill:#457b9d,color:#fff
 style LVS fill:#1d3557,color:#fff
 style NG fill:#1d3557,color:#fff
 style APP fill:#a8dadc

这张图里，流量调度对应"公网 LB → LVS → Nginx"这三层。本篇只讲这三层（DNS / CDN 属于另一条线，Spring Cloud Gateway 是微服务层的网关，留给系列第 3 篇）。

1.2 4 层 vs 7 层：性能与灵活性的权衡

维度	4 层（L4）	7 层（L7）
工作层级	传输层（TCP/UDP）	应用层（HTTP/HTTPS）
看的信息	源 IP、目标 IP、端口	全部 HTTP 头、URL、Cookie、Body
典型代表	LVS、Haproxy（四层模式）、AWS NLB	Nginx、Tengine、Envoy、Traefik
性能	几十万 QPS（内核态）	1-5 万 QPS（用户态）
加密终结	不终结 TLS	可终结 TLS（看 https 证书）
路由能力	仅 IP/端口级	Host / URL / Header / Cookie 级
典型用途	入口抗量、跨机房流量分发	域名路由、灰度、A/B 测试

💡 原理：4 层为什么快？

4 层负载工作在 Linux 内核协议栈的 IPVS（IP Virtual Server）层，数据包在内核态就被转发了，不再上送用户态。7 层负载必须把整个 TCP 流接完、解析 HTTP 头，才能决定转发给谁，至少多两次上下文切换 + 一次内存拷贝。

这就是 LVS 能扛 50 万 QPS 而 Nginx 只能扛 1-5 万 QPS 的根本原因。不是 LVS 算法多牛，是它根本不离开内核。

1.3 流量调度的核心目标

不论用 Nginx 还是 LVS，流量调度的目标都只有 3 个：

均匀：把请求均匀分给后端机器，避免热点
健康：自动剔除故障机器，恢复后自动加回
切换：主节点故障时，备用节点秒级接管（Keepalived 负责）

这 3 个目标对应负载均衡算法、健康检查、故障转移三个具体机制。后文逐个讲。

1.4 4 层 vs 7 层：一场持续 20 年的争论

从 2002 年 Nginx 诞生起，“4 层够用还是必须 7 层"就是架构圈反复争论的话题。本质上是性能 vs 灵活性的取舍：

4 层派的论据：

内核态转发，单包转发延迟 < 10 微秒
看不到应用层数据 = 更安全（攻击面小）
协议无关，MySQL / Redis / MQTT / 游戏 TCP 都能代理

7 层派的论据：

能看 HTTP 头，按 URL 路由 / 按 Cookie 灰度 是刚需
TLS 终结在反代层，后端明文 HTTP 性能高 3 倍
业务错误码（如 5xx）能被反代识别，故障定位更准

实战结论（业界 20 年沉淀的共识）：

入口第一跳用 4 层（LVS）抗量
入口第二跳用 7 层（Nginx）做业务路由
不要"用 7 层做 4 层的事”——比如用 Nginx 做 MySQL 代理，性能差 10 倍
不要"用 4 层做 7 层的事”——比如想用 LVS 按 URL 路由，做不到

💡 原理：4 层 + 7 层是"串联"不是"二选一"

真正的生产架构是 4 层在前、7 层在后，串联成两层。4 层负责"抗量 + 入口安全"，7 层负责"业务路由 + 灰度"。每一层做自己擅长的事，不要试图用一层解决所有问题。

1.5 为什么"切换"比"均衡"更重要？

很多初学者以为负载均衡的核心是"算法选哪个"（轮询、最少连接、一致性哈希……）。错。真正决定系统可用性的是故障切换速度：

算法选错：后端 3 台机器变成 2 台在干活，QPS 降 33%，用户可能没感知
切换太慢：后端 1 台机器挂了，10 秒内没人接管，所有打到这台机器的请求都失败，用户感知强烈

所以本文会用大量篇幅讲 Keepalived 和 LVS 的故障切换——这才是流量调度的"命门"。

二、单机 Nginx：1 万 QPS 的边界

2.1 Nginx 凭什么成为"事实标准"

Nginx 2002 年由俄罗斯工程师 Igor Sysoev 写出来，最初是为了解决 C10K 问题——单机如何同时处理 1 万个并发连接。采用事件驱动的异步非阻塞模型，用 1 个 worker 进程就能扛几千个连接。

核心设计：

Master-Worker 模型：1 个 master 进程负责管理，N 个 worker 进程负责处理请求（worker_processes auto 默认等于 CPU 核数）
事件循环：每个 worker 用 epoll（Linux）/ kqueue（BSD）系统调用，单线程处理所有连接
内存占用低：每个连接约 2-4 KB，而 Apache 一个进程一个连接要 1-2 MB

2.2 反向代理的最简配置

Nginx 做反向代理的最核心 3 段配置：

 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


# /etc/nginx/nginx.conf

http {
 # 1. 定义后端集群
 upstream backend {
 server 192.168.1.10:8080 weight=1 max_fails=3 fail_timeout=30s;
 server 192.168.1.11:8080 weight=1 max_fails=3 fail_timeout=30s;
 server 192.168.1.12:8080 weight=1 max_fails=3 fail_timeout=30s;
 }

 # 2. 终结 TLS（可选）
 server {
 listen 443 ssl;
 ssl_certificate /etc/nginx/cert/server.crt;
 ssl_certificate_key /etc/nginx/cert/server.key;

 # 3. 路由到后端
 location / {
 proxy_pass http://backend;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }
 }
}

3 段配置的职责：

upstream：声明后端服务器列表 + 负载均衡参数
server { listen 443 ssl }：终结 HTTPS
proxy_pass http://backend：把请求转给 upstream，这是反向代理的"反"字所在——客户端只看到 Nginx，看不到后端

2.3 性能调优三件套：worker / connection / keepalive

Nginx 默认配置偏保守，生产环境必须调 3 个参数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 主配置
worker_processes auto; # worker 数 = CPU 核数
worker_rlimit_nofile 65535; # 每个 worker 能打开的最大文件数

events {
 worker_connections 8192; # 每个 worker 能同时处理的连接数
 multi_accept on; # 一次 accept 多个连接
 use epoll; # Linux 强制用 epoll
}

http {
 sendfile on; # 零拷贝发送文件
 tcp_nopush on; # 合并多个 TCP 包
 tcp_nodelay on; # 禁用 Nagle 算法

 # 关键：keepalive 调优（与后端连接）
 upstream backend {
 server 192.168.1.10:8080;
 keepalive 32; # 与每台后端保持 32 个长连接
 keepalive_timeout 60s; # 长连接超时 60 秒
 keepalive_requests 1000; # 单个长连接最多处理 1000 个请求后关闭
 }
}

3 个核心参数的内在逻辑：

参数	含义	调优依据
`worker_processes`	worker 进程数	等于 CPU 核数；过多导致上下文切换开销
`worker_connections`	每 worker 最大连接	受 `worker_rlimit_nofile` 限制；理论最大并发 = workers × connections
`keepalive`	与后端保持的长连接数	关键！默认 0（每次新建 TCP 连接）会导致 TIME_WAIT 飙升

🎯 避坑点：keepalive 默认 0 的隐形坑

Nginx 默认与后端不保持长连接（upstream 里没有 keepalive 指令时）。每个 HTTP 请求都要 3 次握手 + 4 次挥手，并发一大就出现：

TIME_WAIT 状态连接数飙升（端口耗尽）

后端 CPU 飙升（accept 新连接 + 关闭旧连接的开销）

生产配置必加 keepalive 32（与每台后端保持 32 个长连接池）。这是 Nginx 性能调优的"第一性原则"。

2.4 单机瓶颈：1 万 QPS 的天花板

调优到极致后，单机 Nginx 的上限大约：

静态文件：5-10 万 QPS（取决于磁盘 IO / CDN 协同）
动态反代：1-3 万 QPS（受后端应用限制）
TLS 终结：5-8 千 QPS（CPU 密集，受证书算法影响）

单机撑不住怎么办？ 两条路：

路径	适用场景	代价
垂直扩展（换更牛机器）	业务量增长 50% 以内	边际成本急剧上升，10 万 QPS 后失效
水平扩展（多加几台 Nginx）	长期增长	需要在前置加一层负载均衡——这就引出了 Keepalived 和 LVS

📌 实践：什么时候单机 Nginx 就够了？

经验值：

日活 < 10 万：单机 Nginx 足够

日活 10-100 万：Nginx + Keepalived 双机

日活 > 100 万或强 SLA 4 个 9：LVS + Keepalived + Nginx 三层塔

但强可用性要求的系统（金融、交易、支付），即使日活不高也要 LVS 三层塔——因为单机 Nginx 挂了就全挂，没有容错。

2.5 epoll 详解：Nginx 高并发的"内功心法"

Nginx 能扛高并发，核心在于它使用了 epoll（Linux 2.6+ 内核提供的 I/O 多路复用接口）。要理解 epoll 是什么，先看传统模型的瓶颈：

传统 BIO（Blocking I/O）模型：

1
2
3
4
5


// 伪代码：每连接一线程
while (true) {
 int fd = accept(server_fd, ...); // 阻塞等待新连接
 pthread_create(worker, handle_client, fd); // 每连接开 1 个线程
}

1 万并发 = 1 万个线程。每个线程默认栈 8 MB，光内存就要 80 GB。上下文切换开销也爆炸。

NIO（Non-blocking I/O）+ epoll 模型：

1
2
3
4
5
6
7
8
9


// 伪代码：单线程事件循环
struct epoll_event events[MAX_EVENTS];
int epfd = epoll_create(1);
while (true) {
 int n = epoll_wait(epfd, events, MAX_EVENTS, -1); // 阻塞等待事件
 for (int i = 0; i < n; i++) {
 handle_event(events[i]); // 处理就绪的连接
 }
}

epoll 的 3 个关键优势：

优势	含义
事件驱动	只处理"就绪"的连接，未就绪的连接不消耗 CPU
O(1) 就绪查询	不管 1 万还是 100 万连接，就绪查询都是 O(1)
内核-用户态共享内存	通过 `mmap` 避免每次事件都从内核复制到用户态

Nginx 的 worker 进程 = 1 个 epoll 循环。1 个 worker 处理 1 万连接只需几十 MB 内存。这就是 Nginx “小马拉大车"的秘密。

🎯 避坑点：worker 数不是越多越好

常见错误：worker_processes 32（机器才 8 核）。32 个 worker 抢 8 个 CPU，频繁上下文切换，性能反而下降。

正确配置：worker_processes auto（让 Nginx 自动检测 CPU 核数）。worker 数 = CPU 核数是经验最优值。

三、Nginx + Keepalived：同城双活的"经典双子星”

3.1 为什么需要 Keepalived

单机 Nginx 的"高可用"问题是：Nginx 机器本身挂了怎么办？

用户访问的 IP 是 Nginx 机器的 IP，Nginx 挂了，IP 跟着没了。必须有一个"备用 Nginx"能在主 Nginx 挂掉时接管 IP——这就是 Keepalived 干的事。

graph LR
 U[用户] --> V[Virtual IP
192.168.1.100]
 V -->|平时| M[Master Nginx
192.168.1.10]
 V -.故障时.-> B[Backup Nginx
192.168.1.11]
 M --> APP1[应用 1]
 M --> APP2[应用 2]
 B --> APP1
 B --> APP2

 style M fill:#1d3557,color:#fff
 style B fill:#457b9d,color:#fff

Virtual IP（VIP） 是关键：用户访问的 192.168.1.100 不是任何机器的物理 IP，而是一个虚拟 IP，由 Keepalived 在主备机器之间漂移。

3.2 VRRP 协议：VIP 漂移的原理

Keepalived 的核心是 VRRP 协议（Virtual Router Redundancy Protocol，虚拟路由冗余协议）：

多台机器组成一个"VRRP 路由器组"，共享一个 VIP
选出一台 Master，其他是 Backup
Master 周期性（默认 1 秒）发送 VRRP 通告（advertisement）
Backup 收不到通告（连续 3 次 = 3 秒）就认为 Master 挂了，自己升级为 Master，接管 VIP
Master 恢复后默认会"抢占"回 VIP（可通过 nopreempt 关闭）

💡 原理：为什么是 3 秒而不是立刻切换？

默认 3 秒切换是权衡：

太快（< 1 秒）：网络抖动会被误判为故障，导致"双 Master"脑裂

太慢（> 10 秒）：业务已经超时，用户感知到中断

3 秒是保守且工程化的折中值。生产环境可通过 vrrp_script 自定义健康检查，把切换时间压到 1-2 秒。

3.3 Keepalived 配置实战（主备模式）

3.3.1 准备 2 台机器

角色	IP	说明
Master	192.168.1.10	主 Nginx，持有 VIP
Backup	192.168.1.11	备 Nginx，平时空闲
VIP	192.168.1.100	对外服务的虚拟 IP

两台机器都装好 Nginx（监听 VIP）+ Keepalived。

3.3.2 Master 配置 `/etc/keepalived/keepalived.conf`

 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


! Configuration File for keepalived

global_defs {
 router_id NGINX_MASTER # 唯一标识，集群内不能重复
 script_user root
 enable_script_security
}

# 健康检查：Nginx 进程是否存活
vrrp_script check_nginx {
 script "/usr/local/bin/check_nginx.sh"
 interval 2 # 每 2 秒检查一次
 weight -20 # 失败时优先级降 20
 fall 3 # 连续失败 3 次才认为故障
 rise 2 # 连续成功 2 次才算恢复
 timeout 2 # 单次检查超时 2 秒
}

# VRRP 实例定义
vrrp_instance VI_1 {
 state MASTER # 初始状态 MASTER
 interface eth0 # 绑定的网卡
 virtual_router_id 51 # 虚拟路由 ID（主备必须一致）
 priority 100 # 优先级（MASTER > BACKUP）
 advert_int 1 # VRRP 通告间隔 1 秒
 authentication {
 auth_type PASS
 auth_pass 1111 # 简单密码，生产建议复杂
 }
 virtual_ipaddress {
 192.168.1.100/24 dev eth0 label eth0:1 # VIP 配置
 }
 track_script {
 check_nginx # 引用上面的健康检查
 }
 nopreempt # 故障恢复后不抢占（避免抖动）
 notify_master "/usr/local/bin/notify.sh master"
 notify_backup "/usr/local/bin/notify.sh backup"
 notify_fault "/usr/local/bin/notify.sh fault"
}

3.3.3 Backup 配置（只改 3 处）

1
2
3
4
5


vrrp_instance VI_1 {
 state BACKUP # ← 改成 BACKUP
 priority 90 # ← 优先级低于 MASTER
 # 其他完全一致
}

3.3.4 健康检查脚本 `/usr/local/bin/check_nginx.sh`

1
2
3
4
5
6
7


#!/bin/bash
# 检查 Nginx 是否存活
count=$(ps -ef | grep "nginx: master process" | grep -v grep | wc -l)
if [ $count -eq 0 ]; then
 exit 1 # 失败返回非 0
fi
exit 0

1

chmod +x /usr/local/bin/check_nginx.sh

3.3.5 启动与验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 两台机器分别启动
systemctl start keepalived
systemctl enable keepalived

# Master 上验证 VIP 是否绑定
ip addr show eth0
# 应该能看到 eth0:1 192.168.1.100

# 模拟 Master 故障
systemctl stop keepalived
# 在 Backup 上看 VIP 是否漂移过来
ip addr show eth0
# eth0:1 192.168.1.100 漂过来了 ✓

3.4 Nginx 端的 5 个真实 keepalive 参数

Nginx 跟后端保持长连接这 5 个参数必须配对出现，少一个就掉坑里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


upstream backend {
 server 192.168.1.20:8080;
 keepalive 32; # ① 启用长连接池，每 worker 与后端保持 32 个连接
}

server {
 listen 80;
 location / {
 proxy_pass http://backend;
 proxy_http_version 1.1; # ② HTTP/1.1（keepalive 必须的协议）
 proxy_set_header Connection ""; # ③ 清空 Connection 头（关键！避免后端 close）
 # ④ ⑤ 这两个参数在 upstream 块
 }
}

参数	作用	不配的后果
`keepalive 32`	启用连接池	每次新建 TCP 连接，性能差 5 倍
`proxy_http_version 1.1`	HTTP/1.1 协议	1.0 不支持 keepalive
`proxy_set_header Connection ""`	清空 Connection 头	后端收到 `Connection: close` 主动关连接
`keepalive_timeout 60s`	连接池超时	连接长时间不释放
`keepalive_requests 1000`	单连接最多请求数	防止单个长连接无限累积状态

🎯 避坑点：Connection: close 是隐形杀手

proxy_set_header Connection "" 这一行看起来"无关紧要"，实际上是最容易踩的坑。如果不写，Nginx 默认会把客户端的 Connection: close 透传给后端，后端收到后主动关闭 TCP 连接——keepalive 形同虚设。

现象：监控看到 Nginx 到后端的连接数正常，但后端 netstat -an 看到大量 TIME_WAIT 状态。100% 是这个参数没配。

3.5 脑裂：Keepalived 最大的坑

脑裂（split-brain）：Master 和 Backup 同时认为自己是 Master，同时持有 VIP。结果：

用户请求被随机分到两台机器
两台机器状态不一致，数据被双向覆盖
监控告警狂响，运维一脸懵

脑裂的 3 大成因：

网络分区：Master 和 Backup 之间的心跳线中断，但 Master 实际还活着
防火墙拦截 VRRP 通告：VRRP 用多播地址 224.0.0.18，某些安全策略会拦
优先级配置错误：两台机器优先级都设成 100，谁都觉得自己是 Master

脑裂的 3 道防线：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 防线 1：使用单播 VRRP 通告（避开多播问题）
vrrp_instance VI_1 {
 unicast_src_ip 192.168.1.10 # 本机 IP
 unicast_peer {
 192.168.1.11 # 对端 IP
 }
}

# 防线 2：双心跳线（主备之间连 2 根网线 + 2 个交换机）
# 防线 3：业务侧防脑裂检测（脚本检查双 VIP 冲突时报警）

🛑 误区警示：脑裂 = 数据灾难

脑裂一旦发生，比单点故障更可怕。单点故障至少业务中断是确定的，脑裂是"两台机器各自服务一部分用户，状态还不一致"——数据被双向覆盖，等发现时已经无法回滚。

防御永远比治疗重要：单播 VRRP + 独立心跳线 + 业务侧冲突检测，三道防线缺一不可。

四、LVS：跨城市流量调度的内核王牌

4.1 为什么需要 LVS：Nginx 的天花板

Nginx + Keepalived 能扛 1-5 万 QPS（同城双活），但遇到大促、双 11 之类 50 万 QPS 场景就远远不够。Nginx 是用户态进程，受限于：

单进程事件循环（虽然多 worker 提升有限）
HTTP 协议解析开销
内存带宽

LVS 走的是另一条路：直接在内核协议栈里转发数据包，根本不进入用户态。理论上限是几十万到百万 QPS，是 Nginx 的 10-50 倍。

4.2 LVS 的 4 种工作模式

LVS 有 4 种转发模式（NAT / DR / TUN / FULLNAT），每种对应不同的网络拓扑：

graph TD
 C[Client] --> LB[LVS Server]
 LB -->|NAT模式| RS[Real Server]
 LB -->|DR模式| RS
 LB -.->|TUN模式| RS
 LB -.->|FULLNAT模式| RS

 style LB fill:#1d3557,color:#fff
 style RS fill:#457b9d,color:#fff

4.2.1 NAT 模式（Network Address Translation）

sequenceDiagram
 participant C as Client
 participant L as LVS
 participant R as Real Server

 C->>L: src=C_IP, dst=VIP:80
 L->>R: src=L_IP, dst=R_IP:80 (DNAT)
 R->>L: src=R_IP, dst=L_IP (响应)
 L->>C: src=VIP:80, dst=C_IP (SNAT)

特点：

进出都经过 LVS（进出流量都改 IP）
Real Server 可以跨网段（甚至跨 VLAN）
LVS 是性能瓶颈（双向流量都过它）
适合小规模、Real Server 少的场景

4.2.2 DR 模式（Direct Routing，直接路由）⭐ 最常用

sequenceDiagram
 participant C as Client
 participant L as LVS
 participant R as Real Server

 C->>L: src=C_IP, dst=VIP:80
 L->>R: src=C_IP, dst=VIP:80 (改MAC，不改IP)
 R->>C: src=VIP:80, dst=C_IP (直接回客户端)

特点：

请求进 LVS，响应直接出 Real Server（响应不经过 LVS）
LVS 只负责"改 MAC 地址"（L2 转发）
性能最高（LVS 只承担一半流量）
Real Server 必须和 LVS 在同一 VLAN（L2 互通）
Real Server 需要配置 VIP 在 lo 网卡上（让它能处理目的 IP 是 VIP 的包）

💡 原理：DR 模式为什么快？

DR 模式 LVS 做的只是改 MAC 地址——把数据包的目的 MAC 从 LVS 自己的改成 Real Server 的。包头 IP 都不动。

整个过程在内核的 IPVS 模块完成，单次转发 < 10 微秒。而 NAT 模式要改 IP + 改端口 + 算校验和，慢 10 倍。

4.2.3 TUN 模式（IP Tunneling，IP 隧道）

把数据包再封装一层 IP 头，通过隧道发给 Real Server。Real Server 可以跨地域（公网可达即可），但需要在 Real Server 上做解封装。

4.2.4 FULLNAT 模式（阿里独创）

双向都做 SNAT + DNAT，Real Server 看不到客户端真实 IP（双向都改 IP）。解决了 DR 模式必须同 VLAN 的限制，是阿里云 SLB 的核心实现。

4.2.5 4 种模式对比

模式	性能	Real Server 跨网段	Real Server 看到真实 IP	配置复杂度	典型场景
NAT	中（双向过 LVS）	✅	✅	低	小规模、内网环境
DR	⭐⭐⭐ 最高	❌（必须同 VLAN）	✅	中	同城机房（最常用）
TUN	中	✅（隧道可达）	✅	高	跨地域、异构网络
FULLNAT	中高	✅	❌	高	云厂商、跨 VPC

4.3 IPVS：LVS 的内核态实现

LVS 本身是一个框架，核心实现叫 IPVS（IP Virtual Server），是 Linux 内核 2.6 后内置的模块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 查看本机是否支持 IPVS
modprobe ip_vs
lsmod | grep ip_vs

# IPVS 的工作流程（内核态）
# 1. 数据包从网卡进入
# 2. netfilter 钩子（PREROUTING）拦截
# 3. IPVS 模块判断目的 IP 是否是 VIP
# 4. 若是 VIP → 查 LVS 规则 → 选一个 Real Server → 改包头（MAC/IP）→ 发出
# 5. Real Server 处理后直接回客户端

IPVS vs iptables：很多人误以为 LVS 是用户态工具，其实所有转发逻辑都在内核。ipvsadm 只是配置命令（ipvsadm -A -t VIP:80 -s rr 添加规则），规则写入内核后，包转发完全在内核态完成。

4.4 LVS 调度算法

LVS 支持 10+ 种调度算法，常用的有 5 种：

算法	含义	适用场景
rr（Round Robin）	轮询	后端性能一致（最常用）
wrr（Weighted RR）	加权轮询	后端性能不均
lc（Least Connection）	最少连接	长连接服务
wlc（Weighted LC）	加权最少连接	⭐ 推荐默认
sh（Source Hashing）	源 IP 哈希	需要会话保持

1
2
3
4
5


# 配置示例：8 台 Real Server 轮询
ipvsadm -A -t 192.168.1.100:80 -s rr
ipvsadm -a -t 192.168.1.100:80 -r 192.168.1.20:80 -g
ipvsadm -a -t 192.168.1.100:80 -r 192.168.1.21:80 -g
# ... 一共 8 台

-g 表示 DR 模式（gatewaying），-m 是 NAT，-i 是 TUN。

4.5 LVS 真实性能数据

生产环境的 LVS 集群典型数据：

业务	LVS 模式	Real Server 数	峰值 QPS	备注
阿里云 SLB	FULLNAT	数百	千万级	单集群扛住双 11
美团 MGW	DR	数十	百万级	入口流量调度
某电商大促	DR	8	50 万	单机房
某金融核心	NAT	4	5 万	强一致场景

📌 实践：LVS 的"理论极限"

单 LVS 节点性能上限取决于包转发能力（pps）：

普通服务器（千兆网卡）：148 万 pps ≈ 50 万 QPS（小包）

DPDK 优化：千万 pps

内核优化（irqbalance、RPS/RFS）：300 万 pps

实际生产中 LVS 不会是瓶颈——网络才是。千兆网卡满载 = 148 万 pps ≈ 50 万 HTTP QPS（按平均 200 字节包算）。

4.6 LVS 的历史与章文嵩的故事

讲 LVS 不能不提它的作者——章文嵩。1998 年他还是国防科技大学的一名博士生，因为实验室的 Web 服务器扛不住大量并发访问，自己动手写了 IPVS 模块并贡献给 Linux 内核。这是中国人主导的、为数不多的内核级基础设施项目。

LVS 的几个关键时间节点：

1998：章文嵩在国防科大开发 LVS 1.0 版本
2002：LVS 2.0 发布，加入 NAT / DR / TUN 三种模式
2004：IPVS 正式并入 Linux 2.6 内核主线
2010s：阿里基于 LVS 开发 FULLNAT 模式，解决云环境跨 VPC 问题
2020s：LVS 仍是云厂商负载均衡的事实标准内核

💡 原理：为什么 LVS 20 年不过时？

LVS 之所以能在 Service Mesh、Envoy、eBPF 等新技术层出不穷的今天仍占据入口调度，核心原因：它在内核。任何用户态的方案（Nginx / HAProxy / Envoy）都要走系统调用 → 内核协议栈的路径，而 LVS 本身就在内核协议栈里，少一次上下文切换就少 5-10 微秒。

这是物理规律决定的，不是软件能优化的。eBPF 虽然也在内核，但目前 L4 场景仍未全面取代 IPVS。

4.7 LVS vs HAProxy：4 层反代的"双雄之争"

HAProxy 也是 4 层反代的常见选择（同公司还有 Nginx Ingress 也在用），与 LVS 形成竞争：

维度	LVS	HAProxy
实现位置	Linux 内核（IPVS）	用户态进程
性能	百万级 QPS	10-30 万 QPS
配置复杂度	中（ipvsadm 命令）	低（haproxy.cfg 文件）
健康检查	TCP_CHECK / HTTP_GET	更丰富（支持脚本）
日志	内核态，无业务日志	详细业务日志
典型场景	入口抗量、超大规模	中等规模、需业务可观测

实战选择：

超大规模（> 50 万 QPS）：LVS
中等规模 + 需详细日志：HAProxy
云环境 / 容器环境：HAProxy（K8s 默认 kube-proxy 用的就是 iptables/IPVS，HAProxy 在 Ingress 层常见）

五、LVS + Keepalived + Nginx：异地多活流量层完整链路

5.1 经典三层塔架构

把 LVS、Keepalived、Nginx 串起来，就是异地多活流量层的"前哨班"完整链路：

graph TD
 U[用户] --> VIP[VIP 192.168.1.100
公网入口]
 VIP --> LVS1[LVS Master
eth0: VIP]
 VIP -.故障切换.-> LVS2[LVS Backup
eth0: VIP]
 LVS1 -->|DR模式
只改MAC| N1[Nginx 1]
 LVS1 --> N2[Nginx 2]
 LVS1 --> N3[Nginx 3]
 LVS1 --> N4[Nginx 4]
 LVS2 -.接管.-> N1
 LVS2 -.接管.-> N2
 LVS2 -.接管.-> N3
 LVS2 -.接管.-> N4
 N1 --> APP[微服务集群]
 N2 --> APP
 N3 --> APP
 N4 --> APP

 style LVS1 fill:#1d3557,color:#fff
 style LVS2 fill:#457b9d,color:#fff
 style N1 fill:#a8dadc
 style N2 fill:#a8dadc
 style N3 fill:#a8dadc
 style N4 fill:#a8dadc

为什么需要 3 层而不是直接 LVS → App？

LVS 看不到 HTTP 头：无法按 Host / URL 路由（4 层限制）
LVS 无法终结 TLS：HTTPS 终结在 Nginx 更省 CPU
LVS 无法做应用层健康检查：Nginx 的 upstream_check 模块能做更精细的健康探测

💡 原理：三层塔的职责边界

LVS 层：抗量 + 故障切换（不在乎协议内容）

Nginx 层：七层路由 + TLS 终结 + 应用层健康检查

应用层：业务逻辑 + 微服务路由

每一层只做自己擅长的事，这是分布式系统设计的"第一性原则"。

5.2 双 Keepalived 实例设计

实战中，LVS 层和 Nginx 层都要 Keepalived 保护：

graph TD
 VIP1[公网 VIP
LVS 入口] --> LVSKA[Keepalived 1
保 LVS]
 LVSKA --> LVS_A[LVS Master]
 LVSKA -.-> LVS_B[LVS Backup]
 LVS_A -->|DR| N_A[Nginx 1]
 LVS_A -->|DR| N_B[Nginx 2]
 LVS_B -.接管.-> N_A
 LVS_B -.接管.-> N_B
 VIP2[内网 VIP
Nginx 入口] --> NGKA[Keepalived 2
保 Nginx]
 NGKA --> N_A
 NGKA -.-> N_B
 N_A --> APP[应用]
 N_B --> APP

 style LVSKA fill:#1d3557,color:#fff
 style NGKA fill:#457b9d,color:#fff

2 个 Keepalived 实例的分工：

Keepalived 1（外层）：保 LVS，VIP 是公网入口
Keepalived 2（内层）：保 Nginx，VIP 是内网入口

双 VIP 的好处：

LVS 切换不影响 Nginx：LVS 挂了，Nginx 还在，对应用零感知
Nginx 切换不影响 LVS：Nginx 挂了，LVS 还在，VIP 还在
故障定位更细：告警能精确到"LVS 层故障"或"Nginx 层故障"

5.3 阿里 / 美团 / 字节的真实架构

5.3.1 阿里云 SLB

阿里云 SLB（Server Load Balancer）的内核就是 LVS + Tengine 的组合：

LVS 集群（FULLNAT 模式）：公网入口，扛 100 万级 QPS
Tengine 集群：七层路由 + 业务分流
多 AZ 部署：同城双活 + 异地灾备

关键技术：

FULLNAT 模式（阿里自研）：Real Server 跨 VPC 部署
ECS 健康检查：30 秒无响应自动剔除
会话保持：基于 Cookie 4 层哈希

5.3.2 美团 MGW

美团自研的 MGW（Meituan Gateway）架构：

graph LR
 U[用户] --> DNS[GSLB DNS]
 DNS --> LB[VIP 入口]
 LB --> HA[HAProxy
七层负载]
 HA --> NG[Nginx/Tengine
业务路由]
 NG --> APP[业务集群]

HAProxy 做 L4：替代 LVS，部分场景性能更好
Tengine 做 L7：替代纯 Nginx，加了很多自研模块
多机房单元化：MGW 内部带"机房标签"

5.3.3 字节跳动 BFE

字节的 BFE（Baidu Front End，注：字节和百度都叫 BFE）：

七层网关为主：直接用 Go 自研 BFE 做入口
Service Mesh 协同：跨机房调用通过 Mesh 自动处理
多语言 SDK：Go / Java / Python 都接入

📌 实践：自研还是用开源？

< 50 万 QPS：直接用 LVS + Keepalived + Nginx，业界成熟方案

50 万 - 500 万 QPS：LVS + Tengine + 自研健康检查平台

> 500 万 QPS：必须自研（参考阿里 SLB、美团 MGW、字节 BFE）

不要过早自研。开源方案 80% 场景够用，自研成本是 5-10 倍。

5.4 异地多活的流量调度策略

5.4.1 DNS 层：用户就近接入

graph LR
 BJ[北京用户] --> BJVIP[北京 VIP]
 SH[上海用户] --> SHVIP[上海 VIP]
 GZ[广州用户] --> GZVIP[广州 VIP]
 BJVIP --> BJDC[北京机房]
 SHVIP --> SHDC[上海机房]
 GZVIP --> GZDC[广州机房]

智能 DNS：根据用户 IP 归属地返回最近的 VIP
健康检查融合：DNS 探测机房健康度，故障机房自动从 DNS 摘除
DNS TTL 权衡：TTL 太短切换快但 DNS 压力大，太长切换慢

5.4.2 应用层：单元化路由

承接系列第 1 篇的单元化设计——LVS 不做单元化判断，单元化路由在 Nginx 或 Spring Cloud Gateway 层做：

1
2
3
4
5
6


# Nginx 根据用户 ID 哈希分流
upstream backend {
 hash $cookie_userid consistent; # 一致性哈希
 server 192.168.1.20:8080;
 server 192.168.1.21:8080;
}

5.4.3 故障切换：DNS + LVS 双层

机房级故障时：

DNS 切流（分钟级）：把 VIP 摘除，流量自动去其他机房
LVS VIP 切流（秒级）：同机房内 Keepalived 切换
Nginx upstream 切流（毫秒级）：健康检查失败自动剔除

3 层切换配合：DNS 解决"机房级"、LVS 解决"机器级"、Nginx 解决"应用级"。

5.5 为什么 K8s 内部不直接用 Service/Ingress 而要 LVS？

很多读者会问："我已经在 K8s 上了，为什么入口还要 LVS？"

K8s 内部确实有 Service（kube-proxy 实现）和 Ingress（nginx-ingress / traefik），但它们只解决"集群内"问题，解决不了"集群外"问题：

层级	K8s 组件	解决的问题	解决不了的问题
Pod → Pod	kube-proxy (iptables/IPVS)	集群内服务发现 + 负载均衡	公网入口
集群入口	Ingress (nginx-ingress)	七层路由 + TLS 终结	抗量级（单 ingress 几万 QPS）
机房入口	LVS / 硬件 LB	抗量 + 故障切换	业务路由
跨机房	DNS 调度	用户就近接入	秒级切流

K8s 环境的典型架构：

graph TD
 U[用户] --> DNS[DNS]
 DNS --> LVSC[云厂商 LB
LVS 集群]
 LVSC --> NING[nginx-ingress
Nginx集群]
 NING --> SVC[K8s Service
iptables/IPVS]
 SVC --> POD1[Pod 1]
 SVC --> POD2[Pod 2]
 SVC --> POD3[Pod 3]

 style LVSC fill:#1d3557,color:#fff
 style NING fill:#1d3557,color:#fff
 style SVC fill:#457b9d,color:#fff

LVS 在 K8s 环境承担的角色：

抗量：nginx-ingress 单实例最多 1-3 万 QPS，几十个 pod 才能扛百万级
入口高可用：nginx-ingress pod 漂移，VIP 还在 LVS 上
跨节点均衡：多个 ingress pod 分布在不同节点，LVS 统一对外

📌 实践：K8s 入口的 3 种方案

LVS + nginx-ingress（推荐）：抗量 + 高可用 + 业务路由齐全

云厂商 LB + nginx-ingress：省运维，付出云费用

纯 Ingress（不要 LVS）：只适合中小规模，大促会爆

六、4 种方案选型矩阵 + 真实案例

6.1 选型矩阵

方案	抗量级	RTO	复杂度	成本	适用场景
单机 Nginx	1-3 万 QPS	不可用	最低	1x	Demo、内部工具、低可用业务
Nginx + Keepalived 双机	1-5 万 QPS	< 10 秒	低	2x	中小业务、3 个 9 可用性
LVS-DR + Nginx + Keepalived	5-50 万 QPS	< 5 秒	中	3-4x	同城双活主流方案
LVS + Keepalived + Nginx 三层塔	10-100 万 QPS	< 3 秒	高	5-8x	异地多活、大促、4 个 9
自研 LB（SLB / MGW / BFE）	> 100 万 QPS	< 1 秒	极高	10x+	阿里、美团、字节级别

6.2 真实案例对照

公司	流量调度方案	特点
某 SaaS 初创（日活 5 万）	单机 Nginx	1 台 4C8G 跑一年，挂了重启 5 分钟
某电商中型（日活 100 万）	Nginx + Keepalived 双机	2 台 8C16G，3 个 9 可用性
美团外卖	MGW（自研 HAProxy + Tengine）	单元化 + 异地双活
阿里双 11	SLB（LVS + Tengine）	三地五中心，50 万 + QPS
字节 TikTok	BFE（自研 Go 网关）	海外多 Region

6.3 决策流程

graph TD
 A[开始选型] --> B{日活 ?}
 B -->|< 10万| C[单机 Nginx]
 B -->|10-100万| D{可用性要求 ?}
 B -->|> 100万| E{异地多活 ?}
 D -->|3 个 9| F[Nginx + Keepalived]
 D -->|4 个 9| G[LVS + Nginx]
 E -->|否| G
 E -->|是| H[LVS + Nginx + DNS 调度]

 style C fill:#a8dadc
 style F fill:#457b9d,color:#fff
 style G fill:#1d3557,color:#fff
 style H fill:#1d3557,color:#fff

6.4 反例：选错的代价

反面案例 1：金融初创选了"单机 Nginx"

某支付初创公司 2019 年上线，日活 5 万，CTO 觉得"用 LVS 成本太高"，选了单机 Nginx。2020 年春节红包活动，单机 Nginx 进程被大流量打挂，业务中断 2 小时。事后估算损失 200 万，远超"上 LVS 节省的 30 万成本"。

教训：成本不是按"现在用不用得上"算，是按"挂了损失多少"算。即使是中小业务，强一致性场景也要至少 Nginx + Keepalived。

反面案例 2：电商中型选了"LVS 但没配 Keepalived"

某电商 2021 年自建机房，CTO 觉得"单 LVS 够用"。结果 LVS 机器硬件故障（电源烧了），入口整个挂掉，所有用户访问超时。事后抢修换机器，1 小时恢复。

教训：LVS 本身是高可用组件里的"被保"对象。没有 Keepalived 保护，LVS 挂了入口就挂。永远要有"保 LVS 的人"。

反面案例 3：直播平台选了"LVS + Nginx 但没做异地多活"

某直播平台 2022 年大促，所有流量集中在北京机房。北京机房的光纤被市政施工挖断，平台全挂 6 小时。事后损失数千万。

教训：LVS + Nginx 解决的是"机房内"容灾，“机房外"必须异地多活。两个层次都要做，不能只看一个。

6.5 选型决策清单

业务特征	推荐方案
日活 < 10 万、可用性要求低	单机 Nginx
日活 10-100 万、3 个 9	Nginx + Keepalived
日活 10-100 万、强 SLA 4 个 9	LVS + Keepalived + Nginx 三层塔
日活 > 100 万、4 个 9	LVS 三层塔 + 异地多活
日活 > 1000 万或上市级 SLA	自研 LB（参考 SLB / MGW / BFE）

🎯 避坑点：选型不是越贵越好

见过最离谱的案例：日活 2 万的内部 OA 系统，上了 LVS + Keepalived + 自研监控全套。3 个人的运维团队维护 6 台服务器，效率极低。

选型原则：用最少的组件满足需求。日活 2 万单机 Nginx 就够，别为了"高可用"过度设计。

七、实操手册：一步步搭建 LVS + Keepalived + Nginx

本节是完整可复制粘贴的命令清单。准备 3 台 Linux 机器（CentOS 7 或 Ubuntu 20.04+），按角色分配：

角色	IP	用途
LVS-Master	192.168.1.10	LVS 主节点（也做 Keepalived Master）
LVS-Backup	192.168.1.11	LVS 备节点（也做 Keepalived Backup）
Nginx-Real	192.168.1.20	后端 Nginx 真实服务器（DR 模式）
VIP	192.168.1.100	对外服务的虚拟 IP

💡 小贴士：至少 2 台机器也能跑（Real Server 用 Docker 启 Nginx 模拟）。生产环境请按上面 3 台分配。

7.1 准备环境

7.1.1 关闭防火墙和 SELinux

1
2
3
4
5


# 3 台机器都执行
systemctl stop firewalld
systemctl disable firewalld
setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

7.1.2 开启 IP 转发（DR 模式必需）

1
2
3
4
5
6
7
8


# LVS Master 和 Backup 上执行
echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.conf
sysctl -p

# 关闭 RP_FILTER（防 IP 伪造过滤）
echo "net.ipv4.conf.all.rp_filter = 0" >> /etc/sysctl.conf
echo "net.ipv4.conf.eth0.rp_filter = 0" >> /etc/sysctl.conf
sysctl -p

7.2 安装 IPVS（LVS 内核模块）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# LVS Master 和 Backup 上执行
yum install -y ipvsadm # CentOS
# 或 apt install -y ipvsadm # Ubuntu

# 加载 IPVS 内核模块
modprobe ip_vs
modprobe ip_vs_rr
modprobe ip_vs_wrr
modprobe ip_vs_sh

# 开机自启
echo "ip_vs" >> /etc/modules-load.d/ipvs.conf
echo "ip_vs_rr" >> /etc/modules-load.d/ipvs.conf
echo "ip_vs_wrr" >> /etc/modules-load.d/ipvs.conf
echo "ip_vs_sh" >> /etc/modules-load.d/ipvs.conf

# 验证
lsmod | grep ip_vs

7.3 安装 Nginx（Real Server 上）

 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


# 在 192.168.1.20 上执行
yum install -y nginx # 或 apt install -y nginx

# 配置 Nginx 监听 VIP（在 lo 网卡上）
cat > /etc/nginx/conf.d/vip.conf << 'EOF'
server {
 listen 192.168.1.100:80; # 监听 VIP
 server_name _;
 location / {
 return 200 "Hello from Real Server 192.168.1.20\n";
 add_header Content-Type text/plain;
 }
}
EOF

# 配置 lo 网卡绑 VIP
cat > /etc/init.d/realserver.sh << 'EOF'
#!/bin/bash
VIP=192.168.1.100
case "$1" in
 start)
 ifconfig lo:0 $VIP netmask 255.255.255.255 broadcast $VIP up
 echo "1" > /proc/sys/net/ipv4/conf/lo/arp_ignore
 echo "2" > /proc/sys/net/ipv4/conf/lo/arp_announce
 echo "1" > /proc/sys/net/ipv4/conf/all/arp_ignore
 echo "2" > /proc/sys/net/ipv4/conf/all/arp_announce
 ;;
 stop)
 ifconfig lo:0 down
 echo "0" > /proc/sys/net/ipv4/conf/lo/arp_ignore
 echo "0" > /proc/sys/net/ipv4/conf/lo/arp_announce
 echo "0" > /proc/sys/net/ipv4/conf/all/arp_ignore
 echo "0" > /proc/sys/net/ipv4/conf/all/arp_announce
 ;;
esac
EOF

chmod +x /etc/init.d/realserver.sh
/etc/init.d/realserver.sh start

🎯 避坑点：arp_ignore / arp_announce 必须配

这是 DR 模式最容易踩的坑。不配的话：

arp_ignore = 0（默认）：Real Server 会对 ARP 请求"积极响应”，把 VIP 的 MAC 地址告诉别人

结果：外部请求都到 Real Server 了，LVS 收不到包

arp_ignore = 1：只对"目标 IP 是本机接口的"ARP 请求响应。配合 arp_announce = 2（只向同网段宣告自己接口的 IP）才能正常工作。

启动 Nginx：

1
2
3
4
5
6


systemctl start nginx
systemctl enable nginx

# 验证
curl http://192.168.1.100
# 应输出 "Hello from Real Server 192.168.1.20"

7.4 安装 Keepalived

1
2


# LVS Master 和 Backup 上执行
yum install -y keepalived # 或 apt install -y keepalived

7.4.1 LVS Master 配置 `/etc/keepalived/keepalived.conf`

 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


! Configuration File for keepalived

global_defs {
 router_id LVS_MASTER
 script_user root
 enable_script_security
}

# 监控 LVS 自身进程
vrrp_script check_lvs {
 script "/usr/local/bin/check_lvs.sh"
 interval 2
 weight -20
 fall 3
 rise 2
 timeout 2
}

vrrp_instance VI_1 {
 state MASTER
 interface eth0
 virtual_router_id 51
 priority 100
 advert_int 1
 authentication {
 auth_type PASS
 auth_pass 1111
 }
 virtual_ipaddress {
 192.168.1.100/24 dev eth0 label eth0:1
 }
 track_script {
 check_lvs
 }
 nopreempt
 notify_master "/usr/local/bin/notify.sh master"
 notify_backup "/usr/local/bin/notify.sh backup"
}

# LVS 虚拟服务配置（DR 模式）
virtual_server 192.168.1.100 80 {
 delay_loop 6 # 健康检查间隔
 lb_algo wlc # 加权最少连接
 lb_kind DR # DR 模式
 persistence_timeout 60 # 会话保持 60 秒
 protocol TCP

 real_server 192.168.1.20 80 {
 weight 1
 TCP_CHECK {
 connect_timeout 3
 nb_get_retry 3
 delay_before_retry 3
 connect_port 80
 }
 }
 # 如果有更多 Real Server，复制上面块
}

7.4.2 LVS Backup 配置（只改 3 处）

1
2
3
4
5


vrrp_instance VI_1 {
 state BACKUP # ← 改
 priority 90 # ← 改
 # 其它和 Master 一致
}

7.4.3 健康检查脚本

1
2
3
4
5
6
7
8


# /usr/local/bin/check_lvs.sh（Master 和 Backup 各一份）
#!/bin/bash
# 检查 IPVS 是否加载
lsmod | grep ip_vs > /dev/null
if [ $? -ne 0 ]; then
 exit 1
fi
exit 0

1

chmod +x /usr/local/bin/check_lvs.sh

7.4.4 启动 Keepalived

1
2
3
4
5
6
7


# 两台机器分别启动
systemctl start keepalived
systemctl enable keepalived

# Master 上验证
ip addr show eth0
# 应看到 eth0:1 192.168.1.100

7.5 验证整套链路

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 1. 在 LVS Master 上查 IPVS 规则
ipvsadm -Ln
# 应看到：
# TCP 192.168.1.100:80 wlc
# -> 192.168.1.20:80 Route 1 0 0

# 2. 客户端访问 VIP
curl http://192.168.1.100
# 应返回 "Hello from Real Server 192.168.1.20"

# 3. 看连接数
ipvsadm -Lnc

7.6 故障演练

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 演练 1：停止 Real Server 的 Nginx
ssh 192.168.1.20 "systemctl stop nginx"
# 30 秒后 IPVS 应自动剔除
ipvsadm -Ln
# 192.168.1.20 应消失

# 演练 2：停止 Master 的 Keepalived
systemctl stop keepalived
# 5 秒内 Backup 应接管 VIP
ssh 192.168.1.11 "ip addr show eth0"
# 应看到 eth0:1 192.168.1.100

# 演练 3：恢复 Master
systemctl start keepalived
# 因为配了 nopreempt，不会自动抢占（让 Backup 继续工作）

📌 实践：nopreempt 是好习惯

默认 Keepalived 会在 Master 恢复后自动抢占回 VIP。这种行为在生产中容易导致"脑裂"（短暂的"双 Master"）。

配 nopreempt 后：Master 恢复后保持 Backup 状态，只有 Backup 挂了才接管。切换更稳定，但要手动维护（定期巡检 VIP 是否在期望的机器上）。

7.7 配套 Nginx upstream

如果 Real Server 跑的不是裸 Nginx，而是反向代理（Nginx → 多个微服务），配置就稍微复杂：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# /etc/nginx/conf.d/upstream.conf
upstream backend {
 server 192.168.1.30:8080 weight=1;
 server 192.168.1.31:8080 weight=1;
 keepalive 32; # ⭐ 与后端保持长连接
}

server {
 listen 192.168.1.100:80;
 location / {
 proxy_pass http://backend;
 proxy_http_version 1.1; # ⭐ HTTP/1.1
 proxy_set_header Connection ""; # ⭐ 清空 Connection 头
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_connect_timeout 5s;
 proxy_read_timeout 60s;
 }
}

3 个 ⭐ 参数：

keepalive 32：与后端保持 32 个长连接池
proxy_http_version 1.1：HTTP/1.1（keepalive 必须）
proxy_set_header Connection ""：清空 Connection 头（避免后端主动关闭）

7.8 容器化场景：Docker / K8s 下的等价配置

如果你的后端服务跑在 Docker / K8s 容器里，Nginx 的 upstream 配置需要相应调整：

Docker Compose 场景：

 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


# docker-compose.yml
version: "3.8"
services:
 nginx:
 image: nginx:1.25
 ports:
 - "80:80"
 volumes:
 - ./nginx.conf:/etc/nginx/nginx.conf
 depends_on:
 - app1
 - app2
 networks:
 - appnet

 app1:
 image: myapp:1.0
 networks:
 - appnet
 app2:
 image: myapp:1.0
 networks:
 - appnet

networks:
 appnet:
 driver: bridge

对应的 Nginx upstream（用容器名代替 IP）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


upstream backend {
 server app1:8080; # 容器名直接当主机名
 server app2:8080;
 keepalive 32;
}

server {
 listen 80;
 location / {
 proxy_pass http://backend;
 proxy_http_version 1.1;
 proxy_set_header Connection "";
 # ... 其他配置
 }
}

K8s 场景：

 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


# ConfigMap + Deployment
apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-upstream
data:
 upstream.conf: |
 upstream backend {
 server myapp.default.svc.cluster.local:8080;
 keepalive 32;
 }
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-proxy
spec:
 replicas: 3
 template:
 spec:
 containers:
 - name: nginx
 image: nginx:1.25
 volumeMounts:
 - name: upstream
 mountPath: /etc/nginx/conf.d
 volumes:
 - name: upstream
 configMap:
 name: nginx-upstream

📌 实践：K8s 中 keepalive 的"坑"

K8s 中 Pod IP 随时可能变化（重启、调度、扩缩容）。如果把 Pod IP 写死在 upstream 里，Pod 重启一次就全部失效。

正确做法：用 Service 的 DNS 名称（myapp.default.svc.cluster.local），Nginx 启动时 DNS 解析一次。Service 后端 Pod 变化时，长连接池内残留的旧连接会失败，触发自动重连。

7.9 性能压测：wrk 与 ab 实战

搭建完链路后，必须做压测确认性能。推荐 2 个工具：

wrk（推荐，Lua 脚本扩展）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 安装
git clone https://github.com/wg/wrk.git
cd wrk && make

# 4 线程压 30 秒
wrk -t4 -c1000 -d30s http://192.168.1.100/

# 输出示例
# Running 30s test @ http://192.168.1.100/
# 4 threads and 1000 connections
# Thread Stats Avg Stdev Max +/- Stdev
# Latency 12.34ms 15.67ms 250.00ms 89.32%
# Req/Sec 8.50k 1.23k 9.87k 72.45%
# 900000 requests in 30.00s, 240.00MB read
# Requests/sec: 30000.00
# Transfer/sec: 8.00MB

ab（Apache Bench，简单场景）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1 万请求，100 并发
ab -n 10000 -c 100 http://192.168.1.100/

# 关键看三个指标
# Requests per second: 30000 [#/sec] ← QPS
# Time per request: 3.333 [ms] ← 平均延迟
# Percentage of requests served within a certain time (ms)
# 50% 2
# 95% 8
# 99% 15
# 100% 30

压测要看 P99 延迟，不要只看平均：

平均延迟 5ms，但 P99 500ms → 长尾问题严重
P99 < 50ms 才算健康

八、踩坑与监控

8.1 10 个常见坑速查

#	坑	现象	解决
1	`arp_ignore` / `arp_announce` 没配	LVS 收不到包，外部直接连 Real Server	Real Server 上配 `arp_ignore=1, arp_announce=2`
2	Nginx `upstream` 没配 `keepalive`	TIME_WAIT 飙升，端口耗尽	加 `keepalive 32` + `proxy_http_version 1.1` + `Connection ""`
3	Keepalived 脑裂	双 Master 互相抢 VIP	单播 VRRP + 独立心跳线 + 业务侧冲突检测
4	LVS DR 模式跨 VLAN	Real Server 收不到 ARP	同 VLAN 部署，或换 FULLNAT
5	VIP 漂移后 ARP 表未更新	客户端缓存旧 MAC 地址	在 LVS 配 `notify_master` 脚本，主动广播 gratuitous ARP
6	`nopreempt` 没配	Master 恢复后双 Master 抢 VIP	配 `nopreempt`，避免频繁切换
7	LVS Master 单点	LVS 挂了整个入口挂	必须 Keepalived 双机 + 监控
8	`ip_forward` 没开	DR 模式包转发失败	`sysctl -w net.ipv4.ip_forward=1`
9	Real Server `lo:0` 没绑 VIP	拒绝服务（认为非本机 IP）	Real Server 上 `ifconfig lo:0 VIP netmask 255.255.255.255`
10	LVS 健康检查误判	偶发抖动导致全摘	调大 `nb_get_retry` 和 `delay_before_retry`

8.2 监控告警

8.2.1 必监控指标

指标	阈值	工具
VIP 是否在期望机器上	漂移即告警	Keepalived `notify_*` 钩子 + Prometheus
IPVS 活跃连接数	> 80% 容量告警	`ipvsadm -Ln` + node_exporter
Real Server 健康状态	任何 down 立即告警	Keepalived `virtual_server` 块内置检查
LVS Master / Backup 进程存活	进程消失告警	systemd + Prometheus
Nginx upstream 失败率	> 1% 告警	Nginx `ngx_http_upstream_check_module`
跨机房专线延迟	> 50ms 告警	自研 ping 探针

8.2.2 拨测（公网心跳）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# /usr/local/bin/probe.sh（部署在公网多地域）
#!/bin/bash
TARGET="http://192.168.1.100/health"
for i in {1..10}; do
 code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 $TARGET)
 if [ "$code" != "200" ]; then
 echo "ALARM: probe failed, code=$code" | mail -s "LVS probe failed" ops@example.com
 break
 fi
 sleep 6
done

拨测要部署在公网，机房内的监控不能替代公网探测。

🎯 避坑点：监控盲区

最常见的监控盲区是"机房内一切正常，机房外访问不到"。常见原因：

机房出口防火墙拦截

跨机房专线中断

公网 BGP 路由异常

唯一可靠的判断是"公网能否正常访问"。拨测是异地多活的"生命线"。

8.3 3 个真实故障案例（公开复盘整理）

案例中数字来源于公开复盘报告，已脱敏处理。重点看"现象 → 根因 → 修复"三段式分析。

案例 1：Keepalived 切换抖动导致业务频繁超时

现象：某电商 2022 年大促，业务监控发现每隔 30-60 秒就有 1-2 秒的请求超时。QPS 越高峰越明显。
根因：Keepalived 主备之间的 VRRP 心跳被交换机 MAC 表老化干扰，导致短暂的双 Master / 双 Backup 切换。每次切换有 1-2 秒的 ARP 重学习窗口，期间流量黑洞。
修复：(1) 调整交换机 MAC 表老化时间到 30 分钟；(2) Keepalived 配 unicast_src_ip 单播模式，避免多播丢包；(3) 监控加上"VIP 1 分钟内切换次数"告警。

案例 2：LVS DR 模式跨 VLAN 部署，ARP 全部失败

现象：某金融公司 2021 年新机房部署 LVS，所有请求都直连到 Real Server，LVS 收不到包。Keepalived 健康检查一直告警。
根因：运维把 LVS 和 Real Server 放在不同 VLAN（中间隔了路由器），但 LVS DR 模式是 L2 转发，L2 广播域不通就无法做 ARP 替换。
修复：(1) 把 LVS 和 Real Server 改到同一 VLAN；(2) 如果必须跨 VLAN，改用 FULLNAT 模式（阿里云方案）；(3) 在网络拓扑图里显式标注 LVS 边界，避免后续运维踩坑。

案例 3：nginx keepalive 配置错，TPS 暴跌 70%

现象：某 SaaS 公司 2023 年迁移到新机房，TPS 从 5000 降到 1500，后端 CPU 反而飙到 90%。
根因：运维在 nginx.conf 里漏了 proxy_set_header Connection ""（Nginx 模板是复制的，这一行没复制到）。结果后端收到 Connection: close 主动关闭 TCP 连接，每秒多 5000 次 3 次握手 + 4 次挥手。
修复：(1) 补全 3 个 keepalive 参数；(2) 加上 wrk 压测 baseline 监控，配置变更后自动对比基线；(3) 把 3 个 keepalive 参数写进 Ansible 模板，代码化防止遗漏。

🛑 误区警示：3 个案例的共性

这 3 个案例的共性：

配置层面的错误，不是软件 bug

监控告警虽然响了，但没被及时处理（大促期间没空看）

变更没有"基线对比"——配置改完没和历史数据对比，TPS 跌 70% 都没发现

防御方法：

配置变更走 PR + 评审 + 灰度

关键指标（TPS / P99 / 错误率）配基线告警（偏离基线 30% 立刻报警）

重要配置写进代码（Ansible / Helm Chart），不要让人肉 cp 配置文件

8.4 5 条运维铁律

最后给做流量调度的运维 5 条铁律：

任何变更先在预发环境跑 1 周：配置错误往往不是立即暴露，是运行 3-7 天后才出问题（如内存泄漏、连接耗尽）
关键配置做成"代码"：用 Ansible / Helm Chart 管理，避免人肉 cp 配置文件
监控 + 告警 + Runbook 三件套：监控发现问题，告警通知人，Runbook 指导人怎么修。缺一不可
故障演练常态化：每月 1 次小演练，季度 1 次大演练。没演练过的高可用 = 假高可用
复盘文化：每次故障 24 小时内复盘，输出 Action Item 并跟踪。不复盘的故障 = 还会再发生

总结

9.1 流量调度的演进小结

graph LR
 A[单机 Nginx] --> B[Nginx + Keepalived]
 B --> C[LVS-DR + Nginx]
 C --> D[LVS + Keepalived + Nginx
三层塔]
 D --> E[自研 LB
SLB/MGW/BFE]

 style A fill:#e0e0e0
 style B fill:#b8d8d8
 style C fill:#92d2d2
 style D fill:#457b9d,color:#fff
 style E fill:#1d3557,color:#fff

演进的内在动力：

业务量增长 → 单机撑不住 → 多机
可用性要求提高 → 单点故障不能接受 → Keepalived
性能天花板 → Nginx 不够 → LVS
极致性能 + 异地多活 → 三层塔 + 自研

9.2 3 大核心要素

承接系列第 1 篇的"业务 / 数据 / 流量"三分法，流量调度层的 3 大核心：

冗余：每层都有主备，任意一层挂了下一层接住
分层：LVS 抗量 / Nginx 路由 / App 业务，各司其职
自动化：健康检查 + 自动剔除 + 自动接管，无需人工介入

9.3 系列预告

这是 Java Web 微服务系列 的第 2 篇。后续计划：

第 3 篇：Spring Cloud Gateway：应用层网关的精细化治理 —— 微服务内部路由、灰度、限流、鉴权
第 4 篇：Nacos + Sentinel + Seata 三件套实战 —— 服务发现 + 流量治理 + 分布式事务
第 5 篇：SkyWalking 全链路追踪 —— 异地多活下的链路可观测性
第 6 篇：自研 LB 设计要点 —— 100 万 QPS 级别的流量调度系统

回到系列开篇的命题：异地多活不是"装个软件就完事"，是"用钱换命“的系统工程。流量调度作为"前哨班”，看似只是几个开源组件的拼接，实际踩过的坑足够写 100 篇博客。

本篇的实操清单是"最小可运行版本"，生产环境请结合 §8.2 的监控指标 + 业务场景做调整。异地多活的"前哨班"搭好了，业务系统的可用性才能真正"扛得住"。

附录：常见问题 FAQ

本节是面向架构评审、面试、新人入职的速查清单——把读者最常问的问题集中解答。

A1：LVS 和 Nginx 能不能装在同一台机器上？

技术上可以，生产上不推荐。

LVS 是内核态转发，Nginx 是用户态进程。装同一台会：

资源争抢：LVS 转发吃 CPU，Nginx 处理 HTTP 也吃 CPU，互相挤兑
故障域重叠：机器挂了 LVS 和 Nginx 一起挂，双层塔降级成单层
监控混乱：出问题时分不清是 LVS 还是 Nginx 的锅

正确做法：LVS 机器只跑 LVS + Keepalived，Nginx 机器只跑 Nginx + 应用。职责单一。

A2：Keepalived 主备之间是用多播还是单播？

生产环境推荐单播（unicast_src_ip + unicast_peer）。

多播（默认）的问题：

很多云厂商默认禁止多播（224.0.0.0/4 段）
跨网段多播经常被丢
安全扫描工具会报"未加密的多播协议"漏洞

单播的优点：

点对点通信，经过路由器也能通
更安全（不会被同网段其他机器听到 VRRP 通告）
可观测（TCP 单播能用 tcpdump 抓包分析）

A3：DR 模式下 Real Server 为什么需要把 VIP 绑到 lo 网卡？

因为 DR 模式 LVS 只改目的 MAC、不改目的 IP。Real Server 收到包后发现目的 IP 是 VIP，不是自己的 IP（如 192.168.1.20），默认会丢弃（认为不是发给自己的）。

把 VIP 绑到 lo 网卡后，Real Server 觉得"这个 IP 是我的"，会正常处理。lo 是 loopback 接口，不对外，所以不会引起 ARP 冲突。

A4：Keepalived 检测到 Nginx 挂了，VIP 切到 Backup，但 Backup 的 Nginx 没起来怎么办？

典型场景：Keepalived 进程比 Nginx 进程先起。

Keepalived 默认只检测自身进程是否存活，不会检查 Nginx。所以 Nginx 没起来，Keepalived 也会把 VIP 拉过来——用户访问 VIP，结果是连接被拒。

正确做法：用 vrrp_script 自定义健康检查（参考 §3.3.2 脚本）：

1
2
3
4
5
6
7


#!/bin/bash
# check_nginx.sh
count=$(ps -ef | grep "nginx: master process" | grep -v grep | wc -l)
if [ $count -eq 0 ]; then
 exit 1
fi
exit 0

脚本返回非 0 = 优先级降 20 = 自动让出 VIP。这样只有 Nginx 也起来了，Backup 才接管 VIP。

A5：异地多活的流量调度和同城双活的本质区别是什么？

同城双活：机房之间 RTT < 5ms，LVS/Nginx 跨机房 RPC 几乎无感。技术上同城双活就是"在一个城市里"。

异地多活：机房之间 RTT 30-100ms，任何跨机房调用都是 60-200 倍延迟。所以严格禁止跨机房 RPC，必须靠单元化路由 + DNS 调度让用户"绑死"在一个机房。

对应到流量调度：

同城双活：LVS 可在机房之间漂移（Keepalived + 跨机房心跳）
异地多活：每个机房一套独立的 LVS + Keepalived 集群，机房之间通过 DNS 互导

A6：硬件 LB（F5 / A10）和软件 LVS 怎么选？

维度	硬件 LB	软件 LVS
性能	千万级 QPS	百万级 QPS
成本	几十万到上百万	几千到几万
可定制	黑盒，只能配	完全开源，可深度定制
故障恢复	厂商技术支持	靠自己
典型用户	银行、证券、政企	互联网公司

实战选择：

钱多 + 求稳：硬件 LB
钱紧 + 求灵活：LVS（互联网公司主流）
混合：核心入口用硬件 LB，业务入口用 LVS

A7：为什么很多公司直接用云厂商 LB 而不自己搭 LVS？

直接原因：省事。云厂商 LB 帮你搞定：

多 AZ 高可用（自带 Keepalived）
健康检查 + 自动剔除（自带 LVS 健康检查）
跨 Region 调度（自带 DNS 调度）
DDoS 防护（云厂商自带）
TLS 终结（证书托管）

深层原因：大部分公司没有"自建 LB"的运维能力。一个 5 人运维团队，维护业务都吃力，没人专门优化 LVS 内核参数。用云厂商 LB 是 ROI 更高的选择。

自建 LVS 的场景：

业务量足够大（单 LB 月费用 > 50 万）
有专门的 SRE 团队
公有云满足不了的特殊需求（如跨云、混合云）

A8：流量调度层和应用层网关（Spring Cloud Gateway）是什么关系？

层级不同：

层级	职责	典型组件
流量调度层（本篇）	机房入口 + 抗量 + 7 层路由	LVS、Nginx、HAProxy
应用层网关（系列第 3 篇）	微服务内部路由 + 灰度 + 限流 + 鉴权	Spring Cloud Gateway、Kong、APISIX

举例：

用户访问 https://api.example.com/order → LVS → Nginx（按 host 路由）→ Spring Cloud Gateway（按 URL 路由到 order 微服务）→ order 服务
Nginx 只看 host / URL 前缀，Spring Cloud Gateway 看完整微服务元数据（服务名、版本、灰度标签）

性能差异：

LVS 单实例 50 万 QPS
Nginx 单实例 1-5 万 QPS
Spring Cloud Gateway 单实例 1-5 千 QPS（Java 业务逻辑开销）

所以入口用 LVS/Nginx 抗量，业务内部用 Spring Cloud Gateway 精细治理，两个层都不可少。

A9：怎样评估"流量调度层是否需要升级"？

3 个信号：

容量告警：ipvsadm -Ln 看到活跃连接数持续 > 80% 单机容量
延迟告警：监控显示 P99 延迟持续上涨，已经超过业务容忍上限
故障切换告警：Keepalived 1 周内切换 > 3 次，说明单点故障频繁

升级路径：

单机 Nginx 撑不住 → Nginx + Keepalived（水平扩展）
Nginx + Keepalived 撑不住 → LVS + Keepalived + Nginx（引入 LVS 抗量）
LVS 也撑不住 → 多 LVS 集群 + 云厂商 LB（水平扩展 LVS）
自研成本低于云厂商 LB 费用 → 自研 LB（参考 SLB/MGW/BFE）

不要"为了升级而升级"。日活 50 万的电商上 LVS 是合理，日活 5 万的内部 OA 上 LVS 就是浪费。

A10：流量调度的未来趋势是什么？

3 个明确方向：

eBPF 替代 IPVS：eBPF 可以在内核更早的钩子点（XDP）处理包转发，比 IPVS 性能高 5-10 倍。Cilium 等项目已经在用 eBPF 替代 kube-proxy
Service Mesh 接管 7 层：Envoy + Istio 在 K8s 内部已经能做精细流量治理，部分场景可以替代 nginx-ingress
云原生 LB：云厂商 LB 越来越智能，自带灰度、A/B 测试、流量镜像，未来自建 LB 的场景会越来越少

但这不意味着传统 LVS/Nginx 会被淘汰：

物理机 / 虚拟机场景仍是主流（很多公司没上 K8s）
LVS 内核态转发的性能优势是物理规律，eBPF 只是更近一步
简单可靠的技术会长期存在（KISS 原则）

🛑 误区警示：追新 ≠ 用对

见过最离谱的：日活 10 万的电商，为了"用 Service Mesh"硬上 Istio。结果团队 3 个人花了 3 个月学 Istio，业务没提升，运维复杂度暴涨。

原则：用最熟悉、最稳定、最容易招聘运维的技术。新技术的红利期过了再用。

参考文章

K8s 容器编排：Java 微服务团队的踩坑实录与收益账

Tue, 09 Jun 2026 00:00:00 +0000

K8s 容器编排：Java 微服务团队的踩坑实录与收益账

Java Web 微服务系列 · 第 3 篇 · K8s 容器编排阅读时长：约 35 分钟本文写于 2026 年 6 月

引子：凌晨 3 点的告警电话

2021 年某日深夜，监控大屏突然飘红——某物流公司的订单服务挂了一台机器。值班同学爬起来 SSH 上去，看了一眼：进程没了。systemctl restart order-service 一把梭，服务起来了。然后第二台挂了，第三台挂了。值班同学对着黑漆漆的屏幕，骂了一句脏话。

第二天复盘，发现是部署脚本的 bug——新版本包没拷全，旧进程在内存里撑了 2 个小时才崩。2 个小时里这个服务有 6 个实例在跑，但其中 4 个已经"假死"——能 ping 通但 HTTP 503。更要命的是，值班同学是按 IP 一台台 SSH 上去重启的，光是重启就花了一个半小时。

“这日子没法过了。”

半年后，这家公司把所有 Java 微服务全部搬到了 K8s 集群。三年过去，再没人在凌晨 3 点因为"进程没了"被叫起来过。

但 K8s 也不是银弹。上 K8s 本身就是一个大坑——只是它把你从一个深渊里捞出来，又把你推进了另一个深渊。本文就按"为什么要上 / 解决什么痛点 / 收益是什么 / 有什么坑"四问，把这条路的全貌讲清楚。

一、为什么要上 K8s 集群：业务驱动的演进

1.1 Java 微服务部署的 4 大历史形态

从 2010 年到现在，Java 微服务的部署方式大概经历了 4 个阶段。每个阶段都不是"上一个错了"，而是"业务规模逼着你升级"。

阶段	部署方式	代表工具	适用规模	典型痛点
单机直跑	物理机 / 虚拟机 + Tomcat / jar	scp、shell 脚本	1-5 个服务、< 50 QPS	部署靠人、环境不一致、扩容靠买机器
脚本化	自动化脚本 + 进程管理	Ansible、SaltStack、Supervisor	5-20 个服务、< 500 QPS	脚本维护成本高、回滚慢、灰度靠脚本拼
容器化（无编排）	Docker + docker-compose	Docker、docker-compose	20-50 个服务、< 2000 QPS	跨主机调度、容器自愈、滚动升级都靠人
容器编排	K8s / Swarm / Mesos	K8s、Docker Swarm、Mesos、Nomad	50+ 服务、2000+ QPS	集群本身复杂度、运维门槛陡升

💡 原理：为什么"容器"不等于"K8s"

Docker 只解决了"打包一致"——开发机、测试机、生产机跑同一个 image。但 Docker 解决不了"50 个服务怎么调度到 30 台机器"“某台机器挂了容器怎么办"“滚动升级时如何不停机”。这些是"容器编排"要解决的问题。K8s 是容器编排的事实标准，不是因为它最好，而是因为它最早做大、生态最全。

1.2 业务量爆炸的拐点

什么时候"必须上 K8s”？没有标准答案，但有几个硬指标：

服务数 > 30：人工维护部署脚本开始失控——一个新人改一行配置要培训 1 周
实例数 > 100：单 IP 重启模式失效——光 SSH 串行重启就要 1 小时
QPS > 1000 + 长尾延迟敏感：必须做弹性扩缩容——大促前临时扩容 50%，大促后缩回去
机房数 > 1：跨机房调度、流量切换需要平台化——脚本扛不住

上述任一指标突破，都应该认真评估 K8s。不要"为了上 K8s 而上 K8s"——K8s 本身的运维成本比裸 Docker 高 5-10 倍。

1.3 选型对比：K8s vs Swarm vs Mesos vs Nomad

“K8s 是唯一的答案吗？”不是，但事实上是。看个对比表：

维度	K8s	Docker Swarm	Mesos	Nomad
生态	⭐⭐⭐⭐⭐ CNCF 一哥	⭐⭐ Docker 官方但已停摆	⭐⭐⭐ 老牌但社区萎缩	⭐⭐ HashiCorp 出品，小而美
学习曲线	陡（概念多）	平（Docker 用户秒上手）	极陡（论文级）	中（HashiCorp 一贯简洁）
适用规模	数千节点、数万 Pod	数百节点、几千容器	数万节点	数千节点
自愈能力	强（多种控制器）	弱（基本靠 restart）	中（依赖 Marathon）	中（基础功能）
服务网格	Istio / Linkerd 成熟	无	无	Consul Connect
存储编排	强（CSI 标准）	弱	强（Mesos + 各种 framework）	中（CSI 支持中）
运维成本	高（要专职团队）	低	极高	中
招聘难度	容易（人才多）	容易	难	中

📌 实践：为什么 99% 的团队最终选 K8s

生态绑死：所有云厂商默认托管 K8s（EKS / AKS / GKE / 阿里 ACK），自建也有 kubeadm / kOps

招聘市场最大：K8s 工程师池子 10 倍于 Mesos/Nomad

学习成本虽然高但只付一次：学会 K8s 概念后，5 年内不会被淘汰

二次开发友好：CRD + Operator 让任何复杂业务都能抽象

选 K8s 不是"技术最优"，是"综合 ROI 最高"。

二、解决了什么痛点：5 大类问题

K8s 解决的不是"一两个痛点"，而是Java 微服务规模化后的一整片痛。下面按"团队最痛的"到"运营层面的"排序。

2.1 部署自动化：告别凌晨 3 点的发布

传统部署的核心问题是"人工介入太多"——scp 包、kill 进程、start 进程，串行、慢、易错。K8s 把这一切抽象成一份 YAML：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: apps/v1
kind: Deployment
metadata:
 name: order-service
spec:
 replicas: 3
 strategy:
 type: RollingUpdate
 rollingUpdate:
 maxSurge: 1
 maxUnavailable: 0
 template:
 spec:
 containers:
 - name: order-service
 image: registry.example.com/order-service:v1.2.3
 ports:
 - containerPort: 8080

一次 kubectl apply 完成的事：

拉镜像（v1.2.3）

按 maxSurge/maxUnavailable 策略滚动升级（每次只停 1 个，起来 1 个）

等 readinessProbe 通过才继续下一个

任意一步失败自动回滚

全程无需 SSH 任何机器

场景	传统方式	K8s 方式
滚动升级	写脚本、串行执行、人工盯日志	改 YAML、`kubectl apply`、自动滚
灰度发布	维护两个集群、路由脚本切流量	改 replicas 比例、调整 Service selector
回滚	找回老包、停止服务、重新部署	`kubectl rollout undo`（秒级）
扩缩容	买机器 → 装机 → 部署服务	`kubectl scale` / HPA 自动（分钟级）

2.2 自愈能力：进程挂了不用爬起来重启

K8s 的核心思想是"声明式期望状态"——你告诉它"我想要 3 个 order-service 实例在跑"，它永远会努力维持这个状态。

Pod 挂了 → kubelet 立刻重启（同节点）
节点挂了 → controller-manager 30s 内发现，在其他节点重新拉起
健康检查失败 → readinessProbe 不通过 → 流量切走 → livenessProbe 失败 → 重启

💡 原理：K8s 自愈的三个层次

Pod 级别：kubelet 监控容器，挂了就在同节点重启

节点级别：kube-controller-manager 的 NodeController 30s 心跳，丢失后重新调度

集群级别：kube-scheduler 在 Pod 不可调度时（如资源不够）找其他节点

传统方式下"凌晨 3 点 SSH 上去重启"的事，K8s 在 30 秒内自动完成。

2.3 服务发现与负载均衡：告别 IP 漂移

Java 微服务最头疼的事之一：A 服务调用 B 服务，B 的 IP 变了，调用失败。K8s 用 Service + DNS 解决：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Service
metadata:
 name: order-service
spec:
 selector:
 app: order-service
 ports:
 - port: 80
 targetPort: 8080

部署后，集群 DNS（CoreDNS）会自动注册 order-service.default.svc.cluster.local → 后端 Pod 的虚拟 IP。Java 代码用 order-service:80 调用就行，IP 漂移全自动屏蔽。

维度	传统方式（Eureka / Nacos）	K8s 方式
注册中心	独立部署 Eureka / Nacos 集群	内置（Service + kube-proxy）
客户端依赖	Spring Cloud 组件 + SDK	无（DNS 解析即可）
健康检查	Spring Boot Actuator 主动上报	kubelet 探针（被动）
跨语言支持	Java 友好，其他语言要写 SDK	任何语言都行
配置复杂度	中（要维护注册中心集群）	低（YAML 写一遍就行）

📌 实践：K8s DNS 与 Nacos 的取舍

简单服务用 K8s 内置 DNS 足够。但有状态服务（配置中心、服务治理、可观测）Nacos 仍是首选——它能管理服务元数据、配置、流量规则，K8s DNS 只能做"名字→IP"。

2.4 配置与密钥管理：告别 .properties 走天下

传统 Java 应用的配置问题：

改一个数据库地址 → 改 30 台机器的 application.properties → 重启服务
密码明文写在配置文件里 → 提交到 Git → 安全事故

K8s 用 ConfigMap + Secret 抽象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: v1
kind: ConfigMap
metadata:
 name: order-service-config
data:
 application.properties: |
 server.port=8080
 spring.datasource.url=jdbc:mysql://mysql:3306/order
---
apiVersion: v1
kind: Secret
metadata:
 name: order-service-secret
type: Opaque
stringData:
 DB_PASSWORD: <db-password>

热更新：用 Reloader 之类的 Operator，配置变更自动触发滚动重启。密钥管理：Secret 配合 etcd 加密 + RBAC 权限控制。

🎯 避坑点：Secret 默认是 base64 编码，不是加密！

任何能 kubectl get secret 的人都能解出明文。生产环境必须：① 启用 etcd 加密；② 用外部密钥管理（Vault / 阿里云 KMS）；③ RBAC 收紧到"运维 + 必要开发"。

2.5 资源隔离与调度：告别"那个服务又把内存吃光了"

传统物理机/虚拟机的痛：A 服务 OOM 杀掉了同机器的 B 服务。K8s 用 cgroup + namespace 做硬隔离：

1
2
3
4
5
6
7


resources:
 requests:
 cpu: "500m" # 0.5 核（保证）
 memory: "512Mi" # 512MB（保证）
 limits:
 cpu: "2" # 最多 2 核（超了就节流）
 memory: "1Gi" # 最多 1GB（超了就 OOM Kill）

QoS 等级	设置条件	行为
Guaranteed	requests == limits	最高优先级，最后被驱逐
Burstable	requests < limits（有 request）	中等优先级，资源紧张时被驱逐
BestEffort	没设 requests/limits	最低优先级，资源紧张时最先被杀

🛑 误区警示：limits 设太低 = 性能不稳

JVM 堆内存默认会"贪"到 limit 才 GC。memory.limits=512Mi 但 JVM -Xmx 没设 → JVM 启动后申请 1GB 内存 → OOM Kill。Java 容器必须显式设 -XX:MaxRAMPercentage=70.0 或 -Xmx（详见第四章 4.7）。

三、收益是什么：可量化的账

老板最关心"花了多少钱，赚回多少"。这一节给能写进年度预算答辩的数字。

3.1 资源利用率：从 20% 到 60%

传统物理机部署：

平均 CPU 利用率 15-25%（高峰要预留 3 倍容量）
平均内存利用率 40%（JVM 堆固定分配）

K8s 部署：

平均 CPU 利用率 50-65%（requests/limits + 混部 + HPA）
平均内存利用率 55-70%（动态堆 + 超卖）

📌 实践：10 台物理机 vs 30 台物理机的故事

某电商公司搬 K8s 前用 30 台物理机跑 200 个微服务实例（平均 6.7 实例/机）。搬 K8s 后用 10 台物理机（多核高配）+ 充分利用 requests/limits + HPA，实例数提升到 350 个（平均 35 实例/机）。节省 20 台物理机 × 5 万/年 = 100 万/年。

3.2 发布效率：从 30 分钟到 3 分钟

步骤	传统	K8s	收益
打镜像 + 推仓库	5 分钟	1 分钟（Maven + Jib/Dockerfile）	4 分钟
传包到 10 台机器	10 分钟	0（Pod 拉镜像）	10 分钟
重启服务（滚动）	10 分钟	1 分钟（K8s 自动）	9 分钟
验证 + 监控	5 分钟	1 分钟	4 分钟
合计	30 分钟	3 分钟	节省 27 分钟

按每天发布 10 次算 = 节省 4.5 小时/天。开发体验直接拉满。

3.3 故障恢复时间：MTTR 从小时级到秒级

故障场景	传统 MTTR	K8s MTTR
进程崩溃	5-30 分钟（人工发现 + 重启）	< 30 秒（自动重启）
节点宕机	10-60 分钟（人工迁移）	< 2 分钟（自动迁移）
机房故障	30-120 分钟（脚本切流量）	< 5 分钟（DNS/Ingress 切）
配置错误	5-15 分钟（人工改文件 + 重启）	< 1 分钟（ConfigMap + Reloader）
版本回滚	10-30 分钟（找回老包 + 部署）	< 10 秒（`kubectl rollout undo`）

🎯 避坑点：MTTR < 30s 不是无脑的

K8s 自动重启 / 调度是默认的，但自动迁移不等于自动恢复。“Pod 在新节点起来了” ≠ “流量切过来了”——Service selector 要对、readinessProbe 要过、DNS 缓存要刷新。生产环境要配 PodDisruptionBudget + 反亲和 + 健康检查三件套，K8s 的"自愈"才能真正救你。

3.4 团队协作：从"运维是瓶颈"到"开发自服务"

传统流程：

1

开发提工单 → 运维评审（3 天）→ 运维操作（2 小时）→ 通知开发

K8s 流程：

1

开发写 YAML → kubectl apply（5 分钟）→ 跑起来

开发自服务带来的收益无法直接量化，但让运维从"操作工"变成"平台工程师"，团队效率指数级提升。

3.5 业务连续性：机房级故障 RTO < 30s

承接系列第 1 篇「异地多活」的话题：K8s 是异地多活的基础设施底座。

多集群联邦（Karmada / Kubefed）→ 跨机房调度
Ingress + Global DNS → 跨机房流量切
ArgoCD / GitOps → 配置漂移检测与自动修复
Velero → 集群级备份与恢复

💡 原理：K8s 是"数据中心即一台机器"的抽象

上一篇文章讲异地多活是"把系统分散到多机房"。K8s 把这件事的成本降到 1/10——你不再需要写机房切换脚本，集群联邦 + DNS 切流 + 健康检查就能在 30 秒内完成 RTO < 30s 的机房级故障切换。

四、有什么坑：真实踩雷清单

这一节是全文最长的部分——因为"坑"是 K8s 学习曲线最陡的部分。不讲坑，上 K8s = 找死。下面 8 节按"踩坑顺序"展开。

4.1 二进制部署的复杂度：6 大子系统

K8s 集群不是"装一个软件"——它有 6 大核心组件要装、要配、要互相通信：

组件	角色	装在哪	启动参数数量
etcd	分布式 KV 存储（集群大脑）	3 个 master	3-5 个
kube-apiserver	API 网关（唯一对外入口）	3 个 master	28+ 个
kube-controller-manager	控制器集合（保 reconcile 循环）	3 个 master	18+ 个
kube-scheduler	调度器（决定 Pod 放哪）	3 个 master	8+ 个
kubelet	节点 agent（管容器）	所有节点	30+ 个
kube-proxy	网络代理（管 Service）	所有节点	15+ 个

装完这 6 大件只是开始——还要装 CNI 网络插件（Calico/Flannel）、CoreDNS、Ingress Controller、Metrics Server、Helm、Dashboard……一套完整生产集群有 20+ 组件。

🛑 误区警示：kubeadm 不是"一键安装"

很多人以为 kubeadm init 就是装好 K8s 了。真相是：kubeadm 只装 4 大件（apiserver / controller-manager / scheduler / kubelet），etcd 还得自己装，CNI 还得自己装，Ingress 还得自己装，所有生产级配置都得自己加。kubeadm 是"半成品"——它给你"会跑"的环境，不给你"能生产"的环境。

4.2 节点规划的血泪

K8s 集群"装在哪"是个大问题。生产集群一般分 3 种：

模式	节点组成	适用规模	复杂度
all-in-one	1 master + N worker（小集群）	< 50 Pod	低
3 master + N worker	3 master（HA）+ N worker	50-500 Pod	中
多 master 多机房	9+ master 跨机房	500+ Pod	极高

🛑 坑：异构硬件混部是大忌

见过某公司用 5 台 IBM 老服务器（E5-2660 v2，20 核，64GB）+ 5 台消费级 i7/i9（64GB）+ 1 台 Xeon Gold 80 核 64GB。混部后：

资源利用率算不清：i9 内存 64G 是 2 根 32G，老服务器是 8 根 8G，节点间 OOM 行为不一致

调度不公平：80 核机器被大 Pod 吃掉，20 核机器闲着

故障域混乱：i7/i9 单点故障率高于服务器级 CPU

生产集群应该同构硬件（同型号、同 CPU 架构、同内存配置），最多分 2 档（master vs worker）。别想着"反正都是 x86，能跑就行"——K8s scheduler 会按资源调度，异构会让它的判断出 bug。

端口范围也是坑：默认 K8s Service NodePort 范围是 30000-32767，很多公司的安全策略会拦这个段。要么改范围（--service-node-port-range=8000-9000），要么提前和安全团队对齐。

4.3 系统优化的 20 个坑

K8s 对底层 Linux 有 20+ 项硬性要求。每一项不满足都可能让集群"跑不起来"或"跑着跑着崩"：

4.3.1 swap 必须关

1
2


swapoff -a
sed -ri 's/.*swap.*/#&/' /etc/fstab

不关会怎样：kubelet 默认要求关闭 swap（--fail-swap-on=true），开了 swap 容器会性能骤降（swap 拖慢 GC），且 kubelet 启动失败。

4.3.2 防火墙必须关

1
2


sudo systemctl stop ufw
sudo systemctl disable ufw

不关会怎样：iptables 规则混乱，Pod 之间通信失败。

4.3.3 systemd-resolved 必须删

1
2
3
4


sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo rm -rf /etc/resolv.conf
sudo touch /etc/resolv.conf

🎯 避坑点：systemd-resolved 是 Ubuntu 上 K8s 的大坑

Ubuntu 22.04 默认启用 systemd-resolved，它会拦截 53 端口。CoreDNS 装上后起不来（端口冲突），表现为 coredns Pod 一直 CrashLoopBackOff，但 kubectl logs 看不到明显错误——因为 coredns 进程根本启动失败。99% 的"CoreDNS 装不上"都是这个原因。

4.3.4 ulimit 必须调大

1
2
3
4
5
6


cat >> /etc/security/limits.conf << "EOF"
* soft nofile 655360
* hard nofile 131072
* soft nproc 655350
* hard nproc 655350
EOF

不调会怎样：高并发下 Java 进程的"too many open files"错误。

4.3.5 ipvs 模块必须加载

1
2
3
4
5
6
7


cat >> /etc/modules-load.d/ipvs.conf << "EOF"
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
EOF

不加载会怎样：kube-proxy 退化为 iptables 模式，1000 个 Service 就会让 iptables 规则爆炸（性能 O(n²)）。

4.3.6 内核参数 20+ 项

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


cat > /etc/sysctl.d/k8s.conf << "EOF"
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
net.core.somaxconn = 16384
net.ipv4.tcp_max_syn_backlog = 16384
vm.overcommit_memory=1
fs.file-max=52706963
# ... 还有 15+ 项
EOF
sysctl --system

这些参数少一个都可能在高并发下出怪事——比如"Syn_sent 状态堆积"、“nf_conntrack table full”。

生产建议：用 ansible 一键配置 20+ 项 sysctl + 加载 9 个内核模块，不要手敲。我在这上面栽过 3 次——每次都是少一个参数导致"线上跑得好好的，新机器扩上去就抖"。

4.4 证书管理的麻烦

K8s 集群里有 3 套独立的 CA（证书颁发机构）：

CA 用途	证书	数量	过期
etcd-ca	etcd 集群内部通信	1 CA + 3 server cert	默认 1 年
kubernetes-ca	apiserver / kubelet / controller-manager / scheduler	1 CA + 10+ cert	默认 1 年
front-proxy-ca	apiserver 聚合层（metrics-server 等用）	1 CA + 1 cert	默认 1 年

生成工具：cfssl 三件套（cfssl + cfssljson + cfssl-certinfo）。

🛑 坑：证书 hostname 漏一个 = 集群起不来

生成 apiserver 证书时，hostname 列表必须包含：

所有 master 的 hostname（master1, master2, master3）

所有 master 的 IP（10.0.0.x 格式）

VIP（虚拟 IP，对外服务的）

集群内部地址（kubernetes, kubernetes.default, kubernetes.default.svc, kubernetes.default.svc.cluster.local）

127.0.0.1、localhost

漏任何一个，etcd 报 “x509: certificate is valid for …, not …”，表现是 apiserver 反复重启但 kubectl 连不上。

证书自动续期（1 年期限）：生产集群必须用 cert-manager 之类的工具自动化，手动续期等于给自己挖坑。

TLS Bootstrapping：新 worker 节点加入集群时，自动签发 kubelet 客户端证书（避免把 CA 私钥分发到所有节点）：

1
2
3
4
5


# bootstrap.secret.yaml
stringData:
 token-id: <token-id>
 token-secret: <token-secret>
 # ...

🛑 坑：token-id 和 token-secret 暴露 = 任意节点能加入集群

这个 token 实际是"加入集群的入场券"。生产环境必须：① 缩短 token 有效期（默认 24h）；② 审计 token 使用记录；③ 上线后立即吊销。不要把 token 提交到 Git 仓库（记忆库里有真实事故：某 bootstrap token 在私人笔记里登记，已泄露到 git 历史——前车之鉴）。

4.5 组件配置的 28+ 个参数

光 kube-apiserver 一个组件，启动参数就有 28+ 个：

类别	参数示例	作用
网络	`--bind-address`、`--secure-port`、`--advertise-address`	监听地址
etcd	`--etcd-servers`、`--etcd-cafile`、`--etcd-certfile`	后端存储
认证	`--client-ca-file`、`--tls-cert-file`	TLS 双向认证
授权	`--authorization-mode=Node,RBAC`	RBAC 权限控制
admission	`--enable-admission-plugins=...`	准入控制（12+ 种）
聚合	`--requestheader-*`	聚合层（apiserver 内部 API 转发）

3 个 master 几乎一样的配置，只有 --advertise-address 不同。手动复制 = 易漏：

🎯 避坑点：3 master 配置文件必须用 sed 自动化生成

见过有人手抄 3 份，结果 master2 漏了 --feature-gates=RemoveSelfLink=false，导致 1.28 之后整个集群升级不上去（RemoveSelfLink 已经在 1.16 弃用、1.18 删除）。正确做法：用脚本生成，参数化只有 IP 不同的部分。

controller-manager / scheduler / kubelet / kube-proxy 也有大量参数。生产集群必须有 1 份"配置审计"清单——记录每个参数的原因、默认值、生产值。别"反正跑起来了"——下次升级、扩容、排查时你会感谢现在的自己。

4.6 跑起来之后的坑

集群装好、组件跑起来、Pod 能起——但生产环境会冒出新的问题：

4.6.1 kubelet 启动失败

1

failed to run Kubelet: validate service connection: validate CRI v1 runtime API

原因：服务器重启后服务启动顺序乱了——kubelet 比 containerd 启动早，连不上 CRI socket。

解决：加 systemd After 依赖：

1
2
3


[Unit]
After=containerd.service
# 或 cri-dockerd.service

4.6.2 代理后访问不到 Ingress

开发同学用 Charles / Fiddler 抓包时，发现 https://<your-domain> 进不来——Ingress 域名被代理拦截。

解决：代理软件里 bypass 集群内网域名（如 *.cluster.local、10.0.0.0/8）。

4.6.3 hostNetwork + hostAliases 解决内网域名

有些服务要访问内网老系统的固定 IP（不是 DNS），Pod 默认隔离网络访问不到。

1
2
3
4
5


spec:
 hostNetwork: true
 hostAliases:
 - ip: "<internal-ip>"
 hostnames: ["legacy-service.internal"]

🛑 坑：hostNetwork = 失去 Pod 网络隔离

开了 hostNetwork，Pod 直接用宿主机网络，Service / DNS / 端口分配全失效。能不用就不用——只在调试老系统迁移时用，生产环境应该用 Service + Endpoint 解决。

4.6.4 metrics-server 起不来 = HPA 失效

HPA（Horizontal Pod Autoscaler）依赖 metrics-server 提供 Pod 资源数据。metrics-server 装好但kubectl top node 报 “Metrics API not available”——99% 是证书问题：metrics-server 的 --kubelet-certificate-authority 没指对。

4.7 Java 应用特定的坑

Java 跑在 K8s 里有几个"老问题"必须重新理解——不是 K8s 的锅，是 Java 自己的坑：

4.7.1 时区问题

Pod 默认 UTC 时区。new Date() 拿到的时间比东八区少 8 小时——日志时间、数据库时间、订单时间全错位。

解决（三选一）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 方案 1：环境变量
env:
- name: TZ
 value: Asia/Shanghai

# 方案 2：挂载时区文件
volumeMounts:
- name: tz-config
 mountPath: /etc/localtime
volumes:
- name: tz-config
 hostPath:
 path: /usr/share/zoneinfo/Asia/Shanghai

# 方案 3：JVM 参数（兼容老应用）
env:
- name: JAVA_OPTS
 value: "-Duser.timezone=Asia/Shanghai"

4.7.2 JVM 内存感知

JVM 早期版本不识别容器 cgroup 内存限制——Runtime.getRuntime().maxMemory() 返回宿主机内存，JVM 启动时按 1/4 算堆，结果容器 OOM Kill。

解决：JDK 8u191+ 加上 JDK 10+ 已支持 cgroup v1；JDK 11+ 支持 cgroup v2。但仍需显式声明：

1
2
3
4
5


# 推荐：用百分比，让 JVM 自己感知容器内存
JAVA_OPTS="-XX:MaxRAMPercentage=70.0 -XX:InitialRAMPercentage=50.0"

# 不推荐：写死堆大小（容器内存改了 JMX 还按老值）
JAVA_OPTS="-Xmx1g"

模式	优点	缺点
`MaxRAMPercentage`	自动适配容器内存	调优时不可预测峰值
`-Xmx` 写死	行为可预测	换机器要重算
OpenJ9 `memoryLimit`	准生产级，OpenJ9 内部感知 cgroup	团队要学 OpenJ9

🎯 避坑点：JVM 调优必须和 Pod limits 配合

memory.limits=1Gi + JAVA_OPTS=-Xmx2g → JVM 启动时被 K8s OOM Kill。memory.limits=1Gi + JAVA_OPTS=-XX:MaxRAMPercentage=70.0 → JVM 自动算 700MB 堆，正合适。

4.7.3 探针配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


readinessProbe:
 httpGet:
 path: /actuator/health/readiness
 port: 8080
 initialDelaySeconds: 180 # 给 Spring Boot 启动时间
 periodSeconds: 10
 failureThreshold: 9 # 容忍 90s 启动期
livenessProbe:
 httpGet:
 path: /actuator/health/liveness
 port: 8080
 initialDelaySeconds: 180
 periodSeconds: 10
 failureThreshold: 6 # 死 60s 才杀

探针	失败后果	失败阈值	配多少合适
readinessProbe	流量切走（不杀进程）	9 × 10s = 90s	给应用启动时间
livenessProbe	重启 Pod	6 × 10s = 60s	比 readinessProbe 更严格

🛑 坑：livenessProbe 太严 = 雪崩

配 livenessProbe.failureThreshold=1 → 应用 GC 抖一下就重启。正确做法：livenessProbe 阈值 ≥ 2 次失败（至少 20s），给 GC / 业务高峰一点缓冲。见过某公司 livenessProbe 阈值 1，结果大促时 Java Full GC 1 秒卡顿 → livenessProbe 失败 → Pod 重启 → Full GC 又卡 → 雪崩式重启。

4.8 三种工作负载选错 = 数据丢失

K8s 有 3 种核心工作负载控制器，选错 = 业务崩：

控制器	适用场景	关键特性	典型应用
Deployment	无状态服务	副本数随机命名、Pod IP 不固定、可任意扩缩	Web 服务、API 服务、网关
StatefulSet	有状态服务	副本名固定（pod-0/pod-1/…）、稳定的持久卷和 DNS	数据库、消息队列、ZooKeeper
DaemonSet	节点级守护	每个节点跑 1 个 Pod，新节点自动拉起	日志收集、监控 agent、存储插件

场景	选错结果
MySQL 用 Deployment	三个 Pod 各自写不同 PVC → 数据 3 份不一致 → 业务崩
Redis 哨兵用 Deployment	Pod 名字带随机后缀 → Sentinel 配置里写的 `redis-0` 找不到 → 集群不可用
Fluentd 日志收集用 Deployment	副本数少于节点数 → 部分节点日志丢失
Fluentd 日志收集用 StatefulSet	副本数固定，新节点加入后不自动拉起 → 新节点没日志

🛑 避坑点：状态用 Deployment = 数据全丢

某团队图省事，MySQL 主从用 Deployment 部署。某天 K8s 升级，Deployment 滚动升级 → 旧 Pod 被 kill → 从库没来得及同步 → 数据丢失。正确做法：数据库永远用 StatefulSet + 稳定的 PVC + PodDisruptionBudget 严格控制。

五、给想上 K8s 的 Java 团队忠告

5 条经过血泪教训的务实建议：

不要为了上 K8s 而上 K8s——服务数 < 30、QPS < 1000 的团队，docker-compose + 1 个老运维就够了，别给团队加复杂度。
从托管 K8s 开始（EKS/AKS/ACK/GKE），别自建——自建 K8s 需要 1 个全职 SRE 团队维护，省下的人工费比托管费多。
Java 应用先做容器化适配再上 K8s——时区、JVM 内存、启动时间、配置外置、探针，每一项都要测。
灰度上 K8s——新业务先上、存量业务后上。一个 200 服务的团队，半年内推 10% 业务到 K8s 已经很快了。
必须配专职或半专职 SRE——K8s 学习曲线 6-12 个月，让一个开发兼运维的团队会让所有人都痛苦。

💡 最后一条建议：把 K8s 当作"工具"而不是"银弹"

K8s 解决的是"规模化后的部署和运维效率"问题，它不解决业务本身的问题。业务架构差、代码质量差、监控缺失，上 K8s 不会让这些问题消失，只会让它们更复杂。

六、下一篇预告

系列第 4 篇（计划）会讲 Spring Cloud Gateway 在 K8s 上的部署与流量治理——Ingress 怎么配置、Service Mesh 要不要上、灰度发布怎么做。敬请期待。

附录：本文资源

📌 延伸阅读

系列第 1 篇：异地多活：Java Web 微服务的高可用终极形态

关联：系统架构 / K8s 分类下还有 5 篇前置文章（containerd / master 组件 / 高可用 / 单机环境 / 集群插件），建议按顺序读。

技术选型:为什么最终选了 Spring Cloud Alibaba + Dubbo 3

Tue, 09 Jun 2026 00:00:00 +0000

技术选型:为什么最终选了 Spring Cloud Alibaba + Dubbo 3

Java Web 微服务系列 · 第 4 篇 · 技术选型阅读时长:约 45 分钟本文写于 2026 年 6 月配套版本:Spring Cloud Alibaba 2022.0.0.0 / Spring Cloud 2022.0.x / Spring Boot 3.x / Dubbo 3.2.x

引子:第一次技术评审会上我翻的车

2019 年我第一次主导微服务架构的技术评审,信心满满地写了一份**《微服务技术选型方案 v1.0》**——30 多页 PPT,封面是 Spring Cloud 全家桶,封底是 Netflix OSS 矩阵。

会上 CTO 第一个问题:"Netflix OSS 不是 2018 年就进维护模式了吗?你为什么还在用 Zuul、Hystrix、Ribbon?这些组件再过一年就只剩 EOL 公告了。"

我答不上来。

第二个问题是 DBA 提的:“Hystrix 停更,你打算用什么做熔断降级?Resilience4j 吗?它和 Spring Cloud 的集成做完了吗?限流规则怎么持久化?”

第三个问题是测试主管:“你选 Feign 做内部调用,Mock 怎么做?WireMock 集成测过了吗?”

第四个问题是 SRE 主管:“Dubbo 在你们方案里完全没提。咱们的核心交易系统跑了 3 年 Dubbo,你打算全部改成 Feign?业务改造的工时你估过吗?为什么不能内部用 Dubbo、对外用 REST?”

会议开了 2 小时,30 多页 PPT 被翻烂了 3 个问题,最后 CTO 说:"这周重写,先把选型原则列出来,再选技术。别上来就写 PPT。"

这是 2019 年我交的第一笔"学费"。本文把那次踩过的坑,以及后来慢慢悟出来的技术选型方法论,完整地写出来。本文 8000+ 字,一次性把"为什么是 Spring Cloud Alibaba + Dubbo 3 + 对外 RESTful"讲透——给所有在做技术选型的同行参考。

一、核心原则:好的技术选型长什么样

技术选型不是"哪个最火选哪个",也不是"哪个最难选哪个"。我把这些年踩过的坑总结成5 条铁律——前 3 条是"必选条件",后 2 条是"加分项"。

1.1 业务匹配 > 技术先进

再先进的技术,解决不了你的业务问题,就是垃圾。

🛑 误区警示:技术先进性陷阱

“Kubernetes 是未来,Service Mesh 是未来,ServiceComb 是 Apache 顶级项目……所以我们要上!”

错。先进 ≠ 适用。某电商公司花 200 万引入 Service Mesh,结果团队没人懂 Envoy 配置,生产事故频发,最终回滚到 Spring Cloud。这就是"为了先进而先进"的代价。

判断方法:这个技术是解决了我们当前 3-6 个月内的具体痛点,还是为未来 2-3 年画饼?

1.2 团队能力 > 流行度

没有银弹,只有适合团队的技术。

一个 5 人的小团队,上 Istio + Envoy + Spring Cloud 全家桶 + 6 个中间件,就是灾难——没人能 hold 住,出了问题没人能 debug。

判断方法:你团队里有没有人能讲清楚这个技术的核心原理 + 至少 2 个常见坑?如果 5 个人的团队只有 1 个人懂,这就是高风险。

1.3 社区活跃 > 文档齐全

文档可以补,社区活跃不能补。

GitHub Stars > 30k: 主流框架级别(Spring Cloud、Spring Cloud Alibaba 都满足)
最近 6 个月有 release: 框架还活着
Issue 响应时间 < 7 天: 出了问题能找人问
中文社区活跃: 国内公司尤其重要(Stack Overflow 答案少,需要 Gitee/思否/掘金)

反面教材:Spring Cloud Netflix OSS 在 2018 年底宣布进维护模式——Netflix 不再用它,但 Spring Cloud 还在集成它的代码。结果 Hystrix 2020 年 EOL、Zuul 1.x 2022 年 EOL、Archaius 2021 年 EOL,大量历史项目不得不重写。

1.4 避免重复造轮子

💡 原理:开源的本质是"复用别人的代码,自己的代码让别人复用"

你的业务代码、领域模型、核心算法才是真正值钱的部分。注册中心、配置中心、熔断限流、消息队列,业界有成熟方案就别自己写。

自己写一个 ZK 注册中心 3 个月,业界用 Nacos 1 周就搞定。省下的人力写业务逻辑,产出高 10 倍。

例外:如果某组件在性能/合规/功能上有硬性要求,自己造轮子是合理的。但要先确认"真的没有现成方案满足",不要"为了 KPI 自研"。

1.5 留有演进空间

今天选的方案,3 年后大概率要换。技术选型要选"进可攻退可守“的:

进可攻:框架能跟得上社区演进(Spring Cloud 版本升级、Spring Boot 升级)
退可守:万一被淘汰,业务代码能"低代价"迁移到其他方案

判断方法:框架是不是"被绑定"在某个厂商?Dubbo 当年绑定阿里,2014-2017 几乎停止维护,吓得所有公司都迁移到 Spring Cloud。Spring Cloud Alibaba 现在由阿里持续投入,但核心组件(Nacos/Sentinel/Seata)都是 ASF/Apache 项目,真到那一天迁移成本低。

📌 实践:5 条铁律的检查清单

在做最终决策前,把这 5 条打印出来,逐条回答:

☐ 这个技术解决了我们当前 3-6 个月的具体痛点吗?

☐ 团队里有 ≥ 2 人能讲清楚它的核心原理 + 2 个常见坑吗?

☐ GitHub Stars > 30k 且最近 6 个月有 release吗?

☐ 我们能用开源方案避免自研吗?

☐ 3 年后业务代码能低代价迁移吗?

5 条全 Yes,放心选。4 Yes 1 No,谨慎评估。3 Yes 2 No,立即否决。

二、主流方案横评:4 个候选的 PK

明确原则后,我们把当时(2024 年,本文写于 2026 年但内部评估在 2024)市面上 4 个主流的 Java 微服务技术栈摆到台面上,9 个维度对比。

2.1 4 个候选方案

方案 A:Spring Cloud Netflix OSS(纯 Netflix 系)

注册中心:Eureka
配置中心:Spring Cloud Config + Git
熔断降级:Hystrix(已 EOL)
网关:Zuul 1.x(已 EOL)
客户端负载均衡:Ribbon(已 EOL)
内部调用:Feign + Ribbon

方案 B:Spring Cloud Consul 系

注册中心 + 配置中心:Consul
熔断:Resilience4j
网关:Spring Cloud Gateway
内部调用:OpenFeign

方案 C:纯 Dubbo 系(非 Spring Cloud)

注册中心:ZooKeeper / Nacos
内部调用:Dubbo RPC
网关:Dubbo 自带 / Sentinel
配置中心:Disconf / Apollo / Nacos

方案 D:Spring Cloud Alibaba(SCA)+ Dubbo 3 混合(本文最终选)

注册中心 + 配置中心:Nacos
熔断限流:Sentinel
分布式事务:Seata
消息:RocketMQ
内部调用:Dubbo 3(Triple 协议)
对外网关:Spring Cloud Gateway
客户端 REST:Spring MVC + OpenFeign

2.2 9 维度对比表

维度	A. Netflix OSS	B. Spring Cloud Consul	C. 纯 Dubbo	D. SCA + Dubbo 3
注册中心	Eureka(2.x 已停更)	Consul(强一致,运维重)	ZooKeeper(运维重)	Nacos 2.x(AP/可切 CP,运维轻)
配置中心	Spring Cloud Config(界面弱)	Consul KV(无版本管理)	Apollo/Nacos 二选一	Nacos 内置(带版本/灰度/监听)
熔断降级	Hystrix(EOL)	Resilience4j(社区小)	Sentinel(需独立集成)	Sentinel(Alibaba 原生,控制台完善)
API 网关	Zuul 1.x(EOL)	Spring Cloud Gateway	需自选/自研	Spring Cloud Gateway(响应式)
内部调用协议	HTTP/JSON(Feign)	HTTP/JSON(Feign)	Dubbo 协议(二进制)	Triple(gRPC/HTTP2,跨语言)
分布式事务	无官方方案	无官方方案	无官方方案	Seata(AT/TCC/SAGA/XA)
消息队列	需自选(Kafka/RabbitMQ)	同左	同左	RocketMQ(原生集成,事务消息)
社区活跃度	停止维护	中等	高	高(国内主流,中文资料丰富)
国内生产案例	大量遗留项目	中型公司	阿里系老项目	阿里、滴滴、字节(部分)、小米等头部

🎯 避坑点:为什么 A 方案直接被否

Netflix OSS 在 2018 年宣布进维护模式,2020-2022 年多个核心组件 EOL:

Hystrix:EOL 2020 年

Ribbon:EOL 2022 年

Zuul 1.x:EOL 2022 年

Archaius:EOL 2021 年

这意味着所有基于 Netflix OSS 的项目都要做技术债清理。还在用 A 方案的项目,3-5 年内必须迁移。

2.3 4 个候选的优缺点总结

方案 A(Spring Cloud Netflix OSS)

✅ 优点:文档多、入门快、很多老项目在用
❌ 缺点:多个核心组件已 EOL,长期不可持续
❌ 致命伤:Netflix 自己都不用这套了
结论:不选

方案 B(Spring Cloud Consul)

✅ 优点:Consul 自带服务发现 + 配置中心 + 健康检查,组件少
❌ 缺点:Consul 是 Go 写的,JVM 团队排查问题需要跨语言;Resilience4j 社区相对小
⚠️ 适用:中等规模、对 Consul 运维有经验的团队
结论:备选

方案 C(纯 Dubbo 系)

✅ 优点:内部 RPC 性能强(Dubbo 协议);社区活跃
❌ 缺点:Spring Cloud 生态对接需要自己包装;前端/移动端调用 Dubbo 不方便(Dubbo 接口没有 Swagger 文档)
⚠️ 适用:已有 Dubbo 基础且外部调用走独立 REST 服务的项目
结论:部分选(只取其内部 RPC 优势)

方案 D(SCA + Dubbo 3 混合)

✅ 优点:Nacos/Sentinel/Seata/RocketMQ 全家桶,国内生态成熟,Dubbo 3 Triple 协议兼顾性能与跨语言
⚠️ 缺点:组件多,学习曲线较陡;Seata 分布式事务对业务侵入较高
✅ 结论:选

💡 原理:为什么是"混合"而不是单一技术栈

“微服务全家桶"听上去很美好,但实际工程中:

内部 RPC:性能敏感,Dubbo 3 Triple 协议(基于 HTTP/2)比 Feign + JSON 快 3-5 倍

对外 REST:生态好、易调试、跨语言、Swagger/Knife4j 文档友好

强制只用一种,要么内部性能差(全 Feign),要么对外不友好(全 Dubbo)

混合是工程最优解——各取所长,代价是要多维护一套调用框架。

三、为什么最终选了 Spring Cloud Alibaba

5 个核心理由,从业务匹配到社区生态,逐条拆解。

3.1 组件全家桶,开箱即用

Spring Cloud Alibaba 提供完整闭环:

关注点	组件	对标 Netflix
注册中心	Nacos	Eureka
配置中心	Nacos(同一集群)	Spring Cloud Config
熔断限流	Sentinel	Hystrix
分布式事务	Seata	(无对标)
消息队列	RocketMQ	(无对标)
分布式追踪	SkyWalking(可选)	Sleuth + Zipkin
API 网关	Spring Cloud Gateway	Zuul/Gateway
内部 RPC	Dubbo 3(选配)	Feign + Ribbon

一套打天下,不需要像方案 B 那样东拼西凑。

3.2 国内生态成熟,中文资料丰富

Nacos:阿里开源,GitHub Stars 30k+,中文文档齐全
Sentinel:阿里开源,GitHub Stars 22k+,控制台直接用
Seata:阿里开源,GitHub Stars 26k+,国内金融/电商大量案例
RocketMQ:阿里开源,Apache 顶级项目,GitHub Stars 21k+
Dubbo:阿里开源,Apache 顶级项目,GitHub Stars 40k+

📌 实践:中文资料的价值

出了问题去 Stack Overflow 一搜,纯 Netflix 系有 90% 答案,纯 Dubbo 系有 70%,Spring Cloud Alibaba 只有 50%。但 SCA 在思否、掘金、博客园、CSDN 的中文资料比英文还多——这是国内做技术的隐形优势。

3.3 与 Dubbo 兼容,内部 RPC 高性能

这是关键。Spring Cloud Alibaba 官方支持 Dubbo 作为 RPC 框架,通过 Nacos 做注册中心,Dubbo 服务和 Spring Cloud 服务可以互相发现。

这意味着:

内部调用:走 Dubbo 3 Triple 协议(基于 HTTP/2,性能接近 gRPC)
对外调用:走 Spring MVC + OpenFeign(RESTful)
注册中心统一:全部注册到 Nacos,服务治理统一

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<!-- Spring Cloud Alibaba + Dubbo 3 同时引入,自动适配 -->
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-3-starter</artifactId>
 <version>3.2.10</version>
</dependency>

3.4 二次封装好,踩坑成本低

Spring Cloud Alibaba 不只是"组件打包”,还做了深度封装:

Nacos 集成:Spring Boot 风格的 bootstrap.yml 配置,自动注册
Sentinel 集成:注解 @SentinelResource 一行代码接入限流
Seata 集成:@GlobalTransactional 注解开启全局事务
RocketMQ 集成:@RocketMQMessageListener 注解消费消息

对比自己集成:Netflix 体系里 Hystrix 集成 Spring Cloud 需要自己写降级逻辑、Sentinel 已经内置了所有模式。

3.5 商业化平滑,演进路径清晰

纯开源是底线,商业化是加分项。Spring Cloud Alibaba 的核心组件都是 ASF/Apache 顶级项目或独立开源项目,不绑定阿里云。但在需要时:

Nacos → 阿里云 MSE(Nacos 商业版):零代码迁移
Sentinel → 阿里云 AHAS:控制台更强大
Seata → 阿里云 GTS:金融级分布式事务
RocketMQ → 阿里云 RocketMQ 商业版:运维托管

演进路径:开源版 → 商业版 → 阿里云原生——这套路径在阿里内部被验证过,适合"先小规模验证,再大规模上云"的渐进式策略。

🛑 误区警示:不要被"开源+商业版"绑定

万一阿里云商业版涨价,或者你想换腾讯云/AWS,核心代码仍然是 Apache 开源,你可以自建或迁移到其他云。这和"Spring Cloud 绑定 Pivotal/VMware"是同一逻辑——底层开源是退路,商业版是快车道。

四、SCA 核心组件拆解

SCA 的 6 大核心组件逐一拆解。每个组件给出:是什么 / 解决什么问题 / 核心特性 / 版本注意事项。

4.1 Nacos:注册中心 + 配置中心二合一

是什么:阿里开源的动态服务发现、配置管理和服务管理平台。GitHub Stars 30k+。

解决什么问题:

服务注册与发现:服务启动时注册到 Nacos,调用方从 Nacos 拉取服务列表
动态配置:配置变更实时推送到所有客户端,无需重启
健康检查:自动剔除不健康实例

核心特性:

AP/CP 模式可切换:默认 AP(可用性优先,类似 Eureka),集群模式可切 CP(强一致,类似 ZooKeeper)
配置灰度:支持 Beta 发布(指定 IP 生效)、灰度比例、配置版本回滚
Namespace + Group + DataId:三段命名空间,适合多环境/多租户

版本注意:

Nacos 2.x 必须用 Nacos 2.x 客户端(1.x 客户端与 2.x 服务端不兼容!)
Spring Cloud Alibaba 2022.0.0.0 内置 Nacos Client 2.3.x
Nacos 集群至少 3 节点(避免脑裂),生产环境强烈不建议单机模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# bootstrap.yml 关键配置
spring:
 application:
 name: order-service
 cloud:
 nacos:
 discovery:
 server-addr: nacos-cluster:8848
 namespace: prod  # namespace 隔离
 group: ORDER_GROUP  # 业务分组
 config:
 server-addr: nacos-cluster:8848
 file-extension: yaml
 refresh-enabled: true # 开启配置自动刷新

4.2 Sentinel:流量治理的瑞士军刀

是什么:阿里开源的流量控制、熔断降级、系统负载保护组件。GitHub Stars 22k+。

解决什么问题:

限流:QPS 限流、并发线程数限流、关联限流(订单限流连带支付限流)
熔断:慢调用比例、异常比例、异常数三种熔断策略
热点参数限流:同一接口不同参数分别限流(如 /order/query?id=100 和 /order/query?id=200 单独计数)
系统自适应限流:根据 CPU、Load、入口 QPS 动态调整限流阈值
授权规则:黑白名单(只允许特定 IP 访问)

对比 Hystrix:

Hystrix 已 EOL,Sentinel 是事实标准
Sentinel 控制台开箱即用(Hystrix Dashboard 早已不维护)
Sentinel 支持秒级规则推送(Hystrix 是分钟级)

版本注意:

Sentinel 1.8.x 配套 SCA 2022.0.0.0
Sentinel Dashboard 必须独立部署,Sentinel Client 启动时连接 Dashboard 拉取规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 注解式限流
@SentinelResource(value = "createOrder",
 blockHandler = "handleBlock",
 fallback = "handleFallback")
public Order createOrder(OrderRequest req) {
 // 业务逻辑
 return orderRepository.save(req.toEntity());
}

public Order handleBlock(OrderRequest req, BlockException ex) {
 throw new BusinessException("系统繁忙,请稍后重试");
}

public Order handleFallback(OrderRequest req, Throwable ex) {
 log.warn("订单创建降级", ex);
 return Order.deferred(req);
}

4.3 Seata:分布式事务的标准答案

是什么:阿里开源的分布式事务解决方案,提供 AT、TCC、SAGA、XA 四种模式。GitHub Stars 26k+。

解决什么问题:

跨服务的数据一致性问题(下单扣库存 + 创建订单 + 扣账户余额)
4 种事务模式,适配不同业务场景

4 种模式对比:

模式	一致性	性能	业务侵入	适用场景
AT	最终一致	高	低(自动回滚)	80% 业务,推荐首选
TCC	最终一致	高	高(3 个方法)	高并发/金融
SAGA	最终一致	中	中(补偿逻辑)	长事务/跨多服务
XA	强一致	低	低(数据库原生)	强监管行业

版本注意:

Seata Server 必须独立部署(1.6+ 性能优化明显)
Seata AT 模式依赖 undo_log 表(在每个业务库创建,Seata 自动管理)
业务库需要开启 binlog(MySQL)或 WAL(PostgreSQL)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// @GlobalTransactional 一行开启全局事务
@GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
public OrderResult createOrder(OrderRequest req) {
 // 1. 创建订单
 Order order = orderService.create(req);
 // 2. 扣库存(Dubbo 调用)
 inventoryService.deduct(req.getSkuId(), req.getQuantity());
 // 3. 扣账户余额(Dubbo 调用)
 accountService.debit(req.getUserId(), order.getAmount());
 return OrderResult.success(order);
}
// 任一环节抛异常,Seata 自动回滚所有操作

🎯 避坑点:Seata 选模式的决策树

业务是否涉及钱?→ TCC(可控性强)

事务链路是否**≤ 3 个服务**?→ AT(最简单)

事务链路**> 3 个服务**?→ SAGA(避免长时间锁资源)

强监管行业(银行/证券)?→ XA(强一致)

80% 业务选 AT 即可,别上来就用 TCC(侵入高,3 个方法要写)。

4.4 RocketMQ:消息中间件的工业级选择

是什么:阿里开源,Apache 顶级项目,低延迟、高可靠、高吞吐的消息队列。GitHub Stars 21k+。

解决什么问题:

异步解耦:订单创建后异步发短信、发优惠券
削峰填谷:秒杀时把请求先入队列,后台慢慢处理
事务消息:下单+扣库存分布式事务的"本地消息表"替代方案
顺序消息:同一订单的消息严格按顺序处理
定时消息:延迟投递(15 分钟未支付取消订单)

核心特性:

事务消息:生产端先发 prepared 消息,本地事务 commit 后发 commit,失败发 rollback,RocketMQ 自动清理 prepared 消息
严格顺序:同一队列的消息严格 FIFO
百万级 TPS:实测单集群 100 万+ TPS
金融级可靠性:同步双写 + 异步刷盘,数据不丢

对比 Kafka:

Kafka 优势:超高吞吐 + 生态成熟(大数据领域标配)
RocketMQ 优势:事务消息 + 顺序消息 + 定时消息(业务领域更友好)
选型建议:业务消息(订单/支付/通知)选 RocketMQ,日志/大数据管道选 Kafka

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 事务消息示例
@RocketMQTransactionListener(txProducerGroup = "order-tx-group")
public class OrderTransactionListener implements RocketMQLocalTransactionListener {
 @Override
 public RocketMQLocalTransactionState executeLocalTransaction(Message msg, Object arg) {
 try {
 // 本地事务:创建订单
 orderService.create((OrderRequest) arg);
 return RocketMQLocalTransactionState.COMMIT;
 } catch (Exception e) {
 return RocketMQLocalTransactionState.ROLLBACK;
 }
 }
 // 回查机制:RocketMQ 定期询问未确认的消息
 @Override
 public RocketMQLocalTransactionState checkLocalTransaction(Message msg) {
 // 根据 msg 查询订单是否创建成功
 return orderService.exists(msg.getKeys()) 
 ? COMMIT : ROLLBACK;
 }
}

4.5 Spring Cloud Gateway:对外 API 网关

是什么:Spring Cloud 官方推出的 响应式 API 网关,基于 Spring WebFlux + Reactor Netty。性能是 Zuul 1.x 的 1.6 倍。

解决什么问题:

统一入口:所有外部请求先到 Gateway,做鉴权/限流/路由
动态路由:根据请求路径/Header/参数动态转发到不同服务
过滤器链:鉴权 → 限流 → 日志 → 灰度 → 转发
跨域处理:统一 CORS 配置
协议转换:HTTP/JSON → Dubbo/HTTP2 内部协议

核心特性:

断言(Predicates):基于 Path、Header、Cookie、Method、Query 的路由匹配
过滤器(Filter):GlobalFilter(全局) + GatewayFilter(路由级)
限流集成:内置 RequestRateLimiter GatewayFilter,直接对接 Redis 限流

注意:

Gateway 基于 WebFlux 响应式,不能和 Spring MVC 混用!
如果你的服务用了 Spring MVC,把 Gateway 单独部署,别和业务服务一起
Gateway 是单线程事件循环,CPU 密集型操作(比如压缩)要谨慎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# Gateway 路由配置示例
spring:
 cloud:
 gateway:
 routes:
 - id: order-service
 uri: lb://order-service  # lb = load balancer
 predicates:
 - Path=/api/order/**
 - Method=GET,POST
 filters:
 - StripPrefix=2  # 去掉 /api 前缀
 - name: RequestRateLimiter
 args:
 redis-rate-limiter.replenishRate: 100
 redis-rate-limiter.burstCapacity: 200
 - name: Hystrix  # 配合熔断(已 EOL,改 Sentinel)
 args:
 fallbackUri: forward:/fallback

4.6 Spring Cloud Alibaba 不直接包含的"配件”

这几个组件不是 SCA 直接提供,但在微服务里同样重要,顺手列一下:

SkyWalking / Zipkin:分布式链路追踪
XXL-JOB / Elastic-Job:分布式定时任务
ELK / Loki:日志收集与分析
Prometheus + Grafana:监控告警

💡 原理:微服务是"组件组合",不是"全家桶"

Spring Cloud Alibaba 解决服务治理的 80% 问题,剩下的 20%(监控、日志、定时任务)由独立组件补齐。不要追求"一套打天下"——每个组件在自己的领域做到极致,组合起来才是最优解。

五、内部调用:Dubbo 3 实战

这是本文最硬核的一节。Dubbo 3 不只是"Dubbo 2 升级版",它在协议、服务发现、跨语言、可观测性上做了全面重构。这里重点讲Triple 协议——这是 Dubbo 3 相比 2.7 最大的变化。

5.1 为什么内部用 Dubbo 不走 OpenFeign

性能对比(单次调用,本地环境,JDK 17):

方案	序列化	协议	延迟(P50)	延迟(P99)	TPS
OpenFeign + JSON	Jackson	HTTP/1.1 JSON	2.5ms	8ms	6000
OpenFeign + Protobuf	Protobuf	HTTP/1.1	1.8ms	6ms	8500
Dubbo 3 Triple	Protobuf	HTTP/2	0.8ms	2.5ms	18000
Dubbo 2.x (Hessian)	Hessian2	Dubbo TCP	0.6ms	2ms	22000

📌 实践:什么时候该用 Dubbo,什么时候该用 Feign

Dubbo 3 Triple:内部服务调用,QPS > 1000,延迟敏感

OpenFeign:跨语言调用、对外 REST、低 QPS 业务(< 100)、管理后台

混合使用:本文架构,内部 Dubbo + 对外 Feign

Dubbo 3 Triple 协议 vs Dubbo 2.x 经典协议:

Triple:基于 HTTP/2 + Protobuf,跨语言友好(Go/Python/Node.js 都能调)
经典:基于 Dubbo 自定义协议 + Hessian,性能更强但只支持 Java

🎯 避坑点:Triple 不是为了取代 gRPC

Triple 协议设计时参考了 gRPC,在 gRPC 之上做了扩展(支持自定义负载均衡、跨集群路由)。如果你的系统已经用了 gRPC,不需要为了 Dubbo 3 而迁。

但如果你从零开始,Triple 比 gRPC 多了"服务治理"能力(内置路由、限流、熔断),这是 gRPC 需要配合 Istio 才能做到的。

5.2 Triple 协议原理

Triple 协议的核心设计:

协议层:基于 HTTP/2,支持多路复用、流控
序列化:默认 Protobuf(也可选 JSON、Hessian)
服务定义:IDL(.proto 文件)或 Java Interface
通信模式:Unary(一元)、Server Streaming、Client Streaming、Bidirectional Streaming(完整 gRPC 兼容)
服务发现:通过 Nacos 拉取服务列表,默认 dubbo 协议头

5.2.1 协议栈分层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


┌─────────────────────────────────────┐
│ 业务接口(Java Interface) │
├─────────────────────────────────────┤
│ Stub / Proxy(Dubbo 生成) │
├─────────────────────────────────────┤
│ Triple 协议(基于 HTTP/2 + Protobuf)│
├─────────────────────────────────────┤
│ Netty 4.x 传输层 │
├─────────────────────────────────────┤
│ TCP │
└─────────────────────────────────────┘

5.2.2 Triple 与 gRPC 的兼容性

关键:Triple 协议和 gRPC 协议在网络层完全兼容。这意味着:

Go/Python/Node.js 客户端可以用标准 gRPC 调 Dubbo 3 服务
Java 端既可以用 Dubbo 3 Client,也可以用 grpc-java Client
同一端口(默认 50051)既服务 gRPC,也服务 Triple

💡 原理:为什么能"完全兼容"

gRPC 的协议规范是公开的(grpc/grpc-proto)。Triple 在协议层严格遵循 gRPC 规范,只是在服务元数据(服务名、版本、分组)做了扩展,所以 gRPC 客户端能"假装是 Triple 服务"去调,服务端也能识别"gRPC 风格的请求"。

5.3 实战:定义一个 Triple 服务

步骤 1:定义接口

1
2
3
4
5
6


@DubboService // 暴露服务
public interface InventoryService {
 // Java 接口,标注 IDL 信息
 boolean deduct(String skuId, int quantity);
 Inventory query(String skuId);
}

步骤 2:实现服务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@DubboService(version = "1.0.0", group = "inventory")
public class InventoryServiceImpl implements InventoryService {
 @Autowired
 private InventoryRepository repo;
 
 @Override
 public boolean deduct(String skuId, int quantity) {
 Inventory inv = repo.findBySkuId(skuId)
 .orElseThrow(() -> new NotFoundException(skuId));
 if (inv.getStock() < quantity) {
 return false;
 }
 inv.setStock(inv.getStock() - quantity);
 repo.save(inv);
 return true;
 }
 
 @Override
 public Inventory query(String skuId) {
 return repo.findBySkuId(skuId)
 .orElseThrow(() -> new NotFoundException(skuId));
 }
}

步骤 3:引用服务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@RestController
public class OrderController {
 @DubboReference(version = "1.0.0", group = "inventory")
 private InventoryService inventoryService; // 像本地 Bean 一样用
 
 @PostMapping("/order")
 public OrderResult create(@RequestBody OrderRequest req) {
 // 内部调用 Dubbo,走 Triple 协议
 boolean ok = inventoryService.deduct(req.getSkuId(), req.getQuantity());
 if (!ok) {
 return OrderResult.fail("库存不足");
 }
 // ...
 }
}

5.4 与 Nacos 注册中心互通

核心配置(Nacos 作为注册中心 + 配置中心,Dubbo 服务注册到同一 Nacos):

 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


# application.yml
dubbo:
 application:
 name: inventory-service
 registry:
 address: nacos://nacos-cluster:8848
 protocol:
 name: tri  # Triple 协议
 port: 50051
 provider:
 timeout: 3000
 retries: 2
 consumer:
 timeout: 3000
 retries: 2
 check: false
 cloud:
 subscribed-services: inventory-service  # 订阅哪些服务

spring:
 cloud:
 nacos:
 discovery:
 server-addr: nacos-cluster:8848
 namespace: prod

关键点:

dubbo.registry.address 配 Nacos 地址,服务自动注册到 Nacos
Spring Cloud 的服务(用 @SpringBootApplication + @EnableDiscoveryClient)和 Dubbo 服务同时注册到 Nacos
Spring Cloud 服务能发现 Dubbo 服务,Dubbo 服务也能发现 Spring Cloud 服务——只要都是注册到同一 Nacos

5.5 Dubbo 2.7 升级 3.x 的关键差异

如果你是 Dubbo 2.7 老项目,升级 3.x 要注意:

维度	Dubbo 2.7.x	Dubbo 3.x
协议	默认 Dubbo 协议(Hessian)	默认 Triple 协议(HTTP/2 + Protobuf)
注册中心	ZK 主流	Nacos 主流
服务发现	接口级(Interface)	应用级(Application)——按应用名发现,支持大规模集群
跨语言	不支持	支持(gRPC 兼容)
路由策略	条件路由、脚本路由	条件路由 + 标签路由 + 动态配置
可观测性	弱	内置 Micrometer 集成
K8s 集成	不支持	原生支持(基于 Service/DNS)
性能	强	略弱(因为 HTTP/2 开销)但更通用

🎯 避坑点:Dubbo 2.7 → 3.x 升级的最大坑

服务发现模型变了——从"接口级"变成"应用级"。

Dubbo 2.7 同一应用的不同接口都注册成独立服务。Dubbo 3 同一应用的所有接口共享一个应用实例,按 service:version:group 区分。

这意味着:

Nacos 上的服务数会减少(从 N 多个 → N 个)

客户端的负载均衡策略要重配

跨集群路由配置要重新梳理

建议:先在测试环境全量验证,再灰度上线——别一上来就生产升级。

六、对外暴露:RESTful 实战

6.1 为什么对外走 RESTful,不走 Dubbo

维度	Dubbo	RESTful
跨语言	需 SDK(只支持 Java)	HTTP 标准,任意语言可调
调试难度	难(需 Dubbo 工具)	易(curl/Postman/浏览器)
文档工具	无(手写)	Swagger / Knife4j 自动生成
API 治理	弱(无标准)	强(OpenAPI 规范)
前端友好度	差(需后端代理)	好(直接 fetch/axios)
第三方对接	难	易(标准 HTTP)
性能	强	中(JSON 序列化开销)
适合场景	内部服务	外部接口

结论:对外一律 REST,内部一律 Dubbo。这是 5.1 节"性能对比表"的延伸——对外流量不追求极致性能(单次 2ms vs 0.8ms 用户感知不到),但追求生态与可调试性。

6.2 三件套组合:Spring MVC + OpenFeign + Spring Cloud Gateway

组合架构:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


外部 APP
 │
 ▼
┌──────────────────┐
│ Spring Cloud │ ← 对外 API 网关(统一鉴权/限流/路由)
│ Gateway │
└────────┬─────────┘
 │
 ▼
┌──────────────────┐
│ 业务服务 │ ← Spring MVC 暴露 REST API
│ (Order/User/...) │
│ @RestController │
└────────┬─────────┘
 │
 │ (内部调用,可能跨服务)
 ▼
┌──────────────────┐
│ Dubbo 3 Triple │ ← 内部 RPC
│ (Inventory/...) │
└──────────────────┘

关键设计:

Controller 层用 Spring MVC(@RestController),不直接用 Dubbo
服务间调用用 Dubbo 3(@DubboReference)
第三方/前端调用走 Gateway → Controller
OpenFeign 只用于特殊场景(比如跨业务线的服务调用,对方没有 Dubbo 服务)

6.3 实战:订单服务的完整 API

 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


@RestController
@RequestMapping("/api/v1/order")
@Tag(name = "订单服务", description = "订单的创建、查询、取消") // Knife4j 注解
public class OrderController {
 
 @Autowired
 private OrderApplicationService orderService; // 应用层服务
 
 @PostMapping
 @Operation(summary = "创建订单")
 public Result<OrderDTO> create(@RequestBody @Valid OrderRequest req) {
 return Result.success(orderService.create(req));
 }
 
 @GetMapping("/{orderId}")
 @Operation(summary = "查询订单详情")
 public Result<OrderDTO> getById(@PathVariable Long orderId) {
 return Result.success(orderService.getById(orderId));
 }
 
 @PostMapping("/{orderId}/cancel")
 @Operation(summary = "取消订单")
 public Result<Void> cancel(@PathVariable Long orderId, @RequestParam String reason) {
 orderService.cancel(orderId, reason);
 return Result.success();
 }
}

Swagger/Knife4j 自动生成文档:

访问 http://gateway-host:8080/doc.html 查看 API 文档
前端/测试团队可以直接在线调试

6.4 OpenFeign 的应用场景

OpenFeign 在 SCA + Dubbo 3 架构里,主要用于"非 Dubbo 服务"的调用:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 场景:调用一个外部团队的 REST 服务(对方没有 Dubbo)
@FeignClient(name = "external-erp", url = "https://erp.internal/api")
public interface ErpClient {
 @PostMapping("/sync")
 ErpSyncResult sync(@RequestBody ErpSyncRequest req);
}

// 场景:前端 BFF 层聚合多个内部服务
@FeignClient(name = "inventory-service", path = "/api/v1/inventory")
public interface InventoryFeignClient {
 @GetMapping("/{skuId}")
 InventoryDTO getBySkuId(@PathVariable String skuId);
}

OpenFeign vs Dubbo 3 的选型决策:

场景	推荐方案
内部服务调用(高 QPS、延迟敏感)	Dubbo 3 Triple
内部服务调用(低 QPS、跨业务线)	OpenFeign
外部服务调用(对方无 Dubbo)	OpenFeign
前端 BFF 层聚合	OpenFeign
后台管理类接口	OpenFeign

七、实战:一个接口的完整链路

用一个真实例子,把所有组件串起来:用户下单。

7.1 场景描述

流程:

APP 发起 POST /api/v1/order 请求
Gateway 鉴权 + 限流
OrderController 接收请求
OrderService 调用 InventoryService(Dubbo)扣库存
OrderService 调用 AccountService(Dubbo)扣账户余额
Seata 全局事务保证数据一致
创建订单,落 MySQL
发送 RocketMQ 消息(异步发券 + 短信)
返回结果给 APP

7.2 完整代码骨架

Controller 层:

1
2
3
4
5
6
7


@PostMapping
@GlobalTransactional(name = "create-order-tx", rollbackFor = Exception.class)
@SentinelResource(value = "createOrder", blockHandler = "handleBlock")
public Result<OrderDTO> create(@RequestBody @Valid OrderRequest req, 
 @RequestHeader("X-User-Id") Long userId) {
 return Result.success(orderService.create(userId, req));
}

ApplicationService 层(组合领域服务):

 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


@Service
public class OrderApplicationService {
 
 @DubboReference(version = "1.0.0", group = "inventory")
 private InventoryService inventoryService;
 
 @DubboReference(version = "1.0.0", group = "account")
 private AccountService accountService;
 
 @Autowired
 private OrderRepository orderRepository;
 
 @Autowired
 private RocketMQTemplate rocketMQTemplate;
 
 public OrderDTO create(Long userId, OrderRequest req) {
 // 1. 扣库存(Dubbo Triple 协议)
 boolean deducted = inventoryService.deduct(req.getSkuId(), req.getQuantity());
 if (!deducted) {
 throw new BusinessException("库存不足");
 }
 
 // 2. 扣账户余额(Dubbo Triple 协议)
 accountService.debit(userId, req.getAmount());
 
 // 3. 创建订单(本服务数据库)
 Order order = Order.create(userId, req);
 orderRepository.save(order);
 
 // 4. 发送异步消息(RocketMQ 事务消息)
 rocketMQTemplate.sendMessageInTransaction(
 "order-topic", 
 MessageBuilder.withPayload(order).build(),
 order
 );
 
 return OrderDTO.from(order);
 }
}

7.3 全链路追踪

SkyWalking 配置(看一个请求的完整链路):

1
2
3
4
5
6


# agent/config/agent.config
agent.service_name=order-service
collector.backend_service=skywalking-oap:11800
# 自动追踪 Dubbo + HTTP 调用
plugin.dubbo.trace_internal=true
plugin.spring.webflux.trace_internal=true

SkyWalking Dashboard 看到的链路:

1
2
3
4
5
6
7
8


[Gateway 鉴权] 3ms
 └─ [OrderController] 25ms
 ├─ [OrderService.create] 18ms
 │ ├─ [Dubbo: InventoryService.deduct] 6ms ← 内部 Dubbo 调用
 │ ├─ [Dubbo: AccountService.debit] 5ms
 │ ├─ [MySQL: insert order] 3ms
 │ └─ [RocketMQ: sendMessage] 2ms
 └─ [Seata: branch register] 2ms

任何一环慢,都能秒级定位——这才是微服务可观测性的价值。

7.4 故障场景演练

场景:库存服务宕机

OrderController 收到请求
Dubbo 调用 InventoryService.deduct(),3 秒超时
抛 RpcException: Timeout
@GlobalTransactional 触发回滚,账户扣款被回滚,订单未创建
业务侧返回"系统繁忙,请稍后重试"
Sentinel 触发熔断,后续 30 秒内直接拒绝请求(避免雪崩)
RocketMQ 消息未发送,无副作用

整套流程在 3 秒内完成——没有库存数据不一致,没有脏消息,没有雪崩。

八、总结:选型决策树与避坑清单

8.1 选型决策树

graph TD
 A[启动技术选型] --> B{业务规模?}
 B -->|日活<10万| C[单体 + Spring Boot]
 B -->|10万~100万| D{团队规模?}
 B -->|日活>100万| E{自研 vs 云?}
 
 D -->|<10人| F[Spring Cloud + Alibaba]
 D -->|>10人| G{有 Dubbo 基础?}
 
 G -->|有| H[SCA + Dubbo 3 混合]
 G -->|无| F
 
 E -->|自研为主| H
 E -->|全面上云| I[云原生全家桶 MSE/AHAS]
 
 style H fill:#457b9d,color:#fff
 style F fill:#a8dadc

结论:

< 10 万日活:单体 Spring Boot + MySQL,别上微服务
10-100 万日活:Spring Cloud Alibaba 套件足够
> 100 万日活:SCA + Dubbo 3 混合架构(本文方案)
超大规模(> 1000 万日活):上云原生 + Service Mesh

8.2 6 条避坑点

🛑 误区警示:这些坑别踩

盲目追新——Spring Cloud 还在用 2020.x 版本,公司新项目就上 2023.0.x,踩了一堆兼容性 bug。新版本至少观察 6 个月再上生产

混用多种 RPC 框架——服务 A 用 Dubbo、服务 B 用 Feign、服务 C 用 gRPC,团队没人能讲清楚。统一一套,要么 Dubbo,要么 Spring Cloud OpenFeign

Sentinel 规则没接 Dashboard——本地写了 @SentinelResource 但没接控制台,所有规则硬编码。生产前必须接 Dashboard,规则要可动态调整

Seata AT 模式没开 binlog——MySQL 没开 binlog,Seata AT 模式直接报错,临时改 TCC 又没时间。架构阶段就要确认 binlog 配置

Dubbo 2.7 升级 3.x 没灰度——直接全量升,服务发现模型变了,新模型在测试环境没压测过,生产雪崩。先灰度 10% 流量,观察 1 周再全量

Spring Cloud Gateway 跟 Spring MVC 混用——Gateway 是 WebFlux 响应式,跟业务模块的 Spring MVC 一起启动,Bean 冲突,启动直接报错。Gateway 单独部署,不和业务服务同进程

8.3 版本兼容性矩阵(2026.06 当前主流)

Spring Boot	Spring Cloud	Spring Cloud Alibaba	Nacos	Sentinel	Seata	Dubbo	备注
3.2.x	2023.0.x	2023.0.0.0	2.3.x+	1.8.6+	1.7+	3.2.x	最新版
3.1.x	2022.0.4	2022.0.0.0-RC1	2.3.x	1.8.6	1.6+	3.2.x	次主流
3.0.x	2022.0.x	2022.0.0.0	2.2.x+	1.8.6	1.6+	3.1.x	本文基线
2.7.x	2021.0.x	2021.0.x	1.4.x	1.8.4	1.5+	2.7.x	老项目在用

📌 实践:版本升级的"先小后大"原则

先升小版本(如 3.0.5 → 3.0.10),观察 1 周

再升次版本(3.0 → 3.1),灰度 10% 流量

最后升大版本(3.x → 4.x),至少 6 个月观察期

永远不要跨大版本直接升——除非你已经放弃了兼容性的执念,愿意重写。

九、常见问题 FAQ

Q1:Spring Cloud Alibaba 和"阿里云微服务引擎(MSE)“是什么关系?

A:MSE 是 SCA 核心组件的阿里云商业版。

Nacos 开源版 → MSE 商业版
Sentinel 开源版 → AHAS(应用高可用服务)
Seata 开源版 → GTS(全局事务服务)
Spring Cloud Gateway 开源版 → 云原生 API 网关

关系:核心代码同源,商业版加运维、监控、扩缩容能力。

小规模(< 50 服务):用开源版自建——成本低,够用
中规模(50-500 服务):核心组件商业版,周边组件开源——平衡
大规模(> 500 服务):全面上云原生——专业的事交给专业的

如果不想用阿里云,SCA 的核心组件都是 ASF/Apache 项目,可以在腾讯云、AWS、Azure 上自建或用对应商业服务。

Q2:Dubbo 3 和 OpenFeign 能不能在一个项目里混用?

A:完全可以,本文架构就是混用。

混用原则:

Dubbo 3 Triple:所有内部服务间的高 QPS 调用——性能优先
OpenFeign:跨业务线服务、第三方服务、前端 BFF 聚合——生态优先
不要在同一服务的同一调用链上混用——选择了一种就坚持到底

实战配比:Dubbo 80% + OpenFeign 20% 是健康的比例。

Q3:升级到 Spring Cloud Alibaba 2022.0.0.0(Spring Boot 3.x)的最大坑是什么?

A:javax → jakarta 命名空间切换。

Spring Boot 3.x 把 javax.servlet.* 全部改成 jakarta.servlet.*——所有第三方库必须升级。

MyBatis:升级到 3.5.x+
Hibernate Validator:升级到 8.x+
Servlet 容器:Spring Boot 3.x 内置 Tomcat 10+
所有 @Resource、@PostConstruct 等 不受影响(javax.annotation 仍兼容)

最稳的升级路径:

先升 Spring Boot 2.7 → 3.0(只改 spring-boot-starter 版本)
再升 javax.* → jakarta.*(用 IDE 全局替换)
最后升 Spring Cloud + SCA 到 2022.0.0.0

预计工作量:3 个月(50 个微服务规模)。别在双 11 前升。

Q4:Nacos 配置中心的数据怎么加密?

A:Nacos 1.4+ 支持配置加密。

1
2
3
4


# nacos 控制台 → 配置管理 → 新建配置
# DataId: order-service.yaml
# 加密配置:配置内容用 jasypt 或 nacos-aes 加密
# 客户端解密:配置 spring.cloud.nacos.config.ext-config

更推荐的方式:敏感配置放 KMS(密钥管理服务),不直接放 Nacos。

阿里云 KMS、腾讯云 KMS、AWS KMS
业务服务启动时从 KMS 拉取敏感配置,缓存在内存
Nacos 只放非敏感配置(超时时间、开关、限流阈值等)

Q5:Sentinel 集群限流怎么做?

A:Sentinel 集群限流依赖 Token Server。

单机限流只能保护单实例,但总流量超限时无法保护。集群限流把限流决策放到中心化 Token Server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


┌─────────┐ ┌─────────┐ ┌─────────┐
│ 实例 1 │ │ 实例 2 │ │ 实例 3 │
│ (Token │ │ (Token │ │ (Token │
│ Client) │ │ Client) │ │ Client) │
└────┬────┘ └────┬────┘ └────┬────┘
 │ │ │
 └────────────┼────────────┘
 ▼
 ┌────────────────┐
 │ Token Server │ ← 集群限流中心
 │ (Cluster) │
 └────────────────┘

生产配置:3 个 Token Server 节点 + Nacos 配置规则。所有 Sentinel Client 启动时连接 Token Server 拉取令牌。

注意:集群限流增加 1-2ms 延迟,延迟敏感场景要权衡。

Q6:Seata 在分库分表下能用吗?

A:能用,有限制。

AT 模式:支持分库分表——每个分片都是独立的数据源,Seata 会在每个分片创建 undo_log 表
TCC 模式:天然支持——分库分表对 TCC 是透明的
SAGA 模式:支持——补偿逻辑在分库分表上正常执行

注意:

ShardingJDBC + Seata 集成需要特殊配置:每个分片数据源都要注册到 Seata
全局锁在分库分表下是跨分片锁,性能会下降
建议:核心交易用 AT + 简单分片(< 16 个),复杂分片场景用 TCC

Q7:Spring Cloud Gateway 怎么实现"按 IP 限流”?

A:Sentinel 支持按 IP 限流。

1
2
3
4
5
6
7
8
9


@Bean
public GlobalFilter ipFilter() {
 return (exchange, chain) -> {
 String ip = exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();
 // 调 Sentinel API 限流
 Entry entry = SphU.entry("ip-rate-limit", 1, ip);
 return chain.filter(exchange).doFinally(s -> entry.exit());
 };
}

生产更推荐:用 Sentinel 控制台配 IP 黑白名单,不用写代码。

Q8:微服务怎么和单元化(第 1 篇的异地多活)结合?

A:这是 Java Web 微服务系列后续的重点。

简短回答:

Dubbo 3 标签路由:Dubbo 内置"按机房标签路由",结合 Nacos 的 cluster-name 元数据,自动隔离跨机房调用
Sentinel 集群限流:按机房分别限流,避免单机房过载拖垮全网
Seata:跨机房分布式事务强烈不推荐——跨机房延迟 30-100ms,事务延迟会飙升到秒级
消息:RocketMQ 跨机房用 同城双写 + 异地灾备,业务层做幂等消费

详细方案见系列第 7 篇「异地多活下的微服务治理」。

十、系列预告 + 推荐阅读

10.1 系列预告

这是 Java Web 微服务系列 的第 4 篇。后续计划覆盖:

序号	主题	状态
第 1 篇	异地多活(高可用终极形态)	✅ 已发布
第 2 篇	微服务拆分与领域建模	🔜 计划中
第 3 篇	服务治理:注册中心、配置中心、限流熔断	🔜 计划中
第 4 篇	技术选型(本文)	✅ 本文
第 5 篇	Nacos 实战:集群搭建 + 配置灰度	🔜 计划中
第 6 篇	Sentinel 实战:限流规则 + 熔断降级	🔜 计划中
第 7 篇	Seata 实战:AT/TCC 模式选型	🔜 计划中
第 8 篇	Dubbo 3 实战:Triple + 标签路由	🔜 计划中
第 9 篇	异地多活下的微服务治理	🔜 计划中
第 10 篇	全链路压测 + 混沌工程	🔜 计划中

💡 学习路径建议

入门:本文 + Nacos 官方文档

进阶:Dubbo 3 官方文档(https://dubbo.apache.org)

实战:研究 SCA 各组件 GitHub 仓库的 spring-cloud-alibaba-examples

深潜:动手搭一套完整 PoC(推荐 5 个服务:Order/Inventory/Account/Pay/Notify)

10.2 推荐阅读

官方文档:

书籍:

《Spring Cloud Alibaba 微服务原理与实战》(谭勇德)—— 国内最系统的 SCA 实战书
《深入理解 Apache Dubbo 与实战》(诣极、林琳)—— Dubbo 原理 + 实战
《数据密集型应用系统设计》(DDIA, Martin Kleppmann)—— 分布式系统圣经

开源项目(学习用)：

mall-swarm:macrozheng 开源,微服务电商完整 demo
Spring Cloud Alibaba Examples:官方 example 集合
Nepxion Discovery:分布式链路追踪 + 灰度发布

博客:

阿里中间件团队博客:Nacos/Sentinel/Seata 源码解析
美团技术团队:分布式服务治理实践
InfoQ 中文站:SCA 系列实战文章

📌 工程实践:技术选型不是一次性决策

本文写于 2026 年 6 月,但技术选型是 3-5 年的事。今天选的方案,2029 年大概率要再选一次。

选型时考虑的不是"哪个最对",而是"哪个能让我 3 年后再选一次"。留有演进空间比"一次选对"更重要。

参考文章

本文完。下篇预告:第 5 篇 · Nacos 实战:集群搭建 + 配置灰度。

服务拆分:康威定律、DDD 领域建模与生产落地指南

Tue, 09 Jun 2026 00:00:00 +0000

服务拆分:康威定律、DDD 领域建模与生产落地指南

Java Web 微服务系列 · 第 5 篇 · 服务拆分阅读时长:约 70 分钟本文写于 2026 年 6 月配套版本:Spring Cloud 2022.0.x / Spring Boot 3.x / Dubbo 3.2.x 前置阅读:《技术选型:为什么最终选了 Spring Cloud Alibaba + Dubbo 3》(系列第 4 篇) 后续衔接:《Nacos:Java 微服务的服务中心与配置中心怎么选、怎么用》(系列第 6 篇)

引子:38 个微服务大泥球的那一年

2021 年初我接手一个团队的微服务架构,上一任架构师留下的"遗产"是这样的:8 个业务域、38 个 Spring Boot 服务、2 个 PHP 老系统、3 个 Python 脚本、1 个没人敢动的 jQuery 前端。所有服务都通过 Eureka 注册,看起来"很微服务",但剖开看内核是一场灾难:

38 个服务共享同一个 MySQL 集群(16 个分库),改一个字段要同步 12 张表
几乎所有"业务服务"都依赖一个 9000 行的 user-core 服务,这个服务被 27 个上游调用,改一个方法签名要发 27 个版本
order-service、pay-service、inventory-service 三个服务循环依赖:order 调 pay 算价格、pay 调 order 查订单状态、inventory 调 pay 锁库存、pay 又反过来调 inventory 查库存数
4 个团队抢一个共享代码仓库 common-utils,每个团队都在里面塞自己的工具类,1 万 2 千行代码,谁都不敢删
一次普通的需求评审,需要协调5 个团队、2 周排期才能上线,因为每个服务都有自己的"上线窗口"

更让我崩溃的是 CEO 在季度会上问的问题:"我们已经是微服务了,为什么改个东西比 3 年前的单体还慢?"

我花了 3 个月调研、6 个月重构,才让这个系统从"38 个微服务大泥球"变成"12 个真正自治的服务"。这篇文章把那段经历的方法论 + 工具箱 + 实战案例 + 踩坑教训完整写出来。

本文不是讲 Spring Cloud 怎么配置(那是第 4 篇技术选型),也不是讲 Nacos 怎么部署(那是第 6 篇)。本文讲的是"为什么拆、怎么拆、拆错了怎么救"——也就是"先有边界,再有服务"的整套思维框架。

核心三块:

康威定律 + Team Topologies:为什么"组织"决定了"架构",以及怎么"反向"利用它
DDD 领域驱动设计:怎么用战术工具(实体/值对象/聚合根/限界上下文)识别真正的业务边界
5 条工业级拆分原则 + 6 个生产案例 + 10 个踩坑清单:把方法论落到代码、数据库、团队三个层面

一、拆分之前先想清楚:业务边界 = 团队边界 = 康威定律

“Any organization that designs a system… will inevitably produce a design whose structure is a copy of the organization’s communication structure.” —— Melvin Conway, 1967

1.1 康威定律的原始表述

1967 年,计算机科学家 Melvin Conway 在《How Do Committees Invent?》一文中提出一个观察:系统的设计结构,必然反映设计该系统的组织沟通结构。也就是说,如果你的团队有 4 个后端、2 个前端、1 个 DBA,那产出的系统大概率是"前端-后端-DBA 三层架构",而不是按业务域划分的微服务。

康威定律不是技术规律,是社会学规律——它描述的是"人和人怎么沟通"决定了"代码怎么组织"。一个团队 8 个人都在同一个 Slack 频道,他们写出来的代码大概率会在同一个代码仓库、用同一种技术栈、按同一种部署节奏发布。

1.2 推论:4 种系统设计映射组织结构

康威定律有 4 个广为流传的推论(Jim McCarthy):

Communication dictates design:组织沟通结构决定系统设计
Time and space:时间(同步/异步) + 空间(同地/异地) 影响协作效率
There’s never enough time to do it right, but always enough time to do it over:没时间做对,但有时间重做
The design that succeeds is the one that’s actually built:最终交付的设计才是设计

第 1 条是最致命的:你写的不是代码,是你团队沟通结构的镜像。一个 50 人团队按"前端组/后端组/DBA 组/测试组/运维组"分,不管他们多努力按业务域拆微服务,最后产出的还是"前端-后端"双层架构——因为沟通壁垒在团队结构里。

1.3 Inverse Conway Maneuver:先调组织,再调架构

既然康威定律说"组织决定架构",那反过来:先调整组织结构,再让架构跟着变。这就是 Jonny LeRoy 在 2009 年提出的 Inverse Conway Maneuver(反向康威)。

实际操作就 3 步:

画组织结构图:把当前团队的人员、汇报关系、Slack 频道、代码仓库权限全画出来
画系统架构图:把当前服务的依赖关系、数据库归属、部署关系全画出来
对比两张图,看哪里不一致:
- 团队结构和系统结构一致 → 康威定律在生效,这是好事
- 团队结构和系统结构不一致 → 架构师在跟康威定律对着干,这往往就是性能瓶颈的根因

我那次接手 38 个微服务大泥球时,画的组织结构图是这样的:

团队 A(订单业务):6 人,负责 order / pay / inventory 三个服务
团队 B(用户业务):4 人,负责 user / auth / address 三个服务
团队 C(运营业务):5 人,负责 marketing / coupon / points 三个服务
团队 D(基础平台):7 人,负责 gateway / config / monitor 等基础设施

但实际系统调用关系是:订单业务的服务有 30% 的调用跑到用户业务,15% 跑到基础平台,5% 跑到运营业务。团队边界和系统边界完全错位——这就是为什么一次改动要协调 5 个团队。

解决思路不是"让架构师硬性约束跨团队调用"(那只是治标),而是让团队边界和系统边界对齐。具体怎么对齐?这就是 1.4 要讲的 Team Topologies。

1.4 Team Topologies:4 种团队类型 + 3 种交互模式

2019 年,Matthew Skelton 和 Manuel Pais 出版了《Team Topologies》,把康威定律落地成可操作的团队设计模式。核心是把团队分成 4 种类型,互相之间用 3 种交互模式协作:

4 种团队类型:

类型	职责	典型人数	例子
Stream-aligned team	端到端负责一条业务流(从用户到数据库)	5-9	订单业务团队、用户中心团队
Enabling team	帮助 Stream-aligned 团队提升能力	3-5	安全赋能团队、可观测性赋能团队
Complicated-subsystem team	负责需要深度专业知识的复杂子系统	3-7	风控算法团队、推荐引擎团队
Platform team	提供内部平台(自助服务)给 Stream-aligned 团队用	5-12	K8s 平台团队、CI/CD 平台团队

3 种交互模式:

模式	含义	适用场景
Collaboration	紧密合作,共担责任	短期攻坚、新系统搭建初期
X-as-a-Service	一个团队消费另一个团队的服务,弱依赖	稳定子系统、跨域调用
Facilitating	一个团队帮另一个团队"扫除障碍"	能力建设、技术辅导

关键启示:

80% 的团队应该是 Stream-aligned(对应"业务域")
Platform team 不是万能的——平台做得太重会变成新的"巨石服务"
Complicated-subsystem team 的边界要稳,不能随便拆——风控算法不会因为组织调整而"换语言"

1.5 生产案例:某物流公司从 8 个职能团队 → 4 个业务团队

我 2022 年辅导过的一家物流公司,典型康威定律反例:

原组织(8 个职能团队):

Java 组 8 人、DBA 组 3 人、前端组 6 人、测试组 4 人、运维组 5 人、产品组 7 人、UI 组 3 人、数据组 4 人
系统架构:“前端-后端-DBA"三层单体,JSP + Spring MVC + 单库
痛点:改一个"运单状态变更"需求要走 6 个团队、3 周排期

新组织(4 个 Stream-aligned + 2 个支撑):

运单业务团队 7 人(含 1 个后端、1 个前端、1 个测试、1 个产品)—— 端到端负责"运单”
调度业务团队 6 人(同上结构)—— 端到端负责"调度"
司机业务团队 5 人 —— 端到端负责"司机 + 车辆"
财务业务团队 4 人 —— 端到端负责"对账 + 结算"
平台团队 8 人 —— 提供 K8s + 监控 + CI/CD 自助平台
赋能团队 3 人 —— 安全 + 可观测性

结果(6 个月后):

每个 Stream-aligned 团队自己决定技术栈、自己决定发布节奏——运单团队用 Java、调度团队用 Go、司机团队用 Node.js 都可以
部署频率从 1 次/周 → 30 次/天(从 CI/CD 平台拿指标)
MTTR(平均恢复时间)从 4 小时 → 15 分钟(因为业务团队对代码全栈负责,排查不需要跨团队)
改一个"运单"需求,从 3 周 → 2 天(一个团队内部闭环)

这个案例的关键不是"用了微服务",而是"先改了组织,后改的架构"。如果只改架构不改组织,38 个微服务大泥球的悲剧会再上演。

1.6 启示:拆分前先问 3 个问题

回到我自己 2021 年的处境,看完 Team Topologies 后,我在拆分前先问了 3 个问题:

业务边界是什么? —— 我们公司的核心业务流是"下单 → 支付 → 库存 → 物流",沿这条流切业务域
团队边界应该是什么? —— 按业务域组建 4-5 个 Stream-aligned 团队,而不是按"前端/后端/DBA"
业务边界 ≠ 团队边界时,谁先动? —— 永远是组织先动。架构师单方面"按业务拆服务"而不调组织,会变成"38 个微服务大泥球"

这一节建立的认知是:服务拆分不是"技术活",是"组织工程"。下一节讲的 DDD,则是"怎么识别业务边界"的方法论工具箱。

二、领域驱动设计:战术工具箱

上一节讲了"为什么拆"(康威定律、组织先行)。这一节讲"按什么拆"——DDD 给的战术工具。战略设计:识别业务边界(限界上下文) 战术设计:在一个上下文内怎么写代码(实体/值对象/聚合根/领域服务)

Eric Evans 2003 年的《Domain-Driven Design》中文版叫《领域驱动设计》,核心思想:软件的核心是它所服务的领域(domain),技术是手段。DDD 不是一套框架,是一套思维方式 + 一组战术工具,专门解决"复杂业务怎么拆分"这个问题。

我把 DDD 工具箱按"先用、后用"分成两层:**战略层(限界上下文)**先识别业务边界,**战术层(实体/值对象/聚合根)**再在一个上下文内写代码。

2.1 战略层:限界上下文(Bounded Context)

限界上下文是 DDD 最重要的概念,没有之一。

定义:一个限界上下文 = 一个业务领域 + 一套统一语言 + 一个代码边界。在限界上下文内部,术语含义是确定的(比如"订单"特指电商订单);跨限界上下文时,术语含义可能不同(比如"账户"在用户中心指"用户登录账号",在支付中心指"钱包账户")。

实战:电商系统的限界上下文切分

限界上下文	核心语言	职责	对应微服务
销售上下文	订单/购物车/优惠	创建订单、计算价格、应用优惠	order-service / cart-service / promotion-service
支付上下文	交易/退款/钱包	收款、退款、对账	pay-service / refund-service / wallet-service
库存上下文	SKU/库存/预占	库存数量管理、预占/释放	inventory-service / warehouse-service
物流上下文	运单/配送/签收	运单创建、配送调度、签收记录	logistics-service / dispatch-service
用户上下文	用户/地址/等级	用户信息、收货地址、会员等级	user-service / address-service / member-service
营销上下文	优惠券/积分/活动	优惠券发放、积分累积、活动配置	coupon-service / points-service / campaign-service

关键判断:为什么"订单"和"支付"必须分两个上下文?

因为它们的"核心语言"不同:

订单上下文里"订单" = 一份意图(“我想买 X 商品,共 100 元”)
支付上下文里"交易" = 一笔事实(“我已支付 100 元,支付渠道是支付宝”)

订单和支付通过领域事件(OrderCreated、PaymentCompleted)异步解耦,而不是订单服务直接调支付服务同步收钱。这种"异步 + 事件"的设计,是微服务拆分后避免分布式事务的第一道防线。

2.2 战术层 1:实体(Entity) vs 值对象(Value Object)

实体:有唯一标识(ID)、生命周期可变、状态可变的对象。例:Order(orderId=20240101001)、User(userId=10086)。

值对象:没有唯一标识、不可变、只描述属性的对象。例:Address(地址)由"省/市/区/详细地址"组成,两个完全相同的地址可以互相替换;Money(金额)由"数字 + 货币类型"组成,5 元和 5 元是等价的。

实战对比:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// ❌ 反例:用实体表示地址(过度设计)
@Entity
public class Address {
 @Id
 private Long id; // 地址有自己的 ID
 private String province;
 private String city;
 // ... getter/setter
}

// ✅ 正例:用值对象表示地址(不可变,按值相等)
@Value
@Builder(toBuilder = true)
public class Address {
 private String province; // 省
 private String city; // 市
 private String district; // 区
 private String detail; // 详细地址
}
// 值对象的好处:User 修改地址时,直接 setAddress(new Address(...))
// 不用考虑"旧地址对象要不要清空引用"

判断口诀:

有 ID 吗?有 → 实体;没有 → 值对象
可变吗?可变 → 实体;不可变 → 值对象
生命周期独立吗?独立 → 实体;依附于其他对象 → 值对象

2.3 战术层 2:聚合根(Aggregate Root) — DDD 最难也最重要的概念

聚合根 = 一组紧密相关的实体 + 值对象的"管理者",外部访问聚合内部的实体,只能通过聚合根。

经典案例:订单聚合

1
2
3
4
5
6
7
8


Order (聚合根)
├── OrderItem (实体) — 订单项
│ ├── SkuId
│ ├── Quantity
│ └── UnitPrice
├── ShippingAddress (值对象) — 收货地址
├── Buyer (值对象) — 买家信息
└── OrderStatus (枚举) — 订单状态

聚合根的不变式(invariant):

订单必须有 1 个或多个 OrderItem,不能有 0 个
订单的总金额 = 所有 OrderItem 的数量 × 单价之和(永远一致)
订单创建后,收货地址不能修改(可以修改前 cancel + recreate)
订单状态转换有规则:CREATED → PAID → SHIPPED → COMPLETED,不能跳过

这些规则只在聚合根 Order 内执行,外部服务(支付、物流)不能直接改 OrderItem,只能通过 Order 暴露的方法(order.pay()、order.ship())间接修改。

实战代码(Spring Boot + JPA):

 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


@Entity
@Table(name = "t_order")
public class Order {
 @Id
 private String orderId;
 
 // 聚合根内部包含实体和值对象
 @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.EAGER)
 @JoinColumn(name = "order_id")
 private List<OrderItem> items = new ArrayList<>();
 
 @Embedded
 private ShippingAddress shippingAddress;
 
 @Enumerated(EnumType.STRING)
 private OrderStatus status;
 
 // 不变式:通过聚合根的方法保证
 public void addItem(SkuId skuId, Quantity qty, Money unitPrice) {
 if (status != OrderStatus.CREATED) {
 throw new IllegalStateException("只有 CREATED 状态的订单能加商品");
 }
 this.items.add(new OrderItem(skuId, qty, unitPrice));
 }
 
 public Money totalAmount() {
 return items.stream()
 .map(item -> item.getUnitPrice().multiply(item.getQuantity().value()))
 .reduce(Money.ZERO, Money::add);
 }
 
 public void pay() {
 if (status != OrderStatus.CREATED) {
 throw new IllegalStateException("只有 CREATED 状态的订单能支付");
 }
 if (items.isEmpty()) {
 throw new IllegalStateException("空订单不能支付");
 }
 this.status = OrderStatus.PAID;
 // 领域事件:发布 OrderPaid 事件
 registerEvent(new OrderPaidEvent(this.orderId, totalAmount()));
 }
}

聚合根的"事务边界"价值:

一个聚合根 = 一个事务边界。改一个聚合根内的多个实体,在同一个数据库事务里(因为它们物理上在同一张表或同一组表)。跨聚合根的修改,必须用最终一致性(领域事件),不能用分布式事务(2PC/Saga)。

这是拆分微服务后最关键的事务策略——同一个微服务内部的多个表 = 强一致性(本地事务);跨微服务的数据 = 最终一致性(事件 + 对账)。

2.4 战术层 3:领域服务(Domain Service) vs 应用服务(Application Service)

层级	职责	是否持有状态	例子
实体 / 值对象	业务逻辑、自身状态变更	有	Order.pay()、User.changePassword()
领域服务	跨实体的业务规则、不属于任何实体的逻辑	无状态	PriceCalculator(算价格,跨 OrderItem + Promotion)
应用服务	编排用例、事务边界、外部调用	无状态	OrderApplicationService.createOrder()
基础设施	数据库、消息、缓存、RPC	有	OrderRepository、EventPublisher

实战案例:下单流程

 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


// ✅ 应用服务:编排用例(不写业务规则)
@Service
public class OrderApplicationService {
 @Autowired private OrderRepository orderRepository;
 @Autowired private PriceCalculator priceCalculator; // 领域服务
 @Autowired private InventoryService inventoryService; // 外部服务
 @Autowired private EventPublisher eventPublisher;
 
 @Transactional
 public Order createOrder(CreateOrderCommand cmd) {
 // 1. 创建订单(聚合根内部的不变式)
 Order order = new Order(cmd.getBuyer(), cmd.getShippingAddress());
 
 // 2. 调领域服务算价格
 for (OrderItemCommand item : cmd.getItems()) {
 Money unitPrice = priceCalculator.calculate(item.getSkuId(), item.getQuantity());
 order.addItem(item.getSkuId(), item.getQuantity(), unitPrice);
 }
 
 // 3. 预占库存(跨聚合根,走最终一致性)
 inventoryService.reserve(order.getOrderId(), order.getItems());
 
 // 4. 保存
 orderRepository.save(order);
 
 // 5. 发布领域事件
 order.getDomainEvents().forEach(eventPublisher::publish);
 
 return order;
 }
}

判断口诀:

逻辑只涉及一个实体?→ 写在实体里
逻辑跨多个实体、但只涉及领域?→ 写在领域服务里
逻辑涉及"调用外部系统、事务边界、事件发布"?→ 写在应用服务里

2.5 战术层 4:领域事件(Domain Event)

领域事件 = 业务上已经发生的事实。“OrderCreated"是事实,“CreateOrderCommand"是意图(还没发生)。

事件结构:

1
2
3
4
5
6


public class OrderPaidEvent {
 private String orderId;
 private Money amount;
 private Instant paidAt;
 // getter...
}

事件命名:用过去时态(OrderPaid、PaymentCompleted、InventoryReserved),不要用"动作时态”(CreateOrder 这种是命令不是事件)。

实战消费:支付完成后,触发物流 + 积分 + 通知三个动作

 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


// 支付服务发布事件
@EventPublisher
public class PaymentApplicationService {
 public void handlePayment(PaymentCommand cmd) {
 // ... 处理支付 ...
 eventPublisher.publish(new PaymentCompletedEvent(cmd.getOrderId(), cmd.getAmount()));
 }
}

// 物流服务订阅
@EventHandler
public class LogisticsEventHandler {
 public void on(PaymentCompletedEvent event) {
 // 创建运单、调度配送
 shipmentService.createShipment(event.getOrderId());
 }
}

// 积分服务订阅
@EventHandler
public class PointsEventHandler {
 public void on(PaymentCompletedEvent event) {
 // 加积分
 pointsService.addPoints(event.getBuyerId(), event.getAmount());
 }
}

关键设计原则:

事件是不可变的(已经发生的事不能改)
事件订阅是异步的(支付服务不等物流服务完成)
事件要有版本号(v1、v2),演化时兼容老版本
事件持久化到消息中间件(Kafka/RocketMQ),消费者崩溃可重放

2.6 上下文映射(Context Map):跨上下文怎么协作

当限界上下文确定后,跨上下文怎么交互?这就是上下文映射要解决的问题。 常见 9 种模式(选最常见的 4 种):

模式	含义	实战例子
Partnership(伙伴)	两个上下文互相依赖、同步演进	订单 ↔ 库存(双向紧密配合)
Customer-Supplier(客户-供应商)	上游提供服务、下游消费	支付服务 → 订单服务(上游)
Anti-Corruption Layer(防腐层)	翻译老系统的"烂接口”	集成遗留 ERP 时加 ACL
Shared Kernel(共享内核)	两个上下文共享一小段代码	共享 `Money` 值对象

ACL(防腐层)实战:对接老 ERP 系统

老 ERP 系统的接口是这样的(典型的"大泥球"对外暴露):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 老 ERP 的返回结构(各种字段混在一起)
public class ErpLegacyResponse {
 private String order_id_erp; // 下划线命名
 private String user_no;
 private String sku_code;
 private int qty;
 private double price_rmb; // 混币种
 private String status_code; // "01"/"02"/"99" 这种魔数
 private String memo; // 万能字段
 // ... 200 多个字段
}

不写 ACL 的下场:订单服务里全是 if (status.equals("01")) { ... } else if (status.equals("02")) { ... } 这种魔数判断,改一次 ERP 字段全崩。

写 ACL 的实战:

 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


// 1. 在订单服务里定义自己的领域模型
public class Order {
 private OrderId orderId;
 private OrderStatus status; // 枚举:PAID / SHIPPED / COMPLETED
 private Money totalAmount;
 // ...
}

// 2. ACL 把老 ERP 的"魔数"翻译成领域枚举
@Component
public class ErpAntiCorruptionLayer {
 public Order translate(ErpLegacyResponse erp) {
 return new Order(
 new OrderId(erp.getOrder_id_erp()),
 translateStatus(erp.getStatus_code()),
 new Money(BigDecimal.valueOf(erp.getPrice_rmb()), Currency.CNY),
 // ... 字段映射
 );
 }
 
 private OrderStatus translateStatus(String erpCode) {
 return switch (erpCode) {
 case "01" -> OrderStatus.PAID;
 case "02" -> OrderStatus.SHIPPED;
 case "99" -> OrderStatus.COMPLETED;
 default -> throw new IllegalArgumentException("未知 ERP 状态: " + erpCode);
 };
 }
}

// 3. 订单服务的其他代码只看 Order,不接触 ErpLegacyResponse
@Service
public class OrderSyncService {
 @Autowired private ErpAntiCorruptionLayer acl;
 
 public void syncFromErp(String erpOrderId) {
 ErpLegacyResponse erp = erpClient.getOrder(erpOrderId);
 Order order = acl.translate(erp); // ACL 翻译
 orderRepository.save(order);
 // 业务代码只看 Order
 }
}

ACL 是微服务拆分中最被低估的设计。每当你要"集成老系统"“对接外部第三方"“统一多个数据源"时,先想 ACL——不要让外部的脏数据污染你的领域模型。

2.7 事件风暴(Event Storming):DDD 的工作坊方法

事件风暴是 Alberto Brandolini 2013 年提出的 DDD 工作坊方法,核心是用"事件"驱动团队讨论业务,最终识别出限界上下文、聚合根、领域事件。

15 步流程(简化版,1-2 天):

邀请业务专家 + 开发 + 测试 + 运维(全栈人员,10 人左右)
准备一面大白墙 + 橙色便签(领域事件) + 蓝色便签(命令) + 黄色便签(外部系统) + 紫色便签(问题)
从业务流程的"起点"开始(如"用户下单”),贴第 1 个事件便签:OrderCreated
依次向后推演:用户支付 → PaymentCompleted,库存预占 → InventoryReserved,发货 → ShipmentDispatched,签收 → ShipmentDelivered
每个事件前面贴一个命令:用户想下单 → CreateOrder,支付 → PayOrder
事件之间识别"聚合根”:OrderCreated + OrderPaid + OrderShipped + OrderCompleted 围绕 Order
聚合根按业务相关性归类 → 限界上下文:Order、Pay、Inventory 三个聚合根 → 销售上下文
画上下文边界:不同上下文用不同颜色便签区分
识别上下文映射:Order → Inventory(下游消费)、Order → Pay(下游消费)
补充遗漏:贴紫色便签写"未解决的问题"“模糊的业务规则”
优先级排序:最重要的 1-2 个上下文先实施

事件风暴的价值:

业务专家第一次和开发面对面讨论流程,消除了"开发自以为是"和"业务想当然"
可视化产出物就是微服务的拆分依据
一次事件风暴的结果能用 6-12 个月——边界识别后,微服务边界、API 边界、数据库边界都按这个走

我那次 38 个微服务大泥球重构,关键的"销售上下文/支付上下文/库存上下文"划分,就是 2 天事件风暴的产物。没有一个架构师能独自想清楚业务边界,必须业务专家+开发+测试一起推演。

三、微服务拆分 5 条工业级原则

上一节讲了 DDD 工具箱(限界上下文、聚合根、领域事件、ACL、事件风暴),这一节讲把这套工具落到"代码 + 数据库 + 团队"上的 5 条工业级原则。这 5 条不是教条,是"踩过 38 个大泥球"后归纳的"高概率正确"经验。

3.1 原则 1:单一业务职责(One Bounded Context, One Service)

口诀:一个微服务 = 一个限界上下文 = 一组紧密相关的聚合根。

反例:把订单、支付、物流、库存放在一个"交易服务"里——这是单体服务的微服务外壳,依然是大泥球。看起来是微服务,实际部署 1 次要协调 4 个业务的发布窗口,本质还是单体。

正例:

订单服务:只管 Order 聚合(订单 + 订单项)
支付服务:只管 Payment 聚合(交易 + 退款)
库存服务:只管 Inventory 聚合(SKU 库存 + 预占)

判断标准:用"如果改这个服务,需要不需要协调其他业务团队"作为标尺。

改一个服务,需要另一个业务团队配合 → 拆得不够细
改一个服务,只影响当前业务团队 → 拆得刚好
改一个服务,只影响 1-2 个聚合根 → 可能拆得太细(每个聚合根一个服务是过度拆分)

“拆得太细"的反模式:Order、OrderItem、OrderAddress 三个服务(订单项、地址独立成服务)。问题是:OrderItem 离开 Order 没意义,OrderAddress 离开 Order 也没意义,它们的生命周期和 Order 完全绑定,这种"拆"只是把本地事务变成了分布式事务,徒增复杂度。

3.2 原则 2:边界自治(Autonomy) — 数据库隔离是底线

口诀:一个微服务 = 一套独立的数据库(Schema/DB),不共享表、不共享连接池、不跨服务 JOIN。

反例(38 个大泥球的核心病灶):

38 个服务都连同一个 MySQL 集群
订单服务 SELECT * FROM t_user WHERE user_id = ? 跨服务读用户表
支付服务 UPDATE t_inventory SET stock = stock - 1 跨服务改库存
一旦 DBA 把 t_user 改个字段名,38 个服务全挂

正例:

订单库 t_order、t_order_item(订单库独享)
支付库 t_payment、t_refund(支付库独享)
库存库 t_inventory、t_reservation(库存库独享)
跨服务要数据,只能通过 API 或事件,不能直接 SQL 查

实战:订单服务要查用户地址怎么办?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// ❌ 反例:跨库 JOIN
@Query("SELECT o.*, a.detail FROM t_order o JOIN t_user_address a ON o.user_id = a.user_id WHERE o.order_id = ?")
OrderDetail findDetail(String orderId);

// ✅ 正例:通过 OpenFeign 调用用户服务
@FeignClient("user-service")
public interface UserServiceClient {
 @GetMapping("/api/v1/users/{userId}/addresses/{addressId}")
 AddressDTO getAddress(@PathVariable Long userId, @PathVariable Long addressId);
}

@Service
public class OrderQueryService {
 @Autowired private UserServiceClient userClient;
 
 public OrderDetail getDetail(String orderId) {
 Order order = orderRepository.findById(orderId).orElseThrow();
 AddressDTO addr = userClient.getAddress(order.getBuyerId(), order.getAddressId());
 return new OrderDetail(order, addr);
 }
}

为什么"数据库隔离"这么重要?因为它是微服务"可独立演进"的技术底线。共享数据库时,改一个表要协调所有用的服务;隔离后,改库 = 改当前服务,不用协调别人。

3.3 原则 3:独立演进(Independent Evolution) — 接口稳定、内部可改

**口诀:微服务的 API 接口(对外暴露的 OpenAPI/gRPC IDL)**一旦发布,就尽量不改;实现细节(代码、数据库、缓存)可以随时重构。

反例(常见的"服务失控”):

支付服务 V1 接口 POST /api/pay 返回 { "payId": "P001" }
3 个月后产品改需求,支付服务改返回 { "transactionId": "P001" }
订单服务 27 个调用方全挂
支付团队为了不挂调用方,把"transactionId" 改回 “payId” 但内部多加一个"transactionId" 字段(双写)——API 越来越乱,最终没人敢动

正例:版本化 API + 内部实现可改:

支付 V1:POST /api/v1/pay 返回 { "payId": "P001" } —— 永久保留,标记 deprecated
支付 V2:POST /api/v2/pay 返回 { "transactionId": "P001" } —— 新接口
订单服务新代码用 V2,老代码保留 V1(并设 6 个月废弃时间表)
支付服务内部实现可改:V1/V2 共享同一个 PaymentAppService,只是 Controller 层路由不同

“接口稳定"的额外保障:

用 OpenAPI 3.0 规范写接口(代码生成,人写容易漏)
改接口前先在 API 仓库发 RFC,所有调用方在 PR 里 ack
没有 ack 的 PR 不能合 master(流程强制)

“内部可改"的边界:

改一个服务的代码 → 这个服务的 owner 团队自己决定
改数据库表结构 → 同上
改 API 契约 → 必须走 RFC 流程

3.4 原则 4:可观测(Observability) — 拆不开就先建观测

口诀:在拆之前先把"链路追踪 + 统一日志 + 指标监控"建好,否则一拆就崩。

我见过很多团队直接拆 38 个服务,但没建观测系统,结果:

一个请求跨 8 个服务,出问题不知道卡在哪
18 个服务都在打 ERROR 日志,但日志格式不统一,grep 不到
数据库慢查询没法定位是哪个服务发的
2 周后 38 个服务重新合并回 1 个单体(因为没人能维护)

可观测的 3 大支柱:

链路追踪(Tracing):一个请求的全链路调用图,看到每个服务的耗时、错误
- 工具:Jaeger、Zipkin、SkyWalking
- 关键字段:traceId(全局唯一)、spanId(单服务内唯一)、parentSpanId(上游)
统一日志(Logging):结构化日志(JSON 格式),带 traceId 串联
- 工具:ELK(Elasticsearch + Logstash + Kibana)、Loki
- 关键字段:traceId、serviceName、level、message、timestamp
指标监控(Metrics):服务的 QPS、错误率、延迟 P99、JVM/DB 连接池
- 工具:Prometheus + Grafana
- 关键指标:RED 方法(Rate 请求数 / Error 错误数 / Duration 延迟)

生产案例:38 个大泥球重构前的"先建观测”:

第一周:全员接入 SkyWalking(零业务代码改动,只加 Java agent)
第二周:把 27 个服务的日志改成 JSON 格式,接 ELK
第三周:Prometheus + Grafana 上线,所有服务的 QPS / 错误率 / 延迟可视化
第四周开始拆服务——这时的可观测是"边拆边看”,不是"先拆再补"

反观测的反模式:

服务 A 用 Logback 写文本日志,服务 B 用 Log4j2 写 JSON 日志,服务 C 直接 System.out.println
每个服务有自己的"日志格式",运维同学想找一条 ERROR,要用 3 种不同的 grep
建观测的第一件事就是统一日志格式(建议 SLF4J + Logback + JSON Encoder)

3.5 原则 5:数据收敛(Data Convergence) — 每个服务管自己的数据

口诀:一个服务 = 一份权威数据源(Source of Truth),其他服务要这个数据,只能"订阅"或"调用"。

反例(数据散落是分布式系统的"癌症"):

用户名"张三"在用户表、订单表、支付表、物流表里都有一份
用户改了昵称"张三" → “Zhang San”,只有用户表更新
订单表、物流表、支付表里还是"张三"
用户看到订单详情里"买家:张三",但个人中心显示"Zhang San"——数据不一致

正例:事件驱动的数据同步

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 用户服务:用户改昵称,发布 UserProfileChanged 事件
@EventPublisher
public class UserApplicationService {
 public void changeNickname(UserId userId, String newNickname) {
 User user = userRepository.findById(userId).orElseThrow();
 user.changeNickname(newNickname);
 userRepository.save(user);
 eventPublisher.publish(new UserProfileChangedEvent(userId, newNickname));
 }
}

// 订单服务:订阅 UserProfileChanged,更新自己表里的冗余字段
@EventHandler
public class OrderEventHandler {
 public void on(UserProfileChangedEvent event) {
 // 异步更新订单表里的冗余字段
 orderRepository.updateBuyerNickname(event.getUserId(), event.getNewNickname());
 }
}

“数据收敛"的关键设计:

唯一权威源:用户的"昵称"只在用户表里是权威,其他表是冗余/快照
事件传播:权威源变更时,广播事件,下游订阅更新自己的冗余
最终一致性:事件传播有延迟(秒级/分钟级),下游最终会和权威源一致
容忍延迟:下游查询要容忍"短暂不一致”——比如订单详情显示"张三"(用户表已变"Zhang San",事件还没到),用户看到的不是最新昵称

为什么不能"实时同步"(同步双写)?

用户改昵称 → 同步调 27 个服务的更新接口
一个服务慢 5 秒,用户就卡 5 秒
一个服务挂了,用户改昵称失败
同步链 = 死链,异步事件 = 活链

数据收敛的 4 个层次(选你需要的):

层次	含义	适用场景
L1 - 强一致(本地事务)	一个聚合根内多表	单服务内部(默认)
L2 - 最终一致(领域事件)	跨服务冗余数据	用户昵称、订单买家快照
L3 - 异步对账(批处理)	跨服务数据校验	T+1 对账、库存盘点
L4 - 妥协查询(直接跨库)	实在没时间做事件同步	老系统迁移期临时方案(必须标记技术债)

反模式:用分布式事务(Seata AT 模式)代替事件——所有跨服务都 Seata 一把梭哈,看似简单,实际性能极差 + 耦合极重,任何服务挂都拖垮全局。Seata 在第 14 篇会细讲,这里只说:优先事件 + 最终一致,只在"必须强一致"的核心金融场景用 Seata。

四、生产场景 6 个真实案例

前三节讲方法论(康威 + DDD + 5 原则),这一节讲 6 个真实的"拆分"案例。每个案例都给:背景、痛点、解决方案、结果、教训。案例来源:3 个来自本人亲历(脱敏处理),3 个来自公开技术博客/技术大会。

4.1 案例 1:订单中台拆分 — 从"巨型 Order"到 5 个领域服务

背景:某 B2B 电商公司,2018 年起家的单体系统,所有业务(订单、库存、支付、促销、会员)都在一个 Spring Boot 应用的 com.xx.order 包下,3 年后这个包代码量达到 67 万行,部署时间 40 分钟。

痛点:

改一行订单代码,整个应用重新编译 + 部署
任何一个小问题都要全量回滚,影响所有业务
团队扩张到 25 人后,合并冲突每天 30+ 次
QPS 撑不住双 11,只能堆机器(已堆到 80 台)

拆分方案(按 DDD 限界上下文):

拆分后服务	聚合根	独立数据库	团队
order-service	Order + OrderItem	订单库 8 张表	订单团队 7 人
inventory-service	Inventory + Reservation	库存库 5 张表	库存团队 5 人
pay-service	Payment + Refund	支付库 4 张表	支付团队 5 人
promotion-service	Coupon + ActivityRule	营销库 6 张表	营销团队 4 人
member-service	Member + Address + Points	会员库 7 张表	会员团队 4 人

关键技术决策:

绞杀者模式(Strangler Fig):新服务逐步替代老接口,而不是一次性"big bang"
API 网关做路由:老接口 /api/legacy/order/* 路由到旧代码,新接口 /api/v2/order/* 路由到新服务
数据双写期 3 个月:老库新库同步写,读用开关切换,逐步放量
事件总线:用 Kafka 做领域事件总线,5 个服务通过 Topic 解耦

结果(6 个月后):

部署时间从 40 分钟 → 单服务 2 分钟
故障爆炸半径从 80 台机器 → 单服务 2-4 台
团队独立发布,从 1 次/周 → 30 次/天
双 11 QPS 峰值从 8000 → 35000(横向扩展更容易)

教训:

第一刀最难——拆第一个服务(order-service)花了 4 个月,后面拆每个服务 1-2 个月
数据双写期一定要有"开关"——不能"老库写、新库不写",必须有双写开关和读开关,出问题秒级回滚
遗留的"老接口"不要立即删——保留 6-12 个月,等所有调用方迁完再删

4.2 案例 2:用户中心拆分 — 多端数据收敛

背景:某社交 App,用户数据散落在 5 个服务里(账号、资料、关系链、设置、设备),每个服务都有自己的 t_user_xxx 表,改一个"昵称"字段要协调 5 个服务。

痛点:

用户改昵称,5 个服务并发更新,经常 2-3 个成功 2-3 个失败,数据长期不一致
“查看用户主页"要调 5 个服务的 API,任何一个慢,主页就慢
新接入业务(如"创作者中心”)要复制一份用户数据,造成"数据散落"恶性循环

拆分方案:

保留一个权威的 user-core 服务(管账号、昵称、头像、状态)
其他服务只冗余需要的字段(如订单服务冗余"昵称"+“头像"用于列表展示)
用 UserProfileChanged 事件传播,下游服务订阅并更新自己表的冗余字段
设置、设备这种"用户私有的配置"下沉到 user-settings 服务,有自己的存储

关键代码:

 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


// user-core:权威源
@Entity
public class User {
 @Id private Long userId;
 private String nickname;
 private String avatarUrl;
 // ... 只有这几个字段是"权威"
}

@EventPublisher
public void changeNickname(Long userId, String newNickname) {
 User user = userRepository.findById(userId).orElseThrow();
 String oldNickname = user.getNickname();
 user.setNickname(newNickname);
 userRepository.save(user);
 // 发布事件,所有订阅方异步更新冗余字段
 eventPublisher.publish(new UserProfileChangedEvent(userId, oldNickname, newNickname, Instant.now()));
}

// 订单服务:订阅,更新冗余
@EventHandler
@Transactional
public void on(UserProfileChangedEvent event) {
 orderRepository.updateBuyerSnapshot(event.getUserId(), event.getNewNickname());
}

结果:

用户改昵称:从 5 服务并发同步 → 1 服务本地事务 + 事件广播
改昵称 P99 延迟:从 800ms → 80ms
数据最终一致时间:通常 2-5 秒,最坏 30 秒
2 年内 0 起"用户数据不一致"工单

教训:

冗余是"成本"不是"问题”——核心问题不是"有冗余",而是"冗余没人维护"
事件总线要持久化 + 重试 + 死信队列——下游消费失败必须能重放,否则数据永久不一致
对账作业不能少——每天 T+1 跑一次"权威源 vs 冗余"对比,发现不一致人工补

4.3 案例 3:支付链路拆分 — 强弱一致的分层

背景:某支付公司,核心是"用户充值 → 钱包账户 → 提现"链路。原架构是 1 个大的 pay-service,内部 5 个模块:账户、充值、提现、对账、风控。

痛点:

5 个模块耦合,改一个"提现限额"要重新部署整个 pay-service
风控规则改 1 行,必须经过全套回归测试
大促时充值并发高,把对账的 CPU 也吃光了

拆分方案(按"强弱一致分层"原则):

account-service:钱包账户(强一致,本地事务)
recharge-service:充值(本地事务)
withdraw-service:提现(本地事务)
risk-service:风控规则(无状态,规则引擎)
reconcile-service:对账(批处理,独立部署,资源隔离)

关键设计:

account-service 的余额修改用本地事务 + 行锁(强一致,绝不能错)
充值流程:用户 → recharge → 调第三方支付 → 回调 → recharge → 发 RechargeSuccess 事件 → account 消费事件 + 加余额
加余额是本地事务,但充值和加余额是最终一致——中间失败靠对账兜底

结果:

单服务 QPS 提升 5 倍(资源隔离,不再相互影响)
风控规则改一行代码,30 秒上线(独立部署)
大促期间 0 起"对账延迟"事故(批处理资源隔离)

教训:

不是所有支付场景都要"强一致"——充值链路可以"最终一致 + 对账",但钱包余额必须"强一致"
“分而治之"在金融场景特别重要——把"实时链路"和"批处理链路"拆开,避免相互挤兑资源

4.4 案例 4:数据一致性 — 事件总线的 4 道防线

背景:某零售公司,营销活动期间单日订单 50 万,涉及 12 个服务的协同,经常出现"订单已支付,库存没扣"“用户已退款,钱包没加"等不一致问题。

痛点:

事件丢失:Kafka 偶发重平衡,消费者没收到事件
重复消费:网络抖动导致事件重发
顺序错乱:用户退款事件比支付事件先到
状态错位:服务 A 说"已发货”,服务 B 说"待支付”

解决方案:事件总线的 4 道防线

 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


// 1. 持久化 + 至少一次语义(防丢失)
@KafkaListener(topics = "OrderPaidEvent", groupId = "inventory-service")
public void onMessage(OrderPaidEvent event) {
 // 持久化到本地 outbox 表
 outboxRepository.save(new OutboxRecord(event.getEventId(), event, "PENDING"));
 // 业务处理
 inventoryService.reserve(event.getOrderId(), event.getItems());
 // 处理完标记
 outboxRepository.markProcessed(event.getEventId());
}

// 2. 幂等消费(防重复)
@Service
public class InventoryEventHandler {
 public void on(OrderPaidEvent event) {
 // 用 eventId 去重:同样的 eventId 处理过一次就跳过
 if (processedRepository.exists(event.getEventId())) {
 return;
 }
 inventoryService.reserve(event.getOrderId(), event.getItems());
 processedRepository.save(event.getEventId(), Instant.now());
 }
}

// 3. 顺序保证(防错乱)
// Kafka 的 partition key 选 orderId,同一个订单的所有事件进同一个 partition
@Bean
public NewTopic orderPaidTopic() {
 return TopicBuilder.name("OrderPaidEvent")
 .partitions(12)
 .replicas(3)
 .config("min.insync.replicas", "2")
 .build();
}
// 生产时用 orderId 作为 key
kafkaTemplate.send("OrderPaidEvent", orderId, event);

// 4. 死信队列 + 人工兜底(防状态错位)
@KafkaListener(topics = "OrderPaidEvent.DLQ", groupId = "dlq-handler")
public void onDlq(OrderPaidEvent event) {
 alertService.sendAlert("事件处理失败,需人工处理", event);
}

4 道防线的成本与收益:

持久化:性能开销 5%,一致性提升 80%
幂等:代码复杂度 +20%,重复消费问题清零
顺序:Kafka 分区策略调优,顺序性提升到 99.99%
死信队列:人工兜底,极端情况仍有出路

结果:

不一致工单:从月均 30 起 → 0 起
大促后对账:T+1 自动对账,人工补单率 < 0.001%

教训:

不要相信"消息中间件一定可靠"——必须有应用层的 4 道防线
事件 schema 必须有版本号——老消费者跑老 schema,新事件跑新 schema,演化兼容

4.5 案例 5:异构系统融合 — 多语言微服务统一治理

背景:某跨国物流公司,核心系统有 4 种技术栈:Java(订单)、Go(调度)、Python(数据)、C#(遗留 ERP)。“微服务化"时,各团队按擅长选了不同语言,治理难度爆炸。

痛点:

4 种语言的注册中心不一致(Eureka / Consul / Nacos / 自研)
4 种语言的配置中心不一致(Spring Cloud Config / Apollo / 自研)
4 种语言的链路追踪不一致(Sleuth+Zipkin / OpenTelemetry+Jaeger / 自研)
一次故障排错 4 个团队,沟通成本极高

解决方案:统一基础设施 + 各语言 SDK

能力	选型	Java	Go	Python	C#
服务发现	Nacos	Nacos-Spring	Nacos-Go	Nacos-Python	Nacos-C#
配置中心	Nacos	Nacos-Spring	Nacos-Go	Nacos-Python	自研 HTTP 调用 Nacos OpenAPI
链路追踪	Jaeger(OTel 标准)	OTel Java	OTel Go	OTel Python	OTel .NET
日志	Loki(统一 JSON 格式)	Logback + JSON Encoder	zap + JSON	logging + JSON	log4net + JSON
指标	Prometheus	Micrometer	prometheus/client_python	prometheus-net	Micrometer
CI/CD	Jenkins + ArgoCD	统一	统一	统一	统一

关键决策:

基础设施统一,但应用代码不强制统一——Java 用 Spring Boot,Go 用 Gin,Python 用 FastAPI,各团队按擅长
统一标准 > 统一实现——所有语言都用 OpenTelemetry 协议(只要符合协议,实现自选)
抽象出"语言无关"的 API 网关 + Service Mesh——所有外部调用走网关,所有内部调用走 Mesh(Istio/Linkerd)

结果(12 个月后):

4 种语言,1 套治理(只要学会 OTel + Prometheus + Loki,就能排查所有服务)
服务发现延迟统一 < 50ms
跨语言链路追踪:从"4 个工具 + 4 个 UI” → “1 个 Jaeger UI 全部串起来”

教训:

不要因为"统一"而强制"同一技术栈"——业务复杂、多团队异构是常态
统一治理的"协议层"是 OpenTelemetry——它跨语言、跨框架、开源标准,5 年内不会被淘汰
异构系统最怕"每个团队自己造轮子"——基础设施部门必须提供"开箱即用"的 SDK

4.6 案例 6:遗留系统拆解 — 绞杀者模式 + 数据双写

背景:某传统国企,核心 ERP 是 2008 年的 C# .NET Framework 2.0,代码 120 万行,改任何功能都要发布 .NET 包 + 重启 IIS 集群。新业务(移动端、API)想用,但这个老系统完全不能扩展。

痛点:

老系统 18 年没人敢动,改一行代码要全量回归(测试 5 个团队、2 周)
移动端想用老系统的"订单查询"功能,但老系统只暴露 COM 组件,跨进程调用慢且不稳定
2018 年后微软停止 .NET Framework 2.0 支持,安全漏洞没人修
但完全替换 ERP 不可能——20 年业务规则沉淀在代码里,没人能说清楚

解决方案:绞杀者模式(Strangler Fig)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


阶段 1(0-3 个月):基础设施
 - 老 ERP 前面架 API Gateway
 - 新建 new-erp-service(Java Spring Boot),先实现"订单查询"一个新功能
 - API Gateway 路由:移动端 → new-erp(新),其他 → 老 ERP

阶段 2(3-12 个月):逐步迁移
 - 每月迁移 1-2 个功能(订单查询 → 订单创建 → 订单退款 ...)
 - 每迁移一个功能,API Gateway 切换路由
 - 老 ERP 代码逐月减少,新服务逐月增加

阶段 3(12-18 个月):数据迁移
 - 老的"t_order"表数据全量同步到 new-erp-service 的新表
 - 双写期 3 个月:同时写老表 + 新表
 - 读用开关切换
 - 3 个月后废弃老表

阶段 4(18-24 个月):老 ERP 下线
 - 路由全部切换到 new-erp
 - 老 .NET 进程灰度下线
 - 服务器资源回收

关键技术点:

API Gateway 是"切换开关"——所有路由都集中管理,切换可秒级
数据双写期必须"可观测"——每次写老库 + 新库,都要记录"是否双写成功",不一致告警
业务功能按"用户使用频次"排序迁移——高频优先,低频最后
老 ERP 的"业务规则"必须文档化——迁移前 2 个月专门做"业务规则考古"

结果(24 个月后):

老的 .NET 系统完全下线,释放 80% 服务器资源
新系统(.NET Core 6 + Spring Boot 混部)支持移动端 + Web + 开放 API
改一个订单功能:从 2 周 → 2 小时
核心业务规则零损失——通过 24 个月的"双写 + 对账"保障

教训:

绞杀者模式是"渐进式重构"的标准答案——不要做"big bang"(一次性重写,风险极高)
数据迁移的"双写期"是必须经历的风险——不要为了"快"跳过
老系统的"业务规则"是最值钱的资产——架构可能过时,业务规则 20 年不变

五、踩坑清单:拆分失败的 10 个真实教训

这一节不讲方法论,讲 10 个我亲眼见过(或亲身踩过)的"拆分失败"教训。每条都附"症状 + 根因 + 解决"。

1. 没做事件风暴就拆服务——症状:微服务拆完后业务逻辑散落,跨服务调用乱成一团;根因:没识别清楚限界上下文;解决:拆之前先 2 天事件风暴。

2. 拆得"过细"——症状:一个聚合根一个服务,本地事务变分布式事务,性能差 + 一致性差;根因:把"DDD 实体"当"微服务边界";解决:一组紧密相关的聚合根 = 一个服务。

3. 共享数据库——症状:DBA 改一个字段,多个服务挂;根因:微服务"逻辑上拆了,物理上没拆";解决:每个服务独立 Schema,跨服务走 API/事件。

4. 同步链路太多——症状:用户改昵称要等 5 个服务响应,3 秒后才返回;根因:用了同步 RPC 而不是异步事件;解决:同步只用于"读自己的数据",其他用事件。

5. 没有可观测就拆——症状:出问题找不到根因,排错 3 天;根因:链路追踪 + 统一日志没建;解决:先建 SkyWalking + ELK + Prometheus,再建微服务。

6. 团队结构没动——症状:微服务是 5 个团队协作,部署时还是 2 周排期;根因:康威定律反着干;解决:组织先行,按业务域组建 Stream-aligned 团队。

7. 分布式事务滥用——症状:Seata AT 模式全链路,一个服务挂全链路卡 30 秒;根因:把"必须强一致"扩展到所有场景;解决:优先事件 + 最终一致,只在金融核心用 Seata。

8. 事件 schema 没版本号——症状:消费方升级后,老事件处理报错;根因:事件结构变了但没兼容老版本;解决:每个事件带 schemaVersion 字段,消费者按版本路由。

9. 没有 API 版本管理——症状:改一个支付接口,订单服务 27 个调用方全挂;根因:接口改动没 RFC 流程;解决:OpenAPI 3.0 + RFC 评审 + 老版本保留 6 个月。

10. 老接口没及时下线——症状:系统里同时跑 V1/V2/V3 接口,代码越积越多;根因:没设废弃时间表;解决:每个老接口设 deprecationDate,到期强制下线。

这 10 条没有一条是"技术难题",都是"流程 + 纪律"问题。微服务拆分的成功,80% 靠组织治理,20% 靠技术。

结语:把"拆"换成"治"

回到开头 CEO 的那个问题:“已经是微服务了,为什么改个东西比单体还慢?”

答案是:没有"自治"的拆分,只是把大泥球切成了小泥球。真正的微服务,不是"部署了 N 个 Spring Boot 应用",而是:

业务边界清晰(DDD 限界上下文)
团队边界对齐(Team Topologies)
数据各自收敛(每个服务一份权威源)
失败有兜底(事件 + 对账 + 死信队列)
演进有节奏(绞杀者模式 + 双写期 + 老接口废弃表)

如果只学一招,我建议把"康威定律"贴在显示器上——任何架构决策前,先看组织结构;组织没动,先动组织。

这就是我那次从 38 个微服务大泥球到 12 个真正自治服务的全部心法。后续的 Nacos 怎么选(第 6 篇)、网关怎么限流(第 7 篇)、熔断怎么做(第 8 篇),都是这套心法的"组件落地"。先有边界,再有服务;先有组织,再有架构——这是 10 年 Java 微服务实践最值钱的 5 个字。

Nacos：Java 微服务的服务中心与配置中心怎么选、怎么用

Tue, 09 Jun 2026 00:00:00 +0000

Java Web 微服务系列 · 第 5 篇 · Nacos 服务中心 & 配置中心阅读时长：约 45 分钟本文写于 2026 年 6 月配套版本：Nacos 2.3.x / Spring Cloud Alibaba 2022.0.0.0 / Spring Boot 3.x / Dubbo 3.2.x 前置阅读：《技术选型：为什么最终选了 Spring Cloud Alibaba + Dubbo 3》（系列第 4 篇）后续衔接：《异地多活：Java Web 微服务的高可用终极形态》（系列第 1 篇）

引子：那个被 Eureka 维护模式打懵的下午

2019 年 6 月某个周五下午，我接到一份"技术债清理"任务——把团队微服务用了三年的 Eureka 注册中心换成另一套方案。背景是这样：

Netflix 官方在 2018 年 7 月宣布 Eureka 2.0 项目无限期搁置，Eureka 1.x 仍能用但不再有新特性
我们当时的痛点：Eureka 的健康检查只能靠应用心跳，对外部依赖（DB / Redis）的真实可用性完全无感——某个 Pod 数据库连接池打满但心跳还在跳，注册中心傻乎乎地继续往它打流量
配置全靠 Spring Cloud Config + Git 仓库，改一次配置要走"提 PR → 合 master → 推 commit → 触发 webhook → 重启服务"五步，灰度配置基本做不了
DBA 还在邮件里追问：现在 200 多个微服务，每个服务的 DB 连接池大小、Redis 集群地址都散在 50 多个 GitLab repo 里，没人能说清楚生产到底用了哪些版本的配置

我接手时候只列了一个核心问题：注册中心 + 配置中心一起换，还是分开换？ 各自选哪个组件？为什么？

把所有候选方案在白板上画了 7 天，最后选定 Nacos 同时承担注册中心 + 配置中心——一个组件解决两件事。理由不是"国产化情怀"，是一份 5 维评分表算下来的硬数据。

这篇就把这份评分表 + 后来 3 年里 Nacos 在生产环境踩的坑 + 跟系列第 1 篇异地多活的联动玩法全部摊开。

一、选型对比：Nacos vs Eureka / Consul / Zookeeper / Apollo / Etcd

很多选型文章只会列"特性矩阵打勾"，但实际选型靠的是按业务场景加权的评分。我把当时白板上的评分表 + 决策过程完整还原出来。

1.1 候选清单与定位

组件	注册中心	配置中心	一致性	主流应用栈	维护方
Nacos	✅ 一流	✅ 一流	AP / CP 可切换	Spring Cloud Alibaba / Dubbo	阿里巴巴 + Apache
Eureka	✅ 已停更	❌	AP	Spring Cloud Netflix（已退场）	Netflix（搁置）
Consul	✅ 优秀	✅ KV 简易	CP（Raft）	多语言 / HashiCorp 生态	HashiCorp
Zookeeper	✅ 一般	✅ ZNode 简易	CP（ZAB）	Dubbo 老用户 / Kafka	Apache
Apollo	❌	✅ 一流	CP	携程开源，Spring 生态	携程
Etcd	✅ 一般	✅ KV 简易	CP（Raft）	Kubernetes / 云原生	CNCF

💡 原理：AP 与 CP 的本质分歧

CAP 理论里，分区容错（P）在分布式系统里是必选的——网络抖动总会发生。剩下 A（可用性）和 C（一致性）只能二选一。

AP 模式：网络分区时，注册中心节点继续对外提供服务，但不同节点看到的服务列表可能短暂不一致（最终一致）。适合服务发现场景——多注册一两个或少注册一两个实例不致命，但注册中心不可用导致服务发现失败，整个系统就瘫了

CP 模式：网络分区时，少数派节点拒绝对外提供服务，保证多数派节点数据强一致。适合配置场景——配置错了直接影响业务逻辑，宁可暂时读不到也不能读到不一致的值

1.2 五维评分模型（每维 1-5 分）

我把候选组件按 5 个维度打分，每维给一个权重（基于业务实际重要性）：

维度	权重	Nacos	Eureka	Consul	ZK	Apollo	Etcd
功能完整性（注册 + 配置双中心）	25%	5	1	4	3	3	3
性能与扩展性（10w+ 实例 / s 级推送）	20%	5	4	4	2	4	4
运维成本（部署 / 监控 / 备份 / 升级）	20%	4	4	3	2	3	3
生态集成（Spring Cloud / Dubbo 一线支持）	20%	5	4	3	4	4	2
社区活跃度（commit 频率 / star / 中文支持）	15%	5	1	4	3	4	5
加权总分	—	4.80	2.85	3.65	2.75	3.55	3.30

📌 实践：评分不是拍脑袋，每一格都有依据

功能完整性 Nacos 5 分 = 注册 + 配置 + DNS + 命名空间隔离 + 灰度推送全套；Eureka 1 分 = 配置中心彻底没有

性能 Nacos 5 分 = 阿里双 11 实战压测过百万级实例；Zookeeper 2 分 = ZAB 协议写入瓶颈在 1w QPS 量级，服务数过万就压不住

运维 Zookeeper 2 分 = 没有官方控制台，JMX 监控自己接，故障定位全靠 zkCli.sh

生态 Etcd 2 分 = Java 客户端能用但很少社区案例，几乎全是 K8s 内部用法

1.3 决策路径：为什么排除 Eureka / ZK / Etcd

Eureka 出局原因：

官方维护模式，未来 5 年内的安全补丁、新 JDK 适配都没保障
配置中心彻底缺位，得再选一个 Apollo 或 Spring Cloud Config，双组件运维成本 ≠ 单组件 × 2，而是 × 3（多了组件间联动 bug 排查）
健康检查机制粗糙——只能靠服务端 TCP 心跳，无法表达"业务健康但依赖异常"

Zookeeper 出局原因：

ZAB 协议强一致带来写入瓶颈——服务数量过万时写 QPS 撑不住
没有官方 UI，故障时只能 zkCli.sh ls /services 一行行翻
会话机制对应用代码侵入大——临时节点失效后客户端要自己处理重连、重新注册

Etcd 出局原因：

Java 生态薄弱，Spring Cloud / Dubbo 官方都没原生支持
K8s 已经在用 Etcd 了——把业务的注册中心也放 Etcd，会把 K8s 控制平面的爆炸半径放大到业务

1.4 决策路径：Nacos vs Consul vs (ZK + Apollo)

剩下三套候选方案的对比是真正的"两难"：

1
2
3


方案 A：Nacos 单组件（注册 + 配置一站式）
方案 B：Consul 单组件（HashiCorp 生态，多语言友好）
方案 C：Zookeeper（注册） + Apollo（配置）双组件

维度	方案 A	方案 B	方案 C
组件数	1	1	2
配置中心成熟度	4	2（KV 简易）	5（Apollo 强大）
多语言支持	3（Java/Go 优先）	5	3
Spring 集成	5	3	4
中文文档 / 社区	5	3	5
学习曲线	平	中	陡（两套）

🎯 最终决策：选 Nacos。理由有三：

生态压倒一切——我们的业务 95% 是 Java，Spring Cloud Alibaba + Dubbo 一线支持 Nacos
单组件运维成本最低——配置 + 注册两个核心能力，SRE 只需要懂一套部署/监控/备份方案
Consul 的 KV 不够强——分组、命名空间、灰度推送、配置历史这些企业级配置中心刚需，Consul 都要自己造轮子

如果业务多语言（Go / Python / Node 大比例），Consul 是更好的选择；如果团队历史包袱重（已经在用 ZK + Apollo），保持现状成本更低。Nacos 的甜点区是"Java 微服务为主、追求开发效率、运维资源紧张的中大型团队"。

二、服务注册中心实战：让服务自动找到彼此

选定 Nacos 之后，第一件落地的事情是把服务注册与发现这条链路打通。本节按"原理 → 部署 → 接入 → 排错"四步走，给出完整可复制粘贴的代码。

2.1 服务注册的完整链路

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


┌──────────────────┐ ┌──────────────────┐
│ Service Provider │ │ Nacos Server │
│ (订单服务实例) │ 注册 │ (注册表 + 推送) │
│ ├─────────►│ │
│ - IP: 10.1.0.5 │ 心跳 │ /services │
│ - port: 8080 ├─────────►│ /instances │
│ - weight: 1.0 │ │ /push │
│ - metadata: {} │ │ │
└──────────────────┘ └─────────┬────────┘
 │
 UDP 推送 / Long-Polling
 ▼
 ┌──────────────────┐
 │ Service Consumer │
 │ (用户服务实例) │
 │ │
 │ 本地缓存: │
 │ order-service │
 │ - 10.1.0.5 │
 │ - 10.1.0.6 │
 └──────────────────┘

💡 原理：Nacos 2.x 用 gRPC 长连接替代了 1.x 的 HTTP 短轮询

Nacos 1.x 时代，客户端心跳是 HTTP 短连接，每 5 秒发一次——10 万实例 × 5 秒间隔 = 平均 2 万 QPS 的心跳流量打到服务端，Nacos Server 的连接处理就成了瓶颈。

Nacos 2.x 改成 gRPC 长连接 + 服务端反向推送：心跳走长连接复用，连接数从"实例 × 心跳频率"降到"实例数"，吞吐能力提升 10 倍以上。这就是为什么 Nacos 2.x 同等硬件下能撑下阿里双 11 百万级实例的服务发现压力。

2.2 单机部署（开发环境）

最快的启动方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 下载 release 包（以 2.3.0 为例）
wget https://github.com/alibaba/nacos/releases/download/2.3.0/nacos-server-2.3.0.tar.gz
tar -xzf nacos-server-2.3.0.tar.gz
cd nacos/bin

# Linux/Mac 启动（单机模式）
sh startup.sh -m standalone

# Windows
startup.cmd -m standalone

# 启动后访问控制台
# http://localhost:8848/nacos
# 默认账号 nacos / nacos（生产环境必改）

📌 实践：默认账号密码必须改

Nacos 控制台默认 nacos / nacos，生产环境从未改过的有 60% 以上（我从公开漏洞案例统计的）。改密码三步：

conf/application.properties 设 nacos.core.auth.enabled=true

nacos.core.auth.server.identity.key 和 nacos.core.auth.server.identity.value 改成强随机字符串（用于集群内部认证）

控制台登录后，用户管理菜单改 nacos 账户密码或新建账号删掉默认账号

2.3 Spring Cloud Alibaba 接入（最常见）

pom.xml：

 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


<properties>
 <spring-boot.version>3.2.0</spring-boot.version>
 <spring-cloud.version>2022.0.4</spring-cloud.version>
 <spring-cloud-alibaba.version>2022.0.0.0</spring-cloud-alibaba.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-alibaba-dependencies</artifactId>
 <version>${spring-cloud-alibaba.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <!-- 服务注册发现 -->
 <dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
 </dependency>
 <!-- 远程调用 -->
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-openfeign</artifactId>
 </dependency>
 <!-- 负载均衡（替代废弃的 Ribbon） -->
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-loadbalancer</artifactId>
 </dependency>
</dependencies>

application.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


spring:
 application:
 name: order-service
 cloud:
 nacos:
 discovery:
 server-addr: 10.1.0.10:8848,10.1.0.11:8848,10.1.0.12:8848
 namespace: prod-order  # 命名空间隔离
 group: ORDER_GROUP  # 分组
 cluster-name: HZ_CELL1  # 集群名（异地多活分单元用）
 username: order-app
 password: ${NACOS_PASSWORD}  # 走环境变量，禁止明文
 metadata: # 自定义元数据（灰度发布、版本路由用）
 version: 1.2.3
 region: hangzhou

主类（Spring Cloud 2022 之后不需要 @EnableDiscoveryClient，自动装配）：

1
2
3
4
5
6


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

服务调用（用 OpenFeign）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


@FeignClient(name = "user-service")
public interface UserFeignClient {
 @GetMapping("/api/users/{id}")
 UserDto getUser(@PathVariable("id") Long id);
}

@RestController
@RequiredArgsConstructor
public class OrderController {
 private final UserFeignClient userFeign;

 @GetMapping("/api/orders/{id}/with-user")
 public OrderDetailDto getOrderWithUser(@PathVariable Long id) {
 // 直接用服务名调用，LoadBalancer 自动从 Nacos 拉实例列表 + 负载均衡
 UserDto user = userFeign.getUser(orderRepo.findById(id).getUserId());
 return OrderDetailDto.of(orderRepo.findById(id), user);
 }
}

2.4 Dubbo 3 接入

Dubbo 3 把 Nacos 当一等公民支持，配置量比 Spring Cloud 还少：

pom.xml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.2.10</version>
</dependency>
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-registry-nacos</artifactId>
 <version>3.2.10</version>
</dependency>

application.yml：

1
2
3
4
5
6
7
8
9


dubbo:
 application:
 name: order-service
 qos-enable: false
 registry:
 address: nacos://10.1.0.10:8848?namespace=prod-order&username=order-app
 protocol:
 name: tri  # Triple 协议（Dubbo 3 推荐）
 port: 20880

服务暴露与调用同 Dubbo 标准用法（@DubboService / @DubboReference）。

2.5 健康检查：临时实例 vs 持久化实例

Nacos 把实例分两种：

类型	健康判定方式	适用场景
临时实例（默认）	客户端心跳（5 秒一次）超时 30 秒判定失联	Spring Boot / Dubbo 应用（重启即注销）
持久化实例	服务端反向探测（TCP/HTTP/MySQL）	数据库 / 中间件这类不自带 SDK 的"哑实例"

切换方式（Spring Cloud）：

1

spring.cloud.nacos.discovery.ephemeral: false # 改为持久化实例

🎯 避坑：临时实例和持久化实例不能切换

同一个服务名下已经存在的实例类型不能更改——比如一开始注册成临时实例，后来想改成持久化，必须先完全注销该服务（所有实例下线 + 等待 1 分钟）后再以新类型注册。否则 Nacos 会报 Current service DCL is not match 错误，新实例注册不上。

2.6 AP / CP 模式切换

Nacos 服务发现默认 AP 模式（牺牲一致性保可用）。需要 CP 时——比如配置中心场景下的强一致需求——可以通过服务级别开关：

1
2


# 通过 Open API 把某个服务切换为 CP 模式
curl -X PUT 'http://nacos:8848/nacos/v1/ns/service?serviceName=order-service&protectThreshold=0.5'

💡 原理：Distro 与 Raft 协议在 Nacos 中的分工

Nacos 2.x 内部其实同时跑两套一致性协议：

Distro 协议（AP）：用于临时实例的服务发现。各节点平均分担实例数据，节点间数据异步复制——单个节点挂掉只影响 1/N 的数据可用性，不影响整体

Raft 协议（CP）：用于持久化实例 + 配置中心数据。Leader 选举 + 日志复制保证强一致，写入需要多数派确认

这就是为什么 Nacos 能"AP/CP 共存"——本质是同一进程跑了两套协议，根据数据类型路由。

三、配置中心实战：让配置改了立刻生效

服务注册解决了"服务怎么找到彼此"，配置中心解决"配置改了怎么不重启就生效"。Nacos 的配置中心是它另外半边天，本节按"接入 → 命名空间设计 → 动态刷新 → 灰度发布"展开。

3.1 配置中心基本接入

pom.xml 增加：

1
2
3
4
5
6
7
8
9


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<!-- Spring Cloud 2022 之后配置由 spring.config.import 引入，bootstrap.yml 已废弃 -->
<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

application.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


spring:
 application:
 name: order-service
 profiles:
 active: prod
 config:
 import:
 - optional:nacos:order-service.yml?refreshEnabled=true
 - optional:nacos:order-service-${spring.profiles.active}.yml?refreshEnabled=true
 - optional:nacos:common-config.yml?refreshEnabled=true&group=COMMON_GROUP
 cloud:
 nacos:
 config:
 server-addr: 10.1.0.10:8848,10.1.0.11:8848,10.1.0.12:8848
 namespace: prod-order
 username: order-app
 password: ${NACOS_PASSWORD}
 file-extension: yml

📌 实践：Spring Cloud 2022 之后 bootstrap.yml 已经不是必需

老版本（Spring Cloud 2021 及之前）配置中心必须在 bootstrap.yml 里写——因为 application.yml 在配置中心加载之后才解析。Spring Cloud 2022 引入了 spring.config.import 机制，配置中心可以直接写在 application.yml，更直观。但也兼容老的 bootstrap.yml，看团队习惯。

3.2 命名空间 + 分组 + DataId 的三级隔离设计

Nacos 配置的定位用 三元组：namespace + group + dataId。怎么设计这三层隔离决定了配置中心的可维护性。

命名空间（namespace）：物理隔离，用作环境维度

1
2
3
4
5
6
7
8


namespace-id namespace-name 含义
─────────────────────────────────────────────────
dev 开发环境 dev、共享资源都在这
test 测试环境 测试 DB / Redis
staging 预发环境 生产镜像 + 真实数据脱敏
prod-order 生产-订单业务线 订单业务线独立
prod-payment 生产-支付业务线 支付业务线独立
prod-search 生产-搜索业务线 搜索业务线独立

🎯 避坑：生产环境按业务线拆 namespace，不要一个 “prod” 装天下

我见过最痛苦的案例：所有生产配置都在一个 prod namespace，全公司 200 个微服务、500 个配置文件混在一起，控制台翻页都翻不动。更要命的是权限完全是公司级——一个业务线的开发误改了另一个业务线的配置，事故才追溯出来。

拆分原则：按"独立的责任团队"拆 namespace，每个 namespace 配独立的 Nacos 账户 + 读写权限。

分组（group）：逻辑分组，用作业务模块或共享配置维度

1
2
3
4
5
6
7


group-name 含义
────────────────────────────────────────────
DEFAULT_GROUP 默认分组（不指定时）
ORDER_GROUP 订单业务专属配置
PAYMENT_GROUP 支付业务专属配置
COMMON_GROUP 所有服务共享的基础配置（Redis 集群地址等）
GRAY_GROUP 灰度发布配置（小流量验证用）

DataId：具体配置文件名，命名规范：

1
2
3
4
5
6
7
8
9


{应用名}.{后缀} # 应用专属
{应用名}-{profile}.{后缀} # 按 profile 区分
{共享配置名}.{后缀} # 跨应用共享配置

例子：
- order-service.yml # 订单服务通用配置
- order-service-prod.yml # 订单服务生产环境配置
- common-redis.yml # 共享 Redis 配置（COMMON_GROUP）
- order-service-gray.yml # 订单服务灰度配置（GRAY_GROUP）

3.3 动态刷新：@RefreshScope 与 @Value 的坑

最经典的动态刷新写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Component
@RefreshScope
public class FeatureToggleConfig {
 @Value("${feature.new-order-flow:false}")
 private boolean newOrderFlowEnabled;

 public boolean isNewOrderFlowEnabled() {
 return newOrderFlowEnabled;
 }
}

但 @RefreshScope 有几个反直觉的坑：

🎯 避坑 1：@RefreshScope 会创建新的 bean 实例

@RefreshScope 标注的 bean 在配置刷新时会被销毁并重建。如果这个 bean 持有数据库连接池、线程池等长生命周期资源，会被一起销毁——重建时再开新连接，旧的连接被泄露。

正确做法：@RefreshScope 只用在纯配置 POJO上，不要用在 Service / Repository 这类持有重资源的 bean 上。Service 需要新配置时，注入这个 POJO 而不是 @Value。

🎯 避坑 2：构造器注入 + final 字段无法刷新
1
2
3
4
5
6
7
8
9
// 错误写法：final 字段 + 构造器注入
@Component
@RefreshScope // 这里加了也没用
public class BadConfig {
 private final boolean enabled;
 public BadConfig(@Value("${feature.enabled:false}") boolean enabled) {
 this.enabled = enabled; // final 字段只能初始化一次
 }
}
@RefreshScope 重建 bean 时确实会再调一次构造器，但 如果你用 final + 构造器注入，Spring 不会重新创建 bean（因为构造器参数没变，缓存命中）。改用字段注入 @Value 或者用 @ConfigurationProperties 绑定到 mutable POJO。

🎯 避坑 3：监听器写法不能 @RefreshScope

如果用 @NacosConfigListener 注解监听配置变化：
1
2
3
4
5
6
7
@Component
public class ConfigListener {
 @NacosConfigListener(dataId = "order-service.yml", group = "DEFAULT_GROUP")
 public void onChange(String newContent) {
 log.info("Config changed: {}", newContent);
 }
}
这个监听器本身不需要 @RefreshScope——它是事件回调，不是配置使用者。

3.4 强推荐：@ConfigurationProperties + 显式刷新事件

我在生产环境推行的写法是完全避开 @RefreshScope，改用 @ConfigurationProperties + RefreshEvent 监听：

 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


// 配置 POJO
@Component
@ConfigurationProperties(prefix = "order")
@Data
public class OrderProperties {
 private int maxQuantityPerOrder = 100;
 private int timeoutSeconds = 30;
 private List<String> blockedRegions = new ArrayList<>();
 private RetryConfig retry = new RetryConfig();

 @Data
 public static class RetryConfig {
 private int maxAttempts = 3;
 private long backoffMs = 100;
 }
}

// Service 直接注入，无需 @RefreshScope
@Service
@RequiredArgsConstructor
public class OrderService {
 private final OrderProperties props;

 public Order createOrder(OrderRequest req) {
 if (req.getQuantity() > props.getMaxQuantityPerOrder()) {
 throw new BizException("超过单笔订单上限");
 }
 // ...
 }
}

// 显式监听刷新事件（需要做一些副作用时）
@Component
@RequiredArgsConstructor
public class OrderConfigRefreshListener {
 private final ConnectionPoolManager poolMgr;
 private final OrderProperties props;

 @EventListener
 public void onRefresh(RefreshEvent event) {
 // 配置变化后，根据需要做副作用（如重建连接池）
 poolMgr.rebuildIfNeeded(props.getRetry().getMaxAttempts());
 }
}

好处：

类型安全——@ConfigurationProperties 自动校验，错配直接启动失败
结构清晰——配置项分组到 POJO，比散落的 @Value 易维护 10 倍
副作用可控——刷新事件显式监听，要不要重建连接池 / 缓存由你自己决定

3.5 配置灰度发布

Nacos 2.1+ 支持配置灰度（Beta 发布）：

控制台编辑配置，点击"发布 Beta"
填入"IP 白名单"（如 10.1.0.5,10.1.0.6）——只有这些 IP 的实例会收到新配置
观察灰度实例日志、监控指标
验证通过 → 点击"发布" 全量推送；验证失败 → 点击"Stop Beta" 撤回

📌 实践：灰度发布是降低配置事故影响面的关键

2020 年我团队有过一次"配置事故"——把 Redis 集群地址改成了一个错误的 IP，全量推送到 200 个 Pod，3 秒内 100% 的请求开始报 Redis 连接超时。事后复盘要求所有"涉及外部依赖"的配置变更必须先 Beta 发布到 2-3 个 Pod 跑 10 分钟，监控无异常再全量。这条规则从 2020 年至今没出过类似事故。

3.6 配置版本管理与回滚

Nacos 控制台对每个配置保留最近 30 天的历史版本：

历史版本可以 diff 对比
可以一键回滚到任意历史版本
回滚操作本身也是一次"发布"，会触发动态刷新

🎯 避坑：历史版本只保留 30 天，不要把 Nacos 当配置仓库

我见过有团队把 Nacos 当代码仓库用——所有配置变更只在 Nacos 控制台改，没有 Git 镜像。30 天后想看 6 个月前的配置改了什么，翻不到了。

正确做法：所有配置变更先在 Git 仓库提 commit，CI 自动同步到 Nacos。Nacos 控制台只在紧急场景用（如临时灰度 / 紧急回滚），日常变更走 Git。

3.7 Long-Polling 推拉模型解析

💡 原理：Nacos 配置变更如何在 1 秒内推送到所有客户端

传统轮询：客户端每 5 秒查一次配置版本，延迟 0-5 秒，但 QPS 高。服务端推送：服务端长连接推送，实时但需要维护长连接。

Nacos 用 Long-Polling（长轮询）平衡两者：

客户端发起 HTTP 请求询问"配置版本是不是 X？" 服务端不立即返回

服务端 hang 住这个请求最多 30 秒

30 秒内如果配置有变化 → 立即返回新版本（推）

30 秒内没变化 → 返回 304，客户端立即发起下一次询问（拉）

效果：客户端总是有一个 hang 在服务端的请求，配置一变就立即收到，延迟 < 100ms。同时心跳本身的 QPS 极低——每个客户端 30 秒一次。

Nacos 2.x 把 Long-Polling 升级为 gRPC 长连接 + 服务端反向推送，效果更好，但模型本质是同一套：把"客户端轮询"伪装成"服务端推送"。

四、企业级避坑：生产环境的 6 个高频地雷

前 3 节是"怎么用"，本节是"怎么不出事"——3 年生产环境趟过的真坑，每个都写明症状 + 根因 + 解决方案。

4.1 集群脑裂

症状：Nacos 集群网络抖动后，部分客户端拿到的服务列表"少了一半"，调用大量超时。

根因：Nacos 集群配置不当，Distro 协议分区时多数派和少数派都对外提供服务，客户端连到不同节点拿到不同视图。

解决方案：

集群节点数必须为奇数 —— 通常 3 或 5 个节点，避免双节点这种"脑裂高发"配置
cluster.conf 用主机名而非 IP——容器化部署时 IP 会变，主机名（k8s service）稳定
跨机房部署时显式配 cluster —— 让 Distro 协议感知机房拓扑，分区时由"多数派机房"接管

1
2
3
4


# cluster.conf 示例（3 节点）
nacos-1.nacos-headless.default.svc.cluster.local:8848
nacos-2.nacos-headless.default.svc.cluster.local:8848
nacos-3.nacos-headless.default.svc.cluster.local:8848

4.2 客户端 CPU 飙高

症状：升级 Spring Cloud Alibaba 后，应用 CPU 比之前高 30%，火焰图发现热点在 Nacos 客户端的 NamingService.subscribe。

根因：Spring Cloud LoadBalancer 默认 1 秒拉一次服务列表缓存，配合 Nacos 客户端的"按需订阅"机制，每次拉缓存都会触发一次订阅检查，累积下来 CPU 消耗显著。

解决方案：

1
2
3
4
5
6
7


spring:
 cloud:
 loadbalancer:
 cache:
 ttl: 10s  # 默认 35s，按业务可调
 nacos:
 enabled: true # 启用 Nacos 专用负载均衡（基于 weight + cluster）

也可以在 Nacos 客户端配置 加大本地缓存 TTL：

1
2
3
4
5
6


spring:
 cloud:
 nacos:
 discovery:
 watch:
 enabled: false # 关闭客户端 watch（如果不需要实时性）

4.3 长轮询风暴

症状：Nacos Server 端 CPU 持续 80%+，netstat 看到大量 ESTABLISHED 长连接，没有明显业务峰值。

根因：客户端Listener 注册过多 —— 一个应用监听了几百个配置，每个配置一个 Long-Polling 连接，单实例 vs Nacos Server 之间维持几百个长连接。

解决方案：

合并配置——能放一个 yml 里的就别拆 100 个 dataId
共享配置走 COMMON_GROUP——多个服务共享一份配置，比每个服务单独拉一份省连接
Nacos 2.x 升级——gRPC 长连接复用，连接数不再随 Listener 数线性增长

4.4 MySQL 持久化模式数据丢失

症状：Nacos 集群启动时报 nacos-mysql connection failed，部分配置数据丢失。

根因：Nacos 集群模式必须用外置 MySQL 做持久化存储（默认嵌入式 Derby 只能单机用）。生产环境如果没切换 MySQL，集群模式下数据写入只在内存，重启即丢。

解决方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# conf/application.properties
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://10.1.0.50:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useSSL=false&serverTimezone=Asia/Shanghai
db.user.0=nacos_user
db.password.0=${NACOS_DB_PASSWORD}

# 连接池调优（生产环境）
db.pool.config.connectionTimeout=30000
db.pool.config.validationTimeout=10000
db.pool.config.maximumPoolSize=20
db.pool.config.minimumIdle=10

🎯 避坑：MySQL 必须有备份和高可用

Nacos MySQL 一旦丢，所有配置归零。建议：

MySQL 主从复制（至少一主一从）

每天全量备份 + 实时 binlog 备份

Git 仓库同步作为终极兜底（前面 §3.6 提到的"Nacos 不当代码仓库"）

4.5 鉴权与多租户

症状：生产 Nacos 默认 nacos/nacos 密码，被攻击者通过控制台修改了一个核心配置，全站服务在 10 秒内开始报错。

根因：没启用 Nacos 鉴权（nacos.core.auth.enabled=false），且 Nacos 端口暴露在公网。

解决方案（多层防御）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# conf/application.properties
# 1. 启用鉴权
nacos.core.auth.enabled=true
nacos.core.auth.system.type=nacos
nacos.core.auth.plugin.nacos.token.secret.key=${NACOS_TOKEN_SECRET} # 32+ 字符随机
nacos.core.auth.plugin.nacos.token.expire.seconds=18000

# 2. 集群内部通信认证
nacos.core.auth.server.identity.key=server-identity-key
nacos.core.auth.server.identity.value=${NACOS_SERVER_IDENTITY}

# 3. 关闭非授权请求
nacos.core.auth.enable.userAgentAuthWhite=false

控制台层面：

不同业务线建独立账号，权限按 namespace 分配
生产 namespace 只给少数人写权限，开发只读
审计日志接 SIEM 系统，敏感操作（删配置/改密码）实时告警

网络层面：

Nacos 端口禁止暴露公网——只允许内网 + VPN 访问
加 WAF 层，限制控制台 /nacos/v1/auth/** 的请求频率（防暴力破解）

4.6 Prometheus 监控关键指标

Nacos 2.x 自带 Prometheus 端点 /nacos/actuator/prometheus，关键指标：

指标	含义	告警阈值
`nacos_monitor{name="serviceCount"}`	注册服务总数	突增/突降 > 20%
`nacos_monitor{name="ipCount"}`	注册实例总数	突降 > 30%（可能脑裂）
`nacos_monitor{name="httpHealthCheckTime"}`	健康检查耗时 P99	> 500ms
`nacos_monitor{name="longPolling"}`	长轮询连接数	> 5w（接近瓶颈）
`jvm_memory_used_bytes{area="heap"}`	堆内存使用	> 80%
`process_cpu_usage`	CPU 使用率	> 70% 持续 5 分钟

📌 实践：Grafana 模板直接复用

Nacos 官方提供 Grafana 模板，导入后开箱即用。别自己从 0 画 Dashboard——官方模板覆盖了 95% 的常用指标。

五、与系列第 1 篇异地多活的联动玩法

到这里 Nacos 的"单机/集群部署 + 服务注册 + 配置管理 + 企业避坑"四件事已经讲完。最后回到系列第 1 篇《异地多活》——Nacos 在异地多活架构里扮演什么角色？

5.1 异地多活下 Nacos 的部署拓扑

第 1 篇里我们讲了"业务单元化 + 存储双向同步 + 流量层分片"三大支柱。Nacos 在这个架构里有两种部署选择：

方案 A：单 Nacos 集群跨机房

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 ┌──────────────────────────────────────┐
 │ Nacos 集群（5 节点） │
 │ HZ-1 HZ-2 SH-1 SH-2 BJ-1 │
 │ └─Raft 协议 + Distro 协议─┘ │
 └──────────────────────────────────────┘
 │ │
 ┌──────┴───────┐ ┌──────┴────────┐
 │ 杭州机房 │ │ 上海机房 │
 │ (UnitA) │ │ (UnitB) │
 └──────────────┘ └───────────────┘

✅ 优点：服务可以跨机房发现 ❌ 缺点：跨机房 30-100ms 延迟，Raft 协议每次写都要跨城市同步，性能差

方案 B：每机房独立 Nacos 集群 + 命名空间路由

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


┌──────────────────────┐ ┌──────────────────────┐
│ 杭州机房 Nacos 集群 │ │ 上海机房 Nacos 集群 │
│ (3 节点) │ │ (3 节点) │
│ namespace: │ │ namespace: │
│ - hz-prod-order │ │ - sh-prod-order │
│ - hz-prod-payment │ │ - sh-prod-payment │
└──────────┬───────────┘ └───────────┬──────────┘
 │ │
 本机房服务 本机房服务
 注册 / 发现 注册 / 发现
 │ │
 └────────────┬───────────────────┘
 │
 跨机房调用极少
 (单元化设计)

✅ 优点：本机房调用零跨城延迟，符合单元化"调用闭环在本机房"的原则 ❌ 缺点：少量跨机房调用（如汇总服务）要做特殊处理

🎯 推荐方案 B——和第 1 篇的"单元化"理念一致，调用闭环比"全局视图"更重要。

5.2 命名空间做单元化分区

复用上面的 namespace 设计，在异地多活下扩展：

1
2
3
4
5
6
7


namespace-id 含义 所在机房
─────────────────────────────────────────────────────────
hz-prod-order 杭州单元-订单业务 HZ 机房 Nacos
hz-prod-payment 杭州单元-支付业务 HZ 机房 Nacos
sh-prod-order 上海单元-订单业务 SH 机房 Nacos
sh-prod-payment 上海单元-支付业务 SH 机房 Nacos
global-config 全局共享配置（如 OSS 域名） 双机房 Nacos 同步

关键设计点：

机房前缀 —— 命名空间名带机房代号（hz / sh），运维一眼看出归属
本机房应用只看本机房 namespace —— 通过启动参数注入
全局配置走双机房同步 —— global-config namespace 用专门的同步工具（Nacos 官方的 nacos-sync）

应用启动配置：

1
2
3
4
5
6
7
8
9


spring:
 cloud:
 nacos:
 discovery:
 server-addr: ${NACOS_LOCAL_ADDR}  # 由部署时注入本机房地址
 namespace: ${UNIT_PREFIX}-prod-order  # UNIT_PREFIX 由 K8s ConfigMap 注入
 config:
 server-addr: ${NACOS_LOCAL_ADDR}
 namespace: ${UNIT_PREFIX}-prod-order

K8s ConfigMap（部署到杭州机房的）：

1
2
3
4
5
6
7
8


apiVersion: v1
kind: ConfigMap
metadata:
 name: env-config
 namespace: prod
data:
 NACOS_LOCAL_ADDR: nacos-hz.svc.cluster.local:8848
 UNIT_PREFIX: hz

部署到上海机房的同名 ConfigMap：

1
2
3


data:
 NACOS_LOCAL_ADDR: nacos-sh.svc.cluster.local:8848
 UNIT_PREFIX: sh

同一份镜像、同一份代码、同一份 yaml——靠 ConfigMap 区分机房，运维成本最低。

5.3 与流量调度的衔接（系列第 2 篇）

系列第 2 篇《流量调度》里我们讲了"公网 LB → LVS → Nginx → 应用网关"四级前哨。Nacos 在这条链路里只在最内圈起作用——应用网关（Spring Cloud Gateway）从 Nacos 拉服务列表，对前面三层完全透明。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


用户请求
 │
 ▼
公网 LB（DNS / 智能调度）→ 决定打到哪个机房
 │
 ▼
LVS（四层转发）→ 把流量打到本机房 Nginx
 │
 ▼
Nginx（七层路由）→ 按 URL 转到应用网关
 │
 ▼
Spring Cloud Gateway（应用网关）→ 从 Nacos 拉服务列表 + 路由
 │
 ▼
微服务（OrderService / UserService...）

📌 实践：Nacos 不替代流量调度

经常有团队问"用了 Nacos 是不是就不需要 Nginx 了？"——不是。Nacos 是应用内的服务发现，解决的是"应用之间怎么找彼此"；Nginx / LVS 是入口层流量调度，解决的是"外部流量怎么进来"。两者不重叠、不替代，是上下游关系。

5.4 故障切换：Nacos 在异地多活中的"切流"角色

异地多活最高频的操作是"切流"——当一个机房出故障时，把它的流量切到另一个机房。Nacos 在这里有两个用法：

用法 1：通过 namespace 隔离实现自动故障转移

1
2
3
4
5
6
7
8


正常态：
 - 用户 A → HZ 机房 → hz-prod-order namespace → HZ 订单服务
 - 用户 B → SH 机房 → sh-prod-order namespace → SH 订单服务

HZ 机房故障：
 - 公网 LB（第 1 篇讲）感知 HZ 不可用，把用户 A 的流量切到 SH
 - 用户 A → SH 机房 → sh-prod-order namespace → SH 订单服务
 - Nacos 不需要做任何切换——本来就独立

用法 2：通过配置中心动态调整路由

在 global-config namespace 放一份单元路由表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# global-config/unit-routing.yml
units:
 hz:
 enabled: true
 weight: 50
 backup: sh
 sh:
 enabled: true
 weight: 50
 backup: hz

 # 故障时把 hz 设为 false，所有流量去 sh

公网 LB 或网关层订阅这份配置，配置一改全网立即生效，故障切换从"分钟级"降到"秒级"。

收尾：本篇要点 + 系列承上启下

✍️ 本篇核心结论：

选型 —— Nacos 的甜点区是"Java 微服务为主、追求开发效率、运维资源紧张的中大型团队"。多语言重的选 Consul，已经在用 ZK + Apollo 的保持现状
服务注册 —— Spring Cloud Alibaba + Nacos 是事实标准，Spring Cloud 2022 之后不再需要 bootstrap.yml 和 @EnableDiscoveryClient
配置中心 —— 强推荐 @ConfigurationProperties + RefreshEvent 模式，避开 @RefreshScope 的副作用坑
企业避坑 —— 集群必须奇数节点 + MySQL 持久化 + 鉴权全开 + 灰度发布做 SOP
异地多活 —— 每机房独立 Nacos + 命名空间做单元化分区，调用闭环优于全局视图

📚 Java 微服务系列地图：

#	主题	关系
1	异地多活	架构总纲
2	流量调度（Nginx/LVS）	外部入口
4	技术选型（SCA + Dubbo3）	选型总结
5	本篇 Nacos	服务发现 + 配置
6	Spring Cloud Gateway	应用网关
7	熔断限流 Sentinel	流量治理

📖 参考资料：

Nacos 官方文档
Spring Cloud Alibaba 官方文档
Dubbo 3 用户手册
Nacos GitHub
Awesome Nacos —— 社区资源汇总
Nacos 设计与实现（深入源码） —— 源码级文档
《阿里巴巴中台战略思想与架构实战》—— 第 6 章服务治理部分对 Nacos 的设计权衡有更详细的论述

下一篇：《Spring Cloud Gateway：微服务流量的"中央调度官"》——从 Nacos 拉到的服务列表，如何在网关层做路由、限流、重试隔离。

Java 微服务认证授权：从 JWT 到 sa-token,双 Token + SSO + Gateway 一站打通

Tue, 09 Jun 2026 00:00:00 +0000

Java Web 微服务系列 · 第 7 篇 · 认证授权阅读时长：约 55 分钟本文写于 2026 年 6 月配套版本：Spring Boot 3.2+ / sa-token 1.37+ / Spring Security 6.2+ / Spring Cloud Gateway 4.0+ / Java 17+ 前置阅读：《Spring Cloud Gateway：微服务流量的"中央调度官"》（系列第 6 篇）

引子：凌晨 2 点被叫醒的 23 分钟

2024 年 11 月某个凌晨 2 点，我正睡得昏沉，手机震动把整张床带得一颤。监控告警群炸了——订单系统的越权访问告警在 5 分钟内触发 1700+ 次。我一边穿衣服一边远程登录，看到的现场比想象中更触目惊心：

攻击者通过某个对外暴露的"查询我的订单"接口，用遍历 userId 的方式，5 分钟内拉走了 12000 条他人订单信息
攻击者只用了普通用户 token，但接口只用 @PathVariable Long userId 取参，没有任何"当前登录用户 = 路径 userId"的校验
安全审计组拉了日志：攻击者 11 月起就在尝试，真正"找到口子"到"拉完数据"只用了 17 分钟——因为我们既没有"按 userId 索引异常访问"的风控规则，也没有任何"短时间高频访问他人数据"的限流

事后复盘会开到凌晨 4 点，CTO 在白板上写下三个问题：

我们的认证到底在防什么？（答：只防了"未登录"，没防"已登录但越权"）
我们的鉴权粒度是什么？（答：基本靠"URL 前缀 + 注解"，没有"数据级鉴权"）
我们如果重来一次，第一刀切哪里？（答：统一认证中心 + 双 Token + 网关层全量校验 + 数据级鉴权）

那天之后我用了 3 周时间重写了整个认证授权层。这篇文章就是这次重写的全景——从密码学基石（JWT / 数字签名 / HTTPS）到框架对比（Spring Security vs sa-token），再到实战集成（双 Token / SSO / Gateway），把 11 个你必须理解的概念、2 套二选一的方案、6 段可复制粘贴的代码、12 条生产铁律，一次讲透。

本文适合谁：

正在做微服务架构统一认证的架构师/技术负责人
负责订单、支付、用户中心等核心业务的后端开发
在 Spring Security 与 sa-token 之间犹豫选谁的团队
排查过"token 失效 / 接口越权 / 跨域登录"等问题的 SRE / 安全工程师
准备系统架构师考试的考生——认证授权是高频考点

本文不适合谁：

已经在用 sa-token / Spring Security 生产稳定的团队——内容偏全景式
业务量很小的单体应用——本文聚焦"多服务多终端"的复杂场景
纯前端工程师——本文主要是后端视角

读完这篇你应该能回答：11 个认证概念分别解决什么问题、Spring Security 与 sa-token 怎么二选一、双 Token 怎么设计、SSO 三种模式怎么落地、Spring Gateway 怎么串起整条链路。如果某个点讲得不够透彻，评论区留言，我会在系列第 8 篇里挑高频问题做专题。

一、认证体系总览：11 个概念一次定位

1.1 11 个概念在 4 层架构里的定位

Java 微服务认证授权的核心是 11 个概念,分 4 大类:密码学基石(对称加密 / 非对称加密 / 数字签名 / HTTPS)、身份凭证(JWT)、应用框架(Spring Security / sa-token)、生产机制(双 Token / SSO / Spring Gateway 集成 / 接口设计)。这 11 个概念不是孤立的——密码学是地基,JWT 是砖,框架是施工队,生产机制是验收清单。理解清楚这 11 个,你就建立了"从 TCP 层到应用层"的完整认证认知。

1.2 四层分类总览

1
2
3
4
5
6
7
8
9


┌─────────────────────────────────────────────────────────────┐
│ L4 生产机制(用户感知) │ 双 Token · SSO · Gateway · 接口设计 │
├─────────────────────────────────────────────────────────────┤
│ L3 应用框架(代码落地) │ Spring Security · sa-token(2 选 1) │
├─────────────────────────────────────────────────────────────┤
│ L2 身份凭证(数据传输) │ JWT │
├─────────────────────────────────────────────────────────────┤
│ L1 密码学基石(底层算法)│ 对称加密 · 非对称加密 · 数字签名 · HTTPS│
└─────────────────────────────────────────────────────────────┘

1.3 11 个概念速查表

#	概念	一句话定义	核心作用	所在章节
1	对称加密	加解密用同一把密钥	加密大量数据(性能快)	二
2	非对称加密	公钥加密,私钥解密	密钥交换 + 身份认证	二
3	数字签名	私钥签名,公钥验签	防篡改 + 不可否认	二
4	HTTPS / TLS	HTTP + TLS 握手	传输加密 + 服务端认证	二
5	JWT	JSON Web Token 自包含凭证	无状态身份凭证	三
6	Spring Security	Spring 全家桶的认证鉴权框架	复杂 RBAC + 生态完整	四
7	sa-token	国产轻量级 Java 鉴权框架	上手快 + 鉴权代码极简	四 + 五
8	双 Token 机制	access + refresh 双凭证	短 access + 长 refresh 自动续签	五
9	SSO 单点登录	一处登录,处处通行	跨域多系统身份共享	五
10	接口设计	RESTful + 状态码 + 幂等	鉴权友好的接口规范	五
11	Spring Gateway 集成	网关层统一鉴权	微服务流量入口鉴权	五

1.4 为什么这 11 个,而不是别的?

Why not 单一 JWT 就够? 很多人误以为"认证 = JWT",但实际生产中:JWT 自己防不了重放攻击(需要 nonce / 时间戳),JWT 也管不了权限(需要 Spring Security / sa-token 配合),JWT 还解决不了"过期后用户重新登录"的体验问题(需要双 Token)。JWT 是"凭证格式"而不是"完整方案"。

Why not 直接用 OAuth 2.0? OAuth 2.0 是"授权框架"不是"认证框架",它解决的是"用户授权第三方应用访问自己的资源"——比如"用微信登录第三方网站"。如果你只是想做"自家系统的登录",OAuth 2.0 是过度设计。但如果你要"用第三方身份登录自家系统",OAuth 2.0 + OIDC 才是正解。

Why not Session? Session 是"服务端存状态",在单体应用下简单有效,但微服务架构下:

每个服务都要共享 Session(Redis 或 Spring Session)
跨域 Cookie 麻烦(浏览器同源策略)
服务端存储开销大(用户量上千万时 Redis 内存爆炸)

JWT 之所以流行,核心是"无状态"——服务端不需要存储,只需验签。这跟微服务的"无状态设计原则"完美契合。

1.5 一张图看完整条链路

 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


客户端 网关 业务服务
 │ │ │
 │ ① HTTPS 握手(TLS) │ │
 ├───────────────────────>│ │
 │ ② 登录 → 拿 access+refresh │
 ├───────────────────────>│ → 鉴权服务签发 token │
 │ │ │
 │ ③ 业务请求带 access │ │
 ├───────────────────────>│ → Gateway 验签 │
 │ │ → 解析 userId/role │
 │ │ → X-User-Id 透传到下游 │
 │ ├─────────────────────────>│
 │ │ │ ④ 业务服务
 │ │ │ 本地鉴权
 │ │ │ (Spring Security
 │ │ │ 或 sa-token)
 │ ⑤ access 过期 │ │
 ├───────────────────────>│ → refresh 换新 access │
 │ ⑥ 返回新 access │ │
 <────────────────────────┤ │
 │ │
 │ ⑦ 单点登录(SSO) │ │
 │ a.example.com ─┐ │
 │ b.example.com ─┼─→ 共享 SSO 中心 │
 │ c.example.com ─┘ (Cookie 同域/跨域) │

关键观察:

L1 密码学贯穿全链路——TLS 握手(HTTPS)、JWT 签名(数字签名)、refresh token 存储(对称加密)
L3 框架只在业务服务侧——Gateway 通常只做"验签 + 透传",不调框架
L4 生产机制是用户体验层——双 Token 让用户少登录,SSO 让用户一处登录处处通行

💡 原理:为什么"分层"这么重要?

认证体系之所以复杂,是因为它同时涉及"算法层 / 凭证层 / 框架层 / 业务层"。分层的好处:

每层可独立替换——JWT 换成 PASETO、JWS 换成 Ed25519、Spring Security 换成 sa-token,都不影响其他层

每层可独立测试——密码学层用单元测试、JWT 层用集成测试、框架层用 e2e 测试

故障定位清晰——token 验签失败 = 密码学问题;@PreAuthorize 拒绝 = 框架问题;前端不传 token = 接口设计问题

业界最反模式的"一锅烩"做法:把所有逻辑堆在一个 AuthUtil 类里(加密 + 验签 + 鉴权 + SSO 跳转全混在一起),改一行要测全链路,出问题不知道在哪层。

1.6 微服务认证的 3 大趋势(2024-2026)

认证体系不是"一成不变的老技术",过去 3 年有 3 个明显趋势在重塑整个行业。

趋势 1:零信任(Zero Trust)替代"城堡 + 护城河"

传统架构是"内网 = 安全,外网 = 危险"——只要进了内网就信任。但 2020 年 SolarWinds 供应链攻击(攻击者拿到一个内部账号就横扫整个内网)让业界反思:

永远不信任——每个请求都要鉴权,无论来自内网还是外网
最小权限——给每个服务账号只授予必需的权限(不超授)
持续验证——不仅登录时验证,操作过程中也持续验证(行为异常就重新验证)
mTLS 加密所有内网通信——服务间调用也走双向证书,不再"内网明文"

零信任的落地三件套:SPIFFE/SPIRE(服务身份标准)、Istio mTLS(服务间加密)、OPA(策略引擎)。这三个是 2025 年以后 Java 微服务认证的"事实标准组件"。

趋势 2:Passkey / WebAuthn 替代密码

2022 年苹果/谷歌/微软联合推动 Passkey(FIDO2/WebAuthn),用户不再记忆密码,改用"设备生物识别(指纹/人脸)+ 私钥本地存储"登录。优势是:

抗钓鱼——私钥不出设备,钓鱼网站拿不到
无密码泄露——服务端只存公钥,数据库泄露也不破
用户体验好——指纹/面容一键登录

国内应用:微信支付、支付宝、Apple ID 已全量支持;但企业内网系统普及率还低。预测 2027 年 WebAuthn 将成为新项目默认认证方式,密码降级为"备选方案"。

趋势 3:Token 标准化(OpenID Connect + OAuth 2.1)

早期的"各系统一套自定义 token"被证明是反模式。2020 年后业界统一到 OpenID Connect(OIDC) + OAuth 2.1:

OAuth 2.1 —— 授权框架标准化(简化了 OAuth 2.0 的 4 种 grant type,合并成 2 种)
OIDC —— 在 OAuth 2.1 之上加 ID Token(标准化用户信息)
PKCE —— 强制使用 PKCE(防授权码拦截),不再允许 implicit grant

落地表现:Spring Authorization Server(替代老旧的 Spring Security OAuth 项目)、Keycloak、Auth0、阿里云 IDaaS 全部支持 OIDC。本系列第 8 篇消息队列里会涉及"用 OIDC 做服务间身份传递"。

1.7 学习路线图:从入门到生产(6 个月计划)

认证体系知识量大,新手容易迷失方向。这是我给团队新人的"6 个月学习路线图",按优先级排:

阶段	时长	学习内容	产出
基础(1-2 月)	6-8 周	TLS/HTTPS 原理、JWT 原理、密码学入门(《图解密码技术》)	能讲清"为什么 HTTPS 安全"
框架(2-3 月)	4-6 周	sa-token 或 Spring Security 二选一,吃透一套(API + 源码 + 实战 demo)	能独立搭一套认证中心
生产(4-5 月)	6-8 周	双 Token、SSO、Gateway 集成、限流风控、审计日志	能上生产(12 条铁律)
进阶(6 月+)	持续	零信任、Passkey、OIDC、OPA 策略引擎	能做架构选型和技术决策

关键节点:

第 1 个月末:能解释"为什么 HTTPS 比 HTTP 安全"(讲出 TLS 握手的 4 步)
第 2 个月末:能写出 JWT 生成/解析/验签的完整代码
第 3 个月末:能用 sa-token 搭出"双 Token + 简单 SSO"的 demo
第 4 个月末:能讲出 12 条生产铁律,并对照自己公司系统打分
第 6 个月末:能独立完成"统一认证中心"的设计文档和 POC

💡 原理:为什么"先吃透一套框架"而不是"两套都学"?

见过有团队新人"两边都看一下"——结果半年过去两套都"半瓶水",遇到问题不知道查哪边文档。深度优先于广度——把 sa-token 的所有高级特性(SSO、临时 token、二级认证、账号封禁)都用一遍,比浅尝 Spring Security 强 10 倍。

我的建议:先学 sa-token(国内友好,2 周上手),生产 2 年后再补 Spring Security(看团队项目需要)。

二、密码学基石:从对称加密到 HTTPS 4 步握手

2.1 密码学 4 件套在 HTTPS 里的协作

Java 微服务认证的密码学基石是 4 件事:对称加密(快,加解密同一把密钥)、非对称加密(慢,公钥私钥配对)、数字签名(用私钥签,公钥验,防篡改)、HTTPS/TLS(用非对称加密交换密钥,再用对称加密传数据)。这 4 件事不是互斥的,而是组合的——HTTPS 就是"非对称加密 + 对称加密 + 数字签名"的集大成者。

2.2 对称加密:加解密同一把密钥

代表算法:AES-128 / AES-256 / ChaCha20 / SM4(国密)

核心原理:

1
2


明文 ──[密钥 K]──> 密文 ──[密钥 K]──> 明文
 encrypt decrypt

Java 代码(AES-256-GCM):

 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


import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.SecureRandom;
import java.util.Base64;

public class AesGcmUtil {
 private static final int KEY_SIZE = 256;
 private static final int IV_SIZE = 12; // GCM 推荐 12 字节
 private static final int TAG_SIZE = 128; // 认证标签长度

 public static String encrypt(String plaintext, String keyBase64) throws Exception {
 byte[] keyBytes = Base64.getDecoder().decode(keyBase64);
 SecretKey key = new SecretKeySpec(keyBytes, "AES");

 // IV 每次随机(关键:不能复用)
 byte[] iv = new byte[IV_SIZE];
 new SecureRandom().nextBytes(iv);

 Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
 cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_SIZE, iv));
 byte[] ct = cipher.doFinal(plaintext.getBytes("UTF-8"));

 // 输出 = IV(12) + ciphertext(含 tag)
 byte[] out = new byte[iv.length + ct.length];
 System.arraycopy(iv, 0, out, 0, iv.length);
 System.arraycopy(ct, 0, out, iv.length, ct.length);
 return Base64.getEncoder().encodeToString(out);
 }

 public static String decrypt(String ciphertextBase64, String keyBase64) throws Exception {
 byte[] keyBytes = Base64.getDecoder().decode(keyBase64);
 byte[] data = Base64.getDecoder().decode(ciphertextBase64);
 SecretKey key = new SecretKeySpec(keyBytes, "AES");

 // 拆 IV + ciphertext
 byte[] iv = new byte[IV_SIZE];
 System.arraycopy(data, 0, iv, 0, iv.length);
 byte[] ct = new byte[data.length - iv.length];
 System.arraycopy(data, iv.length, ct, 0, ct.length);

 Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
 cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_SIZE, iv));
 return new String(cipher.doFinal(ct), "UTF-8");
 }
}

关键点:

IV 必须每次随机——GCM 模式下 IV 复用会泄露明文,SecureRandom 是必需
GCM 模式自带认证——除了加密还防止密文被篡改
密钥管理是难题——对称密钥谁持有谁能解密,生产中通常用 **KMS(AWS KMS / 阿里云 KMS)**管理,不直接落地明文

🎯 避坑:对称加密的 3 个常见错误

IV 写死成常量 → GCM 加密完全失效(直接输出相同密文)

用 ECB 模式 → 不隐藏明文模式(图片加密后还能看出轮廓)

密钥硬编码在代码里 → Git 泄露 = 整个加密系统报废,生产用 KMS 或 Vault

2.3 非对称加密:公钥 + 私钥配对

代表算法:RSA / ECC(椭圆曲线)/ ECDH / ECDHE

核心原理:

1
2
3
4
5


公钥加密,私钥解密(机密性):
明文 ──[公钥 PK]──> 密文 ──[私钥 SK]──> 明文

私钥签名,公钥验签(真实性):
明文 ──[私钥 SK]──> 签名 ──[公钥 PK + 明文]──> true/false

RSA vs ECC 对比:

维度	RSA-2048	ECC-256	备注
安全性等价	RSA-2048 ≈ ECC-224	ECC-256 ≈ RSA-3072	ECC 用更短密钥达到相同安全
性能(签名)	慢	快 5-10 倍	ECC 在移动端优势明显
密钥体积	2048 bit(256 字节)	256 bit(32 字节)	ECC 适合 IoT / 移动端
生态成熟度	100%	99%	RSA 历史久,ECC 现代主流
TLS 1.3 推荐	可选	默认	TLS 1.3 默认 X25519(ECC)

Java 代码(ECDHE 密钥交换):

 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


import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.spec.ECGenParameterSpec;
import javax.crypto.KeyAgreement;

public class EcdhDemo {
 public static void main(String[] args) throws Exception {
 // 1. Alice 生成密钥对
 KeyPairGenerator kpg = KeyPairGenerator.getInstance("EC");
 kpg.initialize(new ECGenParameterSpec("secp256r1"));
 KeyPair aliceKp = kpg.generateKeyPair();

 // 2. Bob 生成密钥对
 KeyPair bobKp = kpg.generateKeyPair();

 // 3. Alice 用自己的私钥 + Bob 的公钥 → 共享密钥
 KeyAgreement aliceKa = KeyAgreement.getInstance("ECDH");
 aliceKa.init(aliceKp.getPrivate());
 aliceKa.doPhase(bobKp.getPublic(), true);
 byte[] aliceShared = aliceKa.generateSecret();

 // 4. Bob 用自己的私钥 + Alice 的公钥 → 共享密钥
 KeyAgreement bobKa = KeyAgreement.getInstance("ECDH");
 bobKa.init(bobKp.getPrivate());
 bobKa.doPhase(aliceKp.getPublic(), true);
 byte[] bobShared = bobKa.generateSecret();

 // 5. 双方得到相同的共享密钥(用于后续对称加密)
 System.out.println(aliceShared.length == bobShared.length); // true
 // 攻击者即使截获双方公钥,也算不出共享密钥(离散对数难题)
 }
}

关键点:

非对称加密比对称慢 100-1000 倍——所以 HTTPS 不用非对称加密"数据本身",只用它交换对称密钥
ECDHE 比 ECDH 多一个"E"——Ephemeral(临时),每次握手生成临时密钥对,支持前向保密(PFS):即使长期私钥泄露,历史会话也不被破解
公钥谁都能拿到——公钥不需要保密,但私钥泄露 = 整个系统报废

2.4 数字签名:防篡改 + 不可否认

代表算法:HMAC(对称签名)/ RSA-PSS(非对称签名)/ Ed25519(现代主流)/ ECDSA

核心流程:

1
2
3
4
5
6


签名:
明文 M ──[hash]──> 摘要 H ──[私钥 SK]──> 签名 S

验签:
明文 M ──[hash]──> 摘要 H' ←─┐
签名 S ──[公钥 PK]──> 摘要 H ──┴─> 比较 H == H'

HMAC vs RSA 签名:

维度	HMAC-SHA256	RSA-PSS-2048	Ed25519
类型	对称签名(双方共享密钥)	非对称签名(公钥验签)	非对称签名(现代曲线)
性能	最快	慢	快
用途	JWT 内部签名	证书签名 / 传统 API 签名	现代 API 签名 / Git commit
密钥管理	1 个密钥	1 对密钥	1 对密钥
安全强度	强(密钥不泄露)	强	强(更短密钥 = 相同安全)

Java 代码(JWT 用 HMAC-SHA256 签名):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class HmacUtil {
 public static String sign(String data, String secret) throws Exception {
 Mac mac = Mac.getInstance("HmacSHA256");
 mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
 byte[] sig = mac.doFinal(data.getBytes("UTF-8"));
 return Base64.getUrlEncoder().withoutPadding().encodeToString(sig);
 }

 public static boolean verify(String data, String signature, String secret) throws Exception {
 String expected = sign(data, secret);
 // 恒定时间比较,防时序攻击
 return java.security.MessageDigest.isEqual(
 expected.getBytes("UTF-8"), signature.getBytes("UTF-8")
 );
 }
}

关键点:

签名的目的是"完整性 + 身份认证"——证明"这段数据确实是私钥持有人签的,且未被篡改"
HMAC 不是加密——HMAC 不隐藏明文(明文还在),只是证明"明文没被改 + 是我签的"
必须用恒定时间比较——== 字符串比较会泄露时序信息(攻击者可以通过响应时间逐字节猜签名),MessageDigest.isEqual 是恒定时间

📌 实践:为什么 JWT 用 HMAC 不用 RSA?

JWT 签名场景是"签发方 = 验证方"(都是认证服务),用 HMAC-SHA256 性能更快、密钥管理更简单。

如果场景是"签发方 A,验证方有 N 个"——比如 GitHub 用私钥签名 commit,所有人用 GitHub 公钥验签——就必须用 RSA/Ed25519 这类非对称签名。

2.5 HTTPS / TLS 1.3 握手:把上面 3 件事串起来

TLS 1.3 完整握手时序图(1-RTT,比 TLS 1.2 快 1 步):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


客户端 服务端
 │ │
 │ ① ClientHello(支持的密码套件+随机数+密钥共享)│
 ├────────────────────────────────────────────>│
 │ │
 │ 生成临时 ECDHE 密钥对
 │ 用 CA 证书(公钥+签名)响应
 │ ② ServerHello + EncryptedExtensions + Certificate + CertificateVerify + Finished
 <────────────────────────────────────────────┤
 │ │
 │ 验证证书链(数字签名验签) │
 │ 用服务器 ECDHE 公钥 + 自己 ECDHE 私钥 │
 │ → 计算出 pre-master secret │
 │ → 派生出会话密钥(对称加密密钥) │
 │ │
 │ ③ Finished(用会话密钥加密) │
 ├────────────────────────────────────────────>│
 │ │
 │ 解密 Finished(对称加密) │
 │ 验证握手完整性 │
 │ │
 │ ④ Application Data(开始用对称加密传输) │
 <──────────────────────────────────────────>│

TLS 1.3 的 4 个关键步骤:

ClientHello:客户端声明"我支持哪些密码套件 + 随机数 + 我的 ECDHE 临时公钥"
ServerHello + 证书:服务端选定密码套件,发回自己的 ECDHE 临时公钥 + CA 证书(含服务端的 RSA/ECC 长期公钥 + CA 数字签名)
Finished:双方用 ECDHE 算法 + 双方临时公钥 → 算出"共享密钥" → 派生出对称加密密钥,所有后续数据用这个对称密钥加密
Application Data:握手完成,正常 HTTP 通信(全部走对称加密)

为什么 TLS 1.3 比 TLS 1.2 安全?

删除不安全算法:禁用 RC4、MD5、SHA-1、3DES、CBC 模式(这些都被破解过)
强制前向保密(PFS):TLS 1.3 必须用 ECDHE,即使长期私钥泄露,历史会话也不破
0-RTT 模式(可选):第二次连接可以"0-RTT"——客户端先发数据,服务端收到后再验证。但0-RTT 有重放攻击风险,谨慎使用

💡 原理:TLS 为什么要"先非对称后对称"?

全程非对称:性能太差,100 KB 数据要加密 100 KB×RSA 慢操作(几秒级)

全程对称:无法安全传递密钥(明文传密钥 = 明文传密码)

组合方案:用非对称加密传递对称密钥,再用对称加密传数据——兼顾安全和性能

这是密码学最经典的设计思想:用慢的算法做关键步骤,用快的算法做大量数据。

2.6 密码学在 Java 微服务中的真实用法

场景	用什么算法	用途
HTTPS 通信	TLS 1.3 (ECDHE + AES-256-GCM)	浏览器 → Gateway 全程加密
JWT 签名	HMAC-SHA256 (单服务) / Ed25519 (跨服务)	token 防篡改
refresh token 存储	AES-256-GCM	DB 里存密文,即使 DB 泄露也不破
密码存储	bcrypt / Argon2	用户密码单向 hash(不可逆)
API 请求签名	HMAC-SHA256 + nonce + timestamp	防止重放攻击(类似支付宝签名)
跨服务调用 mTLS	TLS + 双向证书	微服务间零信任加密

三、JWT 核心原理:从 base64 到 5 种攻击

3.1 JWT 是什么、不是什么

JWT(JSON Web Token)是一种"自包含"的字符串凭证,由 Header + Payload + Signature 三部分用 . 拼接,本质是"用 base64 编码的 JSON + 数字签名"。 它解决的是"无状态身份凭证"问题——服务端不需要存 session,只需验签即可信任 JWT 内的用户信息。但 JWT 不加密,内容明文可见,绝对不能放密码等敏感信息。

3.2 JWT 的 3 段结构

1
2
3


eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. ← Header (base64)
eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJ4eHgiLCJleHAiOjE3MzAwMDB9. ← Payload (base64)
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ← Signature

Header 解码后:

1
2
3
4


{
 "alg": "HS256", // 签名算法
 "typ": "JWT"
}

Payload 解码后(注意:明文,不是密文!):

1
2
3
4
5
6
7
8
9


{
 "sub": "12345", // 用户 ID
 "name": "liangweidong",
 "role": "admin",
 "iat": 1700000000, // 签发时间
 "exp": 1700003600, // 过期时间(1 小时后)
 "iss": "auth-service", // 签发方
 "aud": "order-service" // 接收方
}

Signature 计算:

1
2
3
4


HMAC-SHA256(
 base64UrlEncode(header) + "." + base64UrlEncode(payload),
 secret
)

关键:Signature = HMAC(header.payload, secret)——Header + Payload 任何字符变了,Signature 必然变(因为 HMAC 对单字符差异都极度敏感)。

3.3 完整 Java 工具类(生成 + 解析 + 验签)

 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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

public class JwtUtil {
 private static final String SECRET = "${JWT_SECRET:从环境变量注入,32+ 字节随机}";
 private static final long DEFAULT_TTL_SECONDS = 3600; // 1 小时
 private static final ObjectMapper MAPPER = new ObjectMapper();
 private static final Base64.Encoder ENCODER = Base64.getUrlEncoder().withoutPadding();
 private static final Base64.Decoder DECODER = Base64.getUrlDecoder();

 /** 生成 JWT */
 public static String generate(Long userId, String role, long ttlSeconds) throws Exception {
 // 1. Header
 Map<String, String> header = new HashMap<>();
 header.put("alg", "HS256");
 header.put("typ", "JWT");
 String headerB64 = ENCODER.encodeToString(MAPPER.writeValueAsBytes(header));

 // 2. Payload(标准 claim)
 Map<String, Object> payload = new HashMap<>();
 payload.put("sub", userId);
 payload.put("role", role);
 payload.put("iat", Instant.now().getEpochSecond());
 payload.put("exp", Instant.now().getEpochSecond() + ttlSeconds);
 String payloadB64 = ENCODER.encodeToString(MAPPER.writeValueAsBytes(payload));

 // 3. Signature
 String data = headerB64 + "." + payloadB64;
 String sig = ENCODER.encodeToString(hmacSha256(data.getBytes(StandardCharsets.UTF_8)));

 return data + "." + sig;
 }

 /** 解析 JWT(不验签,只解码 Payload) */
 public static Map<String, Object> parseUnsafe(String token) throws Exception {
 String[] parts = token.split("\\.");
 if (parts.length != 3) {
 throw new IllegalArgumentException("invalid JWT format");
 }
 byte[] payloadBytes = DECODER.decode(parts[1]);
 return MAPPER.readValue(payloadBytes, Map.class);
 }

 /** 验签 + 检查过期 */
 public static boolean verify(String token) throws Exception {
 String[] parts = token.split("\\.");
 if (parts.length != 3) return false;

 String data = parts[0] + "." + parts[1];
 String expected = ENCODER.encodeToString(hmacSha256(data.getBytes(StandardCharsets.UTF_8)));
 // 恒定时间比较
 if (!MessageDigest.isEqual(
 expected.getBytes(StandardCharsets.UTF_8),
 parts[2].getBytes(StandardCharsets.UTF_8))) {
 return false;
 }

 // 过期检查
 Map<String, Object> payload = parseUnsafe(token);
 long exp = ((Number) payload.get("exp")).longValue();
 return Instant.now().getEpochSecond() < exp;
 }

 private static byte[] hmacSha256(byte[] data) throws Exception {
 Mac mac = Mac.getInstance("HmacSHA256");
 mac.init(new SecretKeySpec(SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
 return mac.doFinal(data);
 }
}

关键点:

签名 secret 至少 32 字节随机——短 secret 容易被暴力破解
HS256 是单密钥方案——签发方和验证方共享同一个 secret(本服务内部用 OK,跨服务签名要用 RS256)
过期检查必须做——JWT 默认不过期,容易泄露后被永久滥用
MessageDigest.isEqual 恒定时间比较——防止时序攻击

3.4 JWT 的 5 种常见攻击与防御

攻击 1:算法替换(alg=none)

1

攻击者把 header 改成 {"alg": "none"} → 删掉 signature → 服务端如果"按 alg 选算法",直接放行

防御:

1
2
3
4


// 拒绝 alg=none
if (!"HS256".equals(alg)) {
 throw new SecurityException("unsupported alg: " + alg);
}

攻击 2:算法混淆(HS256 ↔ RS256)

1

攻击者把服务端用 RS256(公钥验签)的算法 → 改成 HS256 → 用"公钥"作为 HMAC 密钥伪造 token

防御:

1
2
3
4
5


// 强制用配置的算法,不信 header 里的 alg
String alg = (String) header.get("alg");
if (!ALLOWED_ALG.equals(alg)) {
 throw new SecurityException("alg mismatch");
}

攻击 3:重放攻击(过期 token 复用)

1

攻击者截获合法 token → token 还在有效期内 → 重复使用

防御:

JWT 短期过期(15 分钟)+ refresh token 续签
关键操作(支付/转账)要求一次性 token(jti claim + 一次性使用)
服务端记录已用 jti,二次使用拒绝

攻击 4:敏感信息泄露

1

攻击者 base64 解码 Payload → 看到明文 userId / role → 篡改 role=admin 重新签名

防御:

JWT 只能放"用户 ID + 权限标识"等公开信息
严禁放密码、身份证号、银行卡等敏感数据
篡改 role 会被签名校验拦截(除非密钥泄露)

攻击 5:密钥泄露

1

开发者把 JWT secret 提交到 GitHub → 攻击者拿到 secret → 伪造任意 token

防御:

secret 从环境变量 / KMS 注入,不写代码
定期轮换 secret(生产建议 90 天)
不同服务用不同 secret(避免一个泄露全破)
提交前用 git-secrets / gitleaks 工具扫描

🛑 误区:JWT 是加密的?

JWT 不是加密,是签名!Payload 用 base64 编码,任何人都能解码看明文。JWT 解决的是"防篡改"(签名校验),不是"防偷看"(加密)。

真要加密 Payload,要用 JWE(JSON Web Encryption)——比 JWT 复杂 10 倍,生产中很少用。如果真的需要"加密 + 签名",建议用 PASETO(Platform-Agnostic Security Tokens,JWT 的现代化替代)或 Macaroon(Google 开源,带"权限衰减"特性)。

3.5 JWT vs Session:怎么选?

维度	JWT	Session
存储	客户端(自带)	服务端(Redis)
扩展性	无状态,易水平扩展	有状态,需要 Session 共享
跨域	直接放 Header,无 Cookie 限制	需 CORS + Cookie 配置
撤销	困难(只能等过期)	简单(删 Session 即可)
适合场景	微服务、移动端、第三方授权	单体应用、后台管理
用户量	千万级无忧	百万级开始考虑优化

生产经验:

用户量 < 100 万 + 简单单体 → Session 更省事
用户量 > 100 万 + 微服务/移动端 → JWT 更合适
需要"踢人下线"功能 → Session 或 JWT + 黑名单
超大规模(亿级) → JWT + 短过期 + refresh token + 风控

3.6 JWT 的现代替代:3 种新兴凭证格式

JWT 统治了 2015-2022 年的认证体系,但 2020 年后业界反思出 3 个问题,催生了 3 种替代方案。

问题 1:JWT 不可撤销——签发后即使发现泄露,也只能等过期(默认 24 小时太长)。

问题 2:JWT 太灵活导致 alg 攻击——alg 字段由 token 自己声明,攻击者可改为 none 或混淆算法。

问题 3:JWT 的"标准"太宽泛——可选算法 8 种、压缩方式 2 种、JWK 来源 4 种,实现时容易出兼容性问题。

替代方案 1:PASETO(Platform-Agnostic Security Tokens)

2018 年 Scott Arciszewski 提出的"反 JWT"方案。核心区别:

不声明 alg 字段——签发时决定算法,验证时用对应密钥
强制版本化——v2.local(对称加密)、v2.public(非对称签名)
Payload 默认加密——v2.local 模式下 Payload 是密文不是明文

代码示例(PASETO v2.local):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 引入 dev.sigstore:paseto
String token = Paseto.builder()
 .setSubject(String.valueOf(userId))
 .setExpiration(Instant.now().plus(15, ChronoUnit.MINUTES))
 .setIssuer("auth-center")
 .setKey(KeyUtil.encodeKeyToHex(secretKeyBytes)) // 32 字节对称密钥
 .compact(Paseto.V2.LOCAL); // LOCAL = 对称加密模式

// 解析
Map<String, Object> claims = Paseto.parser(Paseto.V2.LOCAL)
 .key(KeyUtil.encodeKeyToHex(secretKeyBytes))
 .build()
 .parseClaims(token);

对比:

维度	JWT	PASETO
alg 字段	显式声明(可被替换)	隐式(由版本决定)
Payload	base64 明文	加密(v2.local)
算法支持	8 种可选	1 种强制
生态成熟度	100%	10%(社区驱动)
学习曲线	平	平

替代方案 2:Macaroon(Google 开源,2014)

特色是"权限衰减"——token 可以被"消减"出子 token,而不需要服务端介入。

应用场景:Google Cloud 的"服务账号委托链"就是 Macaroon 的工业实践——一个服务账号能"授权"另一个服务只能做"读但不能写"。

替代方案 3:DPoP(Delegated Proof of Possession, RFC 9449, 2023)

DPoP 不是替代 JWT,而是给 OAuth 2.0 token 加"持有者证明"——客户端用私钥对每个请求签名,即使 token 被偷,攻击者没私钥也用不了。这是 2023 年最值得关注的认证技术之一,GitHub、Auth0、Okta 都已经支持。

结论:90% 的项目用 JWT 就够了;新项目建议用 PASETO v2.local(更安全、API 更简洁);超大规模(亿级)或 OAuth 2.0 场景加 DPoP。

3.7 何时不用 JWT?4 个反模式场景

JWT 不是银弹,以下 4 个场景用 JWT 是反模式:

反模式 1:用户量小 + 简单单体应用

用户 < 10 万 + 单体 + 后台管理 → 直接用 Spring Session + Cookie 即可。JWT 反而增加复杂度(JWT 工具类 + 刷新逻辑 + 黑名单),Session 简单几行 yml 就搞定。

反模式 2:需要实时踢人下线

JWT 一旦签发,服务端无法撤销(只能等过期或加黑名单)。如果业务强需求"管理员踢人立即生效"——比如"封禁违规账号立即让其下线"——用 Session 或 JWT + 实时黑名单。纯 JWT + 长过期 = 永远踢不掉人。

反模式 3:需要服务端主动失效 token

某些场景要求"服务端能主动让 token 失效"(密码被改后所有 token 立即失效、双因素认证升级)。JWT 做不到,需要:

短过期(15 分钟) + 轮询查 DB(高开销)
JWT 黑名单(自己实现的"伪 session")
或者用 PASETO + revocation server

反模式 4:涉及支付/金融等强一致场景

支付系统需要"每一笔交易都强可追溯",JWT 里的 userId 字段不能直接作为"是谁付的款"的证据——因为 JWT 是客户端可控的(签名校验只防篡改,不防"用户主动用别人的 token")。支付系统需要二次验证(短信/密码) + 服务端业务校验。

🎯 避坑:JWT 不是万能钥匙

见过有团队"用 JWT 实现一切"——结果遇到"踢人下线"需求时被迫加黑名单,加完之后发现"那不就是 Session 吗"——绕一圈回到原点。正确的思路是:按业务需求选凭证格式,别被"JWT 流行"绑架。

四、Spring Security vs sa-token:理念对比 + 最小 demo

4.1 Spring Security 与 sa-token 的核心分歧

Spring Security 和 sa-token 是"二选一"的关系,不是"两套都集成"。 Spring Security 是 Spring 全家桶的官方安全框架,生态完整、功能强大但学习曲线陡;sa-token 是国产轻量级框架,API 极简、上手快但生态相对小。选谁取决于:团队规模、权限复杂度、生态依赖。国内中小项目首选 sa-token(5 行代码完成 90% 鉴权),集团级复杂 RBAC 选 Spring Security(方法级注解 + 表达式)。

4.2 理念对比:重量级 vs 轻量级

维度	Spring Security	sa-token
出身	Spring 官方 / Pivotal	国产 / 一位大佬个人项目
代码量	庞大(核心 ~3 万行)	轻量(核心 ~5000 行)
学习曲线	陡(Filter Chain / AuthenticationManager / AccessDecisionManager 三大件)	平(注解驱动)
核心抽象	Filter Chain(13+ 个内置 Filter)	拦截器(StpUtil 一行调用)
鉴权粒度	URL 级 + 方法级(@PreAuthorize)+ 表达式(SpEL)	URL 级 + 注解(@SaCheckLogin / @SaCheckRole)
分布式会话	Spring Session(Redis)	内置(Redis / DB 模式)
SSO	需集成(spring-security-oauth2)	内置(@SaOAuth2 注解)
生态集成	Spring 全家桶无侵入	Spring Boot / Solon / JFinal 多框架
社区	国际主流 / Stack Overflow 答案多	国内主流 / 中文文档好
缺点	配置复杂、调试不直观	复杂场景(自定义 Filter 链)较繁琐

4.3 Spring Security 最小 demo(只为对比,生产不主推)

核心:SecurityFilterChain Bean

 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


@Configuration
@EnableWebSecurity
public class SecurityConfig {

 @Bean
 public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 return http
 // 1. 关闭 CSRF(前后端分离 + JWT 不需要)
 .csrf(csrf -> csrf.disable())
 // 2. 关闭 Session(用 JWT 替代)
 .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
 // 3. 允许匿名访问的路径
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/api/public/**", "/api/auth/login").permitAll()
 .anyRequest().authenticated()
 )
 // 4. 添加自定义 JWT 过滤器
 .addFilterBefore(new JwtAuthFilter(), UsernamePasswordAuthenticationFilter.class)
 // 5. 异常处理
 .exceptionHandling(eh -> eh
 .authenticationEntryPoint((req, res, e) -> {
 res.setStatus(401);
 res.getWriter().write("{\"code\":401,\"msg\":\"未登录\"}");
 })
 )
 .build();
 }
}

自定义 JWT 过滤器:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@Component
public class JwtAuthFilter extends OncePerRequestFilter {
 @Override
 protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
 throws ServletException, IOException {
 String token = req.getHeader("Authorization");
 if (token != null && token.startsWith("Bearer ")) {
 token = token.substring(7);
 try {
 Map<String, Object> payload = JwtUtil.parseUnsafe(token);
 if (JwtUtil.verify(token)) {
 // 把用户信息塞进 SecurityContext
 Long userId = ((Number) payload.get("sub")).longValue();
 String role = (String) payload.get("role");
 List<SimpleGrantedAuthority> auths = List.of(new SimpleGrantedAuthority("ROLE_" + role));
 UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(userId, null, auths);
 SecurityContextHolder.getContext().setAuthentication(auth);
 }
 } catch (Exception ignored) {}
 }
 chain.doFilter(req, res);
 }
}

行数统计:核心鉴权 = 25 行(SecurityConfig) + 20 行(JwtAuthFilter) = 45 行。这是 Spring Security 的"最简形态"——再加 RBAC 表达式、CSRF、自定义 UserDetailsService 就要 100+ 行。

4.4 sa-token 最小 demo(生产主推方案)

核心:SaTokenConfig + 拦截器自动启用

 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


@Configuration
public class SaTokenConfig {
 // 1. 注册 Sa-Token 拦截器(打开注解鉴权)
 @Bean
 public SaInterceptor saInterceptor() {
 return new SaInterceptor();
 }

 // 2. 注册路由拦截器
 @Bean
 public WebMvcConfigurer saTokenWebMvcConfigurer() {
 return new WebMvcConfigurer() {
 @Override
 public void addInterceptors(InterceptorRegistry registry) {
 registry.addInterceptor(saInterceptor())
 .addPathPatterns("/**")
 .excludePathPatterns("/api/auth/login", "/api/public/**");
 }
 };
 }

 // 3. 自定义权限验证接口(从 DB 查 userId 的权限列表)
 @Bean
 public StpInterface stpInterface() {
 return new StpInterface() {
 @Autowired private UserService userService;

 @Override
 public List<String> getPermissionList(Object loginId, String loginType) {
 return userService.getPermissions((Long) loginId);
 }
 @Override
 public List<String> getRoleList(Object loginId, String loginType) {
 return userService.getRoles((Long) loginId);
 }
 };
 }
}

业务代码(控制器加注解 = 鉴权完成):

 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


@RestController
@RequestMapping("/api/order")
public class OrderController {

 // 1. 登录即可访问
 @SaCheckLogin
 @GetMapping("/list")
 public List<Order> list() {
 return orderService.listByUser(StpUtil.getLoginIdAsLong());
 }

 // 2. 需要 admin 角色
 @SaCheckRole("admin")
 @DeleteMapping("/{id}")
 public void delete(@PathVariable Long id) {
 orderService.delete(id);
 }

 // 3. 需要特定权限标识
 @SaCheckPermission("order:export")
 @GetMapping("/export")
 public void export() {
 orderService.export();
 }

 // 4. SSO 鉴权(从认证中心回调后校验)
 @SaCheckLogin
 @GetMapping("/profile")
 public User profile() {
 return userService.getById(StpUtil.getLoginIdAsLong());
 }
}

行数统计:核心鉴权 = 30 行(SaTokenConfig) + 4 个注解 + 2 行调用 = 38 行。比 Spring Security 少 15%,但开发体验是数量级的提升——业务代码完全不用写"if 没登录"这种判断。

4.5 选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


Q1: 团队有 Spring Security 历史经验吗?
 ├─ 有 + 复杂 RBAC 需求 → Spring Security
 └─ 没有 / 经验少
 Q2: 业务权限复杂度?
 ├─ 简单(用户/角色/资源)→ sa-token
 └─ 复杂(用户/角色/资源/数据范围/字段级)→ Spring Security

 Q3: 微服务 + 分布式会话需求?
 ├─ 强(多端登录踢人)→ Spring Security + Spring Session Redis
 └─ 弱 → sa-token 内置方案

 Q4: 鉴权代码量敏感度?
 ├─ 敏感(想少写代码)→ sa-token
 └─ 不敏感(要可扩展)→ Spring Security

最终推荐:
- 中小项目 + 国内团队 + 追求开发效率 → sa-token
- 集团级 + 复杂权限 + Spring 全家桶 → Spring Security
- 已经在用 Spring Security → 不要为换而换
- 新项目 + 团队没经验 → sa-token(更快上手)

4.6 为什么"二选一"而不是"两套都用"?

生产中两套并存的代价:

配置混乱——Spring Security 的 SecurityFilterChain 和 sa-token 的 SaInterceptor 都会拦截请求,顺序错乱导致鉴权绕过
学习成本 ×2——团队要同时懂两套机制,新人入职 3 个月才能摸清
调试地狱——一个请求被两个框架各拦截一次,日志相互打架,出问题时不知道是哪个拦的
依赖膨胀——两套都引,jar 包体积多 5-10MB,启动慢 1-2 秒
维护成本 ×2——安全漏洞时两套都要升级,工作量翻倍

🛑 误区:“两套都装,做双保险”

实际是两套都互相干扰。比如:Spring Security 的 permitAll() 让请求通过,sa-token 的 StpUtil.checkLogin() 失败抛异常——结果是"通过 Spring Security 但被 sa-token 拒"——反直觉,排查一天找不到原因。

正确做法:选定一套,把它用到极致。深度优先于广度——把一套框架的所有高级特性都搞透,比浅尝两套安全得多。

4.7 sa-token 鉴权代码极简的秘密:`注解 + 拦截器 + 上下文`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


请求进入
 ↓
[SaInterceptor] ← 拦截带 @SaCheckLogin 等注解的请求
 ↓
[AOP 切面] ← 解析注解(角色/权限/登录)
 ↓
[StpUtil.getLoginId()] ← 从 ThreadLocal 拿当前登录用户
 ↓
[StpInterface] ← 自定义接口查 userId → 角色/权限
 ↓
业务代码(完全不用 if 判断鉴权)

vs Spring Security:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


请求进入
 ↓
[SecurityFilterChain] ← 13+ 个 Filter 按顺序执行
 ↓
[JwtAuthFilter] ← 自定义 Filter 解析 JWT
 ↓
[AuthenticationManager] ← 认证管理器
 ↓
[AccessDecisionManager] ← 鉴权决策
 ↓
[@PreAuthorize 表达式解析] ← 业务代码写表达式
 ↓
[SecurityContextHolder] ← ThreadLocal 存用户信息
 ↓
业务代码(偶尔要 SecurityContextHolder.getContext().getAuthentication())

核心差异:

sa-token = 约定优于配置(注解 + 默认行为,业务零感知)
Spring Security = 配置优于约定(每个 Filter 都要配置,业务要知道 Spring Security 在做什么)

没有绝对好坏,只有适合与否。

4.8 性能压测对比:sa-token vs Spring Security

测试环境:3 节点 Spring Boot 3.2 应用,Redis Cluster 6 节点,wrk 100 并发持续 60 秒,接口 GET /api/user/profile(登录后访问)。

框架	配置	TPS	P99 延迟	CPU 占用	启动时间
sa-token	@SaCheckLogin 注解	12000	8ms	25%	3.2s
sa-token	StpUtil.checkLogin() 手动调用	11500	9ms	27%	3.2s
Spring Security	13 个默认 Filter 全开	8200	22ms	45%	6.8s
Spring Security	裁剪到 4 个核心 Filter	10500	14ms	35%	5.5s

关键观察:

sa-token 性能领先 ~30%——核心是"拦截器比 Filter Chain 轻",sa-token 一个 SaInterceptor 解决 90% 场景,Spring Security 13 个 Filter 链式调用有 ~5ms 固定开销
Spring Security 启动慢 2 倍——加载的安全自动配置多(很多是用不上的)
裁剪后 Spring Security 能追平 70%——但需要团队深入理解每个 Filter 的作用(新人做不到)

生产建议:

性能敏感(高 QPS) + 简单鉴权 → sa-token(默认)
性能要求一般 + 复杂权限 → Spring Security(用裁剪配置)
性能要求极致(秒杀/抢券) → sa-token + 自研 Filter(更激进的优化)

五、sa-token + 双 Token + SSO + Gateway 一站打通

⚠️ 本章是 sa-token 实战主线。如果你的项目选 Spring Security,请回到第四章看最小 demo,本节的 sa-token 配置需要替换为对应的 Spring Security 写法。

5.1 sa-token 实战 4 件套的协作关系

Java 微服务认证的实战组合是:sa-token 负责应用层鉴权(业务服务内)、双 Token 机制负责无感续签(access 15 分钟 + refresh 7 天)、SSO 负责跨系统身份共享(三种模式:同域 Cookie / 跨域 OAuth2 / 跨域 OIDC)、Spring Gateway 负责统一鉴权入口(GlobalFilter 验签 + 透传用户信息)。这 4 件事必须一起做才算完整的"统一认证中心"——少任何一件都漏风。

5.2 完整架构图

 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


 ┌─────────────────────────────────────┐
 │ 浏览器 / App / 小程序 │
 └─────────────────┬───────────────────┘
 │ HTTPS (TLS 1.3)
 ↓
 ┌─────────────────────────────────────┐
 │ Nginx (SSL 卸载 / 静态资源) │
 └─────────────────┬───────────────────┘
 ↓
 ┌─────────────────────────────────────┐
 │ Spring Cloud Gateway │
 │ ┌─────────────────────────────┐ │
 │ │ AuthGlobalFilter │ │
 │ │ - 解析 access token │ │
 │ │ - 验签 + 过期检查 │ │
 │ │ - 注入 X-User-Id / X-Role │ │
 │ └─────────────────────────────┘ │
 └────┬──────────────┬─────────────┬───┘
 ↓ ↓ ↓
 ┌─────────┐ ┌─────────┐ ┌─────────┐
 │ user-svc │ │order-svc│ │pay-svc │
 │ sa-token │ │ sa-token │ │ sa-token│
 │ @SaCheck │ │ @SaCheck │ │ @SaCheck│
 └────┬─────┘ └────┬────┘ └────┬────┘
 ↓ ↓ ↓
 ┌─────────────────────────────────────┐
 │ Redis (sa-token 会话 / refresh) │
 │ + MySQL (用户/角色/权限) │
 └─────────────────────────────────────┘
 ↑
 │ (SSO 时)
 ┌─────────────────────────────────────┐
 │ SSO 认证中心 (auth-center) │
 │ - 统一登录页 │
 │ - 颁发 ticket (一次性) │
 │ - 颁发 access+refresh (双 Token) │
 └─────────────────────────────────────┘

5.3 第一步:sa-token 完整 application.yml

 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


# sa-token 配置
sa-token:
 # token 名称(同时也是前端请求头的 key)
 token-name: Authorization
 # token 有效期(单位:秒,默认 30 天,-1 代表永久)
 timeout: 900 # access token 15 分钟
 # 临时有效期(指定时间内无操作就视为 token 过期,单位:秒,默认 -1 不过期)
 active-timeout: 1800 # 30 分钟活跃
 # 是否允许同一账号并发登录(为 true 时共用一个 token,为 false 时新登录挤掉旧的)
 is-concurrent: true
 # 在多人登录同一账号时,是否共用一个 token(为 true 时,所有登录共用一个 token)
 is-share: false
 # token 风格(默认可不填,使用默认值)
 token-style: uuid
 # 是否输出操作日志
 is-log: true
 # 是否从 cookie 中读取 token
 is-read-cookie: false
 # 是否从 header 中读取 token
 is-read-header: true
 # token 前缀
 token-prefix: "Bearer "
 # 写入 token 时是否拼接前缀
 is-write-prefix: true
 # jwt 签名密钥(HS256,32+ 字节随机)
 jwt-secret-key: ${SA_TOKEN_SECRET:从环境变量注入,32+ 字节随机}
 # 单独配置 refresh token(用不同的 timeout,本配置用 7 天)
 # (sa-token 原生没有 refresh 概念,我们在自定义逻辑里实现,见 5.5)

# Redis 存储(sa-token 的会话、token 验证信息都放 Redis)
spring:
 data:
 redis:
 host: ${REDIS_HOST:127.0.0.1}
 port: 6379
 password: ${REDIS_PASSWORD}
 database: 0
 timeout: 3000ms
 lettuce:
 pool:
 max-active: 200
 max-idle: 50
 min-idle: 10

# HTTPS 配置(生产环境)
server:
 port: 8443
 ssl:
 enabled: true
 key-store: classpath:keystore.p12
 key-store-password: ${SSL_KEYSTORE_PASSWORD}
 key-store-type: PKCS12
 key-alias: tomcat

5.4 第二步:登录接口 + 双 Token 生成

 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


@RestController
@RequestMapping("/api/auth")
public class AuthController {

 @Autowired private UserService userService;
 @Autowired private PasswordEncoder passwordEncoder;
 @Autowired private RefreshTokenService refreshTokenService;

 /**
 * 登录:颁发 access + refresh 双 token
 */
 @PostMapping("/login")
 public Result<LoginResponse> login(@RequestBody LoginRequest req) {
 // 1. 校验密码
 User user = userService.getByUsername(req.getUsername());
 if (user == null || !passwordEncoder.matches(req.getPassword(), user.getPasswordHash())) {
 return Result.fail(401, "用户名或密码错误");
 }

 // 2. 颁发 access token(15 分钟,放 sa-token 默认存储)
 StpUtil.login(user.getId());
 String accessToken = StpUtil.getTokenValue();

 // 3. 颁发 refresh token(7 天,自己用 DB 或 Redis 存)
 String refreshToken = refreshTokenService.create(
 user.getId(),
 7 * 24 * 3600 // 7 天过期
 );

 // 4. 返回双 token
 return Result.ok(new LoginResponse(
 accessToken,
 refreshToken,
 900, // access 过期秒数
 7 * 24 * 3600 // refresh 过期秒数
 ));
 }

 /** 登出 */
 @PostMapping("/logout")
 public Result<Void> logout() {
 // 注销当前 access
 StpUtil.logout();
 // 同时撤销 refresh token
 refreshTokenService.revoke(StpUtil.getLoginIdAsLong());
 return Result.ok();
 }
}

关键点:

access token 用 sa-token 默认机制——自动存 Redis、自动续期
refresh token 自己实现——因为 sa-token 原生没有"双 token"概念(见 5.5 自定义实现)
密码用 BCrypt 加密——passwordEncoder.matches() 是恒定时间比较,防时序攻击

5.5 第三步:refresh token 持久化服务

 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


@Service
public class RefreshTokenService {

 @Autowired private StringRedisTemplate redis;

 // 存储 key 前缀
 private static final String PREFIX = "auth:refresh:";

 /**
 * 创建 refresh token(随机 32 字节)
 */
 public String create(Long userId, long ttlSeconds) {
 String token = generateRandomToken();
 String key = PREFIX + token;

 // 存 Redis(值是 userId,带过期时间)
 redis.opsForValue().set(key, String.valueOf(userId), Duration.ofSeconds(ttlSeconds));
 return token;
 }

 /**
 * 校验 + 撤销旧的 + 创建新的(轮换机制)
 */
 public Long verifyAndRotate(String refreshToken) {
 String key = PREFIX + refreshToken;
 String userId = redis.opsForValue().get(key);

 if (userId == null) {
 throw new BizException("refresh token 无效或已过期");
 }

 // 撤销旧的 refresh token(防重放)
 redis.delete(key);

 return Long.valueOf(userId);
 }

 /**
 * 撤销
 */
 public void revoke(Long userId) {
 // 反向查找:用户的所有 refresh token
 // 简单做法:维护"用户 → refresh token 列表" 的映射
 // 实际生产中用 userId 前缀存储,模糊匹配删除
 Set<String> keys = redis.keys(PREFIX + "*:" + userId);
 if (keys != null) redis.delete(keys);
 }

 private String generateRandomToken() {
 SecureRandom random = new SecureRandom();
 byte[] bytes = new byte[32];
 random.nextBytes(bytes);
 return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
 }
}

关键设计:

refresh token 不存 JWT 格式——直接用随机字符串(32 字节 = 256 位熵,无法暴力破解)
每次使用都轮换——验证后立刻撤销旧的,签发新的(防重放)
Redis 存 userId——验证时只查 Redis,不需要再 join 数据库

5.6 第四步:用 refresh token 换新 access token

 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


@RestController
@RequestMapping("/api/auth")
public class AuthController {

 @Autowired private RefreshTokenService refreshTokenService;

 /**
 * 刷新 access token(access 过期时调用)
 */
 @PostMapping("/refresh")
 public Result<LoginResponse> refresh(@RequestBody RefreshRequest req) {
 // 1. 校验 + 轮换 refresh token
 Long userId = refreshTokenService.verifyAndRotate(req.getRefreshToken());

 // 2. 颁发新 access token
 StpUtil.login(userId); // 会顶掉旧的 access(因为 is-concurrent=false)
 String newAccessToken = StpUtil.getTokenValue();

 // 3. 颁发新 refresh token(已经在 verifyAndRotate 里轮换过了)
 String newRefreshToken = refreshTokenService.create(userId, 7 * 24 * 3600);

 return Result.ok(new LoginResponse(
 newAccessToken,
 newRefreshToken,
 900,
 7 * 24 * 3600
 ));
 }
}

前端配合逻辑:

 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


// axios 拦截器:access 过期时自动 refresh
axios.interceptors.response.use(
 response => response,
 async error => {
 const originalRequest = error.config;
 if (error.response?.status === 401 && !originalRequest._retry) {
 originalRequest._retry = true;
 try {
 // 用 refresh token 换新 access
 const refreshToken = localStorage.getItem('refresh_token');
 const resp = await axios.post('/api/auth/refresh', { refreshToken });
 localStorage.setItem('access_token', resp.data.data.accessToken);
 localStorage.setItem('refresh_token', resp.data.data.refreshToken);
 // 重试原请求
 originalRequest.headers.Authorization = `Bearer ${resp.data.data.accessToken}`;
 return axios(originalRequest);
 } catch (refreshError) {
 // refresh 也过期,跳登录页
 window.location.href = '/login';
 return Promise.reject(refreshError);
 }
 }
 return Promise.reject(error);
 }
);

5.7 第五步:SSO 单点登录(同域模式最常见)

场景:a.example.com、b.example.com、c.example.com 三个子域要"一处登录,处处通行"。

核心思路:

登录页和 token 颁发放在统一认证中心(sso.example.com)
三个业务系统检测到"未登录"时,302 跳转到 SSO 中心
SSO 中心登录后,颁发"一次性 ticket" + 写共享 Cookie
业务系统用 ticket 换 access+refresh token

SSO 中心登录跳转 Controller:

 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
60
61
62
63
64


@RestController
@RequestMapping("/sso")
public class SsoController {

 @Autowired private UserService userService;
 @Autowired private RefreshTokenService refreshTokenService;

 // 1. SSO 中心登录页
 @GetMapping("/login")
 public String loginPage(@RequestParam String redirect, Model model) {
 model.addAttribute("redirect", redirect); // 登录后跳回的地址
 return "sso-login"; // 模板
 }

 // 2. SSO 中心登录提交
 @PostMapping("/doLogin")
 public Result<String> doLogin(@RequestBody LoginRequest req,
 @RequestParam String redirect,
 HttpServletResponse response) {
 // 1. 验证密码
 User user = userService.getByUsername(req.getUsername());
 if (user == null || !passwordEncoder.matches(req.getPassword(), user.getPasswordHash())) {
 return Result.fail(401, "用户名或密码错误");
 }

 // 2. 颁发一次性的 ticket(5 分钟有效,只能使用一次)
 String ticket = UUID.randomUUID().toString().replace("-", "");
 redis.opsForValue().set("sso:ticket:" + ticket, String.valueOf(user.getId()),
 Duration.ofMinutes(5));

 // 3. 写共享 Cookie(关键:domain=.example.com 让所有子域共享)
 Cookie ssoCookie = new Cookie("sso_token", ticket);
 ssoCookie.setDomain(".example.com"); // 关键:点开头的 domain 让所有子域共享
 ssoCookie.setPath("/");
 ssoCookie.setHttpOnly(true); // 防 XSS 偷 cookie
 ssoCookie.setSecure(true); // 只在 HTTPS 下发送
 ssoCookie.setMaxAge(5 * 60); // 5 分钟
 response.addCookie(ssoCookie);

 // 4. 跳回业务系统(URL 携带 ticket)
 String redirectUrl = redirect + "?ticket=" + ticket;
 return Result.ok(redirectUrl);
 }

 // 3. 业务系统用 ticket 换 token
 @GetMapping("/callback")
 public Result<LoginResponse> callback(@RequestParam String ticket) {
 // 1. 校验 ticket + 立即销毁(防重放)
 String userIdStr = redis.opsForValue().get("sso:ticket:" + ticket);
 if (userIdStr == null) {
 return Result.fail(401, "ticket 无效或已使用");
 }
 redis.delete("sso:ticket:" + ticket);

 Long userId = Long.valueOf(userIdStr);

 // 2. 颁发 access + refresh
 StpUtil.login(userId);
 String accessToken = StpUtil.getTokenValue();
 String refreshToken = refreshTokenService.create(userId, 7 * 24 * 3600);

 return Result.ok(new LoginResponse(accessToken, refreshToken, 900, 7 * 24 * 3600));
 }
}

业务系统接入:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 业务系统启动时:检查是否有 SSO cookie,没有则跳 SSO 中心
// 伪代码(实际写在拦截器里)
if (userNotLoggedIn() && hasSsoCookie()) {
 String ticket = getSsoCookie();
 LoginResponse tokens = ssoClient.callback(ticket);
 saveTokens(tokens);
 return page;
} else if (userNotLoggedIn() && !hasSsoCookie()) {
 return "redirect:https://sso.example.com/sso/login?redirect=" + currentUrl;
}

三种 SSO 模式对比:

模式	适用场景	实现复杂度	安全性
同域 Cookie 共享	所有系统在 `*.example.com` 下	低	高(共享 cookie + ticket 防重放)
跨域 OAuth2	多个不同主域	中(需要回调 URL)	中(回调域校验)
跨域 OIDC	第三方身份登录(GitHub/微信)	高(完整 OIDC 协议)	最高(标准协议)

5.8 第六步:Spring Gateway 集成 sa-token

Gateway 内的 AuthGlobalFilter:

 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


@Component
@Order(-100) // 数字越小越早执行,鉴权必须在最前
public class AuthGlobalFilter implements GlobalFilter {

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

 // 1. 白名单直接放行
 if (path.startsWith("/api/public/") || path.startsWith("/api/auth/login")) {
 return chain.filter(exchange);
 }

 // 2. 提取 access token
 String authHeader = request.getHeaders().getFirst("Authorization");
 if (authHeader == null || !authHeader.startsWith("Bearer ")) {
 return unauthorized(exchange, "缺少 token");
 }
 String token = authHeader.substring(7);

 // 3. 验签 + 过期检查
 try {
 Map<String, Object> payload = JwtUtil.parseUnsafe(token);
 if (!JwtUtil.verify(token)) {
 return unauthorized(exchange, "token 过期");
 }

 // 4. 解析 userId / role 注入到下游请求头
 Long userId = ((Number) payload.get("sub")).longValue();
 String role = (String) payload.get("role");

 ServerHttpRequest mutated = request.mutate()
 .header("X-User-Id", String.valueOf(userId))
 .header("X-User-Role", role)
 .header("X-Request-Id", UUID.randomUUID().toString()) // 链路追踪
 .build();
 return chain.filter(exchange.mutate().request(mutated).build());
 } catch (Exception e) {
 return unauthorized(exchange, "token 解析失败: " + e.getMessage());
 }
 }

 private Mono<Void> unauthorized(ServerWebExchange exchange, String msg) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.UNAUTHORIZED);
 response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
 String body = String.format("{\"code\":401,\"msg\":\"%s\"}", msg);
 return response.writeWith(Mono.just(response.bufferFactory().wrap(body.getBytes())));
 }
}

关键点:

Gateway 自己做验签——不调下游业务服务,降低下游服务负载
X-User-Id 透传——下游服务不用再解析 token,直接拿 header 即可
白名单——/api/auth/login 等接口不需要 token,直接放行

5.9 接口设计:鉴权友好的 6 条铁律

RESTful 资源命名:GET /api/users/{id} 而不是 GET /api/getUser?id=1
用 HTTP 状态码表达业务结果:
- 200 OK = 成功
- 400 Bad Request = 参数错误
- 401 Unauthorized = 未登录
- 403 Forbidden = 已登录但没权限
- 404 Not Found = 资源不存在
- 429 Too Many Requests = 限流
POST/PUT/DELETE 必须幂等——用 Idempotency-Key 请求头(类似 Stripe)
敏感操作二次验证——转账/删除需要"短期 token + 短信验证码"
不返回明文密码/身份证——即使内部 API 也不返回,日志里用 * 脱敏
统一错误响应格式:{"code": 401, "msg": "未登录", "data": null}

🎯 避坑:状态码滥用

把所有错误都返回 200 OK,body 里写 code: 500 是反模式——HTTP 层和网关层看不到错误,监控系统统计 QPS 时把"100% 失败"误判为"100% 成功"。正确做法:HTTP 状态码表达"请求级别成功/失败",body 里的 code 表达"业务级别成功/失败"。

5.10 sa-token 集群部署:3 个生产关键点

关键点 1:Token 共享存储必须用 Redis Cluster

sa-token 的 token 信息默认存 Redis(单实例)。生产环境必须用 Redis Cluster(至少 3 主 3 从)——否则 Redis 挂了所有用户全部掉线。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# application.yml
spring:
 data:
 redis:
 cluster:
 nodes: 192.168.1.10:6379,192.168.1.11:6379,192.168.1.12:6379
 max-redirects: 3
 password: ${REDIS_PASSWORD}
 lettuce:
 pool:
 max-active: 500 # 集群环境下调大
 max-idle: 100

关键点 2:Token 存储格式优化

sa-token 默认用 String 存 token,在 Redis Cluster 下 hash 槽不均(所有 key 集中在一个槽)。生产优化:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Bean
public SaTokenDao saTokenDao(RedisTemplate<String, Object> redisTemplate) {
 // 自定义 Dao,key 加业务前缀,分散到不同 hash 槽
 return new SaTokenDaoForRedis(redisTemplate) {
 @Override
 public String getKey(String key) {
 return "auth:token:" + key; // 加业务前缀
 }
 };
}

关键点 3:多机房容灾

异地多活架构下,sa-token 的 Redis 必须跨机房同步:

方案 A:Redis 自带的跨机房复制(主写 + 备机房读,延迟 100ms 以内)
方案 B:CRDT 工具(Redis CRDT / Pika)——支持双向同步,延迟更低

5.11 跨域 CORS 完整配置

前后端分离架构下,CORS 是必踩的坑。正确配置 3 处:

第 1 处:Spring Boot WebMvcConfigurer(单服务调用)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Configuration
public class CorsConfig implements WebMvcConfigurer {
 @Override
 public void addCorsMappings(CorsRegistry registry) {
 registry.addMapping("/api/**")
 .allowedOriginPatterns("*") // Spring Boot 2.4+ 必须用 Patterns
 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
 .allowedHeaders("*")
 .allowCredentials(true) // 允许携带 cookie
 .maxAge(3600); // 预检请求缓存
 }
}

第 2 处:Spring Cloud Gateway(网关层)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


spring:
 cloud:
 gateway:
 globalcors:
 cors-configurations:
 '[/**]':
 allowedOriginPatterns: "*"
 allowedMethods: "*"
 allowedHeaders: "*"
 allowCredentials: true
 maxAge: 3600

第 3 处:Nginx(反向代理层,可选)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


location /api/ {
 add_header 'Access-Control-Allow-Origin' '$http_origin' always;
 add_header 'Access-Control-Allow-Credentials' 'true' always;
 add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
 add_header 'Access-Control-Allow-Headers' '*' always;

 if ($request_method = 'OPTIONS') {
 return 204; # 预检请求直接 204
 }

 proxy_pass http://gateway;
}

🎯 避坑:allowCredentials: true + allowedOrigins: * 的经典错误

这两个配置不能同时存在——CORS 规范禁止"通配 origin + 带 cookie"。正确做法:

知道具体 origin:用 allowedOrigins("https://app.example.com")

不知道 / 多个 origin:用 allowedOriginPatterns("*") 代替

这是初学者最常踩的坑,Stack Overflow 上同名问题 5000+ 回答,但 90% 都是错的对策(用 Filter 自定义响应头绕过)——按规范来,别绕。

六、生产清单:认证授权的 12 条铁律

这一节是给"已经理解了原理,准备上生产"的同学的速查清单。前 5 节是"为什么 + 怎么做",这一节是"必须做/绝对不能做"。

HTTPS 强制全站——任何明文 HTTP 都不允许(即使是内部网络),用 HSTS 头防止降级攻击
JWT secret 从环境变量注入——绝不写代码、绝不提交 Git,长度 ≥ 32 字节随机
access token 短期(15-30 分钟) + refresh token 长期(7-30 天)——access 泄露影响时间窗小,refresh 用一次轮换一次
refresh token 一次性使用——验证后立即撤销旧的,防重放
密码用 BCrypt/Argon2 单向 hash——不用 MD5/SHA-1,可逆编码明文存储是灾难
关键操作(支付/转账/删数据)二次验证——短期 token + 短信/邮箱 OTP
接口幂等性——所有 POST/PUT/DELETE 用 Idempotency-Key 请求头
限流 + 风控——同 IP 短时间高频访问、跨用户访问、未登录接口的限流,缺一不可
审计日志——登录/登出/权限变更/关键操作全记录,包含 userId / IP / 时间 / 设备指纹
告警规则——同一账号 5 分钟内 5 次失败登录、同一 IP 1 分钟 100 次未授权访问,自动告警
JWT 黑名单——支持"踢人下线"功能(在 Redis 维护短黑名单,验签前先查)
定期安全扫描——用 dependency-check / trivy 扫依赖漏洞,用 OWASP ZAP 做渗透测试,至少季度一次

📌 实践:12 条铁律的优先级

P0 必做:#1 HTTPS、#2 secret 安全、#3 双 token、#5 密码 hash、#8 限流

P1 应该做:#4 一次性 refresh、#6 二次验证、#7 幂等、#9 审计

P2 锦上添花:#10 告警、#11 黑名单、#12 扫描

12 条全做 = 顶级安全团队水平,只做 P0 = 不会出大事故。

🛑 误区:“用了 sa-token 就安全了”

框架只是"工具",安全 = 框架 + 配置 + 业务逻辑 + 运维。见过有团队:

配了 sa-token 但 secret 写在 yml 里—— Git 泄露 = 整个认证系统报废

用 sa-token 但所有接口 @SaCheckLogin 都不加—— 框架等于没装

access token 设了 30 天过期—— 等同于把安全押在"token 不泄露"上

没审计日志—— 出事找不到攻击者是谁、从哪来、干了什么

框架是必要条件,不是充分条件。安全的 80% 在于"对细节的偏执"。

6.13 上线前 24 小时 Checklist

把 12 条铁律浓缩成 8 步上线 checklist,贴在工位上:

步骤	检查项	通过条件
1	HTTPS 证书	证书有效期 > 30 天;TLS 1.3 已启用;HSTS 头已加
2	密钥管理	JWT secret 从环境变量注入(非代码);KMS 已对接
3	密码存储	DB 抽查 10 个用户,密码字段都是 bcrypt/argon2 格式(以 $2a$ 开头)
4	token 过期	access ≤ 30 分钟,refresh ≤ 30 天;refresh 一次性轮换
5	风控规则	5 分钟 5 次失败登录告警已配;1 分钟 100 次未授权访问告警已配
6	审计日志	登录/登出/权限变更/支付操作都有 userId+IP+时间戳记录
7	依赖扫描	trivy / dependency-check 扫描,Critical/High 漏洞 = 0
8	渗透测试	OWASP ZAP 自动化扫描通过;至少 1 个手工渗透测试 case 通过

8 步全过 = 可上线。任何一步不过,延期上线——安全债比延期代价大 10 倍。

6.14 写在最后:认证的本质是信任

写完这 12 条铁律 + 8 步 checklist,回头看,认证体系的本质其实就一句话——在不可信的环境里,建立"我信他"的机制。密码学给了我们"防偷看、防篡改"的工具,JWT/sa-token/Spring Security 给了我们"易用的工程实现",但真正的安全不靠工具,靠"对每个细节都不放过"的偏执。生产环境上踩过的每一个坑,都是这套偏执的一部分。把这篇里的 11 个概念 + 2 套二选一方案 + 6 段实战代码 + 14 条铁律吃透,基本能应付 90% 的微服务认证场景。剩下的 10%,靠实战中慢慢补。

收尾:本篇要点 + 系列承上启下

✍️ 本篇核心结论:

认证体系 4 层 11 概念——密码学 → JWT → 框架(2 选 1)→ 生产机制
密码学是地基——对称加密(快) + 非对称加密(密钥交换) + 数字签名(防篡改) + HTTPS(集大成)
JWT 是凭证格式,不是完整方案——必须配合双 token、refresh 轮换、HTTPS
Spring Security 与 sa-token 二选一——中小项目选 sa-token(开发快),复杂 RBAC 选 Spring Security(可扩展)
双 Token + SSO + Gateway 是生产三件套——缺一不可,组合在一起才算"统一认证"
12 条铁律——P0 必做 5 条(安全下限),P1 应该做 4 条(生产标准),P2 锦上添花 3 条(顶级)

📚 Java 微服务系列地图:

#	主题	关系
1	异地多活	架构总纲
2	流量调度(Nginx/LVS)	外部入口
4	技术选型(SCA + Dubbo3)	选型总结
5	Nacos	服务发现 + 配置
6	Spring Cloud Gateway	应用网关
7	本篇认证授权	统一认证中心
8	消息队列	异步解耦
9	熔断限流 Sentinel	流量治理
10	监控与日志	可观测性

📖 参考资料:

JWT 官方 RFC 7519
Spring Security 官方文档
sa-token 官方文档
RFC 8446: TLS 1.3 协议规范
OWASP Authentication Cheat Sheet
NIST SP 800-63B: 数字身份指南
OAuth 2.0 授权框架 RFC 6749
OIDC Core 1.0 规范
《Java 核心技术》第 11 章 - 集合、附录 - 密码学基础
《Spring 实战》第 11 章 - Spring Security
《深入理解 Java 虚拟机》第 12 章 - Java 密码学架构(JCA)
Spring Cloud Gateway OAuth2 集成
Cloudflare HTTPS 最佳实践
Auth0 认证架构白皮书

下一篇:《消息队列：从 Kafka 到 RocketMQ,Java 微服务的异步解耦与最终一致性》——认证授权只是"谁来访问",访问之后系统怎么扛住流量、看事件驱动架构怎么落地。

Spring Cloud Gateway：微服务流量的"中央调度官"

Tue, 09 Jun 2026 00:00:00 +0000

Spring Cloud Gateway：微服务流量的"中央调度官"

Java Web 微服务系列 · 第 6 篇 · Spring Cloud Gateway 阅读时长：约 26 分钟本文写于 2026 年 6 月

引子：一次失败的发布让我们重新认识网关

2024 年下半年，我所在的团队做了一次"看似无害"的微服务重构——把原本单体应用里的 4 个核心业务模块拆成独立的 Spring Boot 服务，部署到 K8s 集群。架构图画得漂亮，CI/CD 流水线拉通，灰度发布、回滚机制一应俱全。

上线第一周就出事了。

凌晨 3 点，监控告警群炸了：所有下游服务的连接数（connection count）瞬间打满。我们 4 个服务，每个 50 个 Pod，一共有 200 个 Pod 收到了 20 倍的正常流量。日志翻出来一看——有个调用方在重试机制里写错了，所有失败的请求都被无限重试，而且重试时没有回退到服务名，而是打到了具体 Pod IP。

更糟糕的是：我们在网关层只做了"路径转发"，没有任何限流、熔断、重试隔离。结果 200 个 Pod 直接雪崩，全站不可用 23 分钟。

事后复盘，CTO 在会上问了一个让我记忆深刻的问题：

“我们的网关到底在做什么？”

我答不上来。

那天晚上我回家翻 Spring Cloud Gateway 官方文档，从头读到尾。我意识到我们之前对网关的理解是错的——网关不是"路径转发器"，网关是"微服务的中央调度官"。它该做的事情至少包括：统一鉴权、流量限流、熔断降级、灰度发布、日志追踪、监控告警。

第二天开始动手把网关从"路径转发器"升级成"流量调度官"——限流、熔断、灰度、鉴权、日志、监控一应俱全。这次我把它整理成一篇博客，从技术选型到核心类，从常用模块到实战配置，一次讲透。

下面是我踩过的所有坑。

那天之后我成了团队里的"网关布道师"，每次新项目立项都先过网关设计。我意识到：网关不是"装上去就行了"的基础设施，是要持续投入运维的核心组件。规则、路由、限流、熔断，都要随业务演进动态调整——网关是活的系统，不是死的配置。

一、技术选型：为什么是 Spring Cloud Gateway

1.1 答案（拿分版）

微服务网关的选型，核心是看四件事：性能、协议支持、生态集成、团队熟悉度。 在 Java 技术栈里，Spring Cloud Gateway 是当下最优解——它基于 Reactor Netty 实现响应式编程，性能是 Zuul 1.x 的 1.6 倍；深度集成 Spring Cloud 生态（Nacos / Sentinel / Sleuth / Config 都能无缝对接）；Java 团队几乎零学习成本，会写 Spring Boot 就上手。

1.2 横向对比：六大网关候选

网关	编程模型	性能	协议支持	生态	适用场景
Spring Cloud Gateway	Reactor（响应式）	★★★★★	HTTP/HTTPS/WebSocket/gRPC	Spring 全家桶	Java 微服务首选
Zuul 1.x	Servlet（阻塞）	★★★	HTTP	Netflix OSS	维护期，不推荐新项目
Zuul 2.x	Netty（异步）	★★★★	HTTP	Netflix OSS	文档少，Spring 集成弱
Nginx + OpenResty	Lua/事件循环	★★★★★	HTTP/TCP/UDP	第三方模块	边缘网关 / 静态资源
Kong	OpenResty + Lua	★★★★★	HTTP/gRPC	插件生态	多语言混合架构
APISIX	OpenResty + Lua	★★★★★	HTTP/gRPC/物联网	Apache 顶级	云原生 / 多协议

结论：

纯 Java 微服务 → Spring Cloud Gateway（生态、性能、团队成本最优）
多语言混合（Java + Go + Python）→ Kong 或 APISIX（中立网关，插件丰富）
边缘入口（SSL 卸载、静态资源、CDN 协同）→ Nginx / OpenResty
遗留 Zuul 1.x → 升级到 Spring Cloud Gateway

1.3 Zuul → Gateway：Spring 为何换帅

2018 年 Netflix 宣布 Zuul 1.x 进入维护期，Spring Cloud 团队开始自研网关。核心原因有三点：

编程模型代际差：Zuul 1.x 基于 Servlet，每请求一线程，并发 1000 就要 1000 个线程，线程上下文切换开销巨大。Spring Cloud Gateway 基于 Reactor Netty，少量线程通过事件循环处理数万并发。
生态集成：Zuul 是 Netflix OSS 的一员，和 Spring Cloud 其他组件（Nacos / Sentinel / Config）整合需要胶水代码。Spring Cloud Gateway 是 Spring 亲儿子，开箱即用。
动态路由：Zuul 改路由要重启，Spring Cloud Gateway 支持运行时动态刷新（结合 Nacos）。

时间线：

1
2
3
4
5
6
7


2014 Zuul 1.x 诞生（Netflix OSS 标杆）
2018 Netflix 宣布 Zuul 1.x 维护，推荐 Resilience4j
2017 Spring Cloud Gateway 立项
2019 Spring Cloud Gateway 2.1 GA（生产可用）
2022 Spring Cloud Gateway 3.1（基于 Spring Boot 3.0，WebFlux + Reactor Netty）
2024 Spring Cloud Gateway 4.0（响应式 API 全面稳定）
2026 Spring Cloud Gateway 主流选择（Z

💡 原理：响应式 vs 阻塞模型

Zuul 1.x 基于 Servlet，每个请求独占一个线程。并发 1000 请求 = 1000 个线程，每个线程默认占 1MB 栈空间，1GB 内存被线程栈吃光。

Spring Cloud Gateway 基于 Reactor Netty，少量线程（默认 = CPU 核数 × 2）通过事件循环处理数万并发连接。单线程可处理 10000+ 并发，内存占用降一个数量级。

类比：阻塞模型 = 1 个服务员服务 1 桌客人；响应式 = 1 个服务员服务 N 桌客人（客人点完单他就去服务下一桌）。

1.4 Spring Cloud Gateway 的三大核心特性

Route（路由）：定义"什么请求 → 转发到哪"
Predicate（断言）：判断"这个请求匹不匹配这条路由"
Filter（过滤器）：在转发前后做"鉴权、限流、修改请求/响应"

三剑客的关系：Predicate 决定请求走哪条路由，Filter 决定请求在路由上做什么处理。

1.5 一个反直觉的事实：网关不是越复杂越好

很多团队第一次上 Gateway 容易"过度设计"——把所有鉴权、限流、灰度、监控全堆在 Gateway，结果 Gateway 成了新的单点瓶颈。

正确分层：

层	关注点	例子
边缘网关（Nginx）	SSL 卸载、CC 攻击、静态资源	100 万 QPS 也能扛
业务网关（Spring Cloud Gateway）	鉴权、限流、路由	5 万 QPS 以内
业务服务	业务逻辑	1 万 QPS 以内
数据层	读写分离、分库分表	—

经验法则：Gateway 只做"横向能力"（鉴权、限流、灰度），不做"业务逻辑"（订单处理、用户管理）。业务逻辑下沉到下游服务，Gateway 保持轻量。

📌 实践：什么时候用 Spring Cloud Gateway？

✅ Java 微服务架构，服务数 ≥ 5 个

✅ 需要 统一鉴权 / 限流 / 灰度

✅ 需要 WebSocket / gRPC 协议透传

✅ 团队熟悉 Spring 生态

❌ 单一服务、单一入口 → 上 Nginx 就够了

❌ 多语言架构 → 上 Kong / APISIX

二、核心类：把"三剑客"扒到底层

2.1 答案（拿分版）

Spring Cloud Gateway 的内核只有三个核心接口：RouteLocator、Predicate、GatewayFilter。 所有高级特性（动态路由、限流、熔断）都是在这三个接口上的实现。理解了这三个接口，就理解了 Gateway 80% 的设计思想。剩下的 20% 是 RouteDefinitionLocator（路由定义定位器），用于动态路由场景。

2.2 三大核心接口

2.2.1 `Route` —— 路由定义

1
2
3
4
5
6
7
8


public class Route implements Ordered {
 private final String id;
 private final URI uri; // 目标地址
 private final int order;
 private final AsyncPredicate<ServerWebExchange> predicate; // 断言
 private final List<GatewayFilter> filters; // 过滤器
 private final Map<String, Object> metadata;
}

关键字段：

id：路由唯一标识
uri：目标地址（http:// 固定地址 / lb://service-name 服务发现 / ws:// WebSocket）
predicate：匹配条件（注意是 AsyncPredicate 不是 Predicate——支持异步匹配）
filters：过滤器链

2.2.2 `Predicate` —— 断言匹配

Gateway 内置 11 个 Predicate 工厂（PathRoutePredicateFactory、MethodRoutePredicateFactory 等），全部实现 RoutePredicateFactory<C> 接口。源码在 org.springframework.cloud.gateway.handler.predicate 包。

1
2
3
4
5


@FunctionalInterface
public interface RoutePredicateFactory<C> extends ShortcutConfigurable, Configurable<C> {
 Predicate<ServerWebExchange> apply(C config);
 default String name() { return ... }
}

谓词的本质：返回一个 Predicate<ServerWebExchange>，对每个请求做 test() 判断，true → 命中路由。

为什么有"工厂"模式？因为每个 Predicate 需要带配置参数（如 Path=/api/order/** 里的路径）。工厂模式让"配置类 + 应用逻辑"解耦。

2.2.3 `GatewayFilter` —— 过滤器

1
2
3


public interface GatewayFilter {
 Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
}

两种过滤器：

GatewayFilterFactory：路由级别的过滤器（写在 yml 的 filters 下，只对当前路由生效）
GlobalFilter：全局过滤器（实现 GlobalFilter 接口，对所有路由生效）

执行顺序：

1
2


请求进入 → GlobalFilter.order(升序) → GatewayFilter → 路由到下游
 ← GatewayFilter ← GlobalFilter.order(降序) ← 下游响应

chain.filter(exchange) 之前的代码 = pre-filter（请求处理前） chain.filter(exchange) 之后的代码 = post-filter（响应处理后）

2.3 路由定位器：`RouteDefinitionLocator` 全家桶

1
2
3


public interface RouteDefinitionLocator {
 Flux<RouteDefinition> getRouteDefinitions();
}

4 个核心实现（用于动态路由）：

实现类	作用	场景
`InMemoryRouteDefinitionRepository`	内存存储	默认实现，重启丢路由
`PropertiesRouteDefinitionLocator`	读取 `application.yml`	静态路由
`DiscoveryClientRouteDefinitionLocator`	从注册中心读取	集成 Nacos / Eureka
`NacosRouteDefinitionRepository`	自定义写 Nacos 持久化	生产推荐：动态路由

RouteDefinition → Route 的转换由 RouteDefinitionRouteLocator 完成。这条转换链是动态路由的核心——只要能拉取到 RouteDefinition，Gateway 就能转成 Route 生效。

💡 原理：动态路由的关键

Spring Cloud Gateway 启动时通过 RouteDefinitionRouteLocator 把 RouteDefinition 转成 Route 对象。动态路由的本质是定时从外部存储（DB / Nacos / Redis）拉取 RouteDefinition 列表，刷新内存中的路由缓存。这就是为什么生产环境一定要用 NacosRouteDefinitionRepository 而不是 yml。

2.4 三个核心接口的协作流程

1
2
3
4
5
6
7
8
9


HTTP Request
 ↓
[RoutePredicateHandlerMapping] ← 用 Predicate 匹配 Route
 ↓
[FilteringWebHandler] ← 装载 GatewayFilter + GlobalFilter
 ↓
[NettyRoutingFilter] ← Reactor Netty 转发到下游
 ↓
HTTP Response

关键设计：响应式全链路。从 Predicate 到 Filter 到转发，全程 Mono/Flux，没有任何阻塞调用。

2.5 高级接口：`GatewayFilterFactory` 的扩展点

AbstractGatewayFilterFactory<C> 是所有内置 Filter 的父类。自定义 Filter 只需要继承它：

 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


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

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

 @Override
 public GatewayFilter apply(Config config) {
 return (exchange, chain) -> {
 // pre 逻辑
 ServerHttpRequest mutated = exchange.getRequest().mutate()
 .header(config.getName(), config.getValue())
 .build();
 return chain.filter(exchange.mutate().request(mutated).build());
 };
 }

 public static class Config {
 private String name;
 private String value;
 // getter/setter
 }
}

使用方式：

1
2
3
4
5


filters:
 - name: CustomHeader
 args:
 name: X-Source
 value: my-gateway

🎯 避坑：自定义 Filter 时的 3 个易错点

不调用 chain.filter(exchange) → 请求卡住，超时

修改 ServerHttpRequest 后没 mutate() → 改了原对象（ServerHttpRequest 不可变）

在 Filter 里写阻塞代码 → 整个事件循环卡死

2.6 `Route` 的 order 字段：路由优先级

Route 还有一个常被忽略的字段 order，控制多条路由同时匹配时哪条优先：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


spring:
 cloud:
 gateway:
 routes:
 - id: order_route_v2_gray
 uri: lb://order-svc-v2
 order: 0 # 数字越小越优先
 predicates:
 - Path=/api/order/**
 - Header=X-Gray-Tag, beta
 - id: order_route_default
 uri: lb://order-svc-v1
 order: 100
 predicates:
 - Path=/api/order/**

执行顺序：v2_gray 优先匹配（order=0），命中灰度 Header 走 v2；其他走 v1（order=100）。

生产经验：灰度路由 order 设小，兜底路由 order 设大；两者差值至少 50，方便后续插入中间版本。

2.7 Predicate 短路优化

Gateway 的 Predicate 是短路求值——第一个不满足就不继续。比如：

1
2
3
4


predicates:
 - Path=/api/order/**  # 先匹配路径（便宜）
 - Method=GET,POST  # 再匹配方法（便宜）
 - Header=X-Token, \w+  # 最后匹配头（需要正则）

调优技巧：便宜的断言放前面，贵的（如正则）放后面。Path 是最快的（字符串比较），Header 需要正则解析，最慢。

💡 原理：Predicate 的执行顺序

Gateway 内部把 Route 的所有 Predicate 包装成 Predicate<ServerWebExchange> 链。命中顺序是按 yml 配置顺序短路求值——所以你写的第一个 Predicate 一定先执行。

三、常用模块：11 个 Predicate + 30+ Filter 一网打尽

3.1 答案（拿分版）

Gateway 的"常用模块"分四类：路由断言、过滤器工厂、全局过滤器、生态集成。 生产环境必装的是 Path + Method + Header 三个断言、StripPrefix + AddRequestHeader 两个过滤器、以及一个 GlobalFilter 做统一鉴权。掌握这 6 个配置项，就能覆盖 80% 的业务场景。剩下的 20% 来自 Sentinel 限流、Hystrix/Resilience4j 熔断、Prometheus 监控这三个生态集成。

3.2 11 个内置 Predicate 工厂

Predicate	用途	示例
`Path`	路径匹配	`Path=/api/order/**`
`Method`	HTTP 方法	`Method=GET,POST`
`Header`	请求头	`Header=X-Token, \d+`
`Query`	查询参数	`Query=token, \w+`
`Host`	域名	`Host=**.example.com`
`Cookie`	Cookie	`Cookie=session, \w+`
`After` / `Before` / `Between`	时间窗口	`After=2026-01-01T00:00:00+08:00`
`RemoteAddr`	IP 段	`RemoteAddr=192.168.1.0/24`
`Weight`	权重路由	`Weight=order-svc, 80`
`CloudFoundryRoute`	CF 平台	（云平台专用）

Predicate 组合是 AND 关系——一条路由的所有 Predicate 都为 true，请求才命中。

示例：组合 Predicate

1
2
3
4
5
6


predicates:
 - Path=/api/order/**
 - Method=GET,POST
 - Header=X-Tenant, [a-zA-Z0-9_]+
 - After=2026-01-01T00:00:00+08:00
 - RemoteAddr=192.168.0.0/16

含义：/api/order/** 的 GET/POST 请求，必须带 X-Tenant 头（字母数字下划线），从 2026-01-01 起，且来自内网 IP。

3.3 30+ 内置 GatewayFilter 工厂

按功能分 6 大类：

（1）路径处理

Filter	作用	示例
`StripPrefix=1`	去掉路径前缀 1 段	`/api/order/list` → `/list`
`PrefixPath=/api`	加前缀	`/user/list` → `/api/user/list`
`SetPath=/order/{segment}`	重写路径	`/api/o/123` → `/order/123`

（2）请求头 / 响应头

Filter	作用
`AddRequestHeader=X-Source, gateway`	加请求头
`AddResponseHeader=X-Trace-Id, ...`	加响应头
`RemoveRequestHeader=Cookie`	删请求头

（3）参数处理

Filter	作用
`AddRequestParameter=source, web`	加查询参数
`SetQueryString=foo=bar`	重写查询串

（4）重定向 / 状态码

Filter	作用
`RedirectTo=302, https://...`	重定向
`SetStatus=401`	改状态码

（5）限流 / 熔断（需额外依赖）

Filter	作用
`RequestRateLimiter`	Redis 令牌桶限流
`CircuitBreaker`	集成 Hystrix / Sentinel / Resilience4j

（6）其他

Filter	作用
`Retry=3`	重试 3 次
`Hystrix`	熔断（已不推荐）
`SaveSession`	WebFlux Session
`SecureHeaders`	安全响应头
`PreserveHostHeader`	保留原始 Host
`DedupeResponseHeader`	去重响应头

3.4 GlobalFilter：4 个最常用实现

GlobalFilter 对所有路由生效，用 @Component 注册即可。

GlobalFilter	作用	适用场景
自定义鉴权	校验 JWT / Token	所有需要登录的接口
统一日志	记录 request/response	全链路追踪
跨域处理	CORS 配置	前后端分离
限流	Redis 令牌桶	防止突发流量

🎯 避坑：GlobalFilter 注册顺序

@Order 数字越小，越早执行。鉴权 GlobalFilter 必须在限流/日志之前，否则会先限流再鉴权，导致未鉴权用户触发限流统计的脏数据。

推荐顺序：

SecurityFilter 鉴权（@Order(-100)）

RequestLogFilter 日志（@Order(-50)）

RateLimitFilter 限流（@Order(0)）

业务 GlobalFilter

3.5 生态集成：从单网关到微服务流量平台

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 ┌──────────────────────────────────────┐
 │ Spring Cloud Gateway │
 │ ┌──────────┐ ┌──────────────────┐ │
 │ │ 路由动态 │ │ 限流/熔断/降级 │ │
 │ │ Nacos │ │ Sentinel / Hystrix│ │
 │ └──────────┘ └──────────────────┘ │
 │ ┌──────────┐ ┌──────────────────┐ │
 │ │ 服务发现 │ │ 链路追踪 │ │
 │ │ Nacos │ │ Sleuth + Zipkin │ │
 │ └──────────┘ └──────────────────┘ │
 │ ┌──────────┐ ┌──────────────────┐ │
 │ │ 配置中心 │ │ 监控告警 │ │
 │ │ Nacos │ │ Actuator + Prom │ │
 │ └──────────┘ └──────────────────┘ │
 └──────────────────────────────────────┘

生产推荐组合：

服务发现：Nacos（性能优于 Eureka，自带配置中心）
限流熔断：Sentinel（阿里出品，规则可动态推送，优于 Hystrix）
链路追踪：Micrometer Tracing + Zipkin（Sleuth 已弃用）
配置中心：Nacos（路由规则 / 限流规则持久化）
监控告警：Actuator + Prometheus + Grafana

📌 实践：为什么 Sentinel 替代 Hystrix？

Hystrix 2018 年宣布停更，官方推荐用 Resilience4j 或 Sentinel。Sentinel 的核心优势是规则可动态推送——网关限流阈值调整不用重启服务，Nacos 一推即生效。Hystrix 只能改配置重启。

此外 Sentinel 还有：

流量染色：按用户/接口打标，灰度路由

系统自适应限流：根据 CPU / Load 自动降级

热点参数限流：识别高频参数（如秒杀商品 ID）单独限流

3.6 11 个 Predicate 详细使用场景

生产中最常用的 5 个断言（覆盖 90% 场景）：

Predicate	真实场景	示例
`Path`	路由分流	`/api/order/**` → order-svc
`Method`	读写分离	`Method=GET,POST`（部分服务只接 GET）
`Header`	灰度发布	`Header=X-Gray-Tag, beta`
`Query`	鉴权 token 透传	`Query=token, \w+`
`RemoteAddr`	内网/外网分流	`RemoteAddr=10.0.0.0/8`（仅内网）

不常用但有特殊价值的 3 个断言：

Predicate	场景
`After` / `Before`	限时活动（“双 11 凌晨 0 点开始”）
`Cookie`	灰度按用户固定分组（带 cookie 不变）
`Weight`	A/B 测试（按流量比例分流）

示例：限时活动 Predicate

1
2
3
4


predicates:
 - Path=/api/promo/**
 - After=2026-11-11T00:00:00+08:00  # 11.11 凌晨 0 点后生效
 - Before=2026-11-11T23:59:59+08:00  # 11.11 当天 24 点失效

3.7 GatewayFilter 工厂的"链式调用"模式

Gateway 的多个 Filter 按 yml 顺序组成链式调用。重要：每个 Filter 的 chain.filter(exchange) 之前是 pre、之后是 post：

1
2
3
4
5
6
7


filters:
 - StripPrefix=1 # pre: 去掉路径前缀
 - AddRequestHeader=X-Trace, abc123 # pre: 加请求头
 - name: Retry
 args: { retries: 3 } # pre: 准备重试
 - name: CircuitBreaker # pre: 熔断器包装
 args: { name: orderCB }

执行流程：

1
2


请求进入 → StripPrefix(pre) → AddRequestHeader(pre) → Retry(pre) → CircuitBreaker(pre) → 下游服务
 ← StripPrefix(post) ← AddRequestHeader(post) ← Retry(post) ← CircuitBreaker(post) ← 下游响应

调优原则：pre 阶段做"请求处理"（鉴权、加头、限流）；post 阶段做"响应处理"（加响应头、统计耗时）。

🎯 避坑：Filter 顺序的 2 个常见错误

StripPrefix 放在 AddRequestHeader 之后 → AddRequestHeader 引用了 strip 前的路径，调试时找不到头在哪加的

Retry 放在 RequestRateLimiter 之前 → 限流计数时 Retry 重试的请求会算多次，限流阈值要相应调大

四、实战：从 yml 到 Java DSL，从单体 Filter 到灰度发布

4.1 答案（拿分版）

Gateway 的实战分四步：yml 写简单路由 → Java DSL 写复杂路由 → 自定义 GlobalFilter 做鉴权 → 加灰度发布 Header 走灰度。 掌握这 4 步，从 demo 到生产只用 2 小时。核心是：路由配置用 yml 起步、业务逻辑用 GlobalFilter 注入、动态配置用 Nacos 持久化。

4.2 第一步：yml 简单路由

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


spring:
 cloud:
 gateway:
 routes:
 - id: order_route
 uri: lb://order-svc
 predicates:
 - Path=/api/order/**
 - Method=GET,POST
 filters:
 - StripPrefix=2  # /api/order/list -> /list
 - AddRequestHeader=X-Source, gateway

含义：/api/order/** 的 GET/POST 请求，去掉前 2 段路径（/api/order），转发到 order-svc 服务，并加 X-Source: gateway 请求头。

lb:// 前缀：表示走服务发现（LoadBalancer），从 Nacos 拉取 order-svc 的实例列表，做负载均衡。

4.3 第二步：Java DSL 编程式路由

复杂路由用 yml 写不直观，改用 Java DSL：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
 return builder.routes()
 .route("user_route", r -> r
 .path("/api/user/**")
 .and().method("GET")
 .and().header("X-Tenant", "[a-z]+")
 .filters(f -> f
 .stripPrefix(2)
 .addRequestHeader("X-Source", "gateway")
 .retry(3)
 )
 .uri("lb://user-svc"))
 .build();
}

Java DSL 的优势：可加判断逻辑（从 DB / 配置中心读路由参数），适合动态路由场景。

实战场景：根据租户 ID 决定转发到不同集群。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@Bean
public RouteLocator tenantRouteLocator(RouteLocatorBuilder builder,
 TenantConfigService tenantConfig) {
 return builder.routes()
 .route(r -> r
 .path("/api/**")
 .filters(f -> f
 .filter((exchange, chain) -> {
 String tenant = exchange.getRequest().getHeaders()
 .getFirst("X-Tenant");
 String prefix = tenantConfig.getPrefix(tenant);
 // 动态修改 uri
 return chain.filter(exchange.mutate()
 .request(exchange.getRequest().mutate()
 .header("X-Cluster", prefix).build())
 .build());
 }))
 .uri("lb://" + tenantConfig.getDefaultCluster()))
 .build();
}

4.4 第三步：自定义 GlobalFilter（登录校验示例）

 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


@Component
@Order(1) // 数字越小越早执行
public class AuthGlobalFilter implements GlobalFilter {
 @Override
 public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
 ServerHttpRequest request = exchange.getRequest();
 String path = request.getURI().getPath();

 // 1. 白名单直接放行
 if (path.startsWith("/api/public/")) {
 return chain.filter(exchange);
 }

 // 2. 校验 Token
 String token = request.getHeaders().getFirst("Authorization");
 if (token == null || !token.startsWith("Bearer ")) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.UNAUTHORIZED);
 return response.writeWith(Mono.just(
 response.bufferFactory().wrap("{\"code\":401,\"msg\":\"未登录\"}".getBytes())
 ));
 }

 // 3. 解析 Token，将 userId 透传到下游
 String userId = JwtUtil.parseUserId(token);
 ServerHttpRequest mutated = request.mutate()
 .header("X-User-Id", userId)
 .build();
 return chain.filter(exchange.mutate().request(mutated).build());
 }
}

关键点：

exchange.mutate() 修改后必须 chain.filter() 透传
状态码/响应体在 GlobalFilter 里直接 writeWith 即可中断链路
@Order(1) 数字越小越早执行，鉴权必须最先

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


spring:
 cloud:
 gateway:
 routes:
 - id: order_route_v1
 uri: lb://order-svc-v1
 predicates:
 - Path=/api/order/**
 - Weight=order-svc, 90
 - id: order_route_v2
 uri: lb://order-svc-v2
 predicates:
 - Path=/api/order/**
 - Weight=order-svc, 10

升级灰度：v1 占 90% 流量，v2 占 10%。逐步调高 v2 权重到 100%，灰度完成。

更精细的灰度：基于 Header 指定版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


spring:
 cloud:
 gateway:
 routes:
 - id: order_route_gray
 uri: lb://order-svc-v2
 predicates:
 - Path=/api/order/**
 - Header=X-Gray-Tag, beta
 - id: order_route_default
 uri: lb://order-svc-v1
 predicates:
 - Path=/api/order/**

测试人员带 X-Gray-Tag: beta 头走 v2，普通用户走 v1。

🛑 误区：灰度发布的 3 个常见错误

用 Cookie / Session 做灰度 → 用户关浏览器重新打开就走错版本

灰度路由不带版本号 → 紧急回滚时不知道切哪个

灰度期间不监控错误率 → 上线 5% 流量已经报错，迟迟没发现

正确做法：用 Header=X-Gray-Tag, beta 做灰度，灰度路由命名带 _gray 后缀，监控 5xx 错误率超过阈值自动回滚。

4.6 第五步：全局异常处理（`ErrorWebExceptionHandler`）

Gateway 抛异常时（如路由找不到、限流拒绝），默认返回 500 + 空白页面。生产环境必须自定义错误响应：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@Component
@Order(-1)
public class JsonErrorWebExceptionHandler implements ErrorWebExceptionHandler {

 @Override
 public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.OK); // 统一 200
 response.getHeaders().setContentType(MediaType.APPLICATION_JSON);

 Map<String, Object> body = new HashMap<>();
 body.put("code", 500);
 body.put("msg", ex.getMessage());
 body.put("path", exchange.getRequest().getPath().value());

 try {
 byte[] bytes = new ObjectMapper().writeValueAsBytes(body);
 return response.writeWith(Mono.just(response.bufferFactory().wrap(bytes)));
 } catch (Exception e) {
 return Mono.error(e);
 }
 }
}

效果：所有异常返回 JSON {code, msg, path}，前端可解析。

4.7 自定义 Predicate 实战（按租户分流）

内置 Predicate 不够用时，自定义 Predicate 是终极武器。实现 RoutePredicateFactory<MyConfig> 接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


@Component
public class TenantRoutePredicateFactory
 extends AbstractRoutePredicateFactory<TenantRoutePredicateFactory.Config> {

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

 @Override
 public Predicate<ServerWebExchange> apply(Config config) {
 return exchange -> {
 String tenant = exchange.getRequest().getHeaders()
 .getFirst(config.getHeaderName());
 // 命中租户白名单
 return config.getAllowedTenants().contains(tenant);
 };
 }

 @Data
 public static class Config {
 private String headerName = "X-Tenant";
 private List<String> allowedTenants;
 }
}

使用方式（yml）：

1
2
3
4
5
6
7


predicates:
 - name: Tenant
 args:
 headerName: X-Tenant
 allowedTenants:
 - tenant-a
 - tenant-b

实战场景：多租户 SaaS 平台，按租户 ID 决定请求走哪个集群。

4.8 网关压力测试（用 wrk）

生产前必跑压力测试。wrk 是 Linux 高性能 HTTP 压测工具：

1
2
3
4
5


# 安装 wrk（Ubuntu）
sudo apt install wrk

# 压测网关：100 并发，持续 30 秒
wrk -t4 -c100 -d30s --latency http://gateway:8080/api/order/list

关键指标：

指标	含义	健康阈值
`Latency Distribution 50%`	中位数延迟	< 50ms
`Latency Distribution 99%`	99 分位延迟	< 200ms
`Requests/sec`	QPS	≥ 预期峰值 1.5 倍
`Socket errors`	套接字错误	0

生产经验：网关压测必须用真实下游服务 mock（如 wiremock），不能直接压空 Gateway——否则延迟全在下游。

📌 实践：网关压测 3 个关键点

冷启动要算——前 1000 个请求延迟偏高（Netty 启动、类加载），生产要预热

限流要测——故意打超限流阈值，看 Gateway 是否正确返回 429

熔断要测——下游 mock 故意 5xx，看 Gateway 是否触发熔断

阿里云 AHAS 提供了专业的网关压测服务（ahas-console），生产级项目推荐。

五、配置：从 CORS 到限流，从超时到监控

5.1 答案（拿分版）

Gateway 的"必配"配置有 5 项：CORS 跨域、连接超时、限流、熔断、监控。 漏配任何一项都可能引发生产事故——CORS 不配，前端调不通；超时不配，慢调用拖垮网关；限流不配，雪崩；熔断不配，单服务故障扩散全站；监控不配，出了事不知道。

5.2 CORS 跨域完整配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


spring:
 cloud:
 gateway:
 globalcors:
 cors-configurations:
 '[/**]':
 allowedOriginPatterns: "*"
 allowedMethods: "*"
 allowedHeaders: "*"
 allowCredentials: true
 maxAge: 3600

🎯 避坑：allowCredentials: true + allowedOrigins: * 会报错

必须改成 allowedOriginPatterns: "*"（Spring Boot 2.4+ 才支持）。这是初学者最常踩的坑。

5.3 超时与重试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


spring:
 cloud:
 gateway:
 httpclient:
 connect-timeout: 1000 # 连接超时 1s
 response-timeout: 5s  # 响应超时 5s
 routes:
 - id: order_route
 uri: lb://order-svc
 predicates:
 - Path=/api/order/**
 filters:
 - name: Retry
 args:
 retries: 3
 statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
 methods: GET,POST
 backoff:
 firstBackoff: 50ms
 maxBackoff: 500ms
 factor: 2

生产经验：

connect-timeout: 1s、response-timeout: 5s 是大多数场景的安全值
重试只对幂等接口开（GET），POST 重试可能产生重复订单
重试配合 backoff 指数退避，避免雪崩

5.4 限流（内置 Redis 令牌桶）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


spring:
 cloud:
 gateway:
 routes:
 - id: order_route
 uri: lb://order-svc
 predicates:
 - Path=/api/order/**
 filters:
 - name: RequestRateLimiter
 args:
 redis-rate-limiter.replenishRate: 100 # 每秒 100 个令牌
 redis-rate-limiter.burstCapacity: 200 # 桶容量 200
 redis-rate-limiter.requestedTokens: 1
 key-resolver: "#{@userKeyResolver}" # SpEL 表达式

KeyResolver 实现（按用户限流）：

1
2
3
4
5
6


@Bean
public KeyResolver userKeyResolver() {
 return exchange -> Mono.just(
 exchange.getRequest().getHeaders().getFirst("X-User-Id")
 );
}

📌 实践：限流算法选型

算法优点缺点适用

令牌桶平滑限流、允许突发配置稍复杂通用首选

漏桶强制匀速突发流量被截断严格流量整形

滑动窗口精确控制时间窗内存开销大短时间窗口限流

生产推荐令牌桶（replenishRate=平均QPS, burstCapacity=峰值QPS）。

5.5 熔断（集成 Sentinel）

Sentinel 是阿里出品的流量治理组件，比 Hystrix 强在规则可动态推送。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


spring:
 cloud:
 sentinel:
 transport:
 dashboard: localhost:8080  # Sentinel 控制台
 scg:
 fallback:
 mode: response
 response-status: 429
 response-body: '{"code":429,"msg":"服务降级中"}'

Sentinel 控制台配置：

资源名：order-svc:/api/order/list
熔断策略：慢调用比例（RT > 1s 的请求占比 > 50% 触发熔断）
熔断时长：10s
半开恢复：探测请求数 5

5.6 监控（Actuator + Prometheus）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


management:
 endpoints:
 web:
 exposure:
 include: health,info,gateway,prometheus
 metrics:
 tags:
 application: ${spring.application.name}
 prometheus:
 metrics:
 export:
 enabled: true

Gateway 关键指标：

指标	含义
`gateway.requests`	总请求数（带 `routeId` 标签）
`gateway.route.predicate.matched`	路由命中数
`http.client.requests`	下游 HTTP 调用（带 `uri`, `status`, `outcome`）
`jvm.memory.used`	JVM 内存使用

Grafana 仪表盘推荐：

Spring Cloud Gateway 官方仪表盘 ID: 11591
自定义 4 个核心面板：QPS、P99 延迟、5xx 错误率、限流次数

5.7 动态路由（生产推荐）

痛点：yml 路由改一次，要重启网关。10 个路由的微服务集群，每次业务变更都要重启网关 = 不可接受。

解决方案：自定义 RouteDefinitionRepository，从 Nacos 读取路由。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@Component
public class NacosRouteDefinitionRepository implements RouteDefinitionRepository {
 @Autowired
 private NacosConfigService nacosConfigService;

 @Override
 public Flux<RouteDefinition> getRouteDefinitions() {
 // 从 Nacos 拉取路由配置
 List<RouteDefinition> routes = nacosConfigService.getConfig(
 "gateway-routes", "DEFAULT_GROUP", 5000
 );
 return Flux.fromIterable(routes);
 }
}

Nacos 控制台配置：

Data ID: gateway-routes
Group: DEFAULT_GROUP
配置内容：JSON 格式的 RouteDefinition 列表

改路由：在 Nacos 控制台改 JSON，网关 5 秒内自动刷新，无需重启。

🛑 误区：动态路由的 3 个坑

不加缓存 → 每次请求都读 Nacos，性能崩盘。必须本地缓存 + 监听 Nacos 变更事件

路由变更不通知 → 改完 Nacos 没刷内存。必须监听 NacosConfigService 的 addListener

动态路由不校验 → 写错的 JSON 让 Gateway 启动失败。必须有合法 yml 兜底，动态路由加载失败时回退

5.8 完整生产配置模板

 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


server:
 port: 8080
 netty:
 connection-timeout: 30s
spring:
 application:
 name: api-gateway
 cloud:
 nacos:
 discovery:
 server-addr: nacos:8848
 gateway:
 discovery:
 locator:
 enabled: true
 lower-case-service-id: true
 globalcors:
 cors-configurations:
 '[/**]':
 allowedOriginPatterns: "*"
 allowedMethods: "*"
 allowedHeaders: "*"
 allowCredentials: true
 httpclient:
 connect-timeout: 1000
 response-timeout: 5s
management:
 endpoints:
 web:
 exposure:
 include: health,info,gateway,prometheus

5.9 网关安全配置清单

生产环境必配 6 项：

配置	作用	推荐值
`X-Frame-Options`	防点击劫持	`DENY`
`X-Content-Type-Options`	防 MIME 嗅探	`nosniff`
`Strict-Transport-Security`	强制 HTTPS	`max-age=31536000`
`Content-Security-Policy`	防 XSS	`default-src 'self'`
`Referrer-Policy`	控制 Referer	`no-referrer`
`X-XSS-Protection`	浏览器 XSS 防护	`1; mode=block`

Gateway 自带 SecureHeaders Filter，默认开启这 6 个安全头。禁用方式（不推荐）：

1
2
3
4
5
6


spring:
 cloud:
 gateway:
 filter:
 secure-headers:
 disable: "*" # 禁用所有

5.10 网关高可用部署

单点网关是灾难——网关挂了，所有流量进不来。生产必做：网关至少 2 个实例 + 负载均衡 + 健康检查。

架构：

1
2
3
4
5
6
7
8
9


 ┌──────────┐
 │ Nginx │ ← VIP / Keepalived
 └──────────┘
 ↓
 ┌────────┴────────┐
 │ │
┌──┴──┐ ┌──┴──┐
│GW-1 │ │GW-2 │ ← 至少 2 个 Spring Cloud Gateway 实例
└─────┘ └─────┘

K8s 部署（推荐）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: apps/v1
kind: Deployment
metadata:
 name: gateway
spec:
 replicas: 2 # 至少 2 副本
 template:
 spec:
 containers:
 - name: gateway
 image: gateway:1.0
 ports:
 - containerPort: 8080
 readinessProbe: # 就绪探针
 httpGet:
 path: /actuator/health
 port: 8080
 initialDelaySeconds: 30
 periodSeconds: 10

健康检查：Spring Cloud Gateway 默认带 /actuator/health，K8s 探针每 10s 查一次，不健康实例自动从 Service 摘除。

总结：一张图 + 一句话

一张图：Gateway 在微服务架构中的位置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 客户端（Web/App/小程序）
 ↓
 ┌─────────────┐
 │ Nginx │ ← SSL 卸载、静态资源、CC 攻击拦截
 └─────────────┘
 ↓
 ┌─────────────────────────────┐
 │ Spring Cloud Gateway │ ← 鉴权、限流、灰度、路由
 │ ┌────┐ ┌────┐ ┌────┐ │
 │ │Pred│→│Filt│→│Load│ │
 │ └────┘ └────┘ └────┘ │
 └─────────────────────────────┘
 ↓ ↓ ↓
 ┌────────┐ ┌────────┐ ┌────────┐
 │user-svc│ │order- │ │product-│
 │ │ │svc │ │svc │
 └────────┘ └────────┘ └────────┘

一句话总结

Spring Cloud Gateway = “路由 + 断言 + 过滤器” 三个核心接口的精妙组合。用对这三个接口，再配上限流、熔断、监控，就能在 Java 微服务架构里撑起"流量中央调度官"的角色。

选型决策树

1
2
3
4
5


需要 Java 微服务网关吗？
├─ 是 → 团队熟悉 Spring？ → Spring Cloud Gateway
│ └─ 团队熟悉 Lua？ → APISIX / Kong
├─ 边缘入口（SSL/CDN） → Nginx / OpenResty
└─ 单服务单入口 → 上 Nginx 就够了

系列下一篇预告

下一篇会写 Nacos 配置中心 + 注册中心——Gateway 的动态路由、限流规则都依赖它。

速查表：5 大场景的核心配置

场景	核心配置	文件位置
统一鉴权	`GlobalFilter` + JWT	`AuthGlobalFilter.java`
限流	`RequestRateLimiter` + Redis	`application.yml`
熔断	Sentinel 资源规则	Sentinel 控制台
灰度发布	`Header=X-Gray-Tag` + Weight	`application.yml`
动态路由	Nacos + 自定义 `RouteDefinitionRepository`	Nacos 控制台

生产清单：把这 5 件事都做了，网关才真的"中央调度官"——缺一项都是假网关。

参考资料

💡 延伸学习：响应式编程为什么快？

Spring Cloud Gateway 基于 Reactor Netty，本质是 NIO + 事件循环。

阻塞模型（Zuul 1.x）：每请求一线程，线程数 = 并发数。1000 并发 = 1000 线程，每个线程默认占 1MB 栈空间 = 1GB 内存

响应式模型（Reactor）：少量线程（= CPU 核数 × 2）通过事件循环处理数万连接，单线程可处理 10000+ 并发

类比：阻塞模型 = 1 个服务员服务 1 桌客人；响应式 = 1 个服务员服务 N 桌客人（客人点完单他就去服务下一桌）

缺点是调试复杂——堆栈不直观、阻塞代码会让整个事件循环卡死。生产中禁止在 Gateway 里写阻塞代码（JDBC / 同步 HTTP / Thread.sleep）。

服务熔断与限流：Sentinel 凭什么成为 Java 微服务的流量保险丝

Tue, 09 Jun 2026 00:00:00 +0000

服务熔断与限流：Sentinel 凭什么成为 Java 微服务的流量保险丝

Java Web 微服务系列 · 第 7 篇 · 流量治理阅读时长：约 30 分钟本文写于 2026 年 6 月

引子：一场被慢调用拖垮的秒杀

2019 年某日 10 点整，国内某电商的限时秒杀活动开放。预热阶段一切平稳，QPS 稳定在 2 万，CPU 负载 40%。开抢瞬间，QPS 飙到 18 万、库存服务的下游 Redis 集群因为热点 key 出现单节点抖动，P99 响应时间从 50ms 涨到 800ms。

接下来发生的事让 SRE 看得心惊：

库存服务的线程池被慢调用占满，开始拒绝请求
订单服务等待库存超时，自己的线程池也开始耗尽
网关服务等待订单服务超时，请求堆积，连健康检查都开始失败
健康检查失败 → 网关被剔除 → 流量打到剩余节点 → 剩余节点更快被打挂

12 分钟后，整条链路上 80% 的服务节点处于"假死"状态。研发紧急扩容 + 重启，又花了 30 分钟才把业务拉回来。事后复盘，技术总监盯着监控大盘说了一句：

“我们有限流、有熔断、有降级——三套组件，三种规则、三个控制台，真出事的时候没有一个生效。”

这就是雪崩——单点慢调用引发的全链路死亡。它不是新问题，2012 年 Netflix 就因此开源了 Hystrix；2018 年阿里把双 11 的实战经验沉淀成 Sentinel；2019 年 Hystrix 进入维护模式后，Java 生态出现了 Resilience4j vs Sentinel 的二分天下。

本文要回答两个问题：Java 微服务的流量治理工具，凭什么选 Sentinel？选了之后怎么真正用对？

一、核心概念：把术语先掰开

谈具体工具前，先把"熔断 / 限流 / 降级 / 隔离"这四个常被混用的术语定义清楚——很多线上事故的根源是团队对术语的理解不一致。

1.1 四个术语的精准定义

术语	触发条件	行为	类比
限流（Rate Limit）	QPS / 并发数超过阈值	拒绝多余请求	银行排号机
熔断（Circuit Break）	下游错误率 / 慢调用比例超阈值	短路下游调用，直接失败	电闸跳闸
降级（Fallback）	主流程异常	走兜底逻辑（缓存 / 默认值 / 异步）	备用电源
隔离（Bulkhead）	始终生效	不同业务用独立资源池，互不影响	船舱隔间

💡 原理：四者的关系

这四个概念是互补而不是替代：

限流保护自己——拦在入口，不让下游压力来

熔断保护自己——拦在出口，不让下游故障传染过来

降级保护用户体验——主流程跪了还能给用户兜底响应

隔离保护关键链路——核心业务和边缘业务用不同资源池

一套完整的流量治理方案，四者都要有。只做限流的系统遇到下游慢调用一样会死；只做熔断的系统遇到突发流量一样会死。

1.2 雪崩效应：分布式系统的"心肌梗塞"

雪崩的本质是资源耗尽的级联反应。在一个有 100 个微服务的系统里，任意一个下游服务变慢 5 倍，都可能拖垮整条链路：

graph LR
 A[网关] --> B[订单服务]
 B --> C[库存服务]
 B --> D[用户服务]
 C --> E[Redis 集群]

 E -.热点抖动.-> F((P99 飙升))
 F -.线程耗尽.-> C
 C -.超时.-> B
 B -.线程耗尽.-> A
 A -.健康检查失败.-> G((整链路雪崩))

 style F fill:#ffb4b4
 style G fill:#e63946,color:#fff

雪崩的核心特征：

传染性：故障从最末端的存储一路传到入口
非对称性：下游慢一倍，上游可能死十倍（因为重试 + 等待 + 线程堆积放大了影响）
自加速：被打挂的节点会让健康节点承担更多流量，加速崩溃

1.3 流量治理的 4 大场景

实战中流量治理覆盖 4 类典型场景，每类对应不同的策略：

场景	策略	关键参数	典型案例
突发流量保护	限流 + 排队	QPS / Warm Up 系数	秒杀、抢券、明星生日
下游故障隔离	熔断 + 半开探测	错误率 / 慢调用比例	Redis 抖动、DB 慢查询
关键资源保护	系统自适应保护	Load / CPU / RT	大促全站、618/双11
热点参数倾斜	热点限流	参数维度 + QPS	商品页 / 红包 / 直播间

📌 实践：4 大场景的优先级

资源有限时按以下顺序建设：

限流（性价比最高，1 周搞定）

熔断（防止下游传染，2 周搞定）

系统自适应保护（兜底大招，1 周配规则）

热点参数限流（精细化运营，按业务上）

顺序错了会很难受。曾见某团队先做了热点限流，结果普通流量限流没做，618 第一天就被秒杀直接干挂。

二、选型史：从 Hystrix 到 Sentinel

要回答"凭什么选 Sentinel"，先看 Java 生态的流量治理工具演化史。

2.1 工具演进时间线

graph LR
 A[2012
Hystrix
Netflix 开源] --> B[2017
Resilience4j
函数式重构]
 B --> C[2018
Sentinel
阿里开源]
 C --> D[2018-11
Hystrix
停止维护]
 D --> E[2019
Sentinel Cluster
集群限流]
 E --> F[2020+
Service Mesh
下沉到 Sidecar]

 style A fill:#a8dadc
 style C fill:#457b9d,color:#fff
 style E fill:#457b9d,color:#fff
 style D fill:#ffb4b4

2.2 Hystrix：开创者

Netflix 2012 年开源，是熔断器模式的工业级开山之作。

核心设计：

线程池隔离：每个下游依赖一个独立线程池，调用走异步
熔断器三态机：CLOSED（正常）→ OPEN（熔断）→ HALF_OPEN（半开探测）
失败回调：通过 getFallback() 实现降级

致命缺陷（导致 2018 年被废弃）：

线程池切换成本高：每个依赖都开线程池，几十个下游就要几十个池，纯开销占 CPU 5%-10%
API 侵入性强：必须继承 HystrixCommand 或 HystrixObservableCommand
规则修改要重启：动态配置能力差，规则改完要重新发布
维护停滞：Netflix 2018 年宣布"维护模式"，不再增加新特性

2.3 Resilience4j：函数式继承者

2017 年作为"Hystrix 的现代化替代"出现，由前 Hystrix 团队成员主导。

核心改进：

函数式编程风格：Decorators.ofSupplier(supplier).withCircuitBreaker(cb).decorate()
轻量级：不强制线程池隔离，可选信号量
模块化：限流 / 熔断 / 重试 / 缓存 / 隔离各自独立 JAR

短板：

无开箱即用控制台：要自己接 Micrometer + Grafana
动态规则要二次开发：默认配置在 YAML，运行时改要写代码
国内生态弱：中文文档少、社区问答少
集群限流：原生不支持，要配合 Bucket4j 等第三方

2.4 Sentinel：阿里实战派

阿里 2018 年开源，核心技术经过历年双 11 的实战验证。

核心特色：

资源 + 规则解耦：用 @SentinelResource 标注资源，规则在控制台改
完整功能矩阵：流控 / 熔断 / 系统自适应 / 热点 / 授权五大模块
官方 Dashboard：开箱即用的 Web 控制台
生态完整：Spring Cloud Alibaba 一行依赖搞定集成
集群限流：原生支持 Token Server 模式
多语言扩展：Go / C++ / Rust 也有官方版本

2.5 Sentinel Cluster：集群限流

单机限流的痛点：QPS 阈值难定。设大了所有节点都打满，设小了浪费资源。

Sentinel Cluster 解决方案：

用 Token Server 集中发放令牌
所有节点的 QPS 加总不超过总阈值
支持 Embedded（嵌入业务进程）和 Alone（独立部署）两种模式

graph TD
 A[请求] --> B[Sentinel Client]
 B --> C{获取 Token}
 C -->|本机有令牌| D[直接放行]
 C -->|本机无令牌| E[请求 Token Server]
 E --> F{全局令牌池}
 F -->|分配成功| D
 F -->|池已空| G[限流拒绝]

 style F fill:#457b9d,color:#fff

2.6 五维对比表

维度	Hystrix	Resilience4j	Sentinel	Sentinel Cluster
限流维度	不支持（只熔断）	QPS / 并发	QPS / 并发 / 热点参数	全局 QPS
熔断策略	错误率	错误率 / 慢调用 / 异常数	错误率 / 慢调用 / 异常数	同左
隔离方式	线程池 / 信号量	信号量为主	信号量为主	同左
动态规则	弱（要重启）	弱（要二开）	强（Dashboard 实时推）	强
控制台	无官方（自研 Dashboard）	无官方（接 Grafana）	官方 Dashboard	同左
规则持久化	无	无	Nacos / Apollo / ZK 多选	同左
生态集成	Spring Cloud Netflix（已停）	Spring Cloud 通用	Spring Cloud Alibaba	同左
国内文档	少	少	丰富	丰富
维护状态	停滞	活跃	活跃	活跃
典型用户	历史项目	海外团队	国内大厂	国内大厂

💡 原理：选型的本质是"控制力"vs"灵活性"

Hystrix 时代要写代码控制规则，灵活但难运维；Sentinel 把规则抽到 Dashboard，业务方可以不改代码调阈值，运维友好但要部署一套控制平面。

当你的团队规模 < 5 人、规则不常改时，Resilience4j 的轻量是优势。团队规模 > 20 人、规则要按场景动态调时，Sentinel 的 Dashboard 是刚需。

2.7 选型决策树

graph TD
 A{团队技术栈} -->|Spring Cloud Netflix 历史项目| B[Hystrix → 计划替换]
 A -->|Spring Cloud 通用 / 海外项目| C{需要控制台?}
 A -->|Spring Cloud Alibaba / 国内项目| D[Sentinel]

 C -->|需要| D
 C -->|不需要 / 自己接 Grafana| E[Resilience4j]

 D -->|单机 QPS 够用| F[Sentinel 单机模式]
 D -->|需全局 QPS 控制| G[Sentinel Cluster]

 style D fill:#457b9d,color:#fff
 style F fill:#a8dadc
 style G fill:#a8dadc

三、为什么选 Sentinel：5 大理由

收口选型，Sentinel 在 Java 微服务场景下值得选的 5 个理由：

实战出身：阿里双 11 历年验证，单机峰值 10 万 QPS 下规则生效稳定
功能完整：流控 / 熔断 / 系统自适应 / 热点 / 授权五大模块，无需拼第三方
运维友好：官方 Dashboard 开箱即用，规则改完实时生效
生态闭环：Spring Cloud Alibaba 一行依赖完成 Nacos + Sentinel + Seata 集成
持续演进：阿里中间件团队主力维护，每年 4-6 个版本迭代

🛑 误区警示

“Sentinel 是阿里的，不用阿里云就不能用"——这是常见误判。 Sentinel 是 Apache 2.0 协议的纯开源项目，和阿里云无任何绑定。Dashboard 可以部署在任何 Linux 机器上，规则可以存到任何 Nacos / Apollo / ZK 集群里。

实际国内中小厂用 Sentinel 的占比 > 60%，远高于阿里云用户占比。

四、Sentinel 怎么用：从接入到精细化

这是本文最核心的部分。Sentinel 的使用分 7 步走：架构总览 → 接入依赖 → 资源定义 → 规则配置 → 持久化 → Dashboard → 网关集成。

4.1 架构总览：三件套

Sentinel 的生产架构由三部分组成：

graph TD
 subgraph 业务进程
 A[Spring Boot App] --> B[Sentinel Client SDK]
 end

 subgraph 控制平面
 C[Sentinel Dashboard] -->|推规则| B
 B -->|上报指标| C
 end

 subgraph 配置中心
 D[Nacos] <-->|规则持久化| C
 D -->|拉规则| B
 end

 style C fill:#457b9d,color:#fff
 style D fill:#a8dadc

Sentinel Client：嵌入业务进程的 SDK，负责拦截调用、统计、按规则放行/拒绝
Sentinel Dashboard：独立部署的 Web 控制台，看监控、配规则
Nacos（或 Apollo / ZK）：规则持久化存储，Dashboard 重启 / Client 重启都能恢复

4.2 接入依赖

基于 Spring Cloud Alibaba 的接入只需一行依赖：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 选当前最新稳定版本，2026 年常用 2.2.x 系列 -->
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

<!-- 规则持久化到 Nacos（推荐） -->
<dependency>
 <groupId>com.alibaba.csp</groupId>
 <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

application.yml 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


spring:
 cloud:
 sentinel:
 transport:
 dashboard: 127.0.0.1:8080 # Dashboard 地址
 port: 8719 # Client 监听端口（Dashboard 拉指标用）
 datasource:
 flow: # 流控规则
 nacos:
 server-addr: 127.0.0.1:8848
 data-id: ${spring.application.name}-flow-rules
 group-id: SENTINEL_GROUP
 rule-type: flow
 degrade: # 熔断规则
 nacos:
 server-addr: 127.0.0.1:8848
 data-id: ${spring.application.name}-degrade-rules
 group-id: SENTINEL_GROUP
 rule-type: degrade

4.3 资源定义：@SentinelResource

Sentinel 把"被保护的代码段"称为资源，用注解或 API 标识。

 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


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

 @Autowired
 private InventoryClient inventoryClient;

 @PostMapping("/create")
 @SentinelResource(
 value = "createOrder", // 资源名
 blockHandler = "createOrderBlocked", // 被限流/熔断时的处理
 fallback = "createOrderFallback" // 业务异常时的降级
 )
 public OrderResult create(@RequestBody OrderReq req) {
 // 主业务逻辑
 Inventory inv = inventoryClient.deduct(req.getSkuId(), req.getQty());
 return orderService.save(req, inv);
 }

 // 被流控/熔断规则拦截时调用
 public OrderResult createOrderBlocked(OrderReq req, BlockException ex) {
 return OrderResult.fail("当前下单人数过多，请稍后再试");
 }

 // 业务方法抛异常时调用
 public OrderResult createOrderFallback(OrderReq req, Throwable ex) {
 log.error("createOrder fallback, reason={}", ex.getMessage());
 return OrderResult.fail("系统繁忙，订单已记录后续重试");
 }
}

🎯 避坑点：blockHandler vs fallback

这俩很容易混：

blockHandler：被 Sentinel 规则拦截时调用，参数末尾必须是 BlockException

fallback：业务代码抛任意异常时调用，参数末尾必须是 Throwable

同时配两个，且业务真抛异常时，fallback 优先级高于 blockHandler。规则拦截时只走 blockHandler。

实战推荐：两个都写。blockHandler 用于流量异常时的友好提示；fallback 用于业务真挂了时的兜底（如查询本地缓存）。

4.4 五大功能详解

4.4.1 流量控制（限流）

按 QPS 或线程数限流，是最常用的规则类型。

阈值类型	触发条件	适用场景
QPS	每秒请求数 > 阈值	突发流量保护（最常用）
并发线程数	同时执行的请求 > 阈值	慢调用保护（如 DB 操作）

控制效果有三种：

控制效果	行为	适用
快速失败（默认）	超阈值直接拒绝	接口型服务
Warm Up（预热）	阈值随时间线性增长	冷启动后突发流量（如缓存预热）
排队等待	超阈值进队列，匀速处理	异步任务、消息消费

代码示例（手动注册规则，生产环境一般走 Dashboard）：

1
2
3
4
5
6
7


FlowRule rule = new FlowRule();
rule.setResource("createOrder");
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
rule.setCount(1000); // QPS 阈值 1000
rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_WARM_UP);
rule.setWarmUpPeriodSec(10); // 10 秒内预热到阈值
FlowRuleManager.loadRules(Collections.singletonList(rule));

4.4.2 熔断降级

下游服务异常时短路调用，避免线程堆积。

Sentinel 1.8+ 提供三种熔断策略：

策略	触发条件	推荐场景
慢调用比例	慢调用比例 > 阈值（默认 0.5）	下游慢但不挂（最常用）
异常比例	错误率 > 阈值	下游高错误率
异常数	错误数 > 阈值（绝对值）	调用量小的接口

熔断器三态机：

stateDiagram-v2
 [*] --> CLOSED: 启动
 CLOSED --> OPEN: 触发熔断条件
 OPEN --> HALF_OPEN: 熔断时长到期
 HALF_OPEN --> CLOSED: 探测成功
 HALF_OPEN --> OPEN: 探测失败

 note right of CLOSED: 正常调用
持续统计指标
 note right of OPEN: 直接走 fallback
不调用下游
 note right of HALF_OPEN: 放行 1 个请求
看结果

规则示例：

1
2
3
4
5
6
7
8
9


DegradeRule rule = new DegradeRule();
rule.setResource("inventoryClient:deduct");
rule.setGrade(RuleConstant.DEGRADE_GRADE_RT); // 慢调用比例策略
rule.setCount(200); // 响应时间阈值 200ms
rule.setSlowRatioThreshold(0.5); // 慢调用比例 > 50%
rule.setMinRequestAmount(20); // 统计窗口最小请求数
rule.setStatIntervalMs(10000); // 统计窗口 10 秒
rule.setTimeWindow(5); // 熔断 5 秒后试探
DegradeRuleManager.loadRules(Collections.singletonList(rule));

4.4.3 系统自适应保护

按机器整体负载（Load、CPU、入口 QPS、平均 RT）做兜底保护。这是大促级流量的最后一道防线。

1
2
3
4
5
6
7


SystemRule rule = new SystemRule();
rule.setHighestSystemLoad(8.0); // 触发条件：Load1 > 8
rule.setHighestCpuUsage(0.8); // 或 CPU > 80%
rule.setAvgRt(500); // 或平均 RT > 500ms
rule.setMaxThread(800); // 或并发线程 > 800
rule.setQps(20000); // 或入口 QPS > 20000
SystemRuleManager.loadRules(Collections.singletonList(rule));

📌 实践：系统保护是大促必备

单接口限流再准，遇到全站慢就失灵——总流量没超，但 CPU/Load 已经爆了。 系统自适应保护按机器整体状态拒绝请求，是不依赖业务规则的兜底。

大促前必配，阈值参考：

Load1 上限 = CPU 核数 × 2

CPU 上限 80%

平均 RT 上限 = 业务 P99 × 1.5

4.4.4 热点参数限流

某些场景下，同一个接口的不同参数值流量差异巨大。比如商品详情接口，99% 的流量来自 1% 的热门商品。

1
2
3
4
5


@GetMapping("/item/{id}")
@SentinelResource(value = "getItem", blockHandler = "getItemBlocked")
public Item getItem(@PathVariable Long id) {
 return itemService.findById(id);
}

规则配置：

1
2
3
4
5
6
7
8
9


ParamFlowRule rule = new ParamFlowRule("getItem");
rule.setParamIdx(0); // 第 0 个参数（id）
rule.setCount(100); // 单参数值 QPS 默认上限
ParamFlowItem hotItem = new ParamFlowItem();
hotItem.setObject("9527"); // 商品 ID 9527
hotItem.setClassType(String.class.getName());
hotItem.setCount(1000); // 热门商品单独阈值 1000
rule.setParamFlowItemList(Collections.singletonList(hotItem));
ParamFlowRuleManager.loadRules(Collections.singletonList(rule));

💡 原理：热点参数限流为什么不能用普通限流

假设 getItem 总 QPS 上限 10 万，正常时 99% 是热门商品 9527 的请求。此时一波恶意爬虫扫遍所有商品 ID（每个 ID 1 QPS），总 QPS 没超但热门商品 9527 的容量被冷门 ID 挤占了，正常用户被拒绝。

热点参数限流按"参数值"维度统计 QPS，独立给热门商品分配配额，避免被冷门商品挤占。

4.4.5 黑白名单（授权）

按调用方身份允许 / 拒绝。常用于 BFF 网关层。

1
2
3
4
5


AuthorityRule rule = new AuthorityRule();
rule.setResource("inventoryService:deduct");
rule.setLimitApp("orderService,couponService"); // 允许列表
rule.setStrategy(RuleConstant.AUTHORITY_WHITE); // WHITE / BLACK
AuthorityRuleManager.loadRules(Collections.singletonList(rule));

调用方身份从 RPC 框架的上下文里取（Dubbo 取 application name、Spring Cloud 取请求头里的 S-User），需配 RequestOriginParser。

4.5 规则持久化：必须做的事

Sentinel 默认规则存在内存里，Client 重启就没了。生产环境必须把规则持久化到外部存储。

方案	模式	优缺点
Pull 模式	Client 定时拉	简单但有延迟（默认 30 秒）
Push 模式	配置中心推	实时但要选 Nacos / Apollo / ZK

Spring Cloud Alibaba 推荐 Nacos Push 模式，配置如 4.2 节所示。规则存到 Nacos 后：

Dashboard 改规则 → 写 Nacos → Nacos 推送给所有 Client → 实时生效
Client 重启 → 从 Nacos 拉一次 → 规则不丢

🎯 避坑点：规则丢失的元凶

不配持久化的后果：

重启即失效：Client 重启或扩容新节点，规则消失

新节点裸奔：扩容期间新节点没规则，流量直接打到下游

Dashboard 显示假象：Dashboard 显示规则存在（其实存在 Dashboard 内存里），但 Client 实际没生效

上生产前的最后一道 Check：模拟重启一台 Client，规则还在不？

4.6 Dashboard 部署

Dashboard 是个 Spring Boot Jar 包，部署简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 下载（替换为当前版本号）
wget https://github.com/alibaba/Sentinel/releases/download/<version>/sentinel-dashboard-<version>.jar

# 启动（生产环境务必加用户密码）
java -Dserver.port=8080 \
 -Dcsp.sentinel.dashboard.server=localhost:8080 \
 -Dproject.name=sentinel-dashboard \
 -Dsentinel.dashboard.auth.username=admin \
 -Dsentinel.dashboard.auth.password=YourStrongPass \
 -jar sentinel-dashboard-<version>.jar

🛑 误区警示

Dashboard 改规则默认只写到自己内存里——不会自动同步到 Nacos。要做到"Dashboard 改 → Nacos 持久化 → 推给所有 Client”，必须改 Dashboard 源码或用社区改造版（如 nepxion-discovery 提供的整合版）。

这是 Sentinel 官方一直没解决的痛点。生产推荐：

短期：用社区改造版 Dashboard

长期：自研规则配置后台（直接对接 Nacos），Dashboard 仅做监控查看

4.7 Spring Cloud Gateway 集成：网关层限流

把限流前置到网关层，能在更早的环节拦住异常流量。

1
2
3
4


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


spring:
 cloud:
 sentinel:
 filter:
 enabled: false # 关掉默认 servlet 过滤器
 scg:
 fallback:
 mode: response
 response-status: 429
 response-body: '{"code":429,"msg":"too many requests"}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Configuration
public class SentinelGatewayConfig {

 @PostConstruct
 public void initRules() {
 Set<GatewayFlowRule> rules = new HashSet<>();
 GatewayFlowRule rule = new GatewayFlowRule("order-service") // 路由 ID
 .setCount(2000)
 .setIntervalSec(1);
 rules.add(rule);
 GatewayRuleManager.loadRules(rules);
 }
}

4.8 OpenFeign 集成：消费者侧熔断

1
2
3


feign:
 sentinel:
 enabled: true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@FeignClient(name = "inventory-service", fallback = InventoryFallback.class)
public interface InventoryClient {
 @PostMapping("/inventory/deduct")
 Inventory deduct(@RequestParam Long skuId, @RequestParam Integer qty);
}

@Component
public class InventoryFallback implements InventoryClient {
 @Override
 public Inventory deduct(Long skuId, Integer qty) {
 log.warn("inventory deduct fallback, skuId={}", skuId);
 return Inventory.unavailable();
 }
}

五、真实案例

5.1 阿里：双 11 系统自适应保护

阿里电商核心链路用 Sentinel 多年，双 11 零点峰值的兜底就是系统自适应保护：

入口 QPS 阈值按机器规模动态调整
当 Load1 > 阈值时，按 BBR 算法自适应拒绝流量
配合预案系统：高优先级业务（下单 / 支付）继续放行，低优先级（详情 / 推荐）先拒绝

阿里的核心实践："规则不是拍出来的，是压测出来的"——每年双 11 前 2 个月开始全链路压测，每条规则都对应一次压测结论。

5.2 美团：Sentinel + 自研规则中心

美团没用官方 Dashboard，而是把 Sentinel 接入自研的统一规则中心 OCTO：

规则按业务维度组织（不只按服务）
一键灰度（5% / 20% / 50% / 100%）
规则变更走审批流，关键服务需 SRE 双签

教训："Sentinel 官方 Dashboard 适合开发自测，不适合大规模生产运营"。中大厂建议早做自研规则中心。

5.3 中小厂：Spring Cloud Alibaba 直接落地

20-50 人技术团队的典型用法：

Nacos（注册中心 + 配置中心 + Sentinel 规则）一套搞定
官方 Dashboard 改造版（加上 Nacos 双写）
规则按"接口 + 环境"组织
灰度通过 Nacos 的 namespace 区分

性价比拉满，3 天可上线、1 周稳定运行。

💡 原理：选型规模档

5 人以下：Sentinel 单机模式 + 内存规则（先跑起来）

5-50 人：Sentinel + Nacos 持久化 + 官方 Dashboard

50-200 人：Sentinel + 自研规则中心（解决多业务线 / 灰度 / 审批）

200 人以上：Sentinel 作为 Mesh Sidecar 的一部分（流控下沉到基础设施）

六、总结

6.1 流量治理的 3 大核心要素

资源识别：每个对外接口、每个下游依赖，都要打 @SentinelResource
规则配置：限流 / 熔断 / 系统自适应三类规则都要有
持久化 + 实时推送：规则必须存 Nacos，重启不丢、变更秒级生效

6.2 何时不该上 Sentinel

场景	推荐
单体应用、QPS < 100	不需要，加几个简单的限流注解或自己写计数器即可
海外团队、Spring Cloud Netflix	Resilience4j 生态更顺
Service Mesh 架构（Istio 全量）	Envoy 自带流控，Sentinel 部分重复
PoC / Demo	任何工具都行，不要为了 Sentinel 而 Sentinel

6.3 常见陷阱

🛑 误区警示：这些坑别踩

规则不持久化：重启即失效，扩容即裸奔

blockHandler / fallback 用错：两者职责混淆，关键时不生效

只配限流不配熔断：突发流量过了，但下游故障传染没解决

阈值拍脑袋：没压测就上规则，要么误伤要么不生效

不监控规则变化：规则被误改无人发现

Dashboard 暴露公网：默认无 HTTPS，规则被恶意改

Sentinel 是工具，规则才是核心。工具用 1 天就会，规则要持续运营。

📌 实践：流量治理的成本

流量治理是持续投入，不是一次性建设：

初始建设：1-2 周（接入 + Dashboard + Nacos）

规则梳理：每个核心接口 0.5 天压测 + 配规则

持续维护：每季度复盘规则有效性，新接口必须配规则才能上线

演练：每月手动触发一次限流 / 熔断，验证规则生效

投入产出比：一次大促故障的损失 = 5 年的流量治理人力投入。值得。

七、Sentinel 实施清单

按以下清单逐项检查，可以少踩很多坑。

7.1 评估层 Checklist

业务分级：明确哪些接口是 P0 / P1 / P2，决定保护粒度
流量画像：核心接口的日 / 周 / 月 QPS 曲线，P99 响应时间
依赖梳理：每个服务的下游依赖清单（DB / Redis / RPC / HTTP）
历史故障：过去 1 年的故障 Root Cause，对应到限流 / 熔断场景
预算评估：Dashboard 服务器 + Nacos 服务器 + 人力（首期 1 周）

7.2 接入层 Checklist

依赖统一：所有服务用同一个 Spring Cloud Alibaba 版本（避免兼容问题）
基础注解：所有 Controller 接口加 @SentinelResource
降级方法：每个资源都有 blockHandler + fallback
OpenFeign 接入：所有 Feign Client 加 fallback
网关接入：网关层加 sentinel-gateway，限流前置
本地测试：单机跑通限流 / 熔断 / 降级三类场景

7.3 规则层 Checklist

限流规则：核心接口都配 QPS 限流，阈值由压测得出
熔断规则：所有 RPC / HTTP 调用都配熔断（慢调用比例策略最常用）
系统保护：所有机器都配系统自适应规则
热点参数：商品 / 用户等可能热点倾斜的接口配热点限流
规则持久化：Nacos 中规则文件命名规范统一
规则版本：Nacos 中规则按版本管理，可回滚

7.4 监控层 Checklist

Dashboard 实时监控：QPS / 拒绝量 / 异常数实时可看
接 Prometheus：Sentinel metrics 导出到 Prometheus + Grafana
告警规则：拒绝量 > 阈值 → 告警；熔断打开 → 告警
业务大盘：核心业务流量 / 拒绝率 / 熔断状态在大盘上
规则变更审计：所有规则修改有人 / 时间 / 内容记录

7.5 运维层 Checklist

Dashboard 高可用：至少 2 台部署 + 反向代理
Dashboard 鉴权：必须配用户密码，不能裸奔
Dashboard 内网：不暴露公网，VPN 访问
Nacos 高可用：至少 3 节点集群
规则备份：Nacos 规则每日备份
演练机制：每月一次"主动触发熔断"演练
Runbook：每个核心服务有"流量治理 Runbook"

🎯 避坑点：80/20 法则

上面 30+ 项检查，80% 的事故栽在前 10 项：

业务分级不清晰

接口没全部加注解

没配 blockHandler / fallback

规则没持久化

Dashboard 没鉴权

阈值拍脑袋

没接监控

没配告警

没做演练

Runbook 是摆设

先把前 10 项做好，再考虑剩下的。

八、常见问题 FAQ

Q1：从 Hystrix 迁移到 Sentinel 难吗？

A：不难，但工作量不小。主要工作：

替换依赖（去掉 Hystrix 相关，加 Sentinel）
把 @HystrixCommand 改为 @SentinelResource
把 getFallback() 拆为 blockHandler + fallback
规则从 YAML 移到 Nacos
Dashboard 切换

中等规模项目（50 个服务）迁移工期约 4-6 周，可分批进行。

Q2：Sentinel 规则修改后多久生效？

A：取决于持久化方案：

内存规则（不推荐）：立即生效，但重启即失效
Nacos Push：< 1 秒
自定义 Pull：默认 30 秒

生产环境用 Nacos Push，改完控制台到所有节点生效平均 200-500ms。

Q3：Sentinel 性能开销大吗？

A：很小。官方压测数据：

单机 10 万 QPS 场景下，CPU 开销 < 1%
内存开销：每个资源 ~2KB
调用延迟增加：< 0.1ms

性能开销主要来自滑动窗口统计，比 Hystrix 的线程池切换轻 10 倍。

Q4：Service Mesh 时代 Sentinel 还有用吗？

A：有用，但角色变化。

小规模团队：Sentinel 仍是流量治理的主力
全量 Service Mesh 团队：基础限流下沉到 Envoy，Sentinel 转向业务级精细化场景（热点参数 / 业务规则）
混合架构（最常见）：Sentinel 在业务进程内做精细控制，Mesh 在基础设施层做粗粒度

Sentinel 团队也在做 sentinel-mesh-sidecar，把 Sentinel 能力下沉到 Envoy。未来 1-2 年这个方向会更清晰。

Q5：Sentinel 和限流算法（令牌桶 / 漏桶）是什么关系？

A：Sentinel 是工具，限流算法是其内核。Sentinel 内置：

滑动窗口：默认 QPS 统计算法，时间窗口内累积计数
漏桶：排队等待模式（匀速放行）
令牌桶：Warm Up 模式（预热阶段类似令牌桶）

你不需要选择算法，Sentinel 自动按规则类型用最合适的算法。

Q6：Sentinel Cluster 部署复杂吗？

A：比单机复杂，要考虑 Token Server 高可用。

Embedded 模式：Token Server 嵌入业务进程（选一台业务节点充当）
Alone 模式：Token Server 独立部署（推荐）

Alone 模式需要：

Token Server 至少 2 台部署 + Failover
Token Server 故障时降级为单机限流（避免雪崩）

仅当确实需要全局 QPS 控制时才上 Cluster，能用单机就用单机。

Q7：规则配在哪里更合理：代码 / Nacos / 自研后台？

A：按团队规模选：

5 人以下：代码里写规则（启动时加载）
5-50 人：Nacos 存规则 + 官方 Dashboard 改
50-200 人：Nacos 存规则 + 自研后台改（带审批 / 灰度 / 回滚）
200 人以上：规则平台化（多租户 / 多环境 / API 化）

早期不要追求大而全，能跑就行；规模上来再演进。

Q8：Sentinel 报错 “ClusterServerCommandHandler not found” 怎么办？

A：典型的版本兼容问题。检查：

Spring Cloud Alibaba 版本 vs Sentinel Core 版本要对齐（参考阿里官方版本对照表）
同一服务里所有 Sentinel 相关依赖必须同版本
IDE 里看 Maven 依赖树，排查传递依赖冲突

90% 的兼容性问题用 dependencyManagement 锁定 Spring Cloud Alibaba 版本就能解决。

九、推荐阅读

如果想深入 Sentinel 与流量治理，以下资料值得一读：

官方资料：

Sentinel 官方文档（中英文）：https://sentinelguard.io/
Sentinel GitHub Wiki：https://github.com/alibaba/Sentinel/wiki
Spring Cloud Alibaba 官方文档

书籍：

《微服务架构设计模式》（Chris Richardson）—— 第 4 章讲弹性与故障处理
《Release It!》（Michael Nygard）—— 熔断器模式的开山之作，必读
《从 Paxos 到 Zookeeper》—— 理解规则持久化背后的分布式一致性

技术博客：

阿里中间件团队：Sentinel 历年双 11 实战
美团技术团队：流量治理与稳定性建设
字节跳动技术博客：Service Mesh 时代的流量治理

开源项目：

Sentinel：https://github.com/alibaba/Sentinel
Sentinel Dashboard 改造版（社区）：nepxion-discovery
Resilience4j（对比参考）：https://resilience4j.readme.io/
Hystrix（已停维护，仅作历史参考）

💡 学习路径建议

入门：本文 + Sentinel 官方 Quick Start，3 天能跑通基础接入

进阶：阿里中间件博客的双 11 系列，理解工业实践

实战：用一个真实项目接入 Sentinel + Nacos，做一次压测验证规则

深潜：读 Sentinel 源码（建议从 Sph.entry() 入口往下追），理解滑动窗口、规则匹配、Slot Chain

理论 + 实践 + 源码，缺一不可。

参考文章

数据库演化：MySQL → PostgreSQL → 分布式，从单机到 NewSQL 的全链路实战

Tue, 09 Jun 2026 00:00:00 +0000

数据库演化：MySQL → PostgreSQL → 分布式，从单机到 NewSQL 的全链路实战

Java Web 微服务系列 · 第 8 篇 · 数据库演化阅读时长：约 45 分钟本文写于 2026 年 6 月

引子：MySQL 第一次"卡死"的那个深夜

2017 年某日凌晨 3 点，我被一阵急促的电话铃声吵醒。电话那头是刚入职不到半年的运维小哥，声音发颤："哥，订单服务挂了，DB 连接全爆，整个集群处于不可用状态。"

我一边穿衣服一边远程连上服务器，看到的景象触目惊心：

InnoDB buffer pool 利用率 99.8%，已经被锁页撕扯（lock wait）拖到 12 秒
慢查询日志 在 5 分钟内涌进 1.2 万条 SELECT * FROM order WHERE user_id = ? AND status IN (...) 的全表扫
从库延迟 飙到 30 分钟，主从复制的 relay log 把磁盘写满
连接数 跑到 3500/3500，新请求全部被拒绝

事后排查，这是一张 4.2 亿行的 order 表，单表行数已经远超 InnoDB 的最优承载范围。代码里没有按 user_id 建索引，业务员按状态查询导致 90% 的查询全表扫。

那次事故直接损失 38 万元。我开复盘会时说过一句后来被团队当成内部黑话的话："不是 MySQL 不行，是 MySQL 在裸奔"。

从那以后，我们走上了"数据库演化“这条路：

第一步：MySQL 索引优化 + 慢查询治理（4.2 亿行也能跑）
第二步：主从分离 + 读写分离（扛住 5 万 QPS）
第三步：分库分表（订单表按用户 ID 拆 64 库 × 64 表）
第四步：PostgreSQL 上位（复杂报表场景）
第五步：TiDB 试点（解决 MySQL 容量天花板）

到 2025 年回头看，数据库演化就是 Java 微服务架构演化的"地基”——没有它，上层的弹性扩容、服务治理、流量调度全是空中楼阁。

本文要回答四个问题：

MySQL 怎么"榨干最后一滴性能"？（索引 + 参数 + 架构）
什么时候必须升级到 PostgreSQL？
分库分表和分布式数据库怎么选？
容灾备份的底线在哪里？

全文 10000+ 字，一次把数据库演化的全链路讲透。

一、核心概念：把"主从/集群/分库分表/分布式"掰开

谈具体技术前，先把 6 个常被混用的术语定义清楚——很多团队的"分库分表"和"分布式数据库"压根不是一回事。

1.1 单机（Standalone）

单机：所有数据 + 所有请求都在一台服务器上。

graph LR
 A[应用] --> B[单台 MySQL]
 style B fill:#f4a261

维度	表现
容量上限	单盘 10TB、单库行数 5 亿（B+Tree 树高 4）
QPS 上限	1-3 万（写），5-10 万（读）
可用性	单点，故障 = 业务停
适用场景	Demo、测试、内部工具、小型 SaaS

🎯 避坑点：单机能撑多久

经验值（InnoDB + 良好索引）：

单表行数 < 1000 万：完全无压力

1000 万 - 5000 万：需要索引优化

5000 万 - 5 亿：必须考虑分表

> 5 亿：分库分表 or 分布式数据库

5000 万不是"硬指标"，但超过了就别再用单表硬抗。

1.2 主从复制（Master-Slave Replication）

主从复制：一台主库负责写，多台从库同步数据、负责读。

graph LR
 A[应用写入] --> B[Master]
 B --> C[Slave 1]
 B --> D[Slave 2]
 B --> E[Slave 3]
 A2[应用读取] --> C
 A2 --> D
 A2 --> E
 style B fill:#e76f51
 style C fill:#2a9d8f
 style D fill:#2a9d8f
 style E fill:#2a9d8f

维度	表现
容量上限	单机相同，但通过分库可扩
QPS 上限	读线性扩展（10 台从 = 50 万 QPS）
写能力	仍是单机（最大瓶颈）
可用性	主库故障需人工切换，分钟级恢复
同步延迟	异步复制通常 10-100ms

💡 原理：主从复制的"三种姿势"

异步复制（默认）：主库写完 binlog 就返回，从库异步拉。快但不安全——主库挂掉时未同步的 binlog 会丢

半同步复制（MySQL 5.5+）：主库等至少 1 个从库确认收到 binlog 再返回。安全但慢（多 1 次 RTT）

增强半同步（MySQL 5.7.4+）：从库持久化到 relay log 后才算确认。比半同步再安全一层

金融场景必须增强半同步 + GTID；普通业务半同步够用。

1.3 集群（Cluster）

集群：多个节点共同承担同一个数据库的读写，对应用看起来像一台。

集群类型	代表	特点
MySQL Group Replication（MGR）	MySQL 官方	单主或多主，强一致，写性能差
MySQL NDB Cluster	MySQL 官方	内存数据库，实时性极强
Percona XtraDB Cluster（PXC）	Percona	基于 Galera，同步复制
Galera Cluster for MySQL	Codership	同步复制，多主写入
PostgreSQL Patroni + etcd	Zalando	高可用方案

graph TD
 A[应用] --> B[HAProxy 负载均衡]
 B --> C[Node 1]
 B --> D[Node 2]
 B --> E[Node 3]
 C <--> D
 D <--> E
 C <--> E
 style C fill:#e76f51
 style D fill:#2a9d8f
 style E fill:#2a9d8f

💡 原理：集群 vs 主从的本质区别

主从：从库只读，主库单点写。扩读不扩写

集群：所有节点都可读可写。读写都扩

代价：集群的"同步复制"会拖慢写入（每写一次要等所有节点确认）

PXC 写性能约为主从的 30%-50%。如果写为主，集群不是好选择。

1.4 读写分离（Read-Write Splitting）

读写分离：在主从基础上，让写走主库、读走从库，对应用透明。

graph LR
 A[应用] --> R[路由层
ShardingSphere / MyCat]
 R -->|写| M[Master]
 R -->|读| S1[Slave 1]
 R -->|读| S2[Slave 2]
 style R fill:#e9c46a

常见中间件：

ShardingSphere-JDBC（推荐）：客户端嵌入，零依赖，性能好
MyCat：代理模式，独立部署，跨语言
Atlas：奇虎 360 开源，已停更
MaxScale：MariaDB 出品

1.5 分库分表（Sharding）

分库分表：把一个库 / 一张表的数据，按规则拆分到多个库 / 多张表。

graph TD
 A[订单 order] --> B[order_0]
 A --> C[order_1]
 A --> D[order_2]
 A --> E[order_3]
 B --> F[db_order_0]
 B --> G[db_order_1]
 C --> F
 C --> G
 D --> H[db_order_2]
 D --> I[db_order_3]
 E --> H
 E --> I
 style B fill:#2a9d8f
 style C fill:#2a9d8f
 style D fill:#2a9d8f
 style E fill:#2a9d8f

拆分方式	说明
垂直分库	按业务拆（订单库 / 用户库 / 商品库）
垂直分表	把宽表按列拆（主表 + 扩展表）
水平分库	同一张表的数据按规则拆到不同库
水平分表	同一张表的数据按规则拆到同库不同表

1.6 分布式数据库（Distributed SQL / NewSQL）

分布式数据库：原生支持水平扩展的数据库，对应用像单机一样使用。

数据库	类型	一致性协议	特点
TiDB	NewSQL	Raft	兼容 MySQL 协议，HTAP
OceanBase	原生分布式	Paxos 多副本	阿里自研，2010 立项
PolarDB	存储计算分离	Parallel Raft	阿里云原生
CockroachDB	NewSQL	Raft	兼容 PostgreSQL 协议
YugabyteDB	NewSQL	Raft	兼容 PostgreSQL/Cassandra
Citus	PG 扩展	-	把 PG 变成分布式

graph TD
 A[TiDB SQL Layer] --> B[PD 调度层]
 A --> C[TiKV 存储层]
 A --> D[TiKV 存储层]
 A --> E[TiKV 存储层]
 C -.Raft.- D
 D -.Raft.- E
 E -.Raft.- C
 style A fill:#e76f51
 style B fill:#e9c46a
 style C fill:#2a9d8f
 style D fill:#2a9d8f
 style E fill:#2a9d8f

🎯 避坑点：分库分表 ≠ 分布式数据库

维度分库分表分布式数据库

兼容性需改造 SQL 兼容 MySQL/PG 协议

跨库 JOIN 不支持 支持（通过下推）

跨库事务需 Seata 天然支持（Percolator/TCC）

运维复杂（数据迁移、扩容）较简单（自动 Rebalance）

成本中等较高（多副本）

选型时机 1000 万 - 100 亿行 100 亿 + 行

分库分表是"穷人版"分布式数据库——成本低但改造大。

二、选型史：MySQL → PostgreSQL → NewSQL 的三次跃迁

数据库的演化不是一夜之间完成的。从 1995 年 MySQL 1.0 发布到 2015 年 TiDB 开源，20 年时间完成了三次关键跃迁。

2.1 三次跃迁时间线

graph LR
 A[1995 MySQL 1.0] --> B[1996 PostgreSQL 6.0]
 A --> C[2000 MySQL 3.23
InnoDB 引擎成熟]
 C --> D[2010 OceanBase 立项]
 C --> E[2013 MySQL 5.6
GTID / 性能增强]
 E --> F[2015 TiDB 开源]
 F --> G[2020 OceanBase 3.0
开源]
 G --> H[2024 PolarDB / Aurora
云原生]
 style A fill:#f4a261
 style B fill:#2a9d8f
 style C fill:#f4a261
 style D fill:#e76f51
 style F fill:#e76f51
 style H fill:#457b9d,color:#fff

2.2 第一次跃迁：从 MySQL 到 PostgreSQL

触发场景：复杂查询、GIS、JSON、CTE 等高级特性需求。

维度	MySQL 8.0	PostgreSQL 16
SQL 兼容性	中等	强（最接近 SQL 标准）
JSON 支持	JSON 类型	JSONB（二进制索引）
GIS 支持	基础	PostGIS（业界标杆）
CTE / 窗口函数	8.0 才开始	早就支持
全文检索	基础	丰富（多语言、权重）
物化视图	8.0 GA	支持
复杂查询性能	中	强（优化器好）
写入性能	强	中
复制	binlog	流复制 + 逻辑复制
运维生态	丰富（国内首选）	中等（专业领域首选）
适合场景	高并发 OLTP	OLAP + 复杂业务

📌 实践：什么时候该迁到 PG

业务里有 GIS（地图、附近的人、配送范围）

JSON 字段需要查询（半结构化数据）

复杂报表（窗口函数、CTE、递归查询）

全文检索要求高（多语言、模糊搜索）

严格 SQL 规范（金融、政府）

不是性能问题，而是特性问题。MySQL 5.7 之后性能差距已大幅缩小。

2.3 第二次跃迁：从 MySQL 主从到分库分表

触发场景：单库行数超 5 亿，QPS 持续走高，写入瓶颈出现。

代表事件：

2012 年：淘宝"去 IOE"，MySQL + 自主中间件取代 Oracle
2014 年：阿里 OceanBase 在双 11 承担核心交易库
2016 年：Sharding-JDBC（当当，后并入 ShardingSphere）成为事实标准
2018 年：MyCat 流行，代理式分库分表方案成熟

2.4 第三次跃迁：从分库分表到 NewSQL

触发场景：分库分表的运维成本已经超过数据库本身的成本。

痛点	表现
扩容噩梦	32 库扩到 64 库要全量数据迁移
跨库 JOIN	性能差，业务层要做内存 JOIN
分布式事务	强一致事务需 Seata，复杂
运维复杂	几百个分片，几百个 binlog 链路
研发效率	SQL 受限，需求 30% 时间在做"分库适配"

应对：用 NewSQL 把分库分表的"中间件逻辑"下沉到数据库内部。

数据库	立项时间	开源时间	关键节点
OceanBase	2010 阿里	2019（OB 1.0）	2014 双 11 抗住 8 万笔/秒
TiDB	2015 PingCAP	2017（GA）	2018 京东"跑赢"分库分表
CockroachDB	2015 Cockroach Labs	2017	2021 22.1 GA
YugabyteDB	2016 Yugabyte	2018	2.0 GA（PG 兼容）
PolarDB	2015 阿里云	闭源	2018 云原生 + 存储计算分离

💡 原理：NewSQL 的核心创新

计算-存储分离：SQL 层无状态，可无限扩容

数据自动分片（Auto-Sharding）：应用不感知

多副本强一致：Paxos / Raft 协议保证

HTAP 混合负载：一份数据支持 OLTP + OLAP

本质是用分布式协议换"无限扩展"。

三、为什么必须演化：4 大驱动力

3.1 驱动力一：数据量爆炸

来自 IDC 的预测：

2010 年：全球数据量 1.2 ZB
2020 年：59 ZB（5 年涨 50 倍）
2025 年：175 ZB
2030 年：612 ZB

企业级数据库的"舒适区"是 1TB-5TB 单库。超过这个量级，单机的物理极限就开始显现：

B+Tree 树高 > 4，索引深度查询变慢
备份/恢复时间线性增长（10TB 恢复 8 小时+）
主从延迟上升（大事务、批量更新）
运维窗口变窄（DDL 时间从分钟级到小时级）

3.2 驱动力二：并发量陡增

业务阶段	QPS	数据库形态
早期	< 1 万	单机 MySQL
成长期	1-10 万	主从 + 读写分离
爆发期	10-100 万	分库分表 + 缓存
巨型业务	> 100 万	分布式数据库 + 多级缓存

🎯 避坑点：不要过早分库分表

分库分表的成本：

业务改造（30% 工期）

跨库 JOIN 性能损失（10-100 倍）

分布式事务（20% 性能损耗）

运维复杂度 ×3

过早分库分表 = 把工程能力浪费在"应对未来"。先看实际数据量：单表 > 5000 万行再考虑。

3.3 驱动力三：可用性要求

业务连续性分级：

等级	业务类型	RTO	RPO	推荐方案
P0	核心交易	< 5 分钟	< 1 分钟	异地多活
P1	重要业务	< 30 分钟	< 5 分钟	同城双活 + 异地灾备
P2	一般业务	< 数小时	< 1 小时	同城灾备（热备）
P3	后台系统	< 1 天	< 1 天	主从副本即可

MySQL 主从最多撑到 P2。要做到 P0 的 RTO < 5 分钟，必须异地多活 + 分布式数据库。

3.4 驱动力四：合规与云原生

强监管行业（金融、医疗）：要求两地三中心 + 同城双活
GDPR / 等保 2.0：数据本地化 + 可审计
云原生：要求弹性扩缩 + 按量计费 + 跨可用区容灾

自建 MySQL 越来越难满足这些要求，必须演进到云原生数据库（RDS、PolarDB、Aurora）。

四、MySQL 深度优化

在谈"要不要换数据库"之前，先把 MySQL 榨干——大多数团队连 MySQL 8.0 的 50% 性能都没用到。

4.1 存储引擎选择

MySQL 8.0 已经全面 InnoDB，MyISAM 只用于只读历史表。

引擎	锁粒度	事务	崩溃恢复	适用
InnoDB	行锁	支持	Redo + Undo Log	99% 场景
MyISAM	表锁	不支持	无	只读历史表
Memory	表锁	不支持	断电丢	临时表
Archive	行锁	不支持	无	日志归档

4.2 索引原理：B+Tree 是什么

B+Tree 是 InnoDB 的核心数据结构。

graph TD
 A[根节点
P=16] --> B[中间节点 1]
 A --> C[中间节点 2]
 B --> D[叶子节点 1-4]
 B --> E[叶子节点 5-8]
 C --> F[叶子节点 9-12]
 C --> G[叶子节点 13-16]
 style A fill:#e76f51
 style B fill:#e9c46a
 style C fill:#e9c46a
 style D fill:#2a9d8f
 style E fill:#2a9d8f
 style F fill:#2a9d8f
 style G fill:#2a9d8f

B+Tree 特性	影响
数据都在叶子节点	查询路径长度固定
叶子节点双向链表	范围查询 O(log N)
非叶子节点只存键值	单页能放更多索引项
树高 3-4 层	千万级数据查询 < 4 次 IO

B+Tree 的物理结构（InnoDB 16KB 页）：

graph TD
 A[File Header
38 字节] --> B[Page Header
56 字节]
 B --> C[Infimum + Supremum
26 字节]
 C --> D[User Records
实际行数据]
 D --> E[Free Space
空闲空间]
 E --> F[Page Directory
槽位数组]
 F --> G[File Trailer
8 字节]
 style A fill:#e76f51
 style C fill:#e9c46a
 style D fill:#2a9d8f
 style F fill:#e9c46a
 style G fill:#e76f51

每页 16KB（innodb_page_size，默认）
每页最多 7992 行（行最小 2 字节，最大 8KB）
页内查找用二分：Page Directory 槽位记录偏移

页分裂（Page Split）：

随机插入 / 自增主键满时，InnoDB 会做页分裂——把一页拆成两页。页分裂 = 性能杀手：

拆页期间要加锁
产生磁盘碎片
顺序写变成随机写

对策：

主键用自增 ID（顺序写，几乎不分裂）
不要用 UUID（随机写，频繁分裂）
提前预留空间：innodb_fill_factor（8.0）

💡 原理：为什么 B+Tree 而不是 B-Tree 或 Hash

Hash 索引：等值查询 O(1)，但不支持范围查询、不支持排序

B-Tree：非叶子节点也存数据，范围查询要回根节点

B+Tree：数据全在叶子，叶子双向链表，范围查询一次扫描即可

MySQL InnoDB 的自适应哈希索引（AHI）是对 B+Tree 的"局部优化"——把热点页加载到内存 Hash。

4.3 索引优化的 12 条法则

法则 1：最左前缀原则

联合索引 (a, b, c) 相当于建了 (a)、(a, b)、(a, b, c) 三个索引，但不能跳过 a。

1
2
3
4
5
6
7


-- 走索引
SELECT * FROM t WHERE a = 1 AND b = 2;
SELECT * FROM t WHERE a = 1 AND b = 2 AND c = 3;
SELECT * FROM t WHERE a = 1;

-- 不走索引（跳过了 a）
SELECT * FROM t WHERE b = 2;

法则 2：避免在索引列上做计算

1
2
3
4
5


-- 错：索引失效
SELECT * FROM t WHERE YEAR(create_time) = 2025;

-- 对：范围查询
SELECT * FROM t WHERE create_time >= '2025-01-01' AND create_time < '2026-01-01';

法则 3：字符串前缀索引

1
2


-- 邮箱字段，前 10 个字符区分度已经够
ALTER TABLE user ADD INDEX idx_email_prefix (email(10));

法则 4：覆盖索引（Covering Index）

1
2
3


-- 表 user 有索引 (name, age)，查询只要 name 和 age
SELECT name, age FROM user WHERE name = 'tom';
-- 不需要回表 → 覆盖索引

法则 5：OR 改 UNION

1
2
3
4
5
6
7


-- 错：or 可能索引失效
SELECT * FROM t WHERE a = 1 OR b = 2;

-- 对：UNION ALL 拆开
SELECT * FROM t WHERE a = 1
UNION ALL
SELECT * FROM t WHERE b = 2;

法则 6：IN 控制在 1000 以内

1
2
3
4


-- MySQL IN 超过 1000 会拆成 OR，效率急剧下降
SELECT * FROM t WHERE id IN (1,2,3,...,999);
-- 改成 JOIN：
SELECT t.* FROM t JOIN temp_ids ON t.id = temp_ids.id;

法则 7：避免 SELECT *

1
2
3
4
5


-- 错：SELECT * 可能用不到覆盖索引
SELECT * FROM t WHERE user_id = 1;

-- 对：只查需要的列
SELECT id, name FROM t WHERE user_id = 1;

法则 8：NOT IN 改 NOT EXISTS

1
2
3
4
5
6
7


-- 错
SELECT * FROM t WHERE id NOT IN (SELECT id FROM blacklist);

-- 对
SELECT t.* FROM t WHERE NOT EXISTS (
 SELECT 1 FROM blacklist b WHERE b.id = t.id
);

法则 9：连接字段加索引

1
2
3


-- 任何 JOIN 字段必须加索引
ALTER TABLE order ADD INDEX idx_user_id (user_id);
ALTER TABLE order ADD INDEX idx_product_id (product_id);

法则 10：避免深分页

1
2
3
4
5


-- 错：limit 1000000, 20 → 扫 100 万行
SELECT * FROM t ORDER BY id LIMIT 1000000, 20;

-- 对：游标分页
SELECT * FROM t WHERE id > 1000000 ORDER BY id LIMIT 20;

法则 11：批量写入

1
2
3
4
5
6
7
8


-- 错：循环 1 万次 INSERT
for (Order o : orders) {
 insert(o);
}

-- 对：批量 INSERT
INSERT INTO order (...) VALUES (...),(...),(...) ... ;
-- 推荐每批 500-1000 行

法则 12：定期 ANALYZE TABLE

1
2


-- 重新统计索引基数（用于优化器决策）
ANALYZE TABLE order;

4.4 EXPLAIN 执行计划全解

EXPLAIN 是 MySQL 优化的"听诊器"。

1

EXPLAIN SELECT * FROM order WHERE user_id = 1 AND status = 'PAID';

字段	含义	优化目标
id	SELECT 序号	越大越先执行
select_type	类型	SIMPLE > PRIMARY > UNION > SUBQUERY
type	访问类型	system > const > eq_ref > ref > range > index > ALL
possible_keys	可能用的索引	多个候选
key	实际用的索引	NULL = 全表扫
key_len	索引长度	越短越好
rows	扫描行数（估算）	越小越好
Extra	额外信息	关注 Using filesort / Using temporary

type 字段 7 个等级（性能从高到低）：

1
2
3


system > const > eq_ref > ref > range > index > ALL
 ^^^^^^^^
 出现这个要警觉

type	含义	示例
system	系统表	SELECT * FROM mysql.proxied_user
const	主键 / 唯一索引等值	SELECT * FROM t WHERE id = 1
eq_ref	JOIN 主键 / 唯一索引	t1 JOIN t2 ON t1.id = t2.id
ref	非唯一索引	SELECT * FROM t WHERE name = ’tom'
range	索引范围	WHERE id > 100 AND id < 200
index	全索引扫	SELECT id FROM t（只查索引列）
ALL	全表扫	SELECT * FROM t WHERE name LIKE ‘%tom%’

📌 实践：EXPLAIN 看什么

type 是不是 ALL——出现 ALL 必须优化

rows 是不是过大——> 1000 行要警觉

Extra 是不是有 filesort / temporary——出现就考虑加索引

key 是不是 NULL——没走索引

key_len 是不是太小——联合索引没用到前列

4.5 MySQL 参数调优

不要照搬网上参数——要根据实际业务、机器配置、QPS 量级调。

内存相关（最关键）

参数	默认值	建议值	说明
`innodb_buffer_pool_size`	128MB	物理内存 50-70%	InnoDB 缓存池
`innodb_log_buffer_size`	16MB	64-256MB	redo log 缓冲
`key_buffer_size`	8MB	32MB	MyISAM 索引缓冲（基本无用）
`tmp_table_size`	16MB	64-256MB	临时表
`max_heap_table_size`	16MB	64-256MB	MEMORY 引擎表
`sort_buffer_size`	256KB	1-4MB	排序缓冲
`join_buffer_size`	256KB	1-4MB	JOIN 缓冲
`read_buffer_size`	128KB	1-2MB	全表扫读缓冲

连接相关

参数	默认值	建议值	说明
`max_connections`	151	1000-5000	最大连接数
`max_user_connections`	0	0	单用户最大连接
`wait_timeout`	28800	600	空闲连接超时（秒）
`interactive_timeout`	28800	600	交互超时

InnoDB 写入相关

参数	默认值	建议值	说明
`innodb_flush_log_at_trx_commit`	1	1 / 2	1=最安全；2=折中（每 1s 刷盘）
`sync_binlog`	1	1 / 0	1=安全；0=性能
`innodb_flush_method`	-	O_DIRECT	绕过 OS Cache
`innodb_io_capacity`	200	2000（SSD）	刷盘 IO 能力

🛑 误区警示：innodb_flush_log_at_trx_commit=2 是不是不安全？

不是。= 2 表示"每秒刷一次盘"，最多丢 1 秒数据。大多数业务（订单、用户）能接受 1 秒数据丢失以换取 10 倍写入性能。 金融场景必须 = 1。

二进制日志

参数	默认值	建议值	说明
`binlog_format`	ROW	ROW	推荐 ROW（数据一致）
`binlog_row_image`	FULL	FULL / MINIMAL	MINIMAL 减小 binlog
`expire_logs_days`	0	7-30	自动清理
`max_binlog_size`	1GB	512MB-1GB	单文件大小

💡 原理：binlog_format 怎么选

STATEMENT（默认）：记录 SQL 语句。日志小，但有主从一致性问题（如 NOW()）

ROW：记录行变更。日志大但绝对一致。生产推荐 ROW

MIXED：自动判断。别用，行为不可预期

4.6 MySQL 监控指标

SRE 必看 7 大指标：

指标	阈值	监控工具
QPS / TPS	< 80% 设计上限	Prometheus + mysqld_exporter
连接数使用率	< 80%	mysqld_exporter
InnoDB buffer pool 命中率	> 99%	命中率 = 1 - (Innodb_buffer_pool_reads / Innodb_buffer_pool_read_requests)
慢查询数量	< 0.1% 总查询	slow_query_log + pt-query-digest
主从延迟	< 1 秒	`Seconds_Behind_Master`
锁等待	0 长锁	`SHOW ENGINE INNODB STATUS`
磁盘 IO 利用率	< 70%	iostat

🎯 避坑点：buffer pool 命中率

命中率 < 99% 通常意味着热点数据 > buffer pool。 不要急着加内存——先看：

是不是有全表扫占用了 buffer pool（SHOW ENGINE INNODB STATUS 看 LRU 列表）

是不是有 SELECT * 拉大对象

是不是表数据本身远大于内存

盲加内存是治标不治本。

五、PostgreSQL 何时上位 + 杀手特性

5.1 何时该迁到 PG

MySQL 没死，但有些场景 MySQL 就是干不过 PG。

场景 1：复杂 SQL 报表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- PG 窗口函数：一行 SQL 算同比环比
SELECT 
 region,
 month,
 revenue,
 revenue - LAG(revenue, 1) OVER (PARTITION BY region ORDER BY month) AS mom_diff,
 (revenue - LAG(revenue, 12) OVER (PARTITION BY region ORDER BY month)) 
 / NULLIF(LAG(revenue, 12) OVER (PARTITION BY region ORDER BY month), 0) AS yoy_rate
FROM monthly_sales
WHERE month >= '2024-01-01';

-- MySQL 8.0 才支持窗口函数，但优化器没 PG 强

场景 2：GIS 地理信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


-- PG + PostGIS：找用户附近 5 公里的所有商家
SELECT s.*, 
 ST_Distance(s.location, ST_MakePoint(116.4, 39.9)::geography) AS dist_m
FROM shop s
WHERE ST_DWithin(
 s.location, 
 ST_MakePoint(116.4, 39.9)::geography, 
 5000
)
ORDER BY dist_m ASC
LIMIT 20;

场景 3：半结构化数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


-- PG JSONB：可索引
CREATE TABLE product (
 id BIGSERIAL PRIMARY KEY,
 name TEXT,
 attrs JSONB
);
CREATE INDEX idx_attrs ON product USING gin (attrs);

-- 查询 attrs->>'brand' = 'Apple'
SELECT * FROM product WHERE attrs @> '{"brand": "Apple"}';

场景 4：递归查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


-- PG 递归 CTE：组织树 / 评论树
WITH RECURSIVE org_tree AS (
 SELECT id, name, parent_id, 0 AS depth
 FROM department
 WHERE parent_id IS NULL
 
 UNION ALL
 
 SELECT d.id, d.name, d.parent_id, t.depth + 1
 FROM department d
 JOIN org_tree t ON d.parent_id = t.id
)
SELECT * FROM org_tree ORDER BY depth;

场景 5：严格一致性

1
2
3


-- PG 严格遵循 SQL 标准
-- 支持 SERIALIZABLE 隔离级别（MySQL 没有真正的 SERIALIZABLE）
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;

5.2 PG 杀手特性详解

5.2.1 JSONB vs MySQL JSON

维度	MySQL JSON	PG JSONB
存储格式	文本	二进制（解析快）
索引	虚拟列	原生 GIN 索引
查询语法	`JSON_EXTRACT`	`->>` `->` `@>`
性能	一般	快 2-10 倍

5.2.2 MVCC 的优势

MVCC（Multi-Version Concurrency Control）：

MySQL InnoDB：通过 undo log 实现，长事务会膨胀 undo 表空间
PostgreSQL：每行存两个 xmin/xmax，老版本在 vacuum 时清理

📌 实践：autovacuum 调优

PG 的 MVCC 优势是"读不阻塞写、写不阻塞读"。但老版本数据不清理会膨胀。autovacuum 必须调好：

参数默认建议说明

autovacuum_vacuum_scale_factor 0.2 0.05-0.1 触发 vacuum 的死行比例

autovacuum_analyze_scale_factor 0.1 0.05 触发 analyze 的变更比例

autovacuum_vacuum_cost_limit 200 1000-2000 vacuum 速度

autovacuum_max_workers 3 4-8 并发 worker 数

大表要单独配 autovacuum：ALTER TABLE big_table SET (autovacuum_vacuum_scale_factor = 0.02)

5.2.3 复制方案

PG 有 3 种复制：

复制方式	说明	用途
流复制（Streaming Replication）	基于 WAL，类似 binlog	高可用、读写分离
逻辑复制（Logical Replication）	基于发布订阅，跨版本	数据迁移、聚合
级联复制（Cascading Replication）	多级从库	异地灾备

1
2
3
4
5


-- 创建发布
CREATE PUBLICATION pub_orders FOR TABLE orders, order_items;

-- 订阅端
CREATE SUBSCRIPTION sub_orders CONNECTION 'host=primary port=5432 user=repl password=xxx dbname=app' PUBLICATION pub_orders;

5.2.4 分区表

PG 10+ 原生分区表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


-- 范围分区（按时间）
CREATE TABLE order (
 id BIGSERIAL,
 user_id BIGINT,
 amount DECIMAL(10,2),
 created_at TIMESTAMPTZ
) PARTITION BY RANGE (created_at);

CREATE TABLE order_2025 PARTITION OF order
 FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

CREATE TABLE order_2026 PARTITION OF order
 FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');

5.3 PG 参数调优

内存相关

参数	默认值	建议值	说明
`shared_buffers`	128MB	物理内存 25%	PG 缓存池
`work_mem`	4MB	32-256MB	排序/哈希缓冲
`maintenance_work_mem`	64MB	512MB-2GB	vacuum / CREATE INDEX
`effective_cache_size`	4GB	物理内存 50-75%	给优化器的"提示"
`huge_pages`	try	try	大内存机器开启

WAL 相关

参数	默认值	建议值	说明
`wal_level`	replica	replica / logical	logical 启用逻辑复制
`max_wal_size`	1GB	4-16GB	WAL 总大小
`min_wal_size`	80MB	1-2GB	WAL 最小保留
`checkpoint_completion_target`	0.5	0.9	减少 checkpoint 抖动

🎯 避坑点：work_mem 调多大

work_mem 是每个操作的内存，不是全局

一个复杂查询可能有 10 个 sort 节点 → 实际占用 10 × work_mem

1000 个并发连接 × work_mem 256MB = 256GB 内存需求

生产建议 32-64MB，复杂查询用 SET LOCAL work_mem = '1GB'; 临时调大

六、主从复制 + 读写分离

6.1 复制原理

graph LR
 A[主库写入] --> B[binlog dump 线程]
 B --> C[从库 IO 线程
拉 binlog]
 C --> D[relay log]
 D --> E[从库 SQL 线程
重放]
 E --> F[从库数据]
 style A fill:#e76f51
 style F fill:#2a9d8f

三步流程：

主库：所有数据变更写 binlog（ROW 模式）
从库 IO 线程：拉主库 binlog，写入本地 relay log
从库 SQL 线程：重放 relay log 到从库

6.2 复制模式

模式	延迟	安全性	适用
异步（默认）	10-100ms	主库挂丢数据	普通业务
半同步	+1 RTT	主库挂最多丢 1 秒	重要业务
增强半同步	+1-2 RTT	主库挂不丢	金融

SHOW SLAVE STATUS 关键指标（MySQL 8.0 后是 SHOW REPLICA STATUS）：

字段	期望	异常处理
`Slave_IO_Running: Yes`	必须 Yes	No → 网络/账号问题
`Slave_SQL_Running: Yes`	必须 Yes	No → SQL 线程挂了
`Seconds_Behind_Master: 0`	0	> 0 → 主从延迟
`Master_Log_File` / `Read_Master_Log_Pos`	持续增长	不动 → IO 线程有问题
`Relay_Master_Log_File` / `Exec_Master_Log_Pos`	持续增长	不动 → SQL 线程卡住
`Last_Error`	空	非空 → 看错误码

GTID 模式（强烈推荐）

GTID = Global Transaction Identifier，每个事务全局唯一。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- 主库配置
gtid_mode = ON
enforce_gtid_consistency = ON

-- 从库 CHANGE MASTER
CHANGE MASTER TO
 MASTER_HOST='master.host',
 MASTER_USER='repl',
 MASTER_PASSWORD='xxx',
 MASTER_AUTO_POSITION=1; -- 用 GTID 自动定位

START SLAVE;

💡 原理：GTID 解决什么

不开启 GTID 的痛点：

主从切换需要找 binlog file + position（容易错）

级联复制链路复杂（A → B → C，B 故障时 C 找不到位点）

跳过一个错误要手动算位点

开启 GTID 的好处：

自动定位，无需 file + position

跳过错误简单：SET GTID_NEXT='xxx'; BEGIN; COMMIT; SET GTID_NEXT='AUTOMATIC';

故障切换几乎是零配置

6.3 主从延迟的 7 种解决方案

主从延迟是读写分离最大的坑。常见解法：

方案	原理	适用
强制读主	写后立即读主库	强一致场景
Session 标记	同一个 session 写后短时间走主	简单业务
缓存标记	写时在缓存记录 N 秒"读主"标记	通用
查主库判断	读从前先查"是否最近写过"	极端场景
GTID 等待	从库等到指定 GTID 应用完	MySQL 5.7+
延迟监控 + 告警	延迟 > 阈值告警	必须有
业务回避	不做读写分离	一致性要求极高

最推荐"缓存标记法"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


public void write(Order order) {
 // 写主库
 orderRepository.save(order);
 
 // 写后 1 秒内强制读主
 redisTemplate.opsForValue().set(
 "force-master:" + order.getUserId(),
 "1",
 1, TimeUnit.SECONDS
 );
}

public Order read(Long userId, Long orderId) {
 // 查从库前看是否要强制主
 Boolean force = redisTemplate.hasKey("force-master:" + userId);
 if (force) {
 return orderRepository.findMasterById(orderId);
 }
 return orderRepository.findSlaveById(orderId);
}

6.4 读写分离中间件对比

中间件	模式	性能	复杂度	适用
ShardingSphere-JDBC	客户端 jar	最优（无网络跳）	低	Java 应用首选
ShardingSphere-Proxy	代理	中	中	跨语言
MyCat	代理	中	高	复杂分库分表
MaxScale	代理	中	中	MariaDB
ProxySQL	代理	中	中	MySQL

📌 实践：选型建议

纯 Java 应用：ShardingSphere-JDBC（性能最好）

多语言应用：ShardingSphere-Proxy

只用读写分离，不分库分表：ProxySQL / 自研 AOP

七、分库分表

7.1 何时分库分表

经验阈值（InnoDB + 良好索引）：

指标	阈值	风险
单表行数	5000 万	查询性能下降
单表容量	50GB	DDL 变慢
单库 QPS	1-3 万	CPU 打满
写并发	5000 TPS	主从延迟

🎯 避坑点：分库分表不是"应不应该"，是"什么时候"

< 1000 万行：坚决不分

1000 万 - 5000 万：加索引 + 优化 SQL 还能撑

5000 万 - 5 亿：分库分表

> 5 亿：直接上分布式数据库

提前分库分表是过早优化，推迟分库分表是踩坑。

7.2 拆分维度

垂直拆分

graph TD
 A[原始库 db_app] --> B[用户库 db_user]
 A --> C[订单库 db_order]
 A --> D[商品库 db_product]
 style A fill:#e76f51
 style B fill:#2a9d8f
 style C fill:#2a9d8f
 style D fill:#2a9d8f

垂直分库：按业务边界拆。最简单、最有用，应该第一个做。

垂直分表：宽表拆主表 + 扩展表。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


-- 主表（常用字段）
CREATE TABLE user (
 id BIGINT PRIMARY KEY,
 username VARCHAR(50),
 nickname VARCHAR(50),
 avatar VARCHAR(200),
 created_at TIMESTAMP
);

-- 扩展表（不常用字段）
CREATE TABLE user_ext (
 user_id BIGINT PRIMARY KEY,
 bio TEXT,
 address TEXT,
 extra JSON
);

水平拆分

graph TD
 A[订单 order] --> B[order_0]
 A --> C[order_1]
 A --> D[order_2]
 A --> E[order_3]
 B --> F[db_0]
 C --> F
 D --> G[db_1]
 E --> G
 style B fill:#2a9d8f
 style C fill:#2a9d8f
 style D fill:#2a9d8f
 style E fill:#2a9d8f

水平分库：同一张表的数据按规则分到不同库。 水平分表：同一张表的数据按规则分到同库不同表。

7.3 Sharding 策略

策略	优点	缺点	适用
Hash 取模	分布均匀	扩容要数据迁移	通用
Range 范围	不迁移老数据	热点（最新数据访问多）	时序数据
List 列表	业务清晰	数据不均	业务隔离
地理分片	用户延迟低	跨区数据不一致	O2O
一致性 Hash	扩容只影响 1/N	复杂度高	大规模

Hash 取模最常用：

1
2
3
4
5


// 64 库 × 64 表 = 4096 分片
int dbIndex = (int)(userId % 64);
int tableIndex = (int)((userId / 64) % 64);
String tableName = "order_" + tableIndex;
// 实际 SQL: SELECT * FROM db_0.order_15 WHERE user_id = ?;

7.4 分布式主键

分库分表后，自增 ID 失效。常见方案：

方案	性能	全局唯一	推荐度
UUID	优	是	缺点：占空间、无序
Snowflake（雪花算法）	优	是	推荐
美团 Leaf	优	是	推荐
数据库号段	中	是	中小厂
Redis incr	中	是	中小厂

Snowflake 64 位结构：

1
2
3
4


0 | 0000000... | 0000000000 0000000000 0000000000 0000000000 0000 | 00000 | 00000
 ^ 41 位时间戳（毫秒） ^^^^^^^^^^^^ ^^^^^ ^^^^^
 符号 基准 2020-01-01 12 位序列 5 位 5 位
 (每毫秒 4096) 数据中心 机器

每毫秒可生成 4096 个 ID，每秒 409.6 万。

 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


public class Snowflake {
 private final long datacenterId;
 private final long workerId;
 private long sequence = 0L;
 private long lastTimestamp = -1L;
 
 public synchronized long nextId() {
 long timestamp = System.currentTimeMillis();
 if (timestamp < lastTimestamp) {
 throw new RuntimeException("Clock moved backwards");
 }
 if (timestamp == lastTimestamp) {
 sequence = (sequence + 1) & 4095;
 if (sequence == 0) {
 timestamp = waitNextMillis();
 }
 } else {
 sequence = 0L;
 }
 lastTimestamp = timestamp;
 return ((timestamp - 2020_01_01_EPOCH) << 22)
 | (datacenterId << 17)
 | (workerId << 12)
 | sequence;
 }
}

7.5 跨库查询 + 跨库事务

跨库查询

分库分表最大的代价：

1
2
3
4
5


-- 这条 SQL 走不了分库分表
SELECT o.*, u.username 
FROM order o JOIN user u ON o.user_id = u.id
WHERE o.id = 12345;
-- order 在分库 0 的 order_15，user 在分库 32

解决方案：

方案	思路	适用
业务层 JOIN	先查 order 拿到 user_id，再查 user	简单但要 2 次查询
宽表冗余	order 表冗余 username 字段	适合读多写少
搜索引擎	全量同步到 ES，在 ES 查	适合复杂查询
数据仓库	T+1 同步到 Hive / ClickHouse	适合 OLAP
广播表	小表（字典）全库冗余	字典类

跨库事务

分布式事务的 4 种方案（已在前作展开）：

方案	一致性	性能	复杂度
2PC	强	差	高
TCC	强	中	高
Saga	最终	好	中
本地消息表	最终	好	低

Seata AT 模式：业界主流

Seata = Simple Extensible Autonomous Transaction Architecture，阿里开源。AT 模式是其默认工作模式：

graph TD
 A[TM 事务管理器] -->|begin| B[分支事务 1
order]
 A -->|begin| C[分支事务 2
account]
 A -->|begin| D[分支事务 3
storage]
 B -->|commit/rollback| E[RM 资源管理器]
 C -->|commit/rollback| E
 D -->|commit/rollback| E
 A --> F[TC 事务协调者]
 style A fill:#e76f51
 style F fill:#e9c46a
 style E fill:#2a9d8f

AT 模式的"魔法"：

第一阶段：执行业务 SQL，生成 undo log（前镜像），不提交
第二阶段：TC 看所有分支都成功 → 全局提交；任一失败 → 用 undo log 回滚
应用层无感知：基于数据源代理（DataSourceProxy）自动接管

AT 模式的限制：

必须是关系型数据库
SQL 必须是单条（不支持跨 SQL 事务）
全局锁依赖 TC，TC 单点问题

🛑 误区警示：尽量不用分布式事务

能用业务回避就别用事务。

把"扣库存 + 下订单"拆成"先预占库存再下单 + 异步扣库存"

用最终一致性 + 对账保证正确性

99% 的分布式事务场景可以用业务设计绕开

7.6 ShardingSphere 实战

ShardingSphere 5.x 是当前 Java 生态首选。

 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


# application.yml
spring:
 shardingsphere:
 datasource:
 names: ds0,ds1
 ds0:
 type: com.zaxxer.hikari.HikariDataSource
 jdbc-url: jdbc:mysql://10.0.0.1:3306/db_order_0
 ds1:
 type: com.zaxxer.hikari.HikariDataSource
 jdbc-url: jdbc:mysql://10.0.0.2:3306/db_order_1
 rules:
 sharding:
 tables:
 order:
 actual-data-nodes: ds$->{0..1}.order_$->{0..15}
 database-strategy:
 standard:
 sharding-column: user_id
 sharding-algorithm-name: db-mod
 table-strategy:
 standard:
 sharding-column: user_id
 sharding-algorithm-name: tbl-mod
 sharding-algorithms:
 db-mod:
 type: MOD
 props:
 sharding-count: 2
 tbl-mod:
 type: MOD
 props:
 sharding-count: 16

八、NewSQL 三剑客

8.1 TiDB 详解

TiDB = MySQL 协议 + 分布式架构。

组件	作用
TiDB Server	SQL 层，无状态，可横向扩
PD（Placement Driver）	集群调度 + TSO 时间戳
TiKV	存储层，基于 RocksDB + Raft

graph LR
 A[应用] --> B[TiDB Server 1]
 A --> C[TiDB Server 2]
 A --> D[TiDB Server 3]
 B --> E[PD]
 C --> E
 D --> E
 B --> F[TiKV]
 B --> G[TiKV]
 C --> G
 C --> H[TiKV]
 D --> H
 D --> F
 F -.Raft 3副本.- G
 G -.Raft 3副本.- H
 H -.Raft 3副本.- F
 style B fill:#e76f51
 style C fill:#e76f51
 style D fill:#e76f51

优势	说明
MySQL 兼容	95% 场景无需改代码
水平扩展	加 TiKV 节点即扩
强一致	Raft + Percolator 事务
HTAP	TiFlash 列存引擎支持 OLAP
自动 Rebalance	不停服迁移数据

劣势	说明
运维复杂	至少 6 个组件（3 TiDB + 3 PD + 3 TiKV + TiFlash）
大事务支持差	单事务 < 100MB 限制
二级索引	全局索引有性能开销
成本	3 副本起步，资源消耗 3 倍

8.2 OceanBase 详解

OceanBase = 原生分布式 + 金融级。

优势	说明
Paxos 多副本	强一致 + 高可用
Oracle 兼容	替代 Oracle
HTAP	同一份数据 OLTP + OLAP
多模	兼容 MySQL、Oracle、PG

关键事件：

2010：阿里立项
2014：双 11 抗住 8 万笔/秒
2019：OceanBase 1.0 开源
2020：TPC-C 基准测试 7.07 亿 tpmC（世界第一）
2023：OceanBase 4.0 GA

8.3 PolarDB 详解

PolarDB = 存储计算分离。

graph LR
 A[应用] --> B[PolarDB 写节点]
 A --> C[PolarDB 读节点 1]
 A --> D[PolarDB 读节点 2]
 B --> E[共享存储
PolarStore]
 C --> E
 D --> E
 style B fill:#e76f51
 style C fill:#2a9d8f
 style D fill:#2a9d8f
 style E fill:#e9c46a

核心创新：

共享存储：所有节点挂同一份数据，读节点无延迟
RDMA 网络：节点间通信 < 100us
并行回放：从库并行重放 redo log

8.4 选型决策树

graph TD
 A[开始] --> B{业务量?}
 B -->|< 5000 万行| C[单库 MySQL/PG]
 B -->|5000 万 - 10 亿| D{需要分库分表?}
 B -->|> 10 亿| E[NewSQL 分布式]
 D -->|是| F{跨库 JOIN 多?}
 D -->|否| G[MySQL 主从 + 读写分离]
 F -->|是| E
 F -->|否| H[ShardingSphere 分库分表]
 E --> I{协议兼容?}
 I -->|MySQL| J[TiDB / OceanBase]
 I -->|PostgreSQL| K[CockroachDB / YugabyteDB]
 I -->|云原生| L[PolarDB / Aurora]
 style A fill:#f4a261
 style E fill:#e76f51
 style J fill:#2a9d8f
 style K fill:#2a9d8f
 style L fill:#2a9d8f

8.5 一致性协议速览

协议	特点	代表
Paxos	经典，难懂	OceanBase、Chubby
Raft	易懂的 Paxos	TiKV、etcd、CockroachDB
ZAB	ZK 专属	ZooKeeper
EPaxos	Paxos 改进	学术
Parallel Raft	Raft 并行	PolarDB

💡 原理：Raft 怎么保证一致

Leader 选举：多数派投票选主

日志复制：Leader 接收写，复制到多数 Follower

提交时机：多数派落盘才提交

脑裂解决：通过 Term（任期号）防旧 Leader 复活

九、容灾 + 备份

9.1 容灾等级

等级	描述	RTO	RPO	成本
L0	无备份	-	-	0
L1	本地备份	数小时	数小时	1x
L2	本地 + 异地备份	数小时	数小时	1.2x
L3	热备（同城）	分钟	0	2x
L4	双活（同城）	秒	0	3-4x
L5	双活（异地）	秒	秒	5-8x
L6	多活（异地）	秒	0	10-15x

9.2 备份策略

3-2-1 备份铁律：

3 份数据副本
2 种存储介质（如本地 + 异地）
1 份离线（防勒索病毒）

物理备份 vs 逻辑备份

维度	物理备份	逻辑备份
工具	xtrabackup / pg_basebackup	mysqldump / pg_dump
速度	快（直接拷文件）	慢（逐行转 SQL）
压缩	高	中
恢复速度	快	慢
跨版本	不支持	支持
跨平台	受限	不受限
适用	大库（> 100GB）	小库、结构迁移

9.3 xtrabackup 实战

xtrabackup 是 MySQL 物理备份的首选工具（Percona 开源）。

xtrabackup 工作原理（关键 4 步）：

graph TD
 A[1. 启动备份
记录 LSN checkpoint] --> B[2. 拷贝 InnoDB 文件
后台持续跟踪 redo log]
 B --> C[3. 持续拷贝期间
所有新写入的 redo log]
 C --> D[4. 停止拷贝
flush tables with read lock]
 D --> E[5. 拷贝非 InnoDB 文件
frm / ibd / binlog 索引]
 E --> F[6. unlock tables]
 F --> G[7. prepare 阶段
apply redo log + undo log]
 G --> H[8. 备份完成
一致性快照]
 style A fill:#e9c46a
 style B fill:#2a9d8f
 style G fill:#e9c46a
 style H fill:#2a9d8f

xtrabackup 的"魔法"是：备份期间不锁库——通过持续跟踪 redo log 拿到一致性快照。这比 mysqldump 在线备份强 10 倍。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# 全量备份
xtrabackup --backup \
 --target-dir=/data/backup/full/2026-06-09 \
 --user=backup --password=xxx

# 准备（apply-log）
xtrabackup --prepare \
 --target-dir=/data/backup/full/2026-06-09

# 恢复
xtrabackup --copy-back \
 --target-dir=/data/backup/full/2026-06-09 \
 --datadir=/var/lib/mysql

# 增量备份
xtrabackup --backup \
 --target-dir=/data/backup/inc/2026-06-09 \
 --incremental-basedir=/data/backup/full/2026-06-08 \
 --user=backup

📌 实践：xtrabackup 备份策略

全量备份：每周一次（业务低峰期）

增量备份：每天一次

binlog 备份：实时（用 mysqlbinlog 或复制到远程）

保留期：全量 30 天，增量 7 天，binlog 14 天

9.4 PITR（Point-in-Time Recovery）

PITR = 时间点恢复。从全量备份 + binlog 恢复到任意时间点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 假设误操作发生在 14:32:00，要恢复到 14:31:00

# 1. 恢复全量备份
xtrabackup --prepare --target-dir=/data/backup/full/2026-06-09
xtrabackup --copy-back --target-dir=/data/backup/full/2026-06-09

# 2. 启动 MySQL，配置只应用到 14:31:00
# 启动后用 mysqlbinlog 过滤
mysqlbinlog --stop-datetime="2026-06-09 14:31:00" \
 /var/lib/mysql/binlog.000123 \
 | mysql -u root

# 3. 验证数据 OK 后，重启 MySQL

9.5 PostgreSQL 备份

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 逻辑备份
pg_dump -h localhost -U postgres -F c -b -v -f "backup_$(date +%Y%m%d).dump" mydb

# 恢复
pg_restore -h localhost -U postgres -d mydb_new backup.dump

# 物理备份（PG 17+ pg_basebackup 增量）
pg_basebackup -D /data/backup/base -Fp -Xs -P

# 持续归档（用于 PITR）
# postgresql.conf
wal_level = replica
archive_mode = on
archive_command = 'cp %p /data/wal_archive/%f'

9.6 备份验证：恢复演练

最关键的步骤——备份没演练 = 不存在。

graph TD
 A[生产数据] -->|备份| B[备份文件]
 B -->|恢复演练| C[临时环境]
 C -->|验证脚本| D[数据一致性检查]
 D -->|通过| E[标记备份可信]
 D -->|失败| F[排查问题]
 F --> A
 style A fill:#e76f51
 style B fill:#e9c46a
 style C fill:#e9c46a
 style E fill:#2a9d8f
 style F fill:#e76f51

演练清单：

每月一次：全量备份恢复演练（人工）
每季度一次：PITR 演练（恢复到指定时间点）
每年一次：跨机房灾备切换演练
每季度一次：核对备份文件大小、时间、压缩率
每月一次：检查备份脚本日志，告警是否正常

🛑 误区警示：这些坑别踩

备份完从不验证——某公司 3 年备份全部损坏

备份和数据库在同一块盘——磁盘坏了备份也没了

没做异地备份——机房故障 = 全丢

没加密——备份文件泄露 = 数据泄露

没做定期恢复演练——真出事时手忙脚乱

十、真实案例

10.1 某电商：MySQL → TiDB 的迁移史

背景：订单库单表 8 亿行，主从延迟 30 秒，分库分表 128 库 × 16 表。

痛点：

跨库 JOIN 几乎不可用
扩容要全量迁移，耗时 72 小时
分布式事务（Seata）性能损失 30%
DBA 维护 2000+ 分片

方案：

第 1 期：核心订单库迁 TiDB（2023）
第 2 期：迁移商品库（2024）
第 3 期：迁移用户库（2025）

收益：

单库扩到 30 个 TiKV 节点
SQL 改造 5%（MySQL 协议）
跨表 JOIN 性能提升 10 倍
运维复杂度下降 50%

教训：

不要一次性迁全量：分库分批迁移
写好回滚预案：每次迁移都要有回滚方案
性能基线对比：迁移前后必须做压测对比

10.2 某金融：从 Oracle 到 OceanBase

背景：传统银行核心系统，Oracle RAC + 小型机。

痛点：

Oracle 授权费高（年 1000 万+）
RAC 扩展性差，最多 8 节点
国产化合规要求

方案：

数据库国产化：OceanBase 替代 Oracle
应用改造：10% SQL 调整（兼容 Oracle 语法）
灾备：3 地 5 中心部署

收益：

授权费归零
节点扩到 30+
性能持平或略优
通过等保 2.0

10.3 某 SaaS：MySQL → PostgreSQL

背景：CRM 系统，复杂查询多（多表 JOIN + 窗口函数）。

痛点：

MySQL 5.7 优化器对复杂 SQL 支持差
一个 10 表 JOIN 查询要 30 秒
GIS 功能缺失（附近客户查询）

方案：

业务层改造：用 PG 的 CTE、窗口函数重写
数据迁移：logical replication（MySQL → PG）
工具链：MyBatis 适配 PG dialect

收益：

复杂查询从 30 秒降到 1.5 秒
PostGIS 替代 MongoDB（数据一致性更好）
报表 SQL 简化 60%

十一、总结

11.1 数据库演化的 3 大核心要素

业务匹配：根据数据量、QPS、一致性要求选型
渐进演化：单机 → 主从 → 分库分表 → 分布式，不要一步到位
容灾底线：3-2-1 备份铁律 + 异地灾备 + 恢复演练

11.2 何时不该上分布式数据库

业务特征	推荐方案
数据量 < 5000 万	单机 MySQL/PG
数据量 5000 万 - 10 亿	分库分表 + 缓存
写为主（> 5000 TPS）	分库分表优于 NewSQL
强 GIS / 复杂查询	PG 优先
强 SQL 规范	PG 优先

分布式数据库的 ROI 拐点在"单表 10 亿 + 跨库 JOIN 多"。低于这个规模做了也是浪费。

11.3 常见陷阱

🛑 误区警示：这些坑别踩

盲目上 NewSQL：业务量没到，成本先到

忽视 SQL 优化：先 EXPLAIN 再谈架构

不验证备份：3 年没演练过

盲目分库分表：500 万行就分，运维成本爆炸

忽视 PG 优势：复杂查询死磕 MySQL

不监控：buffer pool 命中率、慢查询、主从延迟

不升级 MySQL：还在用 5.6 / 5.7

11.4 系列预告

这是 Java Web 微服务系列 的第 8 篇。后续计划：

服务治理：服务发现、配置中心、熔断降级
网关与限流：Spring Cloud Gateway、Sentinel
分布式事务：Seata、Saga、TCC 模式对比
链路追踪：SkyWalking、Jaeger
Spring Cloud Alibaba 实战：Nacos + Sentinel + Seata 三件套
可观测性体系：Metrics + Logging + Tracing
Kubernetes 落地：从 Docker 到 K8s 的完整路径
多活架构：单元化、流量调度、灰度发布

十二、数据库实施清单

12.1 选型层 Checklist

数据量评估：当前 + 3 年 + 5 年
QPS 评估：日常 + 大促 + 业务峰值
一致性要求：强一致 / 最终一致
特性需求：GIS / JSON / 复杂查询
生态评估：团队熟悉度 + 招聘难度
成本评估：授权费 + 机器 + 运维人力

12.2 性能层 Checklist

索引设计：联合索引遵循最左前缀
慢查询治理：每月清理 top 10 慢 SQL
EXPLAIN 检查：关键 SQL 都跑过 EXPLAIN
参数调优：buffer pool、work_mem、shared_buffers
监控告警：7 大指标全埋点
批量写入：避免循环单条 INSERT
深分页改造：游标分页替代 OFFSET

12.3 高可用层 Checklist

主从复制：GTID + 增强半同步
读写分离：ShardingSphere-JDBC
自动故障切换：MHA / Orchestrator
主从延迟监控：> 1 秒告警
连接数管理：池化 + 限流
熔断降级：Sentinel / Resilience4j

12.4 容灾层 Checklist

3-2-1 备份：3 份、2 种介质、1 离线
定期演练：每月恢复演练
异地备份：至少 100 公里外
PITR 验证：时间点恢复演练
binlog 归档：保留 14 天+
灾备切换 Runbook：写好且演练过
数据校验：备份完成后自动校验

12.5 团队层 Checklist

DBA 能力：能讲清楚 EXPLAIN + binlog 原理
SRE 能力：能做故障切换演练
研发能力：懂索引优化 + 分库分表
值班制度：7×24 数据库故障响应
复盘机制：每次故障 24 小时内复盘

十三、常见问题 FAQ

Q1：MySQL 单表 1000 万行就一定要分表吗？

A：不是。

单表 1000 万行在 InnoDB + 良好索引下毫无压力。要看的不是行数，而是：

实际查询响应时间（> 100ms 要优化）
索引深度（B+Tree 树高 > 4 才考虑）
DDL 时间（> 1 小时考虑分表）

不要为了分表而分表。

Q2：分库分表后 JOIN 怎么办？

A：尽量避免跨库 JOIN。

替代方案：

业务层 JOIN：先查 A 拿 ID 列表，再查 B（接受 N+1）
宽表冗余：A 表冗余 B 的常用字段
搜索引擎：全量同步到 ES
数据仓库：T+1 同步到 OLAP

90% 的跨库 JOIN 可以通过业务改造绕开。

Q3：TiDB 和 OceanBase 怎么选？

A：看场景。

维度	TiDB	OceanBase
协议	MySQL	MySQL / Oracle / PG
一致性	Raft	Paxos
HTAP	TiFlash	OB 自带
生态	开源、社区	阿里主导 + 开源
Oracle 兼容	不支持	支持
适合	互联网、MySQL 替代	金融、Oracle 替代

MySQL 替代选 TiDB，Oracle 替代选 OceanBase。

Q4：MySQL 主从切换怎么做？

A：用 MHA / Orchestrator / MGR。

工具	特点
MHA	老牌，脚本方式，10 秒切换
Orchestrator	Web 界面，MySQL 官方推荐
MGR	MySQL 官方方案，但写性能差
ProxySQL + MHA	代理 + 自动切换

生产推荐 Orchestrator——可视化、自动选主、告警齐全。

Q5：xtrabackup 备份期间影响业务吗？

A：会有一些影响，但可控。

影响：
- 备份期间磁盘 IO 升高 10-20%
- 长事务的 undo log 备份会锁
- 大库（> 1TB）备份时长 4-8 小时
优化：
- 业务低峰期备份
- 用 --parallel=8 并行
- 用 --throttle=200 限速
- 用 --rsync 减少锁

核心库建议凌晨 2-6 点备份。

Q6：PostgreSQL 的 autovacuum 怎么调？

A：分表配置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


-- 大表单独配（普通表可以保留默认）
ALTER TABLE big_order SET (
 autovacuum_vacuum_scale_factor = 0.02, -- 2% 死行触发
 autovacuum_analyze_scale_factor = 0.01, -- 1% 触发 analyze
 autovacuum_vacuum_cost_limit = 2000
);

-- 看 autovacuum 状态
SELECT relname, 
 n_live_tup, n_dead_tup, 
 last_autovacuum, last_autoanalyze
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC
LIMIT 10;

Q7：分布式数据库还要不要分库分表？

A：不要。

TiDB / OceanBase / CockroachDB 已经做了分片，再分库分表是重复建设。

应用层只看到一个逻辑库
数据库自己分片、扩缩、Rebalance
跨节点 JOIN / 事务由数据库自己处理

迁到 NewSQL 后，把分库分表中间件全下掉。

Q8：数据库故障时怎么快速止血？

A：预案 + 演练。

标准止血动作（5 分钟内）：

KILL 长事务：SHOW PROCESSLIST; KILL <id>;
切只读：SET GLOBAL read_only = 1;（让写流量失败而非拖死）
降级非核心业务：关掉报表、推荐、对账
重启主库：最后手段，先备份数据再重启
切主库：主库不可用时切到从库

平时就要演练——真出事时手忙脚乱 = 二次事故。

十四、推荐阅读

官方文档：

MySQL 8.0 Reference Manual：https://dev.mysql.com/doc/refman/8.0/en/
PostgreSQL 16 Documentation：https://www.postgresql.org/docs/16/
TiDB Documentation：https://docs.pingcap.com/
OceanBase Documentation：https://www.oceanbase.com/docs/

书籍：

《高性能 MySQL》（Baron Schwartz）—— MySQL 优化的必读圣经
《MySQL 8.0 高级应用与调优》（张甦）—— 国产佳作
《PostgreSQL 实战》（唐成）—— 中文 PG 实战
《数据密集型应用系统设计》（DDIA, Martin Kleppmann）—— 分布式系统圣经
《大型网站技术架构：核心原理与案例分析》（李智慧）—— 阿里专家作品

技术博客：

阿里云数据库团队博客：RDS、PolarDB、OceanBase 实战
PingCAP 技术博客：TiDB 原理与最佳实践
Percona Database Performance Blog：MySQL 优化全球权威
美团技术团队：数据库运维与分库分表
字节跳动技术博客：分布式数据库落地

开源项目：

TiDB：https://github.com/pingcap/tidb
OceanBase：https://github.com/oceanbase/oceanbase
ShardingSphere：https://github.com/apache/shardingsphere
Percona XtraBackup：https://github.com/percona/percona-xtrabackup
pgcli（PG 命令行）：https://github.com/dbcli/pgcli

💡 学习路径建议

入门：本文 + MySQL 8.0 官方文档，2 周能上手

进阶：阿里 / PingCAP / Percona 博客，理解工业实践

实战：用 ShardingSphere 搭一个分库分表 demo

深潜：读 TiDB 源码（建议从 tidb/server 入口），理解分布式 SQL 引擎

理论 + 实践 + 源码，缺一不可。

参考文章

Jenkins 流水线：Java 微服务从代码提交到金丝雀发布的完整 CI/CD 实战

Tue, 09 Jun 2026 00:00:00 +0000

Java Web 微服务系列 · 第 9 篇 · Jenkins 流水线 / 完整 CI/CD
阅读时长：约 90 分钟
本文写于 2026 年 6 月
配套版本：Jenkins 2.452.x LTS / Kubernetes 1.29 / Argo Rollouts 1.7 / Helm 3.x
前置阅读：本系列第 5 篇「Nacos 服务中心与配置中心」（同 Java Web 微服务系列）
配套参考：站内 K8s 容器编排专题（多个分章节文章）

引子：2020 年那个凌晨 3 点的上线翻车

2020 年 11 月 11 日，距离双 11 大促开场还有 6 小时。

下午 5 点 30 分，我正准备关电脑去会场盯盘，钉钉群里弹出一条消息：「@我 order-service 修复一个 Nacos 配置 bug，紧急上线，11 点前必须完成」。

我看了一下 commit：改动 1 个 yaml 配置，3 行变更。看上去毫无风险。

接下来 90 分钟里，我们 5 个人上演了一出"上线翻车连续剧"：

17:42 — 申请 30 分钟上线窗口（运维审批通过）
17:55 — ssh 到 1 号生产机，手动 scp 上传 app-order-service.jar（错误 1：5 台机器我一台一台 scp，忘了第 3 台）
18:10 — 3 号机没启动新 jar，但 Nacos 配置中心已经推下去，3 号机用旧 jar 读新配置，启动直接失败
18:12 — 3 号机 Pod 持续重启，5 秒一次，Hystrix 触发熔断，订单查询接口返回 502
18:15 — 用户侧开始出现「订单提交失败」提示，监控告警开始轰炸
18:18 — 我和另两个 SRE 一边回滚 3 号机一边改 4 号机，越改越乱
18:30 — 第 4 号机配置文件错位（错误 2：复制粘贴时路径写错），订单服务彻底雪崩
18:35 — 大促预热开始，雪崩被监控捕获，公司副总裁电话打到我手机上

最终回滚 + 重启完成时间：18:52。大促预热 20 分钟完全不可用。

直接损失：

大促预热阶段订单流失估算 80 万+
副总裁级别投诉 1 次
我和团队全员通宵复盘
后续两周所有"小修改"必须走"完整测试 + 灰度"

复盘会上我写了一段话，后来被打印出来贴在工位上：

「不是代码问题，是流程问题。 我们缺的不是更强的程序员，是一条把’代码提交’和’生产部署’彻底打通的自动化流水线——让人为操作降到 0、让 5 台机器同步生效、让回滚一键完成、让配置错误在 CI 阶段就被拦截。」

那次之后，我花了三个月从 0 到 1 搭起了团队的 Jenkins 流水线。后来三年里，团队从 5 个微服务长到 80 个，从 5 台机器扩到 200+ Pod，从手动上线变成全自动化。

这篇文章就是那三个月里踩过的所有坑 + 后续三年里迭代出的所有最佳实践的完整复盘。目标是让你照着做一遍，就能在你团队里落地一套生产可用的 Jenkins + Docker + K8s + 蓝绿/金丝雀的完整 CI/CD 链路。

文章分 8 章 + 1 个收尾，从架构总览到本地可跑通 demo，从 Jenkinsfile 模板到 Argo Rollouts 金丝雀发布，约 16500 字，建议收藏后分章节阅读。

一、Jenkins 体系总览

1.1 Master/Agent 架构：为什么单点 Jenkins 撑不住 200+ 微服务

2021 年初，我第一次把团队 5 个微服务跑上 Jenkins，那时还是单机 Master：Jenkins 装在一台 8C16G 的虚拟机上，所有构建任务都在 Master 本地跑。5 个微服务的时候一切正常。

半年后，团队扩张到 30 个微服务，每天 200+ 次构建。问题开始集中爆发：

构建排队：早高峰 9-10 点，平均 15 个 job 在排队，单个 job 平均等 20 分钟——开发者提交代码到拿到构建结果要 1 小时
插件 OOM：Pipeline + Docker Pipeline + Kubernetes CLI + Helm + 十几个 Sonar/Nexus/Email 插件一起跑，Master JVM 经常 OOM，每周重启 2-3 次
单点故障：Jenkins 升级插件、清理 workspace、重启服务时，整个团队的开发节奏被打断
磁盘撑爆：Maven 仓库 + Docker 镜像缓存 + Sonar 报告 + 构建产物，3 个月吃掉 800GB 磁盘

痛定思痛，我把 Jenkins 拆成了 Master/Agent 架构——这是今天所有中大规模团队的标准做法。

Master 只负责调度，Agent 真正干活：

Master：保存 Job 配置、Pipeline 脚本、构建历史、凭据；不执行任何构建任务；只通过 JNLP 协议把构建任务分发给 Agent
Agent：真正执行 Shell、Docker、Maven、Kubectl 的工作节点；可以是物理机、虚拟机、Docker 容器、K8s Pod
通信协议：JNLP（推荐，HTTP 长连接，跨公网可穿透防火墙）或 SSH（适合内网）

我当时的方案是把 3 类 Agent 拆开，每类干一件事：

Agent 类型	镜像	用途	资源
maven agent	`maven:3.9-eclipse-temurin-17`	Java 编译、单元测试、生成 jar/war	4C8G
docker agent	`docker:24-dind`	Docker in Docker，构建镜像、推 Harbor	4C8G
k8s agent	`jenkins/inbound-agent:latest`	跑 K8s 部署任务、用完即销毁	2C4G

graph TB
 Dev[开发者 push 代码] --> Master[Jenkins Master
调度 + 凭据 + 历史]
 Master -->|JNLP| Mvn[maven agent
mvn package]
 Master -->|JNLP| Doc[docker agent
docker build+push]
 Master -->|JNLP| K8s[k8s agent
kubectl apply]
 Mvn --> Harbor[Harbor 制品库]
 Doc --> Harbor
 K8s --> K8sCluster[(K8s 集群)]
 Master -.插件.-> Sonar[SonarQube]
 Master -.通知.-> Ding[钉钉 / 企微]

 style Master fill:#3c82dc,color:#fff
 style Mvn fill:#5aa0e8,color:#fff
 style Doc fill:#5aa0e8,color:#fff
 style K8s fill:#5aa0e8,color:#fff

这种架构的好处是横向扩展——构建量翻倍时，加 3 个 maven agent 就够了，不用动 Master。

1.2 Pipeline as Code：从 UI 点击到 Jenkinsfile 提交

2018 年之前我用的还是 Jenkins「老模式」：在 Jenkins Web UI 上点 New Item → 配置 Git 仓库地址 → 配置 Build Steps → 配置 Post-build Actions → Save。

这种模式有 4 个致命问题：

配置散落：30 个微服务 × 30 个 Job = 900 个 Job 配置，散在 Jenkins 数据库里，没人能说清楚哪个 Job 在跑什么命令
改不动：想统一加一个 SonarQube 扫描步骤？30 个 Job 全部手动改一遍，改完还要截图存档证明
不可审计：谁在什么时间改了 Job 配置？Jenkins 不记录——出问题时只能看 audit log 里的"管理员在 X 时间编辑了 Y Job"
不可回滚：配错了？只能手动重配，没有 diff 没有 revert

2018 年 Jenkins 推出 Pipeline as Code（也称 Jenkinsfile），所有这一切问题被一次性解决：

配置即代码：Job 配置不再是 UI 点击，而是写在一个叫 Jenkinsfile 的文本文件里，和业务代码一起存在 Git 仓库
PR review 流程：Jenkinsfile 改了 → 走 PR → 同事 review → 合并，和业务代码一样的代码审查流程
版本可追溯：每次改 Jenkinsfile 都有 commit 历史，回滚一行 git revert 就好
可复用：Jenkinsfile 里有公共逻辑（build、test、deploy）？抽成 Shared Library，10 个微服务共用同一段代码

我自己从 2018 年开始用 Jenkinsfile，到 2020 年把所有 freestyle job 全部迁完。这一步是流水线从"能用"到"好用"的关键分水岭。

1.3 声明式 vs 脚本式：怎么选？

Jenkinsfile 写起来有两种风格：

声明式（Declarative）：语法限制严格，结构清晰，像填表
脚本式（Scripted）：完整 Groovy 语法，自由度高，像写程序

90% 的场景用声明式就够了。我团队 80 个微服务，75 个用声明式，只有 5 个复杂动态场景（按需选环境、动态生成 Job）用脚本式。

6 维度对比表：

维度	声明式 (Declarative)	脚本式 (Scripted)
语法限制	严格，结构固定	自由，完整 Groovy
学习曲线	低（半小时上手）	高（需会 Groovy）
复用性	用 `library` 调 Shared Library	用 `Groovy Class` 自己封装
IDE 支持	主流 IDE 都有插件	弱，需要懂 Groovy
错误提示	友好（语法错误立即提示）	一般（运行时才知道）
适用规模	中小团队 / 80% 场景	复杂动态 / 大型平台
推荐度	⭐⭐⭐⭐⭐	⭐⭐

声明式的骨架长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


pipeline {
 agent { label 'maven' } // 在哪个 agent 上跑
 options { // 全局选项
 timeout(time: 30, unit: 'MINUTES')
 disableConcurrentBuilds()
 }
 parameters { // 手动参数
 string(name: 'BRANCH', defaultValue: 'main')
 }
 stages { // 阶段
 stage('Build') { steps { ... } }
 stage('Test') { steps { ... } }
 }
 post { // 后置动作
 always { echo 'cleanup' }
 failure { mail to: 'team@xxx.com' }
 }
}

pipeline / agent / stages / steps / post 是声明式的5 大顶层指令，写错一个 Jenkins 立刻提示。脚本式你写 node { stage { ... } }，语法错误要到运行时才报。

stateDiagram-v2
 [*] --> Pipeline
 Pipeline --> Agent: 分配执行节点
 Agent --> Stages: 串行执行各 stage
 Stages --> Stage1
 Stage1 --> Stage2
 Stage2 --> Stage3
 Stage3 --> Stages
 Stages --> Post: 全部完成
 Post --> Always: 始终执行
 Post --> Success: 成功
 Post --> Failure: 失败
 Post --> [*]

1.4 关键插件清单：20 个就够，多了就是债务

Jenkins 插件生态庞大，官方仓库 1800+ 插件。我见过最夸张的团队装 200+ 插件——Jenkins 启动 5 分钟，OOM 每月 3 次。

经验法则：20 个插件以内，撑起 80 个微服务。

我团队的生产可用最小集（按重要性排序）：

类别	插件	必装	用途
核心	Pipeline	✅	Jenkinsfile 支持
核心	Git	✅	拉代码
核心	Credentials Binding	✅	凭据注入
核心	Workspace Cleanup	✅	清理工作区
核心	Timestamper	✅	日志加时间戳
SCM	GitHub / GitLab	✅	Webhook + 状态回调
SCM	Generic Webhook Trigger	✅	通用 Webhook 触发器
构建	Docker Pipeline	✅	Jenkinsfile 里写 `docker.build`
构建	Kubernetes CLI	✅	`kubectl apply`
构建	Helm	✅	Helm Chart 部署
质量	SonarQube Scanner	✅	代码扫描
质量	JUnit	⭕	测试报告聚合
制品	Nexus Artifact Uploader	✅	推 Maven 包到 Nexus
制品	Warnings NG	⭕	代码告警聚合
通知	Email-ext	✅	邮件通知
通知	DingTalk	✅	钉钉通知
UI	Blue Ocean	⭕	可视化流水线（可选）
运维	Configuration as Code	✅	Jenkins 配置 yaml 化
运维	Matrix Authorization	✅	权限矩阵
运维	Role-based Authorization	✅	角色权限

注意：

装过的插件必须用 JCasC（Configuration as Code）写入 yaml，否则重启就丢
插件升级前先在测试 Jenkins 验证——很多插件升级有 breaking change（比如 Docker Pipeline 1.x → 2.x 改了 API）
半年审一次插件清单，用不到的立即 disable，不常用的 uninstall

第一章总结：Jenkins Master/Agent 架构是规模化的基础，Pipeline as Code 是工程化的关键，声明式 Pipeline 是 90% 场景的最优解，20 个插件覆盖 80% 用法。

下一章我们把这些原则落到本地——用 docker-compose 起一套完整可跑通的 Jenkins + k3d K8s 演示环境。

二、高可用 Jenkins 集群搭建

2.1 本地环境拓扑：Jenkins + k3d 一键起

「看 100 篇文章不如跑 1 遍」——这是我在团队内部推广 Jenkins 时的口头禅。

文章里写的 docker-compose.yml、k3d 启动脚本、Jenkinsfile 模板、Helm Chart 都可以直接复制使用。读者需要做的就是跟着敲命令，在自己电脑上把整套环境跑起来。

本节给出完整可跑通的本地演示环境拓扑：

graph LR
 subgraph Docker[Docker Host 宿主机]
 Jen[Jenkins Master
:8080]
 MA[maven agent
:动态]
 DA[docker agent
DIND]
 end

 subgraph K3d[k3d 本地 K8s 集群]
 KA[k8s agent
:动态]
 Argo[Argo Rollouts]
 Prom[Prometheus]
 App[业务 Pods]
 end

 Dev[开发者] -->|push| Git[(GitHub/GitLab)]
 Git -->|webhook| Jen
 Jen -->|JNLP| MA
 Jen -->|JNLP| DA
 Jen -->|JNLP| KA
 Jen -->|kubectl| Argo
 MA -->|mvn build| Jen
 DA -->|docker push| Harbor[(Harbor
localhost:30002)]
 KA -->|kubectl apply| App
 Argo --> Prom
 Prom -->|指标查询| Argo

 style Jen fill:#3c82dc,color:#fff
 style K3d fill:#1a3a6a,color:#fff
 style Docker fill:#0a1a3a,color:#fff

架构关键点：

Jenkins Master 跑在宿主机 Docker 上（不是 k3d 内）——避免 K8s 故障时 Jenkins 也挂
3 类 Agent 跑在 k3d 之外（也可以跑在 k3d 内作为 Pod，本章用更简单的「固定容器」方案）
k3d 集群跑在宿主机 Docker 里，共享 docker.sock，Jenkins 构建的镜像能被 K8s 看到
Harbor 跑在 k3d 内（用 NodePort 30002 暴露）

资源占用：

最低：8C16G，能跑但卡
推荐：16C32G，这是流畅跑 Jenkins + k3d 的甜点
极致：32C64G，可同时跑 SonarQube + Nexus + 多个项目

2.2 docker-compose.yml：Jenkins Master + 持久化

完整 docker-compose.yml（生产可用 + 本地 demo 两相宜）：

 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
60
61


# docker-compose.yml
# 启动：docker compose up -d
# 查看日志：docker compose logs -f jenkins
version: "3.8"

services:
 jenkins:
 image: jenkins/jenkins:2.452.3-lts-jdk17
 container_name: jenkins-master
 restart: unless-stopped
 user: root  # 容器内用 root，方便调 docker
 ports:
 - "8080:8080" # Web UI
 - "50000:50000" # Agent JNLP
 volumes:
 - jenkins_data:/var/jenkins_home  # 配置持久化
 - /var/run/docker.sock:/var/run/docker.sock # 共享宿主机 docker daemon
 - /usr/bin/docker:/usr/bin/docker:ro  # docker CLI（容器内能用 docker 命令）
 environment:
 - JAVA_OPTS=-Xms2g -Xmx4g -Djava.awt.headless=true
 - JENKINS_OPTS=--httpPort=8080
 networks:
 - jenkins-net
 healthcheck:
 test: ["CMD", "curl", "-f", "http://localhost:8080/login"]
 interval: 30s
 timeout: 10s
 retries: 10

 # 固定 maven agent（也可改成动态 K8s pod agent）
 maven-agent:
 image: jenkins/inbound-agent:3192.v713e3def_8641-1
 container_name: jenkins-maven-agent
 depends_on:
 jenkins:
 condition: service_healthy
 environment:
 - JENKINS_URL=http://jenkins:8080
 - JENKINS_SECRET=<从 Master UI 拷过来>
 - JENKINS_AGENT_NAME=maven-agent-1
 networks:
 - jenkins-net

 docker-agent:
 image: docker:24-dind
 container_name: jenkins-docker-agent
 privileged: true # DIND 必须
 environment:
 - DOCKER_TLS_CERTDIR=
 volumes:
 - docker_data:/var/lib/docker
 networks:
 - jenkins-net

volumes:
 jenkins_data:
 docker_data:

networks:
 jenkins-net:
 driver: bridge

关键配置解析：

/var/run/docker.sock 挂载：让 Master 容器能直接调用宿主机 docker daemon，好处是构建的镜像在宿主机 docker 里可见，k3d 也能用
user: root：容器内 Jenkins 进程用 root 跑，方便调 docker（生产环境用非 root 需要更多配置）
JAVA_OPTS=-Xms2g -Xmx4g：JVM 堆 4G，够 100 个并发 job，超过这个量级需要排查 OOM
JNLP 端口 50000：Agent 通过这个端口和 Master 建长连接，必须开且不能被防火墙挡

首次启动：

1
2
3
4


docker compose up -d
docker compose logs -f jenkins | grep -A 1 "initial"
# 看到一行：Please use the following password to proceed to installation:
# 类似：2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p

把这个密码复制到 http://localhost:8080，第一次进入会走 Setup Wizard：

安装推荐插件（Install suggested plugins）——包含 Git、Pipeline、Credentials Binding 等
创建第一个管理员用户（admin / ）
保存并完成

进入后必须做的 3 件事：

Configure Global Security → 启用 Agent → Master 访问控制（JNLP 协议需要）
Manage Plugins → 搜索并安装 Docker Pipeline / Kubernetes CLI / Helm / DingTalk / SonarQube Scanner
Manage Nodes and Clouds → New Node → 复制 JNLP 秘钥，填到上面 maven-agent 的 JENKINS_SECRET

2.3 k3d 一键起本地 K8s

k3d 是 k3s（轻量 K8s）的 docker 包装器——5 秒拉起一个 K8s 集群，内存只占 300MB。比 kind（K8s in Docker）更轻，比 minikube 启动快 10 倍。

安装 k3d：

1
2
3
4
5
6
7
8


# macOS
brew install k3d k3s

# Linux
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# Windows（WSL2）
wsl -e bash -c "curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash"

启动集群：

1
2
3
4
5
6
7
8


k3d cluster create jenkins-demo \
 --image rancher/k3s:v1.29.4-k3s1 \
 --port "80:80@loadbalancer" \
 --port "443:443@loadbalancer" \
 --port "30000-30100:30000-30100@loadbalancer" \
 --agents 3 \
 --volume "/tmp/k3d-shared:/tmp/shared@all" \
 --k3s-arg "--disable=traefik@server:0"

参数解析：

--image rancher/k3s:v1.29.4-k3s1：K8s 版本固定（避免每次启动版本漂移）
--port "80:80@loadbalancer"：把容器内 80 端口映射到宿主机 80
--port "30000-30100:30000-30100"：NodePort 范围，本地访问业务服务用
--agents 3：3 个 worker node（默认 0，建议至少 2 个才能演示多 Pod 部署）
--volume：共享目录，让 K8s 内的 Pod 能看到宿主机文件（重要！Jenkins 构建的镜像在这里 push 之后 K8s 才能 pull）
--k3s-arg "--disable=traefik@server:0"：禁用默认的 Traefik Ingress（我们用 Nginx Ingress 自己装）

验证集群：

1
2
3
4
5


kubectl get nodes
# 预期看到 4 个 node（1 server + 3 agent），全部 Ready

kubectl get pods -A
# kube-system 下有 coredns、metrics-server 等基础组件

Windows WSL2 用户注意：如果你用 WSL2 + Docker Desktop，/var/run/docker.sock 在 WSL2 内的路径是 //var/run/docker.sock（注意双斜杠），docker-compose.yml 里的挂载可能要改成：

1
2


volumes:
 - //var/run/docker.sock:/var/run/docker.sock

2.4 三类 Agent：maven / docker / k8s

Agent 设计的第一原则：「一类活一台 Agent」——别让一个 Agent 干所有事，原因有三：

资源隔离：Java 构建要 4C8G，Docker 构建也要 4C8G，两个一起跑会抢内存 OOM
环境隔离：Maven Agent 装 JDK + Maven，不要装 Docker CLI（污染 PATH）；Docker Agent 装 Docker CLI + dind，不要装 JDK
故障隔离：某类 Agent 出问题（磁盘满、插件崩），不影响其他类型

我的标准方案（80 个微服务团队实战）：

Agent 类型	镜像	资源	用途	标签
maven agent	`maven:3.9-eclipse-temurin-17`	4C8G	编译、单测、Sonar 扫描、生成 jar	`maven`、`linux`
docker agent	`docker:24-dind`	4C8G	docker build、docker push 镜像	`docker`、`dind`
k8s agent	`jenkins/inbound-agent:latest-jdk17`	2C4G	kubectl、helm、argocd 操作	`k8s`、`linux`

Jenkinsfile 里怎么选：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


pipeline {
 agent none // 顶层不指定 agent
 stages {
 stage('Build') {
 agent { label 'maven' } // 拉 maven agent
 steps { sh 'mvn package' }
 }
 stage('Docker Build') {
 agent { label 'docker' } // 拉 docker agent
 steps { sh 'docker build -t app:${TAG} .' }
 }
 stage('Deploy') {
 agent { label 'k8s' } // 拉 k8s agent
 steps { sh 'kubectl apply -f deployment.yaml' }
 }
 }
}

进阶：用 K8s Pod 作为 Agent（动态伸缩）

如果构建量波动大（白天多、夜里少），用固定 Agent 不划算。Jenkins 支持「K8s Pod Agent」——每次构建拉一个新 Pod，构建完自动销毁。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


agent {
 kubernetes {
 label 'maven-pod'
 yaml '''
apiVersion: v1
kind: Pod
spec:
 containers:
 - name: maven
 image: maven:3.9-eclipse-temurin-17
 command: ['cat']
 tty: true
 resources:
 requests: { cpu: '1', memory: '2Gi' }
 limits: { cpu: '2', memory: '4Gi' }
'''
 }
}

这种方案需要先装 Kubernetes 插件，并在 Jenkins 全局配置里配 K8s Cloud：

Jenkins URL：https://kubernetes.default（Jenkins 跑在 K8s 内的方式）
或：https://<k3d-api-server>:6443（Jenkins 跑在 K8s 外的 k3d 集群方式）
Credentials：ServiceAccount Token 或 Kubeconfig

两种方案对比：

维度	固定 Agent	K8s Pod Agent
启动速度	0 秒（常驻）	20-30 秒（拉镜像）
资源利用率	24/7 占资源	用完即销毁
镜像缓存	常驻，命中率高	每次重新拉（除非配 PV）
适用规模	小到中（<50 并发）	中到大（100+ 并发）
复杂度	低	中（要配 PVC、网络）

我的建议：30 个微服务以内用固定 Agent，简单稳定；超过 50 个用 K8s Pod Agent，节省资源。

2.5 凭据管理 + SSH 互通

Jenkins 凭据是最容易出安全问题的环节——90% 的「Jenkins 被黑」事故根因都是凭据管理不当。

4 类核心凭据：

凭据类型	用途	存哪里
Username/Password	Docker Registry、SonarQube、邮件账号	Jenkins 内置凭据库
SSH Key	Git 仓库、目标机器	Jenkins 内置凭据库
Secret Text	API Token、Webhook URL	Jenkins 内置凭据库
Kubeconfig	K8s 集群访问	Jenkins 内置凭据库

Jenkinsfile 里的标准用法（不要在 Jenkinsfile 写明文密码！）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ❌ 错误写法
sh 'docker login -u admin -p Harbor12345 harbor.xxx.com'

// ✅ 正确写法
withCredentials([usernamePassword(
 credentialsId: 'harbor-creds',
 usernameVariable: 'HARBOR_USER',
 passwordVariable: 'HARBOR_PASS'
)]) {
 sh "docker login -u ${HARBOR_USER} -p ${HARBOR_PASS} harbor.xxx.com"
}

多环境凭据切换（生产 / 预发 / 开发）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
]
def credId = credMap[params.ENV]

withCredentials([file(credentialsId: credId, variable: 'KUBECONFIG')]) {
 sh "kubectl --kubeconfig=${KUBECONFIG} apply -f deployment.yaml"
}

凭据管理 5 大铁律：

不在 Jenkinsfile 写明文——这是 1.0 级别的红线
凭据 ID 命名规范——<服务>-<环境>-<类型>，比如 harbor-prod-user
凭据权限最小化——Matrix Authorization 插件配「谁能用哪些凭据」
定期轮换——90 天换一次 Harbor/数据库密码
审计日志开启——谁在什么时间用了什么凭据，全部记录

第二章总结：Jenkins Master 跑在 docker-compose 里、Agent 按 maven/docker/k8s 三类拆分、k3d 一键起本地 K8s 集群、凭据用 withCredentials 注入——这套组合拳能让你在 1 小时内本地跑通完整演示环境。

下一章我们写一份生产可用的 Jenkinsfile——6 个 stage、150+ 行，覆盖 Build/Test/Sonar/Package/Docker/Deploy 全流程。

2.6 完整启动脚本：一键起所有服务

把上面的 docker-compose 和 k3d 命令封装成一个 shell 脚本，方便反复重置本地环境：

 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


#!/bin/bash
# scripts/start-demo-env.sh
# 一键起 Jenkins + k3d + 必要工具
set -e

echo "==> 1. 启动 Jenkins Master + Agents"
docker compose up -d

echo "==> 2. 等待 Jenkins 就绪"
for i in {1..30}; do
 if curl -sf http://localhost:8080/login >/dev/null 2>&1; then
 echo " Jenkins ready"
 break
 fi
 echo " 等待 Jenkins 启动... ${i}/30"
 sleep 5
done

echo "==> 3. 启动 k3d 集群"
k3d cluster create jenkins-demo \
 --image rancher/k3s:v1.29.4-k3s1 \
 --port "80:80@loadbalancer" \
 --port "443:443@loadbalancer" \
 --port "30000-30100:30000-30100@loadbalancer" \
 --agents 3 \
 --volume "/tmp/k3d-shared:/tmp/shared@all" \
 --k3s-arg "--disable=traefik@server:0" \
 --wait

echo "==> 4. 安装 Argo Rollouts"
kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/download/v1.7.0/install.yaml

echo "==> 5. 安装 Prometheus（轻量版）"
kubectl apply -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.72.0/bundle.yaml

echo "==> 6. 安装 Harbor（轻量）"
helm repo add harbor https://helm.goharbor.io
helm install harbor harbor/harbor \
 --namespace harbor --create-namespace \
 --set expose.type=nodePort \
 --set expose.nodePort.ports.http.nodePort=30002 \
 --set persistence.enabled=false \
 --set core.persistence.enabled=false \
 --set database.persistence.enabled=false \
 --set redis.persistence.enabled=false \
 --set jobservice.persistence.enabled=false \
 --set registry.persistence.enabled=false \
 --set trivy.persistence.enabled=false

echo "==> 7. 验证"
echo " Jenkins: http://localhost:8080"
echo " k3d kubeconfig: k3d kubeconfig write jenkins-demo"
echo " Harbor: http://localhost:30002 (admin/Harbor12345)"
echo ""
echo "全部就绪！"

跑完这个脚本，你的本地就有：

Jenkins Master（http://localhost:8080）
k3d K8s 集群（4 节点）
Argo Rollouts Controller
Prometheus Operator
Harbor 镜像仓库

接下来就可以在 Jenkins UI 上建 Job、配 Webhook、写 Jenkinsfile 跑流水线了。

2.7 常见坑位与排查清单

3 年里我们团队在 Jenkins + K8s 集成上踩过的高频 10 个坑，按出现频率排序：

#	坑位	现象	解决方案
1	docker.sock 权限拒绝	`permission denied while trying to connect to the Docker daemon socket`	Master 用 `user: root` 跑，或在宿主机 `chmod 666 /var/run/docker.sock`
2	k3d 集群内存爆	4G 内存跑 Jenkins + k3d + Harbor，宿主机卡死	宿主机至少 16G；Harbor 用 `--set persistence.enabled=false`
3	Agent 离线	JNLP 连不上，Agent 显示 offline	检查 Master `50000` 端口是否开放；JNLP 秘钥是否过期
4	镜像推送后 K8s 拉不到	`ImagePullBackOff`	k3d 集群和 docker 共享 `/tmp/k3d-shared` 目录；或用 `k3d image import` 导入
5	Maven 依赖下载慢	第一次构建 5 分钟全在 download	挂载 `.m2` 目录到 host：`volumes: ['~/.m2:/root/.m2']`
6	Pipeline 步骤超时	30 分钟还没跑完	`options { timeout(time: 60, unit: 'MINUTES') }` 加大
7	Jenkins OOM	`java.lang.OutOfMemoryError`	调大 `JAVA_OPTS=-Xmx4g`；或加 Master 节点
8	插件升级后 build 失败	Docker Pipeline 1.x → 2.x 改了 API	锁插件版本；先在测试 Jenkins 验证再升级
9	Webhook 不触发	push 代码 Jenkins 没反应	检查 GitHub Webhook 状态码；Jenkins `Manage Webhooks` 日志
10	并发构建冲突	同一 Job 跑两次互相干扰	`options { disableConcurrentBuilds() }` 串行

调试工具：

Jenkins 构建日志：直接看 console output
Agent 状态：Manage Nodes and Clouds → 点 Agent 名 → Log
K8s 状态：kubectl get pods -A、kubectl describe pod <name>
镜像拉取：docker exec -it k3d-jenkins-demo-agent-0 crictl images
网络连通：docker exec -it jenkins-master ping k3d-jenkins-demo-server-0

2.8 Jenkins 配置即代码：JCasC 拯救「文档缺失」

我刚接手团队 Jenkins 时最大的痛苦是——没人知道生产 Jenkins 的 30 个 Job 是怎么配的。某天 Jenkins 挂了重装，所有 Job 全部丢光，只能从 Jenkinsfile 重新跑。

2020 年我引入 JCasC（Configuration as Code） 插件，把所有「在 Jenkins UI 上配的东西」全部 yaml 化，和 Jenkinsfile 一样存进 Git：

 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


# casc/jenkins.yaml
jenkins:
 systemMessage: "团队 CI/CD 中心 - powered by Jenkins 2.452"
 numExecutors: 0 # Master 不跑任务
 mode: EXCLUSIVE  # 一个时间只跑一个 Job（防 OOM）
 securityRealm:
 local:
 users:
 - id: "admin"
 name: "Admin"
 password: "${ADMIN_PASSWORD}" # 从环境变量读
 authorizationStrategy:
 loggedInUsersCanDoAnything:
 allowAnonymousRead: false
 remotingSecurity:
 enabled: true

credentials:
 system:
 domainCredentials:
 - credentials:
 - usernamePassword:
 scope: GLOBAL
 id: "harbor-creds"
 username: "admin"
 password: "${HARBOR_PASSWORD}"
 description: "Harbor 镜像仓库"
 - file:
 scope: GLOBAL
 id: "k8s-prod-kubeconfig"
 fileName: "kubeconfig"
 secretBytes:
 "${K8S_PROD_KUBECONFIG_BASE64}"

unclassified:
 location:
 url: "https://jenkins.xxx.com/"
 adminAddress: "devops@xxx.com"
 tool:
 jdk:
 installations:
 - name: "jdk17"
 properties:
 - installSource:
 installers:
 - adoptOpenJdk:
 id: "jdk-17.0.10+7"

启动时加载：

1
2
3


docker run -e CASC_JENKINS_CONFIG=/var/jenkins_home/casc/jenkins.yaml \
 -v $PWD/casc:/var/jenkins_home/casc:ro \
 jenkins/jenkins:2.452.3-lts-jdk17

JCasC 的 3 大价值：

环境可重建：Jenkins 挂了重装，30 秒自动恢复所有配置（凭据除外，敏感信息走环境变量 / Vault）
变更可审计：所有配置改动走 PR review，谁在什么时间改了 systemMessage 一目了然
多环境一致：dev / staging / prod Jenkins 用同一份 yaml + 不同环境变量，不会出现「测试配了生产没配」的坑

2.9 备份策略：每日 3-2-1 法则

Jenkins 数据分两类，备份策略完全不同：

配置数据（小，KB-MB 级）：

JCasC yaml（已在 Git 里，天然多副本）
Job 配置（如果用 Jenkinsfile 形式，已在 Git 里；如果是 freestyle，必须定期导出）
凭据 ID 清单（凭据值本身不能导出，只能记「有哪些凭据」）
全局安全配置、插件清单

运行时数据（大，GB 级）：

jenkins_data 卷（workspace、构建历史、归档制品、用户内容）
数据库（如果用外部 DB）

我的 3-2-1 备份方案：

数据	备份方式	频率	保留期
JCasC yaml	Git（主仓 + GitLab mirror）	实时	永久
Jenkinsfile	Git（业务仓）	实时	永久
freestyle Job 配置	Job History 插件 + 定时导出 yaml	每日	90 天
jenkins_data 卷	restic 加密备份到 S3 / 阿里云 OSS	每日 03:00	30 天
关键构建产物	推 Nexus / Harbor	实时	按 artifact 策略

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 备份脚本（简化版）
#!/bin/bash
BACKUP_DIR=/backup/jenkins/$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

# 1. 备份 JCasC（已在 Git 里，这里只备份运行时配置）
docker exec jenkins-master bash -c \
 "java -jar /var/jenkins_home/war/WEB-INF/jenkins-cli.jar \
 -s http://localhost:8080 get-job my-job" > $BACKUP_DIR/my-job.xml

# 2. 备份插件清单
docker exec jenkins-master cat /var/jenkins_home/plugins.txt > $BACKUP_DIR/plugins.txt

# 3. 备份 jenkins_data（restic 增量）
restic backup /var/lib/docker/volumes/jenkins_data

# 4. 上传 S3
aws s3 sync $BACKUP_DIR s3://my-backup-bucket/jenkins/$BACKUP_DIR

灾备演练：每季度做一次「Jenkins 全毁 → 1 小时内恢复」的演练，不演练的备份等于没备份。

三、Jenkinsfile 完整模板

3.1 项目结构假设 + Pipeline 总体设计

为了一篇文章讲透 Jenkinsfile，我假设你的项目是这种结构（绝大多数 Java 微服务团队都是这个形态）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


my-microservice/ # Spring Boot 3.x 多模块 Maven 项目
├── pom.xml # 父 POM
├── common-lib/ # 公共库
│ ├── pom.xml
│ └── src/main/java/...
├── order-service/ # 订单服务
│ ├── pom.xml
│ ├── Dockerfile
│ └── src/
├── user-service/ # 用户服务
│ ├── pom.xml
│ ├── Dockerfile
│ └── src/
├── Jenkinsfile # 我们的主角
└── sonar-project.properties # SonarQube 配置

Pipeline 6 阶段总体设计：

graph LR
 A[Checkout
拉代码] --> B[Build
Maven 编译]
 B --> C[Test
单测+集成测试]
 C --> D[Code Scan
SonarQube]
 D --> E[Package
生成 jar]
 E --> F[Docker Build
构建镜像]
 F --> G[Push to Harbor
推镜像]
 G --> H[Deploy
kubectl apply]
 H --> I[Verify
健康检查]
 I --> J[Notify
钉钉通知]

 style A fill:#3c82dc,color:#fff
 style D fill:#ff9a3c,color:#fff
 style F fill:#5aa0e8,color:#fff
 style H fill:#3c82dc,color:#fff

关键设计决策：

agent none + 每个 stage 单独指定 agent——Build/Test 在 maven agent，Docker 在 docker agent，Deploy 在 k8s agent
每个 stage 必须可独立触发——when { expression { ... } } 条件跳过不需要的 stage
post 4 大场景——always 清理、success 通知、failure 告警 + 日志归档、aborted 通知
重试机制——网络类操作（git push、docker push）retry(3) 包一层
超时——整体 Pipeline 30 分钟，单 stage 10 分钟，超时自动 fail

3.2 完整 Jenkinsfile 全文（150+ 行可直接复制）

 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
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231


// Jenkinsfile - 适用于 Spring Boot 多模块微服务
// 用法：放在项目根目录，Jenkins 创建 Pipeline Job 时选 "Pipeline script from SCM"

pipeline {
 agent none // 顶层不指定，由各 stage 决定

 options {
 // 整体超时：30 分钟
 timeout(time: 30, unit: 'MINUTES')
 // 禁止并发构建（同一 Job 同一时间只能跑 1 个）
 disableConcurrentBuilds()
 // 构建历史保留：30 天最多 50 次
 buildDiscarder(logRotator(numToKeepStr: '50', daysToKeepStr: '30'))
 // 日志加时间戳
 timestamps()
 // ansi 颜色
 ansiColor('xterm')
 }

 parameters {
 // 手动参数
 choice(name: 'ENV', choices: ['dev', 'staging', 'prod'],
 description: '部署环境')
 string(name: 'BRANCH', defaultValue: 'main',
 description: '代码分支')
 string(name: 'IMAGE_TAG', defaultValue: '',
 description: '镜像 tag（留空用 commit SHA）')
 booleanParam(name: 'SKIP_TEST', defaultValue: false,
 description: '跳过测试')
 booleanParam(name: 'FORCE_DEPLOY', defaultValue: false,
 description: '强制部署（跳过健康检查）')
 }

 environment {
 // 全局环境变量
 APP_NAME = 'order-service'
 HARBOR_PROJECT = 'myteam'
 K8S_NAMESPACE = "${params.ENV}"
 GIT_COMMIT = sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
 IMAGE_TAG = "${params.IMAGE_TAG?.trim() ? params.IMAGE_TAG : env.GIT_COMMIT}"
 IMAGE_NAME = "harbor.xxx.com/${HARBOR_PROJECT}/${APP_NAME}"
 DOCKER_IMAGE = "${IMAGE_NAME}:${IMAGE_TAG}"
 }

 stages {
 // ===== 阶段 1：Checkout =====
 stage('Checkout') {
 agent { label 'maven' }
 steps {
 checkout scm
 sh 'git status'
 sh 'git log -1 --oneline'
 }
 }

 // ===== 阶段 2：Build =====
 stage('Build') {
 agent { label 'maven' }
 steps {
 sh 'mvn -B -V -T 4 clean compile'
 }
 post {
 failure {
 echo 'Build 失败，请检查代码编译错误'
 }
 }
 }

 // ===== 阶段 3：Test =====
 stage('Test') {
 agent { label 'maven' }
 when {
 expression { return !params.SKIP_TEST }
 }
 steps {
 sh 'mvn -B test'
 // 归档测试报告
 junit '**/target/surefire-reports/*.xml'
 // 代码覆盖率
 jacoco(execPattern: '**/target/jacoco.exec',
 minimumLineCoverage: '0.60')
 }
 }

 // ===== 阶段 4：Code Scan =====
 stage('Code Scan') {
 agent { label 'maven' }
 steps {
 withSonarQubeEnv('sonarqube-server') {
 sh 'mvn sonar:sonar -Dsonar.projectKey=${APP_NAME}'
 }
 // 等待 Quality Gate 结果（10 分钟超时）
 timeout(time: 10, unit: 'MINUTES') {
 waitForQualityGate abortPipeline: true
 }
 }
 }

 // ===== 阶段 5：Package =====
 stage('Package') {
 agent { label 'maven' }
 steps {
 sh 'mvn -B -DskipTests clean package'
 // 归档 jar
 archiveArtifacts artifacts: '**/target/*.jar',
 fingerprint: true,
 allowEmptyArchive: false
 }
 }

 // ===== 阶段 6：Docker Build =====
 stage('Docker Build') {
 agent { label 'docker' }
 steps {
 sh """
 docker build \
 --build-arg JAR_FILE=${APP_NAME}/target/*.jar \
 -t ${DOCKER_IMAGE} \
 -t ${IMAGE_NAME}:latest \
 .
 """
 }
 }

 // ===== 阶段 7：Push to Harbor =====
 stage('Push') {
 agent { label 'docker' }
 steps {
 withCredentials([usernamePassword(
 credentialsId: 'harbor-creds',
 usernameVariable: 'HARBOR_USER',
 passwordVariable: 'HARBOR_PASS'
 )]) {
 sh """
 docker login -u ${HARBOR_USER} -p ${HARBOR_PASS} harbor.xxx.com
 retry 3 docker push ${DOCKER_IMAGE}
 docker push ${IMAGE_NAME}:latest
 """
 }
 }
 }

 // ===== 阶段 8：Deploy =====
 stage('Deploy') {
 agent { label 'k8s' }
 when {
 expression { return params.ENV != '' }
 }
 steps {
 script {
 def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
 ]
 withCredentials([file(
 credentialsId: credMap[params.ENV],
 variable: 'KUBECONFIG'
 )]) {
 sh """
 kubectl --kubeconfig=${KUBECONFIG} \
 set image deployment/${APP_NAME} \
 ${APP_NAME}=${DOCKER_IMAGE} \
 -n ${K8S_NAMESPACE}

 kubectl --kubeconfig=${KUBECONFIG} \
 rollout status deployment/${APP_NAME} \
 -n ${K8S_NAMESPACE} \
 --timeout=5m
 """
 }
 }
 }
 }
 }

 // ===== 构建后操作 =====
 post {
 // 始终执行
 always {
 echo "构建结束：${currentBuild.currentResult}"
 // 清理 workspace
 cleanWs()
 }
 // 成功
 success {
 script {
 def msg = """
 ✅ 构建成功
 Job: ${env.JOB_NAME} #${env.BUILD_NUMBER}
 分支: ${params.BRANCH}
 环境: ${params.ENV}
 镜像: ${DOCKER_IMAGE}
 提交: ${env.GIT_COMMIT}
 链接: ${env.BUILD_URL}
 """.stripIndent()
 dingtalk(
 type: 'MARKDOWN',
 title: '✅ Jenkins 构建成功',
 text: msg,
 at: []
 )
 }
 }
 // 失败
 failure {
 script {
 // 归档失败日志
 archiveArtifacts artifacts: '**/build.log',
 allowEmptyArchive: true
 // 钉钉告警
 dingtalk(
 type: 'MARKDOWN',
 title: '❌ Jenkins 构建失败',
 text: """
 ❌ 构建失败
 Job: ${env.JOB_NAME} #${env.BUILD_NUMBER}
 分支: ${params.BRANCH}
 提交: ${env.GIT_COMMIT}
 链接: ${env.BUILD_URL}
 失败阶段: ${env.STAGE_NAME ?: '未知'}
 """.stripIndent()
 )
 }
 }
 // 终止
 aborted {
 echo '构建被人工终止'
 }
 }
}

这段 Jenkinsfile 包含 8 个 stage、150+ 行，是生产可用的最小完整版本。复制过去改 4 个变量就能用：

APP_NAME：你的服务名
HARBOR_PROJECT：Harbor 项目名
harbor.xxx.com：Harbor 地址
sonarqube-server：SonarQube 配置名（在 Jenkins 全局配置里配）

3.3 Checkout 阶段详解

checkout scm 是声明式 Pipeline 里最简洁也最强大的一行——它会自动用 Job 配置的 SCM 拉代码。

多仓库场景（order-service 依赖 common-lib）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


stage('Checkout') {
 agent { label 'maven' }
 steps {
 checkout([
 $class: 'GitSCM',
 branches: [[name: params.BRANCH]],
 userRemoteConfigs: [[
 url: 'git@github.com:myteam/order-service.git',
 credentialsId: 'github-ssh-key'
 ]],
 extensions: [
 // 拉 common-lib 子模块
 [$class: 'SubmoduleOption',
 recursiveSubmodules: true,
 parentCredentials: true],
 // 浅克隆（只拉最近 50 个 commit，加速）
 [$class: 'CloneOption',
 depth: 50, shallow: true, noTags: false]
 ]
 ])
 }
}

关键参数：

credentialsId：用 SSH key 凭据，别用 https 用户名密码（每次 build 都会触发 2FA）
submodule：如果项目用 Git submodule 拉公共库，必须 recursiveSubmodules: true
shallow: true：浅克隆，从 5 分钟缩到 30 秒
LFS：大文件用 Git LFS 时要额外配

3.4 Build + Test 阶段详解

Maven 加速 5 个技巧：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 1. 批模式：-B 减少 Jenkins 日志噪音
sh 'mvn -B clean package'

// 2. 版本校验：-V 强制用父 POM 版本（防 dep version 漂移）
sh 'mvn -B -V clean package'

// 3. 并行构建：-T 4（4 线程并行）
sh 'mvn -B -T 4 clean package'

// 4. 跳过测试：-DskipTests
sh 'mvn -B -DskipTests package'

// 5. 增量编译：am（also-make）只编译依赖模块
sh 'mvn -B -pl order-service -am clean package'

测试报告：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


stage('Test') {
 agent { label 'maven' }
 steps {
 sh 'mvn -B test'
 // JUnit 报告聚合
 junit allowEmptyResults: true,
 testResults: '**/target/surefire-reports/*.xml'

 // 覆盖率门槛
 jacoco(execPattern: '**/target/jacoco.exec',
 minimumLineCoverage: '0.60',
 minimumBranchCoverage: '0.50')
 }
}

minimumLineCoverage: '0.60' 是个强约束——单测覆盖率低于 60% 直接 fail。我团队的策略是 60% 起步、季度提升 5%，3 年从 60% 干到 78%。

Maven 本地仓库缓存：

如果 Agent 是容器，每次构建都重新下载依赖。解决方法：

1
2
3
4
5


# docker-compose.yml 给 maven agent 挂 .m2
services:
 maven-agent:
 volumes:
 - ~/.m2:/root/.m2  # 共享宿主机 .m2 目录

这样 100 个微服务用同一份 .m2，首次 5 分钟，后续 30 秒。

3.5 SonarQube + Docker 阶段详解

SonarQube 集成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


stage('Code Scan') {
 agent { label 'maven' }
 steps {
 // 1. 注入 SonarQube 配置（从 Jenkins 全局配置里拿 token）
 withSonarQubeEnv('sonarqube-server') {
 sh 'mvn sonar:sonar -Dsonar.projectKey=order-service'
 }
 // 2. 阻塞等结果（10 分钟超时）
 timeout(time: 10, unit: 'MINUTES') {
 // 3. Quality Gate 不通过 abortPipeline: true
 waitForQualityGate abortPipeline: true
 }
 }
}

sonar-project.properties（放项目根目录）：

1
2
3
4
5
6
7
8
9


sonar.projectKey=order-service
sonar.projectName=Order Service
sonar.projectVersion=1.0.0
sonar.sources=order-service/src/main/java
sonar.tests=order-service/src/test/java
sonar.java.binaries=order-service/target/classes
sonar.java.coveragePlugin=jacoco
sonar.coverage.jacoco.xmlReportPaths=order-service/target/site/jacoco/jacoco.xml
sonar.exclusions=**/generated/**,**/proto/**

Quality Gate 规则推荐：

新代码覆盖率 ≥ 80%
新代码 0 个 Blocker/Critical 漏洞
代码异味 < 50
重复率 < 3%

Docker 构建 + 推送：

 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


stage('Docker Build') {
 agent { label 'docker' }
 steps {
 sh """
 docker build \
 --build-arg JAR_FILE=order-service/target/*.jar \
 -t ${DOCKER_IMAGE} \
 -t ${IMAGE_NAME}:latest \
 .
 """
 }
}

stage('Push') {
 agent { label 'docker' }
 steps {
 withCredentials([usernamePassword(
 credentialsId: 'harbor-creds',
 usernameVariable: 'HARBOR_USER',
 passwordVariable: 'HARBOR_PASS'
 )]) {
 sh """
 docker login -u ${HARBOR_USER} -p ${HARBOR_PASS} harbor.xxx.com
 docker push ${DOCKER_IMAGE}
 docker push ${IMAGE_NAME}:latest
 """
 }
 }
}

3 个优化点：

多 tag 同时打：commit SHA + latest，让 K8s 既能精确回滚到某次 commit，也能用 latest 拉最新
--build-arg 注入 jar：多模块项目镜像只装当前服务的 jar，不装别的
Harbor 项目隔离：每个团队一个 Harbor project，用 RBAC 控制谁能 push/pull

3.6 Deploy 阶段详解 + 金丝雀

 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


stage('Deploy') {
 agent { label 'k8s' }
 when {
 expression { return params.ENV != '' }
 }
 steps {
 script {
 // 凭据切换（多环境）
 def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
 ]
 withCredentials([file(
 credentialsId: credMap[params.ENV],
 variable: 'KUBECONFIG'
 )]) {
 sh """
 # 1. 替换镜像版本
 kubectl --kubeconfig=\${KUBECONFIG} \\
 set image deployment/${APP_NAME} \\
 ${APP_NAME}=${DOCKER_IMAGE} \\
 -n ${K8S_NAMESPACE}

 # 2. 等待滚动更新完成
 kubectl --kubeconfig=\${KUBECONFIG} \\
 rollout status deployment/${APP_NAME} \\
 -n ${K8S_NAMESPACE} \\
 --timeout=5m
 """
 }
 }
 }
}

注意：

set image 是原地更新，会触发 K8s 滚动更新（默认 25% maxSurge / 25% maxUnavailable）
如果你用的是 Argo Rollouts（推荐），改用 kubectl argo rollouts set image，后面第七章详讲
镜像 tag 必须是固定值（commit SHA），不要用 latest——latest 会导致 K8s 永远拿最新镜像，回滚失败

3.7 完整流水线时序图

sequenceDiagram
 participant Dev as 开发者
 participant Git as Git 仓库
 participant J as Jenkins
 participant MA as maven agent
 participant DA as docker agent
 participant H as Harbor
 participant K as K8s

 Dev->>Git: push 代码
 Git->>J: Webhook 触发
 J->>MA: 分配构建任务
 MA->>MA: mvn compile
 MA->>MA: mvn test
 MA->>J: 报告测试结果
 MA->>MA: sonar scan
 J->>MA: Quality Gate check
 MA-->>J: pass / fail
 MA->>MA: mvn package
 MA->>J: archive jar
 J->>DA: 分配构建任务
 DA->>DA: docker build
 DA->>H: docker push
 H-->>DA: success
 J->>K: kubectl set image
 K->>K: 滚动更新
 K-->>J: rollout complete
 J->>Dev: 钉钉通知

第三章总结：一份 150+ 行的 Jenkinsfile 覆盖 8 个 stage、4 类 stage agent、6 种 stage 后置动作——这是 Java 微服务 CI/CD 的最小完整骨架。

下一章我们把这个 Jenkinsfile 接到多环境分支策略——develop / staging / release / master 的 GitFlow 怎么映射到 Jenkins Job。

四、多环境 + GitFlow 集成

4.1 GitFlow 分支策略：dev / staging / release / master

Jenkinsfile 写好后，下一步是让它在不同分支跑不同的逻辑——这就是「GitFlow + Jenkins」的精髓。

我们团队用的 GitFlow（2020 年版简化版，去掉了一些繁琐环节）：

gitGraph
 commit
 commit
 branch develop
 checkout develop
 commit
 commit
 branch feature/order-v2
 checkout feature/order-v2
 commit
 commit
 checkout develop
 merge feature/order-v2
 commit
 branch release/1.0.0
 checkout release/1.0.0
 commit
 checkout master
 merge release/1.0.0 tag:"v1.0.0"
 checkout develop
 merge release/1.0.0
 branch hotfix/critical-bug
 checkout hotfix/critical-bug
 commit
 checkout master
 merge hotfix/critical-bug tag:"v1.0.1"
 checkout develop
 merge hotfix/critical-bug

6 类分支各自对应一个环境 + 触发器：

分支	环境	触发器	凭据	通知人
`feature/*`	dev	PR push	dev k8s	作者
`develop`	dev	push	dev k8s	全员
`staging`	staging	push	staging k8s	QA 团队
`release/*`	staging	push	staging k8s	QA + 研发负责人
`master`	prod	push	prod k8s	全员 + 总监
`hotfix/*`	prod	push	prod k8s	全员 + 总监

核心规则：

feature → develop：开发者 fork feature 分支开发，合到 develop 自动跑 dev 流水线
develop → staging：每周末从 develop 切 staging 分支，QA 在 staging 环境做集成测试
staging → release → master：QA 通过后切 release 分支，再合 master + 打 tag，自动触发 prod 流水线
hotfix → master：生产事故从 master 拉 hotfix 分支，修完直接合 master，同时 cherry-pick 回 develop

4.2 Webhook 配置：从 git push 到 Jenkins 触发

GitHub Webhook（Settings → Webhooks → Add）：

1
2
3


Payload URL: http://jenkins.xxx.com/generic-webhook-trigger/invoke?token=order-service-token
Content type: application/json
Events: push, pull_request

GitLab Webhook（Settings → Webhooks）：

1
2


URL: http://jenkins.xxx.com/project/order-service
Events: Push events, Merge request events

Jenkins 端配 Generic Webhook Trigger：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// Jenkinsfile 顶部
triggers {
 GenericTrigger(
 // token 唯一标识这个 job
 token: 'order-service-token',
 // 打印 payload 到控制台（调试用）
 printPostContent: true,
 // 解析 push 事件
 regexpFilterText: '$ref',
 regexpFilterExpression: '^refs/heads/(.*)$',
 // 提取分支名
 causeString: 'Triggered by push on branch',
 // 参数化注入
 genericVariables: [
 [key: 'BRANCH_FROM_PAYLOAD', value: '$.ref'],
 ]
 )
}

通用 Webhook 的 5 大优势（vs 老版 GitHub/GitLab 插件）：

支持任意 Git 平台：GitHub / GitLab / Gitee / 自建 Git，配置都一样
支持任意事件：push / pull_request / tag / release
支持复杂过滤：只触发特定分支、特定文件变更
支持参数化注入：把 webhook payload 里的 commit、author、message 注入到 Job 参数
调试友好：printPostContent: true 把整个 payload 打到控制台

4.3 Parameterized Build + 多环境凭据切换

3 个核心参数：

1
2
3
4
5
6
7
8


parameters {
 choice(name: 'ENV', choices: ['dev', 'staging', 'prod'],
 description: '部署环境')
 string(name: 'BRANCH', defaultValue: 'main',
 description: '代码分支')
 string(name: 'IMAGE_TAG', defaultValue: '',
 description: '镜像 tag（留空用 commit SHA）')
}

多环境凭据切换（最常见的坑）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


stage('Deploy') {
 steps {
 script {
 def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
 ]
 def credId = credMap[params.ENV]
 if (!credId) {
 error("未知环境：${params.ENV}")
 }
 withCredentials([file(
 credentialsId: credId,
 variable: 'KUBECONFIG'
 )]) {
 sh "kubectl --kubeconfig=${KUBECONFIG} apply -f deploy/"
 }
 }
 }
}

凭据 ID 必须用 Map 管理——不要在每个 stage 写 if (params.ENV == 'prod') 这种硬编码。

4.4 通知 + 审批流：钉钉机器人

钉钉自定义机器人配置：

钉钉群 → 群设置 → 智能群助手 → 添加机器人 → 自定义
复制 Webhook URL（含签名）
Jenkins 凭据库添加：dingtalk-webhook，类型 Secret text，值是 Webhook URL

Jenkinsfile 里发钉钉：

 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


post {
 success {
 script {
 withCredentials([string(
 credentialsId: 'dingtalk-webhook',
 variable: 'WEBHOOK'
 )]) {
 sh """
 curl -X POST ${WEBHOOK} \
 -H 'Content-Type: application/json' \
 -d '{
 "msgtype": "markdown",
 "markdown": {
 "title": "✅ 构建成功",
 "text": "## ✅ ${env.JOB_NAME} #${env.BUILD_NUMBER}\n\n**环境**: ${params.ENV}\n**分支**: ${params.BRANCH}\n**提交**: ${env.GIT_COMMIT}\n\n[查看构建](${env.BUILD_URL})"
 }
 }'
 """
 }
 }
 }
 failure {
 // 失败也发，加 @ 负责人
 ...
 }
}

生产部署的「5 分钟审批缓冲」（用 input 步骤）：

 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


stage('Deploy to Prod') {
 when {
 expression { return params.ENV == 'prod' }
 }
 steps {
 script {
 // 1. 部署到 prod
 deployToProd()
 // 2. 等 5 分钟（缓冲回滚）
 echo '等待 5 分钟观察监控...'
 sleep 300
 // 3. 人工确认
 timeout(time: 10, unit: 'MINUTES') {
 input(
 message: '生产部署后 5 分钟观察期已到，是否确认发布？',
 ok: '确认（继续）',
 submitter: 'tech-lead,devops',
 submitterParameter: 'APPROVER'
 )
 }
 // 4. 记录审批人
 echo "Prod 部署由 ${APPROVER} 确认"
 }
 }
}

submitter: 'tech-lead,devops' 表示只有技术负责人或运维才能点确认，其他人在 Jenkins 上看不到「确认」按钮。

双保险：

技术层：input 步骤人工确认
流程层：生产部署走单独的 Job（不是 dev/staging 同一个 Job），且需要 tech-lead 才能触发

第四章总结：GitFlow 分支映射到 Jenkins Job，Webhook 自动触发，参数化构建 + 多环境凭据切换，钉钉通知 + 生产审批流——这套组合拳让「代码提交 → 生产部署」全过程可追溯、可审计、可回滚。

下一章我们把 Jenkinsfile 里的可复用逻辑抽成 Shared Library——80 个微服务共用同一份构建代码。

五、共享库封装：把可复用 Stage 抽成库

5.1 共享库目录结构

到 2021 年，团队里有 80 个微服务，每个微服务的 Jenkinsfile 都长得差不多——都是 Build/Test/Sonar/Package/Docker/Push/Deploy 7 步。

问题是「差不多但不完全一样」：

30% 是 Spring Boot，10% 是 Node.js，5% 是 Python
不同服务 Docker 基础镜像不同（JDK 17 / JDK 21 / JDK 11）
不同服务 K8s namespace 不同
不同服务 SonarQube projectKey 不同

一开始我每个服务的 Jenkinsfile 复制粘贴一遍。结果：

80 个 Jenkinsfile 改了 80 次
改错一个地方，80 个服务出 bug
新人入职配一个服务的 Jenkinsfile 要 2 小时

2022 年我引入 Shared Library（共享库）——把 Jenkinsfile 里的可复用逻辑抽到一个独立 Git 仓库，80 个微服务共用。

graph TB
 Repo1[jenkins-shared-library
独立 Git 仓库] --> Vars[vars/
buildMaven.groovy
deployK8s.groovy]
 Repo1 --> Src[src/com/myteam/ci/
Utils.groovy
DockerUtils.groovy]
 Repo1 --> Res[resources/
sonar-template.properties
dockerfile-templates/]

 M1[order-service
Jenkinsfile] -->|@Library| Vars
 M2[user-service
Jenkinsfile] -->|@Library| Vars
 M3[payment-service
Jenkinsfile] -->|@Library| Vars

 style Repo1 fill:#3c82dc,color:#fff
 style M1 fill:#5aa0e8,color:#fff
 style M2 fill:#5aa0e8,color:#fff
 style M3 fill:#5aa0e8,color:#fff

目录结构（Jenkins 规定）：

 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


jenkins-shared-library/ # 独立 Git 仓库
├── vars/ # 【声明式直接调用的方法】
│ ├── buildMaven.groovy # 文件名 = 方法名
│ ├── buildNode.groovy
│ ├── buildPython.groovy
│ ├── dockerBuild.groovy
│ ├── dockerPush.groovy
│ ├── deployK8s.groovy
│ ├── deployArgoRollout.groovy
│ ├── notifyDingTalk.groovy
│ └── sonarScan.groovy
├── src/ # 【普通 Groovy 类】
│ └── com/myteam/ci/
│ ├── Utils.groovy # 工具类
│ ├── DockerUtils.groovy
│ └── K8sUtils.groovy
├── resources/ # 【静态资源】
│ ├── com/myteam/ci/
│ │ └── Dockerfile-template.txt # Dockerfile 模板
│ └── sonar/
│ └── sonar-template.properties
├── test/ # 【单元测试】
│ └── com/myteam/ci/
│ └── UtilsTest.groovy
├── README.md
└── CHANGELOG.md

关键约定：

vars/ 下的 .groovy 文件文件名 = 方法名，声明式 Pipeline 里直接调用
src/ 下的类不会被声明式直接调用，需要 import 或 def utils = new com.myteam.ci.Utils()
resources/ 下的文件运行时可通过 libraryResource 'path/to/file' 读取

5.2 完整 vars/ 脚本

vars/buildMaven.groovy（构建 Java 服务）：

 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


// vars/buildMaven.groovy
import com.myteam.ci.Utils

def call(Map args) {
 // 参数校验
 if (!args.projectName) {
 error "buildMaven 必须传 projectName 参数"
 }
 def projectName = args.projectName
 def goals = args.goals ?: 'clean package'
 def skipTests = args.skipTests ?: false
 def useJacoco = args.useJacoco ?: true

 // 打印分隔
 Utils.printBanner("Maven Build: ${projectName}")

 // 1. 编译
 sh "mvn -B -V -T 4 -pl ${projectName} -am clean compile"

 // 2. 测试
 if (!skipTests) {
 sh "mvn -B -pl ${projectName} -am test"
 junit allowEmptyResults: true,
 testResults: "**/${projectName}/target/surefire-reports/*.xml"
 if (useJacoco) {
 jacoco(execPattern: "**/${projectName}/target/jacoco.exec",
 minimumLineCoverage: '0.60')
 }
 }

 // 3. 打包
 sh "mvn -B -pl ${projectName} -am -DskipTests clean package"
 archiveArtifacts artifacts: "${projectName}/target/*.jar",
 fingerprint: true
}

vars/deployK8s.groovy（部署到 K8s）：

 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


// vars/deployK8s.groovy
import com.myteam.ci.K8sUtils

def call(Map args) {
 def env = args.env
 def appName = args.appName
 def image = args.image
 def namespace = args.namespace ?: env
 def replicas = args.replicas ?: 3
 def waitTime = args.waitTime ?: '5m'

 // 环境校验
 if (!['dev', 'staging', 'prod'].contains(env)) {
 error "deployK8s env 必须是 dev/staging/prod，当前：${env}"
 }

 // 凭据切换
 def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
 ]

 withCredentials([file(
 credentialsId: credMap[env],
 variable: 'KUBECONFIG'
 )]) {
 Utils.printBanner("Deploy ${appName} to ${env}")

 // 1. 替换镜像
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 set image deployment/${appName} \
 ${appName}=${image} \
 -n ${namespace}
 """

 // 2. 等待 rollout
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 rollout status deployment/${appName} \
 -n ${namespace} \
 --timeout=${waitTime}
 """

 // 3. 健康检查
 K8sUtils.healthCheck(
 kubeconfig: env.KUBECONFIG,
 appName: appName,
 namespace: namespace
 )
 }
}

src/com/myteam/ci/Utils.groovy（共享工具类）：

 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


// src/com/myteam/ci/Utils.groovy
package com.myteam.ci

class Utils implements Serializable {
 private static final long serialVersionUID = 1L

 static void printBanner(String text) {
 def line = '*' * (text.length() + 8)
 println ""
 println line
 println "*** ${text} ***"
 println line
 }

 static String getGitShortSha() {
 return sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
 }

 static Map parseEnv(String envStr) {
 def parts = envStr.split('/')
 return [
 cluster: parts[0],
 namespace: parts.size() > 1 ? parts[1] : 'default'
 ]
 }
}

声明式 Pipeline 里调用：

 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


// order-service/Jenkinsfile
@Library('jenkins-shared-library@1.0.0') _ // 锁版本！

pipeline {
 agent none
 stages {
 stage('Build') {
 agent { label 'maven' }
 steps {
 buildMaven(
 projectName: 'order-service',
 goals: 'clean package',
 skipTests: false
 )
 }
 }
 stage('Deploy') {
 agent { label 'k8s' }
 steps {
 deployK8s(
 env: 'dev',
 appName: 'order-service',
 image: "${DOCKER_IMAGE}"
 )
 }
 }
 }
}

对比两种写法：

维度	每个项目独立 Jenkinsfile	用 Shared Library
新服务接入	复制粘贴 Jenkinsfile，改 5 处	加 1 个调用，改 1 处
改构建逻辑	80 个 Jenkinsfile 改 80 次	共享库改 1 处，80 个服务生效
复用率	30-40% 代码重复	90%+ 复用
学习成本	看懂每个项目的 Jenkinsfile	看懂共享库
推荐	5 个服务以内	5+ 服务必上

5.3 版本管理与灰度发布

共享库版本策略：

1
2
3
4
5
6


# 共享库仓库打 tag
git tag -a v1.0.0 -m "stable"
git push origin v1.0.0

# Jenkinsfile 锁版本
@Library('jenkins-shared-library@1.0.0') _

SemVer 规范：

v1.x.y：1.x 互相兼容，小版本 y 加 feature
v2.0.0：大版本不兼容，必须升级所有调用方

灰度发布策略（推荐）：

graph LR
 A[v1.0.0 老 Pipeline 继续] --> B[新 Pipeline 切 v2.0.0]
 B --> C[观察 1 个月]
 C --> D[所有 Pipeline 升级 v2.0.0]
 D --> E[v1.0.0 弃用]

Jenkins 全局配置共享库：

Manage Jenkins → System → Global Pipeline Libraries
Name: jenkins-shared-library
Default version: main（开发分支）
勾选：Allow default version to be overridden / Include @Library changes in build results
Retrieval method: Modern SCM → Git
Project repository: git@github.com:myteam/jenkins-shared-library.git
Credentials: github-ssh-key

强制锁版本：

Jenkinsfile 第一行必须显式写版本号——@Library('jenkins-shared-library@1.0.0') _，不能省略版本。否则共享库主干一改，所有 Pipeline 立刻受影响，生产事故高发。

5.4 共享库单元测试

共享库没有测试 = 改一行所有服务崩。Jenkins 官方推荐 Jenkins Pipeline Unit 框架：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// test/com/myteam/ci/UtilsTest.groovy
package com.myteam.ci

import org.junit.Test
import static org.junit.Assert.assertEquals

class UtilsTest {
 @Test
 void testParseEnv() {
 def result = Utils.parseEnv('prod/order')
 assertEquals 'prod', result.cluster
 assertEquals 'order', result.namespace
 }

 @Test
 void testParseEnvWithoutNamespace() {
 def result = Utils.parseEnv('dev')
 assertEquals 'dev', result.cluster
 assertEquals 'default', result.namespace
 }
}

跑测试：

1

./gradlew test # 或 mvn test

测试覆盖率要求：共享库核心方法覆盖率 ≥ 80%。

第五章总结：共享库让 80 个微服务共用同一份构建/部署逻辑，改一处生效全栈。版本管理 + 灰度发布保证升级安全。

下一章我们把流水线接到容器化部署——Jenkins 构建 Docker 镜像 + 推 Harbor + Helm 打包 K8s manifests。

六、Docker + K8s 集成

6.1 Docker Agent 设计：DIND vs Docker Socket

Jenkins 构建 Docker 镜像有 3 种方案，选错会爆：

方案	原理	优势	劣势
DIND（Docker in Docker）	Agent 容器内跑独立 docker daemon	完全隔离、安全	慢（每个 build 起 daemon）、镜像缓存不共享
Socket 挂载	挂宿主机 `/var/run/docker.sock`	快（复用宿主机 daemon）、镜像共享	权限大（容器内能改宿主机所有镜像）
Kaniko	不需要 docker daemon，纯 rootless	适合 K8s Pod 内构建、rootless	学习曲线、调试难

我的选型：

本地 demo / 开发环境：Socket 挂载——构建快、镜像能直接在 K8s 看到
生产 CI：DIND——隔离好，每个 build 是干净的 docker daemon
K8s Pod Agent：Kaniko——Pod 内 rootless 构建

DIND 配置（生产推荐）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# docker-compose.yml
docker-agent:
 image: docker:24-dind
 privileged: true # DIND 必须特权模式
 environment:
 - DOCKER_TLS_CERTDIR=  # 关闭 TLS（容器内用）
 volumes:
 - docker_data:/var/lib/docker  # 独立 docker 数据卷
 networks:
 - jenkins-net

Socket 挂载配置（本地 demo）：

1
2
3
4
5
6


# docker-compose.yml
maven-agent:
 image: maven:3.9-eclipse-temurin-17
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock
 - /usr/bin/docker:/usr/bin/docker:ro

注意：

Socket 挂载时 user 必须是 root（默认 user 1000 没有 docker.sock 权限）
或者把 docker.sock 权限改成 666（chmod 666 /var/run/docker.sock）
容器内能调宿主机 docker = 能 rm 任何镜像、起任何容器，生产环境慎用

6.2 Dockerfile 最佳实践

生产级 Dockerfile（Java 17 + Spring Boot）：

 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


# syntax=docker/dockerfile:1.7
# 多阶段构建：第一阶段用 JDK 编译，第二阶段用 JRE 跑

# ===== Stage 1: Build =====
FROM eclipse-temurin:17-jdk AS builder
WORKDIR /build

# 1. 先复制 POM（利用 Docker 缓存）
COPY pom.xml ./
COPY common-lib/pom.xml common-lib/
COPY order-service/pom.xml order-service/
RUN mvn -B -T 4 -q dependency:go-offline

# 2. 复制源码
COPY . .

# 3. 打包
RUN mvn -B -pl order-service -am -DskipTests clean package

# ===== Stage 2: Runtime =====
FROM eclipse-temurin:17-jre-jammy
WORKDIR /app

# 4. 安装必要工具
RUN apt-get update && \
 apt-get install -y --no-install-recommends curl tini && \
 rm -rf /var/lib/apt/lists/*

# 5. 复制 jar
COPY --from=builder /build/order-service/target/*.jar app.jar

# 6. 标签元数据
LABEL org.opencontainers.image.title="order-service" \
 org.opencontainers.image.version="${VERSION}" \
 org.opencontainers.image.revision="${GIT_SHA}" \
 org.opencontainers.image.source="https://github.com/myteam/order-service"

# 7. 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
 CMD curl -f http://localhost:8080/actuator/health || exit 1

# 8. 用 tini 作为 init 进程（处理僵尸进程）
ENTRYPOINT ["/usr/bin/tini", "--", "java", \
 "-XX:+UseContainerSupport", \
 "-XX:MaxRAMPercentage=75.0", \
 "-Djava.security.egd=file:/dev/./urandom", \
 "-jar", "/app/app.jar"]

EXPOSE 8080

5 大最佳实践：

多阶段构建：构建阶段用 JDK（含编译工具），运行阶段用 JRE（省 200MB）
先 COPY POM 再 COPY 源码：利用 Docker layer 缓存，Maven 依赖不重下
-XX:MaxRAMPercentage=75.0：让 JVM 自动适配 K8s limit，不写死 -Xmx
tini 作为 init 进程：处理孤儿进程、转发信号，Java 进程优雅退出
HEALTHCHECK 内置：让 K8s 知道容器是否健康，livenessProbe 不用调外部脚本

镜像体积优化对比：

基础镜像	体积	启动时间
`openjdk:17-jdk`	700MB	慢
`eclipse-temurin:17-jdk`	480MB	中
`eclipse-temurin:17-jre`	280MB	快
`eclipse-temurin:17-jre-alpine`	180MB	最快
`eclipse-temurin:17-jre-jammy`	280MB	快（推荐）

Alpine 注意：musl libc 跟 glibc 不完全兼容，Netty / DNS 解析偶尔有坑，生产建议用 jammy（Ubuntu 22.04 基础）。

6.3 Helm Chart 打包：Deployment + Service + Ingress

Helm Chart 目录结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


charts/order-service/
├── Chart.yaml
├── values.yaml
├── values-dev.yaml
├── values-staging.yaml
├── values-prod.yaml
└── templates/
 ├── deployment.yaml
 ├── service.yaml
 ├── ingress.yaml
 ├── configmap.yaml
 ├── serviceaccount.yaml
 ├── hpa.yaml
 ├── pdb.yaml
 └── _helpers.tpl

Chart.yaml：

1
2
3
4
5
6
7
8
9


apiVersion: v2
name: order-service
description: Order Service for MyTeam
type: application
version: 1.0.0
appVersion: "1.0.0"
maintainers:
 - name: MyTeam DevOps
 email: devops@xxx.com

values.yaml（默认值）：

 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


replicaCount: 3

image:
 repository: harbor.xxx.com/myteam/order-service
 pullPolicy: IfNotPresent
 tag: "" # 留空，CI 覆盖

imagePullSecrets:
 - name: harbor-pull-secret

service:
 type: ClusterIP
 port: 8080
 targetPort: 8080

ingress:
 enabled: true
 className: nginx
 annotations:
 nginx.ingress.kubernetes.io/ssl-redirect: "true"
 hosts:
 - host: order-service.xxx.com
 paths:
 - path: /
 pathType: Prefix
 tls:
 - hosts:
 - order-service.xxx.com
 secretName: order-service-tls

resources:
 requests:
 cpu: 500m
 memory: 1Gi
 limits:
 cpu: 2000m
 memory: 2Gi

autoscaling:
 enabled: true
 minReplicas: 3
 maxReplicas: 10
 targetCPUUtilizationPercentage: 70

probes:
 liveness:
 path: /actuator/health/liveness
 initialDelaySeconds: 60
 periodSeconds: 10
 readiness:
 path: /actuator/health/readiness
 initialDelaySeconds: 30
 periodSeconds: 5

env:
 - name: SPRING_PROFILES_ACTIVE
 value: prod
 - name: JAVA_OPTS
 value: "-Xms512m -Xmx1536m"

templates/deployment.yaml：

 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


apiVersion: apps/v1
kind: Deployment
metadata:
 name: {{ include "order-service.fullname" . }}
 labels:
 {{- include "order-service.labels" . | nindent 4 }}
spec:
 {{- if not .Values.autoscaling.enabled }}
 replicas: {{ .Values.replicaCount }}
 {{- end }}
 selector:
 matchLabels:
 {{- include "order-service.selectorLabels" . | nindent 6 }}
 template:
 metadata:
 labels:
 {{- include "order-service.selectorLabels" . | nindent 8 }}
 spec:
 imagePullSecrets:
 {{- toYaml .Values.imagePullSecrets | nindent 8 }}
 containers:
 - name: {{ .Chart.Name }}
 image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
 imagePullPolicy: {{ .Values.image.pullPolicy }}
 ports:
 - name: http
 containerPort: {{ .Values.service.targetPort }}
 livenessProbe:
 {{- toYaml .Values.probes.liveness | nindent 12 }}
 readinessProbe:
 {{- toYaml .Values.probes.readiness | nindent 12 }}
 resources:
 {{- toYaml .Values.resources | nindent 12 }}
 env:
 {{- toYaml .Values.env | nindent 12 }}

多环境 values 覆盖（values-prod.yaml）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


replicaCount: 5

resources:
 requests:
 cpu: 1000m
 memory: 2Gi
 limits:
 cpu: 4000m
 memory: 4Gi

autoscaling:
 minReplicas: 5
 maxReplicas: 20

env:
 - name: SPRING_PROFILES_ACTIVE
 value: prod
 - name: LOG_LEVEL
 value: INFO

6.4 Jenkinsfile 中调用 Helm 部署

 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


stage('Deploy with Helm') {
 agent { label 'k8s' }
 steps {
 script {
 def credMap = [
 dev: 'k8s-dev-creds',
 staging: 'k8s-stg-creds',
 prod: 'k8s-prod-creds'
 ]
 withCredentials([file(
 credentialsId: credMap[params.ENV],
 variable: 'KUBECONFIG'
 )]) {
 // 1. 校验
 sh """
 helm lint ./charts/order-service \
 --values ./charts/order-service/values-${params.ENV}.yaml
 """

 // 2. 模板预览（dry run）
 sh """
 helm template order-service ./charts/order-service \
 --values ./charts/order-service/values-${params.ENV}.yaml \
 --set image.tag=${IMAGE_TAG}
 """

 // 3. 部署
 sh """
 helm upgrade --install order-service ./charts/order-service \
 --kubeconfig=\${KUBECONFIG} \
 --namespace ${K8S_NAMESPACE} \
 --values ./charts/order-service/values-${params.ENV}.yaml \
 --set image.tag=${IMAGE_TAG} \
 --wait \
 --timeout 5m \
 --history-max 10
 """
 }
 }
 }
}

关键参数解析：

--wait：等到所有 Pod Ready 才返回（阻塞）
--timeout 5m：超时 5 分钟
--history-max 10：保留 10 个历史版本（便于回滚）
--set image.tag=${IMAGE_TAG}：动态覆盖镜像 tag

回滚命令（生产事故救命）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 列出历史版本
helm history order-service -n prod
# 输出：
# REVISION STATUS CHART APP VERSION DESCRIPTION
# 1 failed order-service 1.0.0 Install failed
# 2 superseded order-service 1.0.0 Upgrade complete
# 3 deployed order-service 1.0.0 Upgrade complete
# 4 superseded order-service 1.0.0 Upgrade complete
# 5 deployed order-service 1.0.0 Upgrade complete

# 回滚到版本 4
helm rollback order-service 4 -n prod

Helm + GitOps：把 values.yaml + Chart.yaml + templates/ 推 Git，Argo CD 监听 Git 自动部署（强烈推荐，下章细讲）。

第六章总结：Docker 多阶段构建 + 镜像体积优化 + Helm Chart 多环境覆盖 + Jenkinsfile 调 Helm 部署，容器化部署全链路打通。

下一章我们把 K8s 原生蓝绿发布做透——双 Service + 双 Deployment + 一键切流。

七、蓝绿发布全流程

7.1 蓝绿发布原理：双 Service 双 Deployment

到 2022 年中，我们团队的事故率降到接近 0——主要靠「蓝绿发布」兜底。

蓝绿发布的核心思想：任意时刻只有一套环境接流量。新版本先部署到「非活跃」环境，验证通过后一键切流量；出问题了切回原版本，2 秒回滚。

stateDiagram-v2
 [*] --> BlueActive: 初始状态
 BlueActive --> GreenDeploying: 部署 v2 到 green
 GreenDeploying --> GreenReady: 健康检查通过
 GreenReady --> GreenReady: 5 分钟观察
 GreenReady --> GreenActive: 切流量到 green
 GreenActive --> GreenActive: 监控 1 小时
 GreenActive --> BlueActive: 保留 blue 1 小时（回滚缓冲）
 GreenActive --> Failed: 出问题
 Failed --> BlueActive: 一键切回 blue（2 秒）
 GreenActive --> [*]

4 大优势：

回滚极快——切 Service selector 而非重新部署，2 秒回滚
风险窗口小——切流瞬间只有「活跃服务」接流量，没有「老服务还在接新流量」的中间态
零停机——整个过程用户无感知
数据库兼容测试——可以在 green 跑数据库 schema migration，确认无问题再切

3 大劣势：

资源 2x——同时跑 2 套环境，资源成本翻倍
数据库 schema 必须向前向后兼容——green 和 blue 读同一份数据库，不能有 incompatible 变更
不适合「session 黏性」应用——切流后用户的 session 状态丢失（除非共享 session 存储）

适用场景：

金融、支付类（风险厌恶）
7x24 业务（不能有停机窗口）
单服务变更不频繁（资源成本可接受）

7.2 K8s 资源模板：双 Service + 双 Deployment

核心资源：1 个 Ingress（对外）+ 2 个 Service（blue/green）+ 2 个 Deployment（blue/green）

 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


# deployment-blue.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: order-service-blue
 labels:
 app: order-service
 version: blue
spec:
 replicas: 3
 selector:
 matchLabels:
 app: order-service
 version: blue
 template:
 metadata:
 labels:
 app: order-service
 version: blue
 spec:
 containers:
 - name: order-service
 image: harbor.xxx.com/myteam/order-service:v1.0.0
 ports:
 - containerPort: 8080
 resources:
 requests: { cpu: '500m', memory: '1Gi' }
 limits: { cpu: '2000m', memory: '2Gi' }
 readinessProbe:
 httpGet: { path: /actuator/health/readiness, port: 8080 }
 initialDelaySeconds: 30
 periodSeconds: 5
---
# deployment-green.yaml（与 blue 完全相同，只是 name 和 version 不同）
apiVersion: apps/v1
kind: Deployment
metadata:
 name: order-service-green
 labels:
 app: order-service
 version: green
spec:
 replicas: 3
 selector:
 matchLabels:
 app: order-service
 version: green
 template:
 metadata:
 labels:
 app: order-service
 version: green
 spec:
 containers:
 - name: order-service
 image: harbor.xxx.com/myteam/order-service:v1.0.0
 ports:
 - containerPort: 8080 }
 # ... 同 blue

 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


# service-blue.yaml（流量接到 blue）
apiVersion: v1
kind: Service
metadata:
 name: order-service
spec:
 selector:
 app: order-service
 version: blue  # ← 关键：这里决定流量去哪个 Deployment
 ports:
 - port: 80
 targetPort: 8080
---
# service-green-dummy.yaml（用于健康检查）
apiVersion: v1
kind: Service
metadata:
 name: order-service-green-debug
spec:
 selector:
 app: order-service
 version: green
 ports:
 - port: 80
 targetPort: 8080

关键设计：

主 Service 名为 order-service，不带 blue/green 后缀——Ingress 引用它，对外 URL 不变
service-green-debug 只用于调试访问（开发/QA 内部访问 green 版本，不影响生产流量）
HPA 必须分别配——blue HPA 和 green HPA 独立伸缩
PodDisruptionBudget 分别配——保证滚动更新时至少 1 个 Pod 可用

7.3 Jenkinsfile 蓝绿切流

 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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


stage('Blue-Green Deploy') {
 agent { label 'k8s' }
 steps {
 script {
 def credId = credMap[params.ENV]
 withCredentials([file(credentialsId: credId, variable: 'KUBECONFIG')]) {
 // 1. 判定当前活跃色
 def activeColor = sh(
 returnStdout: true,
 script: """
 kubectl --kubeconfig=\${KUBECONFIG} get svc order-service \
 -n ${K8S_NAMESPACE} \
 -o jsonpath='{.spec.selector.version}'
 """
 ).trim()
 def standbyColor = (activeColor == 'blue') ? 'green' : 'blue'

 echo "当前活跃：${activeColor}，将部署到：${standbyColor}"

 // 2. 部署新版本到 standby
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 set image deployment/order-service-${standbyColor} \
 order-service=${DOCKER_IMAGE} \
 -n ${K8S_NAMESPACE}

 kubectl --kubeconfig=\${KUBECONFIG} \
 rollout status deployment/order-service-${standbyColor} \
 -n ${K8S_NAMESPACE} \
 --timeout=5m
 """

 // 3. 健康检查（访问 green-debug Service）
 sh """
 sleep 30
 for i in {1..10}; do
 if kubectl --kubeconfig=\${KUBECONFIG} \
 exec deploy/order-service-${standbyColor} \
 -n ${K8S_NAMESPACE} -- \
 curl -sf http://localhost:8080/actuator/health; then
 echo "健康检查通过"
 break
 fi
 echo "等待健康检查... \${i}/10"
 sleep 10
 done
 """

 // 4. 灰度（可选）：先切 10% 流量观察
 if (params.ENV == 'prod') {
 input(
 message: "新版本已部署到 ${standbyColor}，是否切流？",
 ok: "切流到 ${standbyColor}",
 submitter: 'tech-lead,devops'
 )
 }

 // 5. 切流量
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 patch svc order-service \
 -n ${K8S_NAMESPACE} \
 -p '{"spec":{"selector":{"version":"${standbyColor}"}}}'

 echo "流量已切到 ${standbyColor}"
 """

 // 6. 观察 1 小时
 echo "观察 1 小时（保留 ${activeColor} 部署做回滚缓冲）"
 sleep 3600

 // 7. 清理旧部署
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 scale deployment/order-service-${activeColor} \
 --replicas=0 \
 -n ${K8S_NAMESPACE}
 """
 }
 }
 }
}

5 大安全卡点：

判定活跃色——自动判断当前在 blue 还是 green
健康检查——切流前确认新版本健康
生产人工审批——input 步骤让 tech-lead 确认
保留旧部署 1 小时——出问题一键切回
1 小时后清理——避免资源浪费

回滚操作（生产事故）：

1
2
3


# 2 秒回滚（假设当前在 green，blue 还在）
kubectl patch svc order-service -n prod \
 -p '{"spec":{"selector":{"version":"blue"}}}'

回滚后检查清单：

监控告警是否恢复（错误率、延迟）
用户反馈（客服群、社交媒体）
业务数据（订单量、转化率）
复盘事故根因

7.4 蓝绿 vs Argo Rollouts：什么时候用哪个

维度	蓝绿	Argo Rollouts
切流粒度	二选一（100% / 0%）	任意比例（1% / 10% / 50% / 100%）
自动判定	需要人工审批	可按 Prometheus 指标自动推进/回滚
资源占用	2x	1.x（滚动过程短暂 2x）
复杂度	中（手工管）	高（Argo Rollouts 概念多）
适用	风险厌恶业务	快速迭代业务

我的混合策略：

核心业务（支付、订单）：用蓝绿——简单、可控、回滚 2 秒
非核心业务（CMS、运营后台）：用 Argo Rollouts 金丝雀——自动化、节省资源

下一章我们把 Argo Rollouts 金丝雀做透——按 Prometheus 指标自动推进/回滚。

八、金丝雀发布全流程

8.1 金丝雀 vs 蓝绿：渐进式 vs 一次性

2023 年初，我们团队开始用 Argo Rollouts 做金丝雀发布——金丝雀是「渐进式切流」，蓝绿是「一次性切流」。

stateDiagram-v2
 [*] --> Stable: 100% 流量老版本
 Stable --> Canary1: 部署金丝雀 5% 流量
 Canary1 --> Analysis1: 跑 5 分钟
 Analysis1 --> Canary2: 指标通过 → 15%
 Analysis1 --> Aborted: 指标失败
 Canary2 --> Analysis2: 跑 5 分钟
 Analysis2 --> Canary3: 指标通过 → 30%
 Analysis2 --> Aborted: 指标失败
 Canary3 --> Analysis3: 跑 5 分钟
 Analysis3 --> Canary4: 指标通过 → 50%
 Analysis3 --> Aborted: 指标失败
 Canary4 --> ManualApproval: 跑 5 分钟
 ManualApproval --> Full: 人工批准 → 100%
 ManualApproval --> Aborted: 人工拒绝
 Aborted --> Stable: 一键回滚
 Full --> Stable: 部署完成

5 大优势：

风险最小——开始只有 5% 流量出错，爆炸半径小
指标驱动——按 Prometheus 指标自动判定，不需要人工盯
资源相对省——不像蓝绿需要 2x 资源，只是短暂 2x
可重复——同样的发布配置，每个服务都能复用
可观测——每个阶段的指标都看得到

3 大挑战：

概念多——Rollout、AnalysisTemplate、AnalysisRun、Experiment、Step
依赖 Prometheus——必须先有完善的指标采集
调试复杂——出问题需要看 Rollout 状态 + AnalysisRun 详情 + Service Mesh 流量分发

8.2 Argo Rollouts 是什么：K8s Deployment 的「超集」

Argo Rollouts 是 Intuit 开源（被 CNCF 接纳为 Incubating）的 K8s 控制器，提供高级部署策略：

Blue-Green（蓝绿）
Canary（金丝雀）
Progressive Delivery（渐进式）
Analysis（基于指标的自动判定）

3 个核心 CRD：

graph LR
 Rollout[Rollout
替代 Deployment] --> AnalysisTemplate[AnalysisTemplate
指标查询模板]
 Rollout --> Service[Service
流量入口]
 AnalysisTemplate -.引用.-> AnalysisRun[AnalysisRun
单次执行]
 AnalysisRun -.查指标.-> Prometheus[Prometheus]

 style Rollout fill:#3c82dc,color:#fff
 style AnalysisTemplate fill:#ff9a3c,color:#fff
 style AnalysisRun fill:#5aa0e8,color:#fff

Rollout：替代 Deployment 的部署对象，支持蓝绿/金丝雀策略
AnalysisTemplate：指标查询模板（PromQL + 成功/失败条件）
AnalysisRun：AnalysisTemplate 的一次执行，返回 success / failure

安装（在 k3d 本地或生产 K8s）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 安装 controller
kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/download/v1.7.0/install.yaml

# 安装 kubectl plugin（本地）
curl -LO https://github.com/argoproj/argo-rollouts/releases/download/v1.7.0/kubectl-argo-rollouts-linux-amd64
chmod +x kubectl-argo-rollouts-linux-amd64
mv kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts

# 验证
kubectl argo rollouts version

8.3 Rollout 资源模板

rollout.yaml（金丝雀策略，5 阶段渐进）：

 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


apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
 name: order-service
 namespace: prod
spec:
 replicas: 5
 revisionHistoryLimit: 3
 selector:
 matchLabels:
 app: order-service
 strategy:
 canary:
 # 5 阶段渐进：5% → 15% → 30% → 50% → 100%
 steps:
 - setWeight: 5
 - pause: { duration: 5m }  # 5 分钟观察
 - setWeight: 15
 - pause: { duration: 5m }
 - setWeight: 30
 - pause: { duration: 5m }
 - setWeight: 50
 - pause: { duration: 5m }
 # 最后一步：人工确认才 100%
 - setWeight: 80
 - pause: { duration: 10m }
 # 自动判定：跑 AnalysisTemplate
 - analysis:
 templates:
 - templateName: success-rate
 - templateName: latency-p99
 - setWeight: 100
 # 流量切分：Nginx Ingress
 trafficRouting:
 nginx:
 stableIngressName: order-service-stable
 additionalIngressAnnotations:
 canary-by-header: X-Canary  # 支持按 header 切
 canary-by-header-value: enabled
 # 失败回滚：自动 abort
 abortScaleDownDelaySeconds: 30
 template:
 metadata:
 labels:
 app: order-service
 spec:
 containers:
 - name: order-service
 image: harbor.xxx.com/myteam/order-service:v1.0.0
 ports:
 - containerPort: 8080
 resources:
 requests: { cpu: '500m', memory: '1Gi' }
 limits: { cpu: '2000m', memory: '2Gi' }
 readinessProbe:
 httpGet: { path: /actuator/health/readiness, port: 8080 }
 initialDelaySeconds: 30
 periodSeconds: 5

配套 Service（金丝雀模式下 Service 指向 stable Service）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Service
metadata:
 name: order-service-stable
spec:
 selector:
 app: order-service
 ports:
 - port: 80
 targetPort: 8080

配套 Ingress（用 Nginx Ingress 做流量切分）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: order-service-stable
 annotations:
 nginx.ingress.kubernetes.io/rewrite-target: /
spec:
 ingressClassName: nginx
 rules:
 - host: order-service.xxx.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: order-service-stable
 port:
 number: 80

Argo Rollouts 自动生成 order-service-canary Ingress，Nginx 控制器按 weight 分发流量。

8.4 AnalysisTemplate：按 Prometheus 指标自动判定

3 个核心指标模板：

 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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95


# 1. 成功率（HTTP 5xx 率 < 1%）
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
 name: success-rate
 namespace: prod
spec:
 args:
 - name: service-name
 - name: canary-hash
 metrics:
 - name: http-5xx-rate
 interval: 60s
 count: 5 # 连续 5 次（5 分钟）指标都满足才通过
 successCondition: result[0] < 0.01
 failureLimit: 2 # 连续 2 次失败就 abort
 failureCondition: result[0] > 0.05
 provider:
 prometheus:
 address: http://prometheus.monitoring.svc.cluster.local:9090
 query: |
 sum(rate(
 http_requests_total{
 app="{{args.service-name}}",
 version="canary",
 status=~"5.."
 }[5m]
 )) /
 sum(rate(
 http_requests_total{
 app="{{args.service-name}}",
 version="canary"
 }[5m]
 ))
---
# 2. P99 延迟（< 500ms）
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
 name: latency-p99
 namespace: prod
spec:
 args:
 - name: service-name
 metrics:
 - name: p99-latency
 interval: 60s
 count: 5
 successCondition: result[0] < 0.5
 failureLimit: 2
 provider:
 prometheus:
 address: http://prometheus.monitoring.svc.cluster.local:9090
 query: |
 histogram_quantile(0.99,
 sum(rate(
 http_request_duration_seconds_bucket{
 app="{{args.service-name}}",
 version="canary"
 }[5m]
 )) by (le)
 )
---
# 3. 业务指标（订单成功率 > 99%）
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
 name: business-conversion
 namespace: prod
spec:
 args:
 - name: service-name
 metrics:
 - name: order-success-rate
 interval: 60s
 count: 5
 successCondition: result[0] > 0.99
 failureLimit: 2
 provider:
 prometheus:
 address: http://prometheus.monitoring.svc.cluster.local:9090
 query: |
 sum(rate(
 orders_created_total{
 app="{{args.service-name}}",
 status="success",
 version="canary"
 }[5m]
 )) /
 sum(rate(
 orders_created_total{
 app="{{args.service-name}}",
 version="canary"
 }[5m]
 ))

判定逻辑解读：

interval: 60s + count: 5 = 每 60 秒查一次，连续 5 次都满足才通过
successCondition: result[0] < 0.01 = 5xx 率 < 1% 算成功
failureLimit: 2 = 连续 2 次失败就 abort
业务指标 + 技术指标双保险——不仅 HTTP 5xx 少，订单成功率也要高

4 大推荐指标：

指标类型	阈值	失败动作
HTTP 5xx 率	< 1%	abort
P99 延迟	< 500ms	abort
JVM 堆使用率	< 80%	warn（不 abort）
业务转化率	> 99%	abort

8.5 Jenkinsfile + Argo Rollouts 调用

 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


stage('Canary Deploy') {
 agent { label 'k8s' }
 steps {
 script {
 def credId = credMap[params.ENV]
 withCredentials([file(credentialsId: credId, variable: 'KUBECONFIG')]) {
 // 1. 更新 Rollout 镜像
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 argo rollouts set image order-service \
 order-service=${DOCKER_IMAGE} \
 -n ${K8S_NAMESPACE}
 """

 // 2. 阻塞等金丝雀完成
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 argo rollouts get rollout order-service \
 -n ${K8S_NAMESPACE} \
 --watch \
 --timeout 1h
 """

 // 3. 检查结果
 sh """
 STATUS=\$(kubectl --kubeconfig=\${KUBECONFIG} \
 argo rollouts get rollout order-service \
 -n ${K8S_NAMESPACE} \
 -o jsonpath='{.status.phase}')

 if [ "\$STATUS" != "Healthy" ]; then
 echo "金丝雀发布未健康完成：\$STATUS"
 exit 1
 fi
 """
 }
 }
 }

 post {
 success {
 echo '金丝雀发布成功！'
 }
 failure {
 script {
 // 自动 abort + 告警
 sh """
 kubectl --kubeconfig=\${KUBECONFIG} \
 argo rollouts abort order-service \
 -n ${K8S_NAMESPACE}
 """
 // 钉钉告警
 ...
 }
 }
 }
}

5 个核心操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 1. 查看状态
kubectl argo rollouts get rollout order-service -n prod

# 2. 暂停金丝雀（手动介入）
kubectl argo rollouts pause order-service -n prod

# 3. 恢复金丝雀
kubectl argo rollouts resume order-service -n prod

# 4. 手动 promote 到 100%
kubectl argo rollouts promote order-service -n prod

# 5. Abort 回滚
kubectl argo rollouts abort order-service -n prod

Dashboard 可视化（强烈推荐）：

1
2
3
4
5
6
7
8


# 安装 Argo Rollouts Dashboard
kubectl apply -f https://github.com/argoproj/argo-rollouts/releases/download/v1.7.0/dashboard-install.yaml

# 端口转发
kubectl port-forward svc/argo-rollouts-dashboard 31000:31000 -n argo-rollouts

# 访问 http://localhost:31000
# 可以看到所有 Rollout 的金丝雀进度、AnalysisTemplate 状态、历史

8.6 金丝雀 5 大实战经验

指标必须有，否则别上金丝雀——没指标的「渐进式发布」等于「盲切」，出问题不知道怎么回滚
prometheus-adapter 必须装——Argo Rollouts 通过 ServiceMonitor 找 Prometheus
canary-hash 标签自动注入——Rollout Controller 会给金丝雀 Pod 打 rollouts-pod-template-hash 标签，PromQL 用来区分版本
可以按 header 切（灰度测试）——设置 X-Canary: enabled header，流量强制走新版本，QA 验证用
失败立即 abort——failureLimit: 2，不要等 5 次失败才反应（5 分钟已经太久了）

第八章总结：Argo Rollouts 是 K8s Deployment 的「超集」，金丝雀发布按 Prometheus 指标自动推进/回滚，5 阶段渐进（5% → 15% → 30% → 50% → 100%），Jenkinsfile 一行命令触发。

九、收尾：从 CI 到 GitOps 闭环

9.1 Argo CD 集成：让 CI 推 Git、CD 同步 K8s

到 2024 年，我们团队把流水线演进到 GitOps 闭环——CI 和 CD 完全解耦：

Jenkins 责任：代码 → 构建 → 测试 → 扫描 → 推镜像
Argo CD 责任：监听 Git 仓库 → 同步 K8s 状态

graph LR
 Dev[开发者] -->|push| Git[Git 仓库
业务代码 + Helm Chart]
 Git -->|webhook| Jen[Jenkins
CI 流水线]
 Jen -->|build + scan| Harbor[Harbor 镜像库]
 Jen -->|update image tag| Git
 Argo[Argo CD
CD 控制器] -->|watch| Git
 Argo -->|apply| K8s[K8s 集群]

 style Jen fill:#3c82dc,color:#fff
 style Argo fill:#ff9a3c,color:#fff

3 大优势：

K8s 状态可追溯——Git 是 single source of truth，所有部署都能从 Git 还原
一键回滚——git revert 一次 commit，Argo CD 自动同步，回滚时间从 5 分钟缩到 30 秒
多环境标准化——dev / staging / prod 用同一份 Helm Chart + 不同 values，K8s 部署逻辑一致

Argo CD Application 模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: order-service-prod
 namespace: argocd
spec:
 project: default
 source:
 repoURL: git@github.com:myteam/order-service.git
 targetRevision: HEAD
 path: charts/order-service
 helm:
 valueFiles:
 - values-prod.yaml
 destination:
 server: https://kubernetes.default.svc
 namespace: prod
 syncPolicy:
 automated:
 prune: true # 自动清理孤儿资源
 selfHeal: true # 自动修复偏离
 syncOptions:
 - CreateNamespace=true

Jenkinsfile 只需要 update Git，不再 apply K8s：

 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


stage('Update Git Manifest') {
 agent { label 'maven' }
 steps {
 withCredentials([usernamePassword(
 credentialsId: 'github-token',
 usernameVariable: 'GIT_USER',
 passwordVariable: 'GIT_TOKEN'
 )]) {
 sh """
 # 1. 配置 git
 git config user.email "jenkins@xxx.com"
 git config user.name "Jenkins Bot"

 # 2. 更新 Helm values 里的 image.tag
 sed -i "s/tag: .*/tag: ${IMAGE_TAG}/" \
 charts/order-service/values-prod.yaml

 # 3. 提交 + push
 git add charts/order-service/values-prod.yaml
 git commit -m "ci: update image tag to ${IMAGE_TAG} [skip ci]"
 git push https://${GIT_USER}:${GIT_TOKEN}@github.com/myteam/order-service.git
 """
 }
 }
}

Argo CD 自动监听 Git，30 秒内自动同步到 K8s。

Why GitOps 优于传统 Jenkins apply：

维度	传统 Jenkins	GitOps
K8s 状态源	Jenkins 任务（临时）	Git（永久）
一键回滚	重新跑 Jenkins job	`git revert`
集群被改后修复	需要手动 sync	自动 selfHeal
多集群管理	需配多个 Jenkins job	1 个 Argo App
审计	Jenkins 日志	Git commit 历史

9.2 配套工具链 + 系列回顾

完整 CI/CD 工具链地图：

graph TB
 subgraph Code[代码层]
 Git[Git 仓库
GitHub / GitLab]
 PR[PR / Code Review]
 end

 subgraph CI[CI 层 - Jenkins]
 JM[Jenkins Master]
 JA[Agents
maven / docker / k8s]
 end

 subgraph Quality[质量层]
 Sonar[SonarQube
代码扫描]
 JaCoCo[覆盖率]
 end

 subgraph Storage[制品层]
 Harbor[Harbor
镜像仓库]
 Nexus[Nexus
Maven 制品]
 end

 subgraph CD[CD 层]
 Argo[Argo CD
GitOps]
 Roll[Argo Rollouts
灰度发布]
 Helm[Helm
Chart]
 end

 subgraph Runtime[运行时]
 K8s[K8s 集群]
 Prom[Prometheus]
 Grafana[Grafana]
 Loki[Loki]
 end

 Git --> JM
 PR --> Git
 JM --> Sonar
 JM --> JaCoCo
 JM --> Harbor
 JM --> Nexus
 JM --> Argo
 Argo --> K8s
 Roll --> K8s
 Helm --> K8s
 K8s --> Prom
 Prom --> Grafana
 K8s --> Loki

 style JM fill:#3c82dc,color:#fff
 style Argo fill:#ff9a3c,color:#fff
 style K8s fill:#5aa0e8,color:#fff

6 大配套工具：

工具	用途	部署位置
Prometheus	指标采集 + 告警	K8s 内（prometheus-operator）
Grafana	指标可视化	K8s 内
Loki	日志聚合	K8s 内
AlertManager	告警路由	K8s 内
Jaeger	分布式追踪	K8s 内（可选）
Argo CD	GitOps 控制器	K8s 内（argocd namespace）

监控流水线本身的指标：

构建成功率（按服务）—— 失败率 > 10% 告警
构建时长（P50 / P95 / P99）—— P95 > 30 分钟告警
镜像大小 —— 单镜像 > 1GB 告警
Maven 依赖下载量 —— 单构建 > 2GB 告警
Jenkins 队列长度 —— 等待 > 10 个 job 告警

系列回顾（Java Web 微服务 1-9 篇）：

篇	主题	类型
1	异地多活：高可用终极形态	架构
2	反规范化设计：性能与一致性的平衡	架构
3	K8s 容器编排	基础设施
4	技术选型：Spring Cloud Alibaba + Dubbo 3	架构
5	Nacos：服务中心 + 配置中心	架构
6	流量调度：网关 + 限流 + 负载均衡	架构
7	熔断限流：Sentinel + Resilience4j	架构
8	数据库演化：MySQL → 分布式	数据
9	Jenkins 流水线：完整 CI/CD 实战	工程收官
后续	可观测性：Metrics / Logging / Tracing 三支柱	待写

一句话总结：

「Jenkins 不是银弹，Pipeline as Code + GitOps + 渐进式发布才是 2026 年 Java 微服务交付的答案。」

附录 A：常见问题 FAQ

Q1：Jenkins 2 已经够用，为什么不用 GitLab CI / GitHub Actions / Tekton？

A：Jenkins 在「插件生态」和「国内企业落地经验」上还是最强的。GitLab CI 适合 GitLab 仓库一体化的团队；GitHub Actions 适合开源项目；Tekton 是云原生未来但生态还弱。对绝大多数中大企业，Jenkins 仍是首选。

Q2：Jenkinsfile 必须放在项目根目录吗？

A：默认是。也可以放在子目录（如 cicd/Jenkinsfile），但 Jenkins Job 创建时要选「Pipeline script from SCM」并指定 Script Path。

Q3：build 出来的 jar 怎么找？

A：两种方式：

archiveArtifacts 归档（推荐）—— 在 Jenkins Job 页面「Build Artifacts」下载
推 Nexus —— 用 Nexus Artifact Uploader 插件

Q4：生产环境怎么回滚到 3 个版本之前？

A：

Helm：helm rollback order-service 3（3 是 revision number）
Argo Rollouts：kubectl argo rollouts undo order-service --to-revision=3
更推荐 GitOps：git revert 对应 commit，Argo CD 自动同步

Q5：流水线跑一半挂了，重跑时跳过已经成功的 stage 怎么实现？

A：Jenkins 原生不支持 stage 级别 skip，两个变通方案：

每个 stage 加 when 条件判断参数
用 Pipeline Stage 视图手动「重跑此 stage」（Blue Ocean 插件支持）

Q6：Argo Rollouts 和 Istio VirtualService 怎么选？

A：

简单场景：用 Argo Rollouts + Nginx Ingress（本文方案）
复杂服务网格：用 Istio VirtualService（更强大但更重）
多协议支持：用 SMI（Service Mesh Interface）

附录 B：Jenkins 性能调优清单

如果你遇到 Jenkins 慢/卡/OOM，按这个清单逐项排查：

现象	根因	优化
早高峰 job 排队	Agent 数量不足	加 maven / docker agent
Master 内存持续上涨	插件内存泄漏	升级插件 / 减插件 / 调大 -Xmx
第一次构建 5 分钟	镜像拉取慢	预热基础镜像 / 用 k3d image import
Maven 下载慢	无本地缓存	挂 .m2 目录到 host
Docker build 慢	镜像没缓存	优化 Dockerfile 层级 / 用 BuildKit
Webhook 不触发	网络/防火墙	检查 `tcpdump` + Jenkins `Manage Webhooks` 日志
制品归档慢	归档大文件	不归档 target/ 整个目录，只归档 jar
SonarQube 扫描慢	仓库太大	拆分项目 / 增量扫描
磁盘满	工作区残留	装 Workspace Cleanup 插件 + 定时清理

JVM 调优（生产 Master）：

1
2


# 8G 内存的 Master
export JAVA_OPTS="-Xms4g -Xmx6g -XX:MaxMetaspaceSize=1g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

Master 高可用（生产级）：

2 个 Master 节点共享 NFS 卷
前面挂 HAProxy / Nginx 做 active-passive
共享存储用 GlusterFS / Ceph

第九章总结 + 系列收官：Jenkins Pipeline + GitOps + 渐进式发布，从代码提交到金丝雀 100% 全自动。配套 Prometheus + Grafana + Loki + Argo CD，完整可观测 + 完整可回滚。这是 Java 微服务从「架构」走向「生产」的最后一公里。

下一篇文章将进入可观测性专题——Metrics / Logging / Tracing 三支柱怎么落地，敬请期待。

缓存体系：本地、集群、锁与持久化全链路实战

Tue, 09 Jun 2026 00:00:00 +0000

缓存体系：本地、集群、锁与持久化全链路实战

Java Web 微服务系列 · 第 9 篇 · 缓存体系阅读时长：约 50 分钟本文写于 2026 年 6 月配套版本：Redis 7.2.x / Redisson 3.27.x / Caffeine 3.1.x / Spring Boot 3.2.x 前置阅读：《数据库演化：MySQL → PostgreSQL → 分布式》（系列第 8 篇）后续衔接：《异地多活：Java Web 微服务的高可用终极形态》（系列第 1 篇）

引子：双 11 零点，一个被缓存雪崩打挂的支付链路

2020 年 11 月 11 日 00:00:03，我盯着监控大屏，心跳比系统心跳还快。

流量曲线 3 秒内从 8 万 QPS 爬到 78 万 QPS，比去年峰值还高 30%
订单服务的 Redis 集群 CPU 突然从 25% 跳到 92%，几秒钟后集群报警「慢查询超过阈值」
0:00:08 库存服务的本地缓存（Caffeine）集体过期，所有请求穿透到 Redis
0:00:11 Redis 连接池打满，订单服务开始大量 timeout
0:00:15 网关层熔断器被触发，支付链路全链路降级

事后复盘，整条故障链清晰可见：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


双 11 零点流量尖峰
 ↓
本地缓存(Caffeine) 集中过期（30 分钟 TTL 在 00:00 同时到期）
 ↓
请求穿透到 Redis
 ↓
Redis 单 Key 热点（库存 stock:{skuId}）打中 master 节点
 ↓
master 节点 CPU 100%，开始拒绝服务
 ↓
连接池排队 → 客户端 timeout → 线程池打满
 ↓
熔断器开启 → 全链路降级

整个故障持续 7 分钟，损失订单约 1200 万 GMV，CEO 在月度复盘会上点名批评。

复盘报告里我写下了八个字："缓存是性能中枢，也是故障放大器。"

之后三年，我把这八个字拆成了 本地缓存、分布式缓存集群、主从同步锁、文件持久化、缓存三大问题、生产场景 六章，逐个补齐工程能力。这篇就是把六章的全部经验摊开——每章都给"原理 + 实战 + 坑 + 解决方案"。

一、本地缓存：JVM 进程内的速度加速器

本地缓存是缓存体系里最快、也最容易被低估的一层。它在 JVM 进程内部，没有网络、没有序列化、QPS 可以跑到百万级。但它的天花板也很明显：容量受限于堆内存、不能跨进程共享、GC 抖动会拖垮整个服务。

1.1 本地缓存 vs 分布式缓存的边界

维度	本地缓存（Caffeine/Guava）	分布式缓存（Redis/Memcached）
访问延迟	纳秒-微秒级	0.1-1ms（同机房）
容量上限	GB 级（受堆内存限制）	TB 级（集群扩展）
一致性	进程内一致即可	需要主从同步、Redlock 保障
适用数据	配置、白名单、热点字典、用户 Session	跨服务共享、订单、库存
失效模式	TTL + LRU/W-TinyLFU	TTL + 主动失效 + 主从同步
失败影响	进程崩溃 = 数据全丢	单点故障可自动切换

💡 原理：本地缓存的 W-TinyLFU 算法为什么比 LRU 好

传统 LRU 淘汰策略有两个致命问题：

突发流量打爆缓存——突发访问的 Key 大量挤入，老的热点 Key 被踢出

缓存污染——一次全表扫把缓存塞满长期不用的 Key

Caffeine 用 W-TinyLFU（Window Tiny Least Frequently Used）：

1% 窗口区（Window Cache）：LRU，吸纳新访问

99% 主区（Main Cache）：SLRU（分段 LRU），按访问频次分「受保护段 + 候选段」

Count-Min Sketch 频率统计：新 Key 进入主区前用 Sketch 估算历史访问频次，比 LR 高的才准入

效果：相同的容量下，Caffeine 的命中率比 Guava Cache 高 30%。这是 2018 年后 W-TinyLFU 论文被工程化后的红利。

1.2 Caffeine 实战

pom.xml：

1
2
3
4
5


<dependency>
 <groupId>com.github.ben-manes.caffeine</groupId>
 <artifactId>caffeine</artifactId>
 <version>3.1.8</version>
</dependency>

三种缓存加载模式（根据业务场景选对，命中率天差地别）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 模式 1：手动填充 (适合数据从外部加载, 业务控制 put 时机)
Cache<String, UserProfile> manualCache = Caffeine.newBuilder()
 .expireAfterWrite(10, TimeUnit.MINUTES) // 写后 10 分钟过期
 .maximumSize(100_000) // 最大 10w 条
 .recordStats() // 开启统计
 .build();

// 模式 2：自动加载 (推荐, 业务只 get, miss 时自动调 loader)
LoadingCache<String, UserProfile> loadingCache = Caffeine.newBuilder()
 .expireAfterWrite(10, TimeUnit.MINUTES)
 .maximumSize(100_000)
 .refreshAfterWrite(1, TimeUnit.MINUTES) // 写后 1 分钟异步刷新
 .recordStats()
 .build(key -> userRepo.findById(key)); // loader, miss 时调用

// 模式 3：异步加载 (loader 慢时用, 不阻塞 get 线程)
AsyncCache<String, UserProfile> asyncCache = Caffeine.newBuilder()
 .expireAfterWrite(10, TimeUnit.MINUTES)
 .maximumSize(100_000)
 .buildAsync();
CompletableFuture<UserProfile> future = asyncCache.get(key, k -> userRepo.findById(k));

1.3 Spring Cache 集成（一行注解切实现）

 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


@Configuration
@EnableCaching
public class CacheConfig {
 @Bean
 public CacheManager cacheManager() {
 CaffeineCacheManager mgr = new CaffeineCacheManager();
 mgr.setCaffeine(Caffeine.newBuilder()
 .expireAfterWrite(10, TimeUnit.MINUTES)
 .maximumSize(10_000));
 return mgr;
 }
}

// 业务代码 - 用 Spring 注解切实现
@Service
@RequiredArgsConstructor
public class ProductService {
 private final ProductRepo productRepo;

 @Cacheable(value = "product", key = "#id", unless = "#result == null")
 public Product getProduct(Long id) {
 // 第一次 miss 时调用, 之后命中 Caffeine
 return productRepo.findById(id).orElse(null);
 }

 @CachePut(value = "product", key = "#product.id")
 public Product updateProduct(Product product) {
 return productRepo.save(product);
 }

 @CacheEvict(value = "product", key = "#id")
 public void deleteProduct(Long id) {
 productRepo.deleteById(id);
 }
}

1.4 本地缓存的 6 个高频坑

🎯 避坑 1：maximumSize 设太小 → 缓存击穿

本地缓存 maximumSize=1000，热点字典有 5000 个 Key，前 1000 个热门常驻，后 4000 个永远 miss。建议：maximumSize = 业务总 Key 数 × 1.5，宁可浪费内存也别让热点被踢。

🎯 避坑 2：TTL 全部一样 → 雪崩

所有 Key 都设 30 分钟 TTL，00:00:00 写入的 Key 在 00:30:00 集体过期。对策：TTL 加随机偏移 expireAfterWrite(Duration.ofMinutes(30).plusSeconds(ThreadLocalRandom.current().nextInt(60)))。

🎯 避坑 3：没有上限 → OOM

用 Guava Cache 时忘记设 maximumSize，Key 无限增长直到 OOM。Caffeine 强制 maximumSize 或 maximumWeight 二选一，比 Guava 安全。

🎯 避坑 4：loader 抛异常 → 缓存击穿

loadingCache.get(key) 时 loader 抛异常，Caffeine 不会缓存异常结果，下一个请求继续调 loader。如果 loader 是数据库查询，一次慢查询会拖垮 N 个并发请求。对策：loader 内部 try-catch，返回 null 或空集合，让缓存层能稳定返回。

🎯 避坑 5：value 是大对象 → GC 抖动

本地缓存里塞了完整的 List<Order>（单条 10KB），10w 条 = 1GB 堆内存，老年代 GC 一次 2 秒。对策：

大对象用 WeakReference：.weakValues()

或者拆成 Map<orderId, OrderDto> 单条存

业务真的需要大集合，走 Redis 别用本地

🎯 避坑 6：进程间不一致 → 数据漂移

订单服务 A 把"商品 X 价格 99"缓存在本地，订单服务 B 的本地还是"商品 X 价格 100"。用户下单时 A 算的价是 99、B 算的是 100，同一笔订单价格不一致。对策：价格类强一致数据禁止本地缓存，必须走 Redis。

1.5 命中率监控

Caffeine 提供了 recordStats() 之后的所有统计：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


Cache<String, UserProfile> cache = Caffeine.newBuilder()
 .recordStats()
 .maximumSize(10_000)
 .build();

// 业务代码
cache.get(key, k -> loader.apply(k));

// 定时上报 (Spring @Scheduled)
@Scheduled(fixedRate = 60_000)
public void reportStats() {
 CacheStats stats = cache.stats();
 log.info("Caffeine stats: hitRate={}, missRate={}, evictionCount={}",
 stats.hitRate(), stats.missRate(), stats.evictionCount());
 // Micrometer 指标上报到 Prometheus
 Metrics.gauge("caffeine.hit_rate", stats.hitRate());
}

指标	健康范围	异常处理
hitRate	> 0.8	< 0.5 = 缓存容量不够或 TTL 太短
missRate	< 0.2	> 0.5 = 同上
evictionCount	稳定	暴增 = 触发淘汰, 检查 maximumSize
loadTime	P99 < 50ms	P99 > 200ms = loader 慢, 考虑异步

二、分布式缓存集群：水平扩展的容量与吞吐

本地缓存受限于单进程内存，业务规模上 10 万 QPS、单 Key 几 MB 后必须上分布式缓存。本节按"为什么需要集群 → Cluster 怎么分片 → Sentinel 怎么切换 → 容量怎么规划"展开。

2.1 集群方案对比

方案	一致性	扩展性	运维复杂度	适用场景
Redis Sentinel	主从异步复制	垂直扩展	低	中小规模（< 50GB）
Redis Cluster	主从异步 + 槽路由	水平扩展	中	中大规模（50GB-10TB）
Codis（豌豆荚）	主从异步 + Proxy	水平扩展	中	历史方案，新项目不用
Twemproxy（Twitter）	主从异步 + Proxy	水平扩展	中	历史方案，新项目不用
Memcached	无	客户端哈希	低	纯 KV、无持久化需求

🎯 决策：90% 场景选 Redis Cluster

Redis Cluster 解决了 Sentinel 的两个痛点：

数据分片——16384 个哈希槽分散到多 Master，容量不再是单节点瓶颈

自动故障转移——Cluster 内置 Raft 协议（其实是类 Paxos 的 gossip + 投票），不再需要 Sentinel 集群

唯一缺点：客户端需要 cluster-aware 客户端（Lettuce/Jedis 都已支持），不能在集群模式下用单节点命令（如 KEYS *）。

2.2 Redis Cluster 架构原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


┌─────────────────────────────────────────────────────────────┐
│ Redis Cluster (6 节点, 3 主 3 从) │
│ │
│ Master A Master B Master C │
│ slots 0-5465 slots 5466-10923 slots 10924-16383 │
│ │ │ │ │
│ Replica A1 Replica B1 Replica C1 │
│ │
└─────────────────────────────────────────────────────────────┘
 ▲ ▲ ▲
 │ │ │
 客户端 (Lettuce/Jedis) 走 CRC16(key) % 16384 路由

💡 原理：16384 个哈希槽的设计取舍

Redis Cluster 用 CRC16 算法对 key 计算 16 位 hash，然后取模 16384得到槽号。为什么是 16384 不是更多？

够用：16384 槽意味着单集群最多 16384 个节点，实际生产 100 节点以内，完全够

配置包小：每个节点的心跳包要带上自己负责的槽位 bitmap，16384 位 = 2KB，如果 65536 槽 = 8KB，每次心跳多 6KB，100 节点集群 = 600KB/s 流量浪费

重新分片粒度细：迁移时按槽为单位，16384 槽比 1024 槽更平滑

2.3 Cluster 部署（最少 6 节点）

生产环境铁律：

至少 3 主 3 从——单 Master 没意义
Master 和 Replica 不要在同一台物理机——避免单机故障把一对主从一起带走
跨机房时按单元化部署——参见系列第 1 篇异地多活

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 1. 准备 6 个节点配置 (redis-7000/7001/7002/7003/7004/7005)
# 配置文件 redis.conf 关键项
port 7000
cluster-enabled yes
cluster-config-file nodes-7000.conf
cluster-node-timeout 15000
appendonly yes
appendfsync everysec
# 持久化目录
dir /var/lib/redis/7000

# 2. 启动 6 个节点
for port in 7000 7001 7002 7003 7004 7005; do
 redis-server redis-${port}.conf &
done

# 3. 创建集群 (3 主 3 从, --cluster-replicas 1 表示每个 Master 配 1 个 Replica)
redis-cli --cluster create \
 10.1.0.10:7000 10.1.0.11:7001 10.1.0.12:7002 \
 10.1.0.13:7003 10.1.0.14:7004 10.1.0.15:7005 \
 --cluster-replicas 1

2.4 Spring Boot 接入

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


spring:
 data:
 redis:
 cluster:
 nodes:
 - 10.1.0.10:7000
 - 10.1.0.11:7001
 - 10.1.0.12:7002
 - 10.1.0.13:7003
 - 10.1.0.14:7004
 - 10.1.0.15:7005
 max-redirects: 3
 timeout: 2s
 lettuce:
 pool:
 max-active: 200
 max-idle: 50
 min-idle: 10
 max-wait: 1000ms

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
 RedisTemplate<String, Object> template = new RedisTemplate<>();
 template.setConnectionFactory(factory);

 // Key 用 String 序列化
 StringRedisSerializer keySer = new StringRedisSerializer();
 template.setKeySerializer(keySer);
 template.setHashKeySerializer(keySer);

 // Value 用 JSON 序列化
 Jackson2JsonRedisSerializer<Object> valSer =
 new Jackson2JsonRedisSerializer<>(objectMapper, Object.class);
 template.setValueSerializer(valSer);
 template.setHashValueSerializer(valSer);

 template.afterPropertiesSet();
 return template;
}

2.5 哈希槽定位的 4 个常见问题

🎯 避坑 1：不同 Key 必须落在同一 slot 才能用 MGET/MSET

批量操作 MGET key1 key2 key3 要求所有 Key 在同一个哈希槽。对策：用 hash tag——Key 中用 {} 包裹的部分会作为哈希依据。
1
2
3
4
5
6
// ❌ 三个 Key 在不同 slot, MGET 报错 CROSSSLOT
redisTemplate.opsForValue().multiGet(Arrays.asList("order:1", "order:2", "order:3"));

// ✅ 用 hash tag 强制同 slot
redisTemplate.opsForValue().multiGet(Arrays.asList(
 "{order}:1", "{order}:2", "{order}:3"));
实际工程里用 multiGet 不如用 Pipeline——Pipeline 不受 slot 限制。

🎯 避坑 2：事务 (MULTI/EXEC) 不支持 Cluster

Redis Cluster 的事务要求 Key 在同一 slot，生产几乎不用 MULTI/EXEC。对策：用 Lua 脚本 替代事务——Lua 脚本在 Cluster 模式下也只允许同一 slot，但通过 hash tag 可以控制。

🎯 避坑 3：KEYS 命令禁用

KEYS * 在 Cluster 下报错（每个节点都得扫，Redis 干脆不支持）。对策：用 SCAN 命令 + 游标分批。
1
2
3
4
5
6
7
ScanOptions options = ScanOptions.scanOptions().match("order:*").count(1000).build();
try (Cursor<byte[]> cursor = redisTemplate.getConnectionFactory()
 .getConnection().keyCommands().scan(options)) {
 while (cursor.hasNext()) {
 // 处理 Key
 }
}

🎯 避坑 4：跨 slot 错误

客户端在 Slot 迁移过程中访问 Key，可能返回 MOVED 或 ASK。Lettuce/Jedis 客户端会自动重试，但重定向超过 max-redirects 次会报错。对策：把 max-redirects 设为 3-5，业务代码处理 RedisCommandExecutionException。

2.6 容量规划公式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


总 Key 数 = DAU × 关键业务对象数
 = 100w × 10
 = 1000w = 1 千万条

单 Key 平均大小 = 2KB
总数据量 = 1 千万 × 2KB = 20GB

加 30% Buffer = 26GB
加主从副本 = 26GB × 2 = 52GB

3 Master 分摊：每 Master 17GB
每 Master 配 32GB 内存（预留 50% 给 fork / 复制 / 碎片）
3 Master × 3 Replica = 6 节点 × 32GB = 192GB 总内存

生产黄金法则：

单 Redis 实例内存不超过 64GB——fork 时间随内存线性增长，64GB 时 fork 已经 100ms+，主线程阻塞明显
Redis 节点数不超过 200——Cluster 内部 gossip 消息 O(N²)，200 节点后心跳开销指数增长
数据量超过 10TB——考虑业务拆分或上 Pika/SSDB 这种磁盘 Redis

三、主从同步与分布式锁：从原理到 4 大生产坑

主从同步是 Redis 高可用的基础，分布式锁是 Redis 最常被滥用的功能。这两件事看似独立，实际在生产里经常踩同一类坑——时钟漂移、网络分区、Master 切换时的锁丢失。

3.1 Redis 主从复制原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 ┌──────────────────┐
 │ Master │
 │ - 写请求处理 │
 │ - 异步复制到 Replica │
 │ - repl_backlog│
 └────────┬─────────┘
 │
 ┌────────────────┼────────────────┐
 │ │ │
 ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ Replica 1 │ │ Replica 2 │ │ Replica 3 │
 │ 全量同步 │ │ 全量同步 │ │ 增量同步 │
 └───────────┘ └───────────┘ └───────────┘

💡 原理：全量同步 vs 增量同步的触发条件

Redis 用 repl_backlog（复制积压缓冲区）记录 Master 最近的写命令流：

全量同步——Replica 第一次连上来 / 主从断开超过 repl-timeout / Replica 需要的 offset 已被 backlog 覆盖

增量同步——Replica 需要的 offset 还在 backlog 里（默认 1MB）

调优 repl-backlog-size：生产建议设为平均写入量 × 60 秒，10MB-100MB 都合理。

⚠️ 主从复制是异步的——Master 写入成功后立即返回客户端，复制到 Replica 有延迟（同机房 1-5ms，跨机房 30-100ms）。这就是为什么 Redis 主从切换时可能有少量数据丢失。

3.2 Sentinel 主从切换流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 Sentinel 1 Sentinel 2 Sentinel 3
 │ │ │
 │ PING 10s 一次 │ │
 ├───────────────────►│ │
 │ ├───────────────────►│
 │ │ │
 │ 主观下线 (PFAIL) │ │
 │ ↓ Master 失联 │ │
 │ 互相发 is-master-down-by-addr │
 │ │ │
 │ ↓ 多数派确认 │ │
 │ 客观下线 (ODOWN) │ │
 │ │ │
 │ ↓ 选举 Leader │ │
 │ (Raft 协议) │ │
 │ │ │
 │ ↓ Leader 执行切换│ │
 │ - 选 Replica 做新 Master │
 │ - 旧 Master 改 Replica │
 │ - 通知客户端新 Master │

📌 实践：Sentinel 至少 3 节点，跨机柜部署

3 节点 = 容忍 1 节点故障，2 节点 = 1 节点故障就脑裂

跨机柜部署避免单机柜断电时 Sentinel 也全军覆没

Sentinel 本身不存数据，用 1 核 1GB 虚拟机足够

3.3 分布式锁的 4 大方案对比

方案	正确性	性能	复杂度	适用场景
SETNX + EXPIRE	差（两条命令非原子）	极高	低	❌ 不推荐
SET key value NX EX 30	中（Master 切换丢锁）	高	低	单 Redis 实例
Redlock 算法	较高	中	中	强一致场景
Redisson	较高	高	中	99% 场景推荐
Zookeeper	高	低	高	强一致 + 低 QPS
etcd	高	中	高	K8s 生态

3.4 Redlock 算法详解

核心思想：不在一个 Redis 实例上加锁，而在 N 个独立 Redis 实例上（官方推荐 5 个），获得 ≥ N/2+1 个实例的锁才算加锁成功。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 ┌─────────┐
 │ Client │
 └────┬────┘
 │ SET key value NX PX 30000
 ┌────────────────┼────────────────┐
 ▼ ▼ ▼ ▼ ▼
 ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
 │Redis-1 │ │Redis-2 │ │Redis-3 │ │Redis-4 │ │Redis-5 │
 │ ✓ 成功 │ │ ✓ 成功 │ │ ✗ 失败 │ │ ✓ 成功 │ │ ✗ 失败 │
 └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
 │
 3/5 = 成功 (过半)

4 个关键参数：

T1 = 获取锁前时间
T2 = 获取锁后时间（获取耗时 = T2 - T1）
Lock TTL = 锁有效期（建议 30 秒）
有效时间 = Lock TTL - 获取耗时（有效时间 < 0 = 加锁失败）

💡 原理：为什么 Redlock 比单 Redis 更安全

单 Redis 加锁的最大风险：Master 还没把锁复制到 Replica 就挂了。Sentinel 把 Replica 提升为新 Master，但新 Master 上根本没有这个锁——其他客户端就能加同一把锁，同一资源被两个客户端同时操作。

Redlock 用 5 个独立 Redis 实例，单个实例丢锁不影响整体——其他 4 个实例还有锁，第二个客户端拿不到过半。

⚠️ 争议：Martin Kleppmann 2016 年发表的《How to do distributed locking》指出 Redlock 也有缺陷（GC 停顿、时钟漂移），业界仍有讨论。Antirez（Redis 作者）做了反驳。结论：在 99% 业务场景，Redlock + 业务幂等性已经够用，不要追求绝对正确。

3.5 Redisson 实战（最推荐）

1
2
3
4
5


<dependency>
 <groupId>org.redisson</groupId>
 <artifactId>redisson-spring-boot-starter</artifactId>
 <version>3.27.2</version>
</dependency>

 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


@Configuration
public class RedissonConfig {
 @Bean
 public RedissonClient redisson() {
 Config config = new Config();
 // 单 Redis 实例 (生产建议 Redisson 集群模式)
 config.useSingleServer()
 .setAddress("redis://10.1.0.10:7000")
 .setPassword("${REDIS_PASSWORD}")
 .setConnectionPoolSize(200)
 .setConnectionMinimumIdleSize(20);
 return Redisson.create(config);
 }
}

// 业务代码
@Service
@RequiredArgsConstructor
public class OrderService {
 private final RedissonClient redisson;
 private final OrderRepo orderRepo;

 public Order createOrder(OrderRequest req) {
 // 1. 加锁 (key = "lock:order:user:{userId}", value = 自动生成 UUID)
 RLock lock = redisson.getLock("lock:order:user:" + req.getUserId());

 // 2. 尝试加锁, 最多等 3 秒, 锁自动释放时间 30 秒
 // 看门狗 (watchdog) 默认 10 秒续期一次, 业务执行完才释放
 try {
 boolean acquired = lock.tryLock(3, 30, TimeUnit.SECONDS);
 if (!acquired) {
 throw new BizException("系统繁忙, 请稍后重试");
 }

 // 3. 业务逻辑
 return doCreateOrder(req);
 } catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 throw new BizException("加锁被中断");
 } finally {
 // 4. 必须释放! 看门狗会在 unlock 时停止续期
 if (lock.isHeldByCurrentThread()) {
 lock.unlock();
 }
 }
 }
}

3.6 分布式锁的 4 大生产坑

🎯 坑 1：锁没释放 → 死锁

业务代码异常但 finally 里没 unlock，锁永远不释放，其他线程永远拿不到。

对策：

finally 里严格 unlock

用 tryLock(timeout) 限时等待，避免无限等

锁 TTL 一定要设（Redisson 默认 30 秒 + 看门狗续期）

🎯 坑 2：锁误删 → 别人干活你删锁

客户端 A 加锁后，业务执行慢超过 TTL，锁自动释放，客户端 B 拿到锁开始干活。这时 A 业务执行完调 unlock——A 删的是 B 的锁。

对策：每个锁有唯一 value（UUID/ThreadId），unlock 时用 Lua 脚本校验 value 是不是自己加的：
1
2
3
4
5
6
// Redisson 内部已经处理, 你只要用 lock.unlock() 即可
// 自己写的话要这样:
String lua = "if redis.call('get', KEYS[1]) == ARGV[1] then " +
 " return redis.call('del', KEYS[1]) " +
 "else return 0 end";
redis.eval(lua, Collections.singletonList(lockKey), uuidValue);

🎯 坑 3：锁粒度太粗 → 性能差

把整个订单服务都加一把大锁，QPS 100 时锁就成为瓶颈。

对策：按业务粒度加锁——

用户维度的锁：lock:order:user:{userId}

商品维度的锁：lock:stock:product:{skuId}

业务维度的锁：lock:order:create（只锁关键操作，不锁整个流程）

🎯 坑 4：Redlock 性能不够 → 排队

Redlock 要访问 5 个独立 Redis，延迟 ≈ 单 Redis × 5。高 QPS 场景下锁本身成为瓶颈。

对策：

优先用单 Redis + 业务幂等——大多数业务能容忍「同一资源被处理 2 次」

把 Redlock 的 Redis 集群和业务 Redis 集群分开——避免业务流量抢占锁的连接池

锁续期用 watchdog 异步续，不阻塞业务线程

四、文件持久化：RDB / AOF / 混合，三种方案怎么选

缓存数据丢了怎么办？——答：看你是什么数据。电商购物车丢了用户重填，订单数据丢了老板提刀。持久化策略按"数据重要性 × 写入性能"权衡。

4.1 RDB 快照

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


时间 ─────────────────────────────────────►

 ▲ ▲ ▲
 │ │ │
 │ save 60 1000 │ save 300 10 │ bgsave
 │ 自动触发 │ 自动触发 │ 手动触发
 │
 │
fork 子进程 ──► 遍历内存数据 ──► 写 dump.rdb
 (COW 内存复制)

💡 原理：RDB 的 fork + COW 机制

bgsave 触发时，Redis fork 一个子进程，父子进程共享内存页。子进程开始遍历内存写 RDB 文件，父进程继续处理写请求——如果父进程要修改某内存页，内核触发 COW（Copy-On-Write），复制出新的内存页给子进程。

优点：主进程不阻塞（除 fork 那瞬间）。缺点：

fork 阻塞——64GB 实例 fork 大约 100ms，这 100ms 主进程不响应任何请求

数据丢失——两次快照之间的写操作丢失（默认 5 分钟窗口，最坏丢 5 分钟数据）

4.2 AOF 追加日志

1
2
3
4
5
6
7
8


写入 ──► appendonly.aof（顺序追加）
 │
 ▼
 AOF 重写 (rewrite)
 │
 ▼
 合并为最小命令集
 (重写不阻塞主进程)

AOF 的 appendfsync 三种策略：

策略	性能	数据安全	适用场景
`always`	差（每条命令 fsync）	零丢失	金融、订单
`everysec`（默认）	高	丢 ≤ 1 秒	99% 业务
`no`	最高	OS 决定	临时缓存

📌 实践：everysec 是 99% 业务的最优解

always 性能下降到 1/10，主线程要等磁盘 fsync——Redis 本身是为了快，always 让它退化成了 MySQL。

everysec 在主线程外异步刷盘，最多丢 1 秒。大多数业务都能接受——购物车、用户 Session 这类非关键数据，丢 1 秒重算即可。

4.3 混合持久化（Redis 4.0+ 默认推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 混合持久化 AOF 文件
 ┌────────────────────────────────────────┐
 │ RDB 格式 │
 │ ┌──────────────────────┐ │
 │ │ 当前内存全量数据 │ │
 │ └──────────────────────┘ │
 │ ↓ │
 │ AOF 增量 │
 │ ┌──────────────────────┐ │
 │ │ RDB 之后的写命令流 │ │
 │ │ (INCR / SET / DEL...) │ │
 │ └──────────────────────┘ │
 └────────────────────────────────────────┘

配置：

1
2
3
4


# redis.conf
aof-use-rdb-preamble yes # 开启混合持久化 (Redis 4.0+ 默认 yes)
appendonly yes
appendfsync everysec

优势：

启动恢复时先全量加载 RDB（速度快），再重放 AOF 增量（补齐数据）
比纯 AOF 恢复快 10 倍（实测 16GB AOF 恢复从 30 分钟降到 3 分钟）
比纯 RDB 丢失数据少（只丢混合点之后的写命令）

4.4 持久化选型矩阵

业务场景	数据丢失容忍	推荐方案	关键配置
购物车 / 用户 Session	丢几秒可接受	RDB + AOF 混合	`appendfsync everysec`
订单 / 支付结果	绝不能丢	AOF always	`appendfsync always`
排行榜 / 计数器	丢几十分钟可接受	纯 RDB	`save 900 1`
配置 / 白名单	启动加载即可	纯 RDB	`save 3600 1`
临时验证码	丢无所谓	关闭持久化	`save ""` + `appendonly no`

4.5 fork 阻塞的 5 个优化

🎯 避坑 1：单实例内存 > 32GB → 慎用 bgsave

64GB 实例 fork 100ms，这 100ms 主进程完全卡死。对策：用 多个小实例（如 4 个 16GB 实例）替代单大实例。

🎯 避坑 2：禁用透明大页 THP

Linux 默认开启 THP（透明大页），THP 让 fork 复制内存页时变慢 10 倍。必须关：
1
echo never > /sys/kernel/mm/transparent_hugepage/enabled

🎯 避坑 3：避免在高峰期 bgsave

Redis 自动 bgsave 触发条件 save 60 1000（60 秒内 1000 次写），高峰触发 bgsave 又叠 fork 阻塞 → 雪崩。对策：

业务低峰期（凌晨 4-5 点）手动 bgsave

调高 save 阈值：save 300 10000（5 分钟 1w 次才触发）

🎯 避坑 4：AOF 重写也 fork

bgrewriteaof 同样要 fork，避免与 bgsave 同时触发（不然 fork 内存页被复制两次）。

🎯 避坑 5：用 SSD 而不是 HDD

AOF 顺序写，SSD 比 HDD 性能高 10-100 倍。HDD 上 appendfsync always 写入 QPS 撑死 1000，SSD 上能撑到 5w+。

五、缓存三大问题：雪崩 / 穿透 / 击穿

缓存是性能加速器，也是故障放大器。三大问题是每个 Java 后端开发必须背得滚瓜烂熟的"老八股"——但 90% 的人答得似是而非，本节给出原理 + 场景 + 解决方案完整链路。

5.1 雪崩：缓存集体失效，请求打爆数据库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


时间 ─────────────────────────────────────────►

 00:00:00 00:30:00 00:30:01
 │ │ │
 ▼ ▼ ▼
 缓存写入 30 分钟 TTL 缓存集体过期
 (批量预热) 集体到期 ↓
 请求全部穿透
 ↓
 DB 被打爆

🎯 解决方案 4 件套（按优先级）

1. TTL 加随机偏移——避免集体过期

1
2
3


int baseTtl = 1800; // 30 分钟
int jitter = ThreadLocalRandom.current().nextInt(60); // 0-60 秒
redisTemplate.opsForValue().set(key, value, baseTtl + jitter, TimeUnit.SECONDS);

2. 多级缓存——本地缓存兜底

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


public UserProfile getUser(Long id) {
 // L1: 本地 Caffeine
 UserProfile p = caffeineCache.getIfPresent(id);
 if (p != null) return p;

 // L2: Redis
 p = redisTemplate.opsForValue().get("user:" + id);
 if (p != null) {
 caffeineCache.put(id, p);
 return p;
 }

 // L3: DB
 p = userRepo.findById(id).orElse(null);
 if (p != null) {
 redisTemplate.opsForValue().set("user:" + id, p, 30 + jitter, TimeUnit.MINUTES);
 caffeineCache.put(id, p);
 }
 return p;
}

3. 熔断降级——Redis 挂了直接走 DB 限流

1
2
3
4
5
6
7
8
9


@CircuitBreaker(name = "userService", fallbackMethod = "getUserFallback")
public UserProfile getUser(Long id) {
 return redisTemplate.opsForValue().get("user:" + id);
}

public UserProfile getUserFallback(Long id, Throwable t) {
 // 走 DB 限流版本
 return rateLimitedDbQuery(id);
}

4. 缓存预热——提前加载热点数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Component
public class CacheWarmer implements ApplicationRunner {
 @Override
 public void run(ApplicationArguments args) {
 // 启动时把热 Key 加载到 Redis
 List<Long> hotIds = hotKeyService.getHotIds();
 hotIds.forEach(id -> {
 UserProfile p = userRepo.findById(id).orElse(null);
 if (p != null) redisTemplate.opsForValue().set("user:" + id, p, 30, TimeUnit.MINUTES);
 });
 }
}

5.2 穿透：查询不存在的数据，缓存形同虚设

1
2
3
4


客户端 ──► Redis (miss) ──► DB (无此数据) ──► 缓存 null ──► 下次同样 miss
 ↑
 但每次还是打 DB
 (空值没缓存, 或缓存时间太短)

🎯 解决方案 3 件套

1. 缓存空值——DB 查不到也缓存一个 null 标记

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public UserProfile getUser(Long id) {
 String key = "user:" + id;
 Object cached = redisTemplate.opsForValue().get(key);
 if (cached != null) {
 return cached == NULL_MARKER ? null : (UserProfile) cached;
 }

 UserProfile p = userRepo.findById(id).orElse(null);
 if (p != null) {
 redisTemplate.opsForValue().set(key, p, 30, TimeUnit.MINUTES);
 } else {
 // 缓存 null 标记, TTL 短一些 (5 分钟), 防止长期占空间
 redisTemplate.opsForValue().set(key, NULL_MARKER, 5, TimeUnit.MINUTES);
 }
 return p;
}

2. 布隆过滤器——前置判断 Key 是否可能存在

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


@Component
public class BloomFilterService {
 private final BloomFilter<Long> bloomFilter = BloomFilter.create(
 Funnels.longFunnel(), 10_000_000, 0.001);

 public void addUser(Long id) {
 bloomFilter.put(id);
 }

 public boolean mightExist(Long id) {
 return bloomFilter.mightContain(id);
 }
}

// 业务代码
public UserProfile getUser(Long id) {
 if (!bloomFilterService.mightExist(id)) {
 return null; // 一定不存在, 直接返回
 }
 // 走正常查询
}

3. 接口校验——业务层拒绝明显非法的查询

1
2
3
4
5
6


public UserProfile getUser(Long id) {
 if (id == null || id <= 0 || id > MAX_USER_ID) {
 throw new IllegalArgumentException("非法的 userId");
 }
 // ...
}

5.3 击穿：单个热点 Key 过期瞬间被高并发打挂

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 ┌─────────────────────┐
 请求 N 个 │ Redis │
 ────────────►│ hotKey 已过期 │
 │ miss │
 └──────────┬────────────┘
 │
 N 个请求同时查 DB
 抢着回填缓存
 ↓
 DB 被打挂

🎯 解决方案 3 种

方案 1：互斥锁（最常用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public UserProfile getUser(Long id) {
 String key = "user:" + id;
 UserProfile p = redisTemplate.opsForValue().get(key);
 if (p == null) {
 // 只让一个线程去查 DB
 if (tryLock("lock:user:" + id, 5, TimeUnit.SECONDS)) {
 try {
 p = userRepo.findById(id).orElse(null);
 if (p != null) {
 redisTemplate.opsForValue().set(key, p, 30, TimeUnit.MINUTES);
 }
 } finally {
 unlock("lock:user:" + id);
 }
 } else {
 // 其他线程 sleep 50ms 后重试 (此时大概率缓存已回填)
 Thread.sleep(50);
 p = redisTemplate.opsForValue().get(key);
 }
 }
 return p;
}

方案 2：逻辑过期（推荐）

缓存不设 TTL，改在 value 里加一个 expire 字段，业务发现过期后异步回填：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


@Data
public class CacheItem<T> {
 private T data;
 private long expireAt; // 逻辑过期时间
}

public UserProfile getUser(Long id) {
 String key = "user:" + id;
 CacheItem<UserProfile> item = redisTemplate.opsForValue().get(key);

 if (item == null) {
 return loadFromDbAndCache(id);
 }

 if (item.getExpireAt() < System.currentTimeMillis()) {
 // 已逻辑过期, 异步回填
 CompletableFuture.runAsync(() -> refreshCache(id));
 }

 return item.getData(); // 永远返回旧数据, 不阻塞
}

方案 3：热点永不过期（业务侧可控）

真正的热点 Key（如商品详情、明星排行榜），直接不设 TTL——业务更新时主动 SET 新值。不推荐：缓存与 DB 一致性管理变难。

六、生产场景 6 个真实案例

本节是 6 个真实生产事故 + 完整解决方案，每个都给出事故症状、根因、解决 SOP。

6.1 多级缓存架构设计

场景：电商商品详情页 QPS 50w，单 Redis 集群撑不住。

架构：

1
2
3
4


用户 ──► Nginx (Lua 缓存) ──► 本地 Caffeine (10w 条) ──► Redis Cluster ──► MySQL
 │ │ │ │
 TTL 30s TTL 5min TTL 30min 主库
 (URL 维度) (商品 ID 维度) (商品 ID) (兜底)

关键设计：

每层命中率目标 ≥ 70%——L1 70% + L2 25% + L3 5%（数据库实际只扛 5%）
每层失效时间递增——L1 短、L2 中、L3 长，任意一层有数据就不穿透
数据变更推送到所有层——商品改价时 mq send 消息 → L1 主动失效 + L2 主动失效 + L3 写新值

6.2 大 Key 与热 Key 处理

场景 1：大 Key 拖慢集群

某运营配置单个 Key 存了 5MB 的 JSON（商品标签字典），DEL 这个 Key 直接阻塞 800ms——Redis 单线程执行 DEL，5MB 数据要遍历。

解决方案：

1
2
3
4
5
6
7
8


# ❌ 直接 DEL 阻塞 800ms
redis-cli DEL big:config

# ✅ 用 UNLINK 异步删除 (Redis 4.0+)
redis-cli UNLINK big:config

# ✅ 或拆成多个小 Key
# big:config:1, big:config:2, ... 每个 1MB

场景 2：热 Key 打挂单节点

秒杀商品 stock:{skuId} 在 Master A 节点，5w QPS 集中打 A，A CPU 100%。

解决方案：

Key 哈希分散——stock:{skuId}:{shard} 分到 10 个 Key，每个 Key 1w QPS
读写分离——读路由到 Replica，写走 Master
客户端本地缓存——秒杀商品库存在客户端本地缓存 1 秒，本地没拿到再走 Redis

1
2
3


// 热 Key 哈希分散 (10 分片)
int shard = (skuId.hashCode() & Integer.MAX_VALUE) % 10;
String key = "stock:" + skuId + ":" + shard;

6.3 缓存与 DB 一致性（Cache-Aside 模式的陷阱）

经典 Cache-Aside 模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 读
public Product getProduct(Long id) {
 Product p = cache.get(id);
 if (p == null) {
 p = db.findById(id);
 cache.set(id, p); // 回填
 }
 return p;
}

// 写
public void updateProduct(Product p) {
 db.update(p);
 cache.del(p.getId()); // 删除缓存 (不是更新缓存)
}

为什么"先更新 DB 再删缓存"比"先删缓存再更新 DB"安全？

时序	先删缓存再更新 DB	先更新 DB 再删缓存
并发问题	A 删缓存 → B 读 miss → 读 DB 旧值 → 回填旧缓存 → A 更新 DB → 缓存是旧值	A 更新 DB → B 读缓存命中旧值 → A 删缓存 → 下次读 miss 走 DB 拿新值
不一致窗口	长（缓存被回填后才发现 DB 已更新）	短（只在下一次读前有旧值）

3 个进阶模式：

模式	一致性	性能	适用
Cache-Aside	最终一致	高	99% 业务
Read-Through	最终一致	中	缓存层统一管理
Write-Through	强一致	低	金融、订单
Write-Behind	弱一致	极高	计数、点赞
延迟双删	较强	中	写少读多

🎯 延迟双删（生产常用）
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
public void updateProduct(Product p) {
 // 1. 先删缓存
 cache.del(p.getId());

 // 2. 更新 DB
 db.update(p);

 // 3. 延迟 500ms 再删一次 (异步)
 CompletableFuture.delayedExecutor(500, TimeUnit.MILLISECONDS)
 .execute(() -> cache.del(p.getId()));
}
第二次删除是处理并发场景——第一次删完到 DB 更新完之间，其他线程可能读了旧 DB 值并回填了缓存。第二次删除把这个旧值清掉。

6.4 慢查询引发的缓存污染

事故：某天 Redis 集群 CPU 突然飙到 90%，查 SLOWLOG GET 10 发现大量 HGETALL order:detail:12345 耗时 500ms+。

根因：单 order 详情 Hash 里有 5000 个 field（订单的多商品 + 多优惠 + 多日志），HGETALL 要遍历全部 field。

解决方案：

拆 Hash——order:detail:12345:basic + order:detail:12345:items + order:detail:12345:logs
业务上避免 HGETALL——用 HSCAN 游标分批
大 Hash 监控——redis-cli --bigkeys 定期扫描，单 Key > 10KB 报警

6.5 Redis 内存淘汰策略选型

Redis 内存满时，根据 maxmemory-policy 决定淘汰哪些 Key：

策略	淘汰规则	适用场景
`noeviction`	不淘汰，写报错	严禁丢数据
`allkeys-lru`	所有 Key 中 LRU 淘汰	通用推荐
`volatile-lru`	仅淘汰带 TTL 的 Key	兜底 + 永久缓存混合
`allkeys-lfu`（Redis 4.0+）	所有 Key 中 LFU 淘汰	热点数据保护更强
`volatile-ttl`	淘汰快过期的 Key	TTL 多样时
`allkeys-random`	随机淘汰	不推荐

生产推荐配置：

1
2
3
4


# redis.conf
maxmemory 16gb
maxmemory-policy allkeys-lru
maxmemory-samples 10 # LRU 采样数, 越大越精确

6.6 监控告警体系

关键指标（Micrometer + Prometheus + Grafana）：

指标	告警阈值	排查方向
`redis_used_memory_bytes`	> 80% maxmemory	Key 增长 / 大 Key
`redis_cpu_usage`	> 70%	慢查询 / 持久化
`redis_connected_clients`	> 80% maxclients	连接泄漏
`redis_instantaneous_ops_per_sec`	突增 > 3x	业务异常
`redis_slowlog_length`	> 10	慢查询堆积
`redis_keyspace_hit_rate`	< 0.7	命中率下降
`redis_blocked_clients`	> 0	BLPOP 阻塞
`redis_master_link_down_since_seconds`	> 10	主从断开

生产必须的 3 条告警：

命中率突降——hit_rate 5 分钟内下降 > 10% → 大概率有热点 Key 过期
主从断开——master_link_down > 30 秒 → 自动切换可能触发
内存接近上限——used_memory / maxmemory > 0.9 → 立刻扩容或清理

七、与系列其他篇的联动

缓存体系不是孤岛，它和数据库演化、熔断限流、异地多活都强相关。本节把这条联动链路拉通。

7.1 与系列第 8 篇《数据库演化》的联动

缓存与 DB 一致性是两者最核心的联动点：

强一致数据（订单状态、支付结果）→ 不走缓存，直接 DB
最终一致数据（商品详情、用户昵称）→ Cache-Aside 模式
统计类数据（阅读数、点赞数）→ Write-Behind 模式（先写缓存，异步刷 DB）

📌 原则：缓存是 DB 的"加速副本"，不是"替代品"

任何缓存数据都必须能通过 DB 重建——这是分布式系统的不变式。缓存丢了 = 重建一次。如果缓存数据没法重建，就根本不该放缓存。

7.2 与系列第 7 篇《熔断限流 Sentinel》的联动

缓存击穿是熔断限流的典型触发场景：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


缓存击穿
 ↓
大量请求穿透到 DB
 ↓
DB 响应慢 (RT 涨到 2s)
 ↓
Sentinel 检测到慢调用比例 > 50%
 ↓
熔断器打开
 ↓
后续请求直接返回降级结果
 ↓
缓存回填后, 熔断器半开探测
 ↓
探测成功 → 熔断器关闭, 恢复正常

📌 实践：缓存三大问题必须配合熔断限流

单独的缓存击穿治理只能降低风险，配合熔断器才能在事故发生时防止雪崩蔓延。

7.3 与系列第 1 篇《异地多活》的联动

异地多活下缓存同步是个两难问题——

方案 A：每机房独立 Redis 集群

1
2
3
4
5


杭州机房 Redis 集群 上海机房 Redis 集群
 │ │
 只服务杭州用户 只服务上海用户
 │ │
 └────── 跨机房调用极少 ──────────────┘

✅ 优点：调用零延迟 ❌ 缺点：跨机房数据不一致（如商品价格）

方案 B：跨机房 Redis 主从

1
2
3


杭州机房 Redis Master ──► 上海机房 Redis Replica (异步复制)
 ▲ ▲
 本机房写 跨机房读

✅ 优点：数据最终一致 ❌ 缺点：跨机房写延迟 30-100ms，主写从读模式下从可能延迟 1-5 秒

方案 C：CRDT + 多主（终极方案）

异地多活多写场景下用 CRDT（Conflict-free Replicated Data Types），每个机房独立写、独立读、后台异步合并冲突——实现难度高，但阿里这类大厂在用。

🎯 决策：业务用方案 A，少数汇总用方案 B

99% 业务走单元化 + 本机房缓存——本机房调本机房，跨机房调用很少。少数需要"全局数据"的场景（排行榜、汇总报表）用方案 B。不推荐方案 C——CRDT 复杂度极高，业务收益不匹配。

收尾：本篇要点 + 系列承上启下

✍️ 本篇核心结论：

本地缓存——Caffeine 的 W-TinyLFU 比 Guava 命中率提升 30%，TTL 必须加随机偏移防雪崩
分布式集群——Redis Cluster 用 16384 哈希槽分片，单实例内存不超过 64GB
主从同步锁——Redisson + watchdog 是 99% 场景的最优解，Redlock 在 5 个独立实例上过半才生效
文件持久化——混合持久化是 4.0+ 默认推荐，everysec 丢 ≤ 1 秒 是大多数业务的最优解
三大问题——雪崩（TTL 偏移+多级缓存）/ 穿透（空值+布隆）/ 击穿（互斥锁+逻辑过期）各有一套
生产场景——多级缓存 + 延迟双删 + 慢查询监控 + LRU 淘汰 + 8 条告警

📚 Java 微服务系列地图：

#	主题	关系
1	异地多活	跨机房缓存同步
2	流量调度（Nginx/LVS）	缓存前哨
3	K8s 容器编排	Redis 部署
4	技术选型（SCA + Dubbo3）	选型总结
5	Nacos	配置中心缓存
6	Spring Cloud Gateway	网关层缓存
7	熔断限流 Sentinel	缓存击穿保护
8	数据库演化	缓存与 DB 一致性
9	本篇缓存体系	本地 + 集群 + 锁 + 持久化

📖 参考资料：

Redis 官方文档 —— Redis 7.2 完整命令 + 配置
Caffeine Wiki —— W-TinyLFU 算法论文
Redisson 官方文档 —— 分布式锁 + watchdog
Redis 设计与实现（黄健宏） —— 源码级中文权威
How to do distributed locking — Martin Kleppmann —— Redlock 争议原始论文
Is Redlock safe? — antirez —— Redis 作者的反驳
Spring Cache 官方文档 —— 注解 + 抽象
Redis 4.0 混合持久化设计 —— RDB+AOF 实现原理
《数据密集型应用系统设计》（DDIA）—— 第 5、6 章缓存与复制
《Redis 深度历险：核心原理与应用实践》（钱文品）—— 国内 Redis 实战最佳读物

下一篇预告：系列第 10 篇《可观测性体系：Metrics + Tracing + Logging 三件套》——缓存只是性能加速器，怎么监控它的健康、定位它的瓶颈、追溯它的链路？下一篇把 Java 微服务的可观测性讲透。

算法	优点	缺点	适用
令牌桶	平滑限流、允许突发	配置稍复杂	通用首选
漏桶	强制匀速	突发流量被截断	严格流量整形
滑动窗口	精确控制时间窗	内存开销大	短时间窗口限流

维度	分库分表	分布式数据库
兼容性	需改造 SQL	兼容 MySQL/PG 协议
跨库 JOIN	不支持	支持（通过下推）
跨库事务	需 Seata	天然支持（Percolator/TCC）
运维	复杂（数据迁移、扩容）	较简单（自动 Rebalance）
成本	中等	较高（多副本）
选型时机	1000 万 - 100 亿行	100 亿 + 行

参数	默认	建议	说明
`autovacuum_vacuum_scale_factor`	0.2	0.05-0.1	触发 vacuum 的死行比例
`autovacuum_analyze_scale_factor`	0.1	0.05	触发 analyze 的变更比例
`autovacuum_vacuum_cost_limit`	200	1000-2000	vacuum 速度
`autovacuum_max_workers`	3	4-8	并发 worker 数

Java微服务 on Liangweidong's blog

异地多活：Java Web 微服务的高可用终极形态

异地多活：Java Web 微服务的高可用终极形态

引子：机房炸了的那一夜

一、核心概念：把术语先掰开

1.1 什么是异地多活

1.2 高可用的衡量标准

1.3 两个关键指标：RTO 与 RPO

二、架构演化史：从单机到异地多活

2.1 七阶段演进时间线

2.2 各阶段对比

2.3 关键阶段详解

单机：一台机器打天下

主从副本：最基础的冗余

同城灾备：机房级容灾

同城双活：机房都承担流量

两地三中心：跨城市的折中

异地双活：迈向真正的多活

异地多活：终态

三、为什么需要异地多活

3.1 城市级故障是真实存在的

3.2 业务中断的代价

3.3 合规与出海

四、具体怎么操作

4.1 存储层：双向同步

主流存储的双向同步方案

MySQL 双主同步的两个坑

阿里 Canal 实战

Canal 部署架构

4.2 数据冲突：必须解决的根本问题

4.3 单元化：异地多活的核心

三种分片规则

直接哈希分片示例

单元化的 3 大原则

单元化的代价

4.4 兜底机制

4.5 全局数据例外

4.6 故障演练：必须做的事

演练清单

演练频率

Netflix Chaos Monkey 的启发

4.7 监控告警：异地多活的"心跳"

三层监控

拨测：业务侧的"心跳"

业务侧的关键指标

五、真实案例

5.1 阿里：三地五中心

5.2 美团：两地三中心

5.3 字节跳动：单元化 + 异地

六、总结

6.1 异地多活的 3 大核心要素

6.2 实施成本

6.3 何时不该上异地多活

6.4 异地多活的常见陷阱

6.5 系列预告

七、异地多活实施清单

7.1 业务层 Checklist

7.2 数据层 Checklist

7.3 流量层 Checklist

7.4 运维层 Checklist

7.5 团队层 Checklist

八、实战案例：同城双活生产落地方案（A 主 B 备，A 挂 B 自动接管）

8.1 需求清单

8.2 架构总览

8.3 关键组件选型

8.4 MySQL HA 配置

主库 /etc/my.cnf

创建用户（主库执行）

备库指向主库

8.5 keepalived VIP（同子网内）

8.6 Orchestrator 部署（B 机房）

post-failover.sh 自动钩子

8.7 ProxySQL 部署（每个机房一个）

8.8 Redis Sentinel

8.9 k8s 双集群

8.10 故障切换全流程

场景 1：A 挂了 → B 升主

场景 2：A 恢复 → 自动切回 A

关键：A 追平 B 的时间

场景 3：B 挂了

主库 `/etc/my.cnf`

3.3.2 Master 配置 `/etc/keepalived/keepalived.conf`

3.3.4 健康检查脚本 `/usr/local/bin/check_nginx.sh`