本系列文档面向”自己复习/理解原理”，素材全部来自 docs/07-面试问题/ 中记录的真实踩坑。
每个技术点只回答一个问题：这个技术在我们项目里为什么会出问题、它的原理决定了它必须怎么用。

最近修订：2026-08-07（全系列按统一结构深化：原理图解、知识扩展、术语表、难度标记）

怎么用这套文档

不建议从头到尾通读。推荐三种打开方式：

  1. 按分类过一遍：想系统复习某个领域（比如”消息队列”）时，直接打开对应文件，里面按”核心概念（含原理图解）→ 我们踩过的坑 → 知识扩展 → 必须记住的结论”组织。
  2. 面试前查漏补缺：每篇文档开头都有”一句话速览”，扫一遍标题和结论就能知道自己是否记得清楚，含糊的再展开细读；每个技术点开头的”难度 + 掌握要求”就是自测标准——达不到掌握要求的，回到正文精读。
  3. 排障时当手册查：遇到线上/测试问题，先想它属于哪个分类，翻到对应篇目的”必须记住的结论”，里面通常有排查的标准动作（比如”数据存在但搜不到 → 先 GET /{index}/_mapping“）。

每篇文档结构统一：

1
2
3
4
5
6
7
8
9
> 一句话速览          —— 本篇主旨，30 秒判断要不要细读
## 目录               —— 长文档快速跳转
## 技术点 N
  > 难度 + 掌握要求    —— ⭐ 数量代表深度，掌握要求即自测清单
  ### 核心概念         —— 这个技术是干什么的，最小知识面 + 原理图解（Mermaid）
  ### 我们踩过的坑      —— 具体问题现象 + 根因（对应 07 目录的原始记录）
  ### 知识扩展         —— 项目没踩过但同主题必须知道的（部分篇目）
  ### 必须记住的结论    —— 提炼成可以直接背的话
## 术语表             —— 本篇关键术语速查

分类目录

分类 文档 涉及技术点
微服务治理 01-微服务治理.md Nacos 注册发现与配置中心（临时/持久实例、三元组）、Sentinel 限流熔断（规则体系、滑动窗口、熔断三态）、OpenFeign（动态代理、超时与重试）、Spring Cloud Gateway（WebFlux、过滤器链）
分布式事务与消息 02-分布式事务与消息队列.md Seata AT 模式（两阶段、undo_log、全局锁、AT/TCC/Saga 对比）、RocketMQ（存储结构、刷盘、消息不丢三环节、重试死信、幂等/顺序/事务消息）
缓存与数据一致性 03-缓存与数据一致性.md 多级缓存（Caffeine+Redis、W-TinyLFU、DCL）、布隆过滤器、穿透/击穿/雪崩、Cache-Aside 与延迟双删、状态变更广播
搜索引擎 04-搜索引擎ES.md 倒排索引、写入流程（refresh/translog/segment）、分片与两阶段查询、Mapping 与动态推断、IK 中文分词、GEO 查询
网络通信 05-网络通信Netty.md Reactor 线程模型、ByteBuf 与零拷贝、Pipeline 责任链、WebSocket 协议升级握手、粘包拆包与心跳
数据库与并发控制 06-数据库与并发控制.md MyBatis-Plus 乐观锁/逻辑删除、并发扣减 SQL 设计、B+树索引与最左前缀、EXPLAIN 慢查询排查、MVCC 与间隙锁、并发手段选型
可观测性 07-可观测性.md SkyWalking 链路追踪（字节码增强、sw8 传播）、JDK 21 兼容性、可观测性三支柱、Prometheus 拉模型与四种指标、MDC 日志透传
容器化部署 08-容器化部署Docker.md Docker Compose 编排、健康检查、数据卷持久化、镜像分层与多阶段构建、容器网络与资源限制、多服务脚本管理与规模演进
认证鉴权与网关架构 09-认证鉴权与网关架构.md JWT 三段结构、HS256/RS256、网关统一鉴权与上下文透传、双 Token 续期与主动失效、CI/CD 基础概念
JVM 与并发编程 10-JVM与并发编程.md JVM 内存结构与 OOM 排查工具链、GC 基础、ThreadLocal 原理与坑、并发三要素与 DCL/volatile、分布式锁、接口幂等性设计

全局踩坑规律（读完所有分类后回来看这一段）

把 07 目录里几十个问题拍平了看，会发现根因高度集中在几种模式，理解了模式比记住每一条具体问题更重要：

  1. “配置了但没生效”比”报错”更危险：网关 Sentinel 限流（P0-06）、IM JWT 公钥缺失（P0-05）、RocketMQ 订阅覆盖（P0-05）都不抛异常、不报错，只是静默不工作。这类问题必须靠主动验证（真实压测、真实调用）才能发现，不能只看服务能不能正常启动。
  2. “简化实现”是债务，不是完成：ES 同步消费者的注释写着”简化实现，实际需要完整数据”（P1-04），布隆过滤器的注释写着”启动时应该预热”（P0-03）——代码里留的 TODO/注释，早晚要还。
  3. 分布式场景下”只改自己”等于没改完：房源冻结只清了本地缓存、忘了广播（P0-02）；WebSocket 消息只走了自己的 Redis 通道、没接入统一的持久化和路由（P0-04-验证问题）。单机测试测不出这类问题，因为单节点下”没广播”和”广播了但只有一个节点”看起来效果一样。
  4. 鉴权信息容易在”手写基础设施代码”时被漏掉：NacosDataSource 默认构造函数不带用户名密码（P0-06），网关 JWT 透传链路里任何一环忘记透传 Header 都会导致下游认为”未登录”（验证问题 P0-01）。凡是要手写 SDK 客户端初始化代码，第一反应就是要不要传鉴权信息。
  5. 验证方式本身也是一种”配置”，用错了会产生假象：直连业务端口绕过网关会导致 UserContext 为空（看起来像 bug，其实是验证方式错了）；SQL 直接插入测试数据会绕过布隆过滤器/ES同步（验证问题 P2-01）。测试数据必须走业务接口，这是本项目反复踩到的同一个坑的不同表现形式。
  6. 和规模相关的配置不会自动跟着规模长大：Nacos 的 JVM_XMX=256m（P1-07）、健康检查的 --max-time 3（P1-08）、启动脚本的 SERVICES 数组（P1-06），都是”规模小的时候合理”的配置，在服务数量翻倍后集中爆发。任何包含具体数字/清单的配置，都要标注它是在什么规模下设定的。