@umacloud/knowledge 1.0.15 → 1.0.17

package/backend/01-standards/queue-and-consumer-reliability.md

@@ -0,0 +1,98 @@
+---
+id: queue-and-consumer-reliability
+title: 队列与消费者可靠性规范（投递语义/幂等有效一次/顺序/可见性超时/毒消息，商业级必读）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [queue, consumer, reliability, idempotent-consumer, effectively-once, at-least-once, dead-letter-queue, poison-message, visibility-timeout, redelivery, ordering, backpressure, consumer-lag, outbox, inbox, 队列, 消费者, 幂等, 有效一次, 死信, 毒消息, 可见性超时, 顺序, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 队列与消费者可靠性规范（商业级必读）
+
+> 异步队列把"耗时/可削峰"的工作从请求路径里挪走，但也引入一组分布式难题：消息会**重复投递**、会**乱序**、会**卡住**、会**毒死消费者**。把这些当"偶发"忽略，结果就是重复扣款、订单错乱、队列雪崩、一条坏消息阻塞整条队列。
+> 这份规范讲的不是选哪个队列产品（选型与各产品用法见 `backend/01-standards/message-queue-patterns`），也不只是"任务该不该异步"（任务编排见 `backend/01-standards/background-jobs-and-async`），而是**消费侧怎么写才可靠**：投递语义、幂等与有效一次、顺序、可见性超时与重投、毒消息与死信、背压与堆积。
+
+## 1. 先认清投递语义（一切的前提）
+
+| 语义 | 含义 | 现实可得性 |
+|---|---|---|
+| 至多一次 at-most-once | 不重复，但可能丢 | 简单，但丢消息通常不可接受 |
+| 至少一次 at-least-once | 不丢，但可能重复 | **主流默认**——必须假设会重复 |
+| 恰好一次 exactly-once | 不丢不重 | 端到端几乎不存在；分布式下是营销词 |
+
+**结论：按"至少一次 + 可能乱序 + 可能重投"来设计。** 真正能做到的不是传输层的"恰好一次",而是**业务上的"有效一次"（effectively-once）**——传输可以重复投递,但靠**消费幂等**保证副作用只发生一次。任何依赖"队列保证不重复"的设计都是错的。
+
+## 2. 幂等消费与有效一次（核心中的核心）
+
+同一条消息可能被投递 2 次、5 次（重投、重平衡、消费者崩溃后重启都会导致）。涉钱/发货/发邮件/外部副作用的消费**必须幂等**：
+
+- **去重键**：用稳定的业务键或消息 ID 作为去重依据（生产者要保证同一逻辑事件用同一 ID）。
+- **去重落地**：处理前检查"这个 ID 处理过吗"，处理后记录；去重表/标记要和业务副作用在**同一事务**里提交，否则"业务做了但没记上去重"仍会重复。
+- **首选天然幂等写**：`UPSERT`、`SET 状态=已支付`、条件更新（`WHERE 状态=待支付`）这类操作天然幂等，优于"先查再插"的竞态写法。
+- **去重窗口**：去重记录保留足够覆盖最大可能重投间隔（含 DLQ 重放),并有清理策略防无限增长。
+- **副作用收口**：把外部副作用（扣款/发消息）做成可幂等或带幂等键调用（见 `backend/01-standards/idempotency-and-safe-retries`）。
+
+## 3. 可见性超时与重投机制
+
+至少一次队列普遍用"取出即隐藏一段时间（可见性超时 / ack 截止），处理完确认（ack），否则到期重新可见被别人取"的机制。用错会**自伤**：
+
+- **处理完才确认**：先处理成功、再 ack/提交位点；**绝不**取出就自动确认（自动提交 = 崩溃即丢消息）。
+- **可见性超时 > 处理耗时**：超时必须覆盖正常处理时间 + 余量。设太短 → 还没处理完消息就被重新投递给另一个消费者，造成**并发重复处理**；设太长 → 真崩溃了消息长时间不重投，延迟恢复。
+- **长任务续租**：处理时间不确定的任务要在处理中**续租/心跳延长**可见性，而不是一开始设一个超大超时。
+- **确认要可靠**：ack/提交本身失败要能感知；位点提交粒度与"处理成功"对齐,避免提交了未处理或处理了未提交。
+
+## 4. 顺序：只在必要处保证，别全局强序
+
+全局严格有序和高吞吐/可扩展天然冲突。
+
+- **按需分区有序**：只对**同一实体**（同一订单/同一账户）要求有序——用实体键路由到同一分区/队列，保证**分区内**有序即可，不同实体并行处理。
+- **别假设跨分区有序**：多分区/多消费者天然乱序;业务逻辑不能依赖"先发的先到"。
+- **乱序容忍设计**：用版本号/时间戳/状态机让消费对乱序与重复**收敛到正确终态**（如旧版本更新被丢弃、状态只能单向前进），比强行保序更健壮。
+- **有序与重试的张力**：严格有序队列里,一条卡住的消息会阻塞其后全部——更需要快速隔离毒消息（见 §5）。
+
+## 5. 毒消息与死信队列（DLQ）
+
+"毒消息"（poison message）= 无论重试多少次都必然失败的消息（数据损坏、不可解析、触发确定性 bug）。不隔离它,它会反复重试**阻塞队列、刷爆日志、耗尽资源**。
+
+- **限次重试 + 退避抖动**：瞬时失败重试有限次,指数退避 + 抖动(避免重试风暴);区分**可重试**(网络/限流/5xx)与**不可重试**(解析失败/校验不过/业务拒绝)——不可重试的别浪费重试,直接进 DLQ。
+- **超限进 DLQ**：超过重试上限的消息移入死信队列,**带上下文**(原消息 + 失败原因 + 重试次数 + 时间),不静默丢弃。
+- **DLQ 必须被监控与处置**：DLQ 不是垃圾桶——堆积要告警,要有人看、能诊断、能修复后**重放**。DLQ 无人管 = 消息悄悄全丢。
+- **隔离优先于阻塞**：宁可让一条坏消息进 DLQ,也不要让它卡住整条队列拖垮正常消息。
+
+## 6. 背压、堆积与消费者健康
+
+- **监控消费滞后(lag)**：盯消费者落后量(待处理积压)。lag 持续增长 = 消费跟不上生产,要么扩消费者、要么限生产、要么优化处理。
+- **有界并发与预取**：消费者设合理预取/并发上限,别一次抓太多撑爆内存或长时间占住不 ack。
+- **背压而非无限缓冲**:下游处理不过来时传递背压(放慢拉取/拒绝),不要把消息全拉进内存无界堆积到 OOM。
+- **慢消费者隔离**:不同类型任务用不同队列/消费者池,一类慢任务别拖垮另一类(呼应 `backend/01-standards/resilience-and-fault-tolerance` 的舱壁)。
+- **优雅停机**:消费者收到停止信号要处理完在途消息(或安全释放回队列)再退出,不硬切。
+
+## 7. 生产侧可靠性：别在源头就丢/错
+
+- **入队与事务一致(outbox)**:"写库 + 发消息"要么都成要么都不成。用 **outbox 模式**——业务与"待发消息"同事务写库,再由投递器异步发出——避免"事务回滚了消息却发了"或"事务提交了消息没发"。
+- **消费幂等也要 inbox 思路**:接收侧记录已处理消息 ID(inbox),配合 outbox 构成端到端有效一次。
+- **载荷小而稳**:消息传 ID/引用而非大对象;Schema 带版本,演进保持兼容,消费者能容忍新增字段。
+
+## 8. 反模式（出现即不合格）
+
+1. **假设恰好一次**:依赖队列"不会重复",消费不幂等 → 重复扣款/重复发货。
+2. **取出即自动确认**:auto-ack/自动提交位点,消费者一崩消息就丢。
+3. **可见性超时短于处理**:消息处理中就被重投,并发重复处理。
+4. **毒消息无限重试**:一条坏消息反复失败阻塞队列、刷爆日志、烧资源。
+5. **有 DLQ 没人看**:死信堆积无告警无重放,消息悄悄全丢。
+6. **全局强序**:为顺序牺牲扩展性,一条卡住阻塞全部。
+7. **无界拉取/缓冲**:消费者一次抓太多或无限缓冲,OOM。
+8. **不监控 lag**:消费早已跟不上,积压到爆才发现。
+9. **入队与事务不一致**:无 outbox,消息与数据状态错位。
+
+## 9. 最低交付 checklist
+
+- [ ] 按"至少一次 + 可能乱序"设计;靠消费幂等实现业务"有效一次"。
+- [ ] 用稳定去重键,去重记录与业务副作用同事务提交;优先天然幂等写。
+- [ ] 处理成功后才 ack/提交位点;可见性超时 > 处理耗时,长任务续租。
+- [ ] 仅对同一实体按分区保证有序,业务对乱序/重复能收敛到正确终态。
+- [ ] 限次重试 + 退避抖动,区分可重试/不可重试;超限进带上下文的 DLQ。
+- [ ] DLQ 有监控告警、可诊断、可重放;坏消息隔离而非阻塞整队。
+- [ ] 监控消费 lag;有界并发/预取 + 背压;慢消费者隔离;消费者优雅停机。
+- [ ] 生产侧用 outbox 保证入队与事务一致;载荷小、Schema 带版本兼容演进。

package/backend/01-standards/resilience-and-fault-tolerance.md

@@ -0,0 +1,101 @@
+---
+id: resilience-and-fault-tolerance
+title: 实现级韧性与容错规范（超时/重试预算/熔断/舱壁/背压，商业级必读）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [resilience, timeout, retry-budget, backoff, jitter, circuit-breaker, bulkhead, backpressure, load-shedding, fallback, deadline, 韧性, 容错, 超时, 重试, 熔断, 舱壁, 背压, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 实现级韧性与容错规范（商业级必读）
+
+> 架构级讲"同城/异地容灾、RPO/RTO"（见 `architecture/resilience-and-disaster-patterns`）；本规范讲**代码里每一次外部调用怎么写才不会被拖垮**。
+> 分布式系统里依赖**一定会**变慢、超时、抖动、半死不活。商业级服务把超时、重试预算、熔断、舱壁、背压写进每一次出站调用，让一个依赖的故障**不会**级联拖垮整个服务。默认值（无超时、无脑重试、共享线程池）正是雪崩的配方。
+
+## 1. 核心原则
+
+- **每一次出站调用都有超时**：没有无限等待这回事。没设超时 = 把自己的命交给对方。
+- **失败要快、要可控**：宁可快速失败 + 降级，也不要慢慢挂死拖垮上游。
+- **重试是有预算的**：重试能救瞬时抖动，也能在故障时制造**重试风暴**压垮已经半死的依赖——必须限额。
+- **隔离故障域**：一个依赖的故障不能耗尽全服务的资源（线程/连接/内存）。
+- **降级有契约**：依赖不可用时返回什么、是否可缓存兜底，要事先设计，不是临时拍。
+
+## 2. 超时与截止时间（deadline）
+
+- **每个出站调用设超时**：连接超时 + 读超时分开设；按依赖的 p99 + 余量定，不要一律 30s。
+- **超时预算自上而下分配**：入站请求带总预算（如 800ms），调 A 花掉的时间从预算里扣，传给 B 的是**剩余预算**——避免"上游已超时放弃、下游还在傻等"。
+- **传播截止时间**：把 deadline 随调用链传递（header/context），下游据此决定还值不值得开工。
+- **超时要小于上游超时**：下游超时必须短于上游，否则上游先放弃，下游白做功还占资源。
+
+| 反例 | 正解 |
+|---|---|
+| 全局一个 30s 超时 | 按依赖分别设（DB 200ms、内网 RPC 300ms、外部 API 2s）|
+| 上游 1s 超时，下游 5s | 下游超时 < 上游，并扣除已耗时 |
+| 无截止时间传播 | deadline 随 context 下传，下游过期即放弃 |
+
+## 3. 重试与重试预算
+
+- **只重试可重试错误**：超时、连接失败、5xx/服务不可用、明确的"瞬时"错误可重试；4xx 参数错、鉴权失败、业务拒绝**不重试**（重试也白搭，还放大压力）。
+- **指数退避 + 抖动（jitter）**：退避间隔指数增长并加随机抖动，避免所有客户端**同步**在同一刻重试形成尖峰。
+- **重试预算（retry budget）**：限制"重试请求占总请求的比例"（如 ≤10%）。一旦依赖整体故障，重试占比飙升即**自动停止重试**——这是防重试风暴的关键，比单纯"最多重试 3 次"更有效。
+- **幂等前提**：只对幂等操作重试；非幂等写（扣款、下单）重试必须配幂等键（见 `backend/01-standards/idempotency-and-safe-retries`）。
+- **不在每一层都重试**：多层各自重试会**指数级放大**请求（3 层各重试 3 次 = 27 倍）。在**一处**重试，其余层只透传错误。
+
+## 4. 熔断器（circuit breaker）
+
+防止对一个已经故障的依赖持续打无效请求，给它恢复时间，并让调用方快速失败。
+
+| 状态 | 行为 | 转移条件 |
+|---|---|---|
+| 关闭（closed）| 正常放行，统计失败率 | 失败率/慢调用率超阈值 → 打开 |
+| 打开（open）| 直接快速失败，不打依赖，走降级 | 冷却时间到 → 半开 |
+| 半开（half-open）| 放少量探测请求 | 探测成功 → 关闭；失败 → 重新打开 |
+
+要点：按**失败率 + 慢调用率**触发（不只是异常数）；冷却期给依赖喘息；半开只放少量探测，别一下子全量灌回去。**熔断打开时必须有降级路径**，否则熔断只是把"慢失败"变成"快失败"，用户还是没结果。
+
+## 5. 舱壁隔离（bulkhead）
+
+把资源按依赖**分池**，一个依赖打满它自己的池，不波及其他。
+
+- **线程/并发隔离**：每个慢依赖用独立的线程池/信号量限并发；它卡住只耗尽自己那一格，主线程池不受影响。
+- **连接池隔离**：不同依赖、不同优先级用独立连接池；别让一个慢查询占满整个 DB 连接池饿死其他请求。
+- **限制在途请求数**：对每个依赖设最大在途（in-flight）上限，满了立即拒绝/降级，而不是无限排队耗内存。
+- **核心与非核心隔离**：关键链路（下单/支付）与非关键（推荐/埋点）用不同资源池，非核心拖垮不了核心。
+
+## 6. 背压与负载保护（backpressure / load shedding）
+
+- **背压**：下游处理不过来时，向上游传递"慢一点"信号（有界队列满即拒绝、流控窗口），而不是无限缓冲到 OOM。
+- **有界队列**：所有队列/缓冲必须有上限；满了走拒绝或降级，**绝不**无界堆积。
+- **主动卸载（load shedding）**：过载时**主动丢弃**低优先级请求，保住核心请求的 SLO——半数请求成功远好于全部一起慢死。
+- **限流前置**：入口按用户/IP/端点限流（见 `backend/01-standards/rate-limiting-complete`），把过载挡在门外。
+- **并发上限**：服务自身设最大并发，超过即排队有界 / 拒绝，保护自己不被打挂。
+
+## 7. 降级与兜底（fallback）
+
+- **降级要有契约**：依赖挂了返回什么——缓存的旧值、默认值、空集合、还是明确的"暂不可用"——事先设计好。
+- **缓存兜底**：读路径可在依赖不可用时返回最近一次缓存（标记为 stale），保证可用性。
+- **优雅降级**：非核心功能（推荐、个性化）失败时静默降级为通用内容，不让整页崩。
+- **降级也要可观测**：降级触发要打点告警，别让"一直在降级"被无声忽略。
+
+## 8. 反模式（出现即不合格）
+
+1. **无超时调用**：任何 HTTP/RPC/DB 调用没设超时，一个慢依赖挂死全服务。
+2. **无脑重试**：对所有错误重试、固定间隔无抖动、无预算 → 故障时制造重试风暴。
+3. **多层叠加重试**：每一层都重试，请求被指数放大压垮下游。
+4. **熔断无降级**：熔断打开但没兜底，用户照样拿不到结果。
+5. **共享资源池**：所有依赖共用一个线程池/连接池，一个慢依赖拖垮全部。
+6. **无界队列/缓冲**：积压无上限，过载直接 OOM。
+7. **超时倒挂**：下游超时比上游还长，上游先放弃、下游白干。
+8. **对非幂等写重试**：重复扣款/重复下单。
+
+## 9. 最低交付 checklist
+
+- [ ] 每个出站调用（HTTP/RPC/DB/缓存）都有连接 + 读超时，按依赖分别设定。
+- [ ] 超时预算自上而下分配，截止时间随调用链传播，下游超时 < 上游。
+- [ ] 只重试可重试错误，指数退避 + 抖动，且有重试预算上限。
+- [ ] 重试只在一层做，非幂等写重试配幂等键。
+- [ ] 关键依赖有熔断器（失败率/慢调用触发）且熔断时有降级路径。
+- [ ] 慢依赖用舱壁隔离（独立线程池/信号量/连接池 + 在途上限）。
+- [ ] 所有队列有界，过载时主动卸载低优先级请求保核心 SLO。
+- [ ] 降级有明确契约，降级触发可观测、有告警。

package/backend/01-standards/transactions-and-concurrency-control.md

@@ -0,0 +1,92 @@
+---
+id: transactions-and-concurrency-control
+title: 事务与并发控制规范（商业级后端必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [transaction, isolation, locking, concurrency, acid, deadlock, consistency, 事务, 隔离级别, 锁, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 事务与并发控制规范（商业级后端必读）
+
+> 多个请求同时改同一份数据时，"看起来能跑"的代码会丢更新、读脏数、超卖。
+> 商业级后端必须显式定义**事务边界**、选对**隔离级别**、用对**锁策略**。
+> 本规范聚焦单库内的本地事务与并发；跨服务/跨库一致性见 `architecture/distributed-transactions`。
+
+## 1. 事务边界 = 用例边界
+
+- **一个用例（业务操作）= 一个事务**。在**应用层/服务层**开启与提交事务，而不是在 repository 里各开各的（否则一个用例里多次提交，失败时一半已落库）。
+- 事务要**短小**：只把"必须原子"的读写包进去。**绝不**在事务里发 HTTP 调用、发消息、等外部 IO——会长时间持锁、放大死锁与连接耗尽。需要对外副作用时，用发件箱（outbox）在事务内只写消息，事务外再投递。
+- 事务里**先做校验/计算，再做写**，把写集中在末尾，缩短持锁时间。
+- 失败必须**整体回滚**；不要 catch 异常后继续提交"半截"数据。
+
+## 2. ACID 与一致性底线
+
+- **原子性**：要么全成功要么全回滚，没有"半完成"。
+- **一致性**：事务结束后所有约束（唯一/外键/check/余额非负）都成立——把不变量尽量交给 **DB 约束**，不要只在应用层校验。
+- **隔离性**：并发事务互不干扰的程度，由隔离级别决定（见 §3）。
+- **持久性**：提交即落盘，宕机不丢。
+- 金额用**定点/整数（分）**，绝不用浮点；时间带时区；并发计数器避免"读-改-写"丢更新。
+
+## 3. 隔离级别与并发异常
+
+选错隔离级别会出现这些异常，按场景选最低够用的级别：
+
+| 隔离级别 | 脏读 | 不可重复读 | 幻读 | 写偏斜(write skew) | 典型用途 |
+|---|---|---|---|---|---|
+| Read Uncommitted | 可能 | 可能 | 可能 | 可能 | 几乎不用 |
+| Read Committed | 否 | 可能 | 可能 | 可能 | OLTP 常见默认 |
+| Repeatable Read | 否 | 否 | 可能/否* | 可能 | 需要稳定快照的读 |
+| Serializable | 否 | 否 | 否 | 否 | 强一致关键写（账务/库存判定） |
+
+\* 不同数据库在 Repeatable Read 下对幻读的处理不同；需要严格不变量时用 Serializable 或显式加锁。
+
+- 异常含义：**脏读**=读到未提交数据；**不可重复读**=同一行两次读值不同；**幻读**=同一查询条件两次返回行数不同；**写偏斜**=两个事务各自读一致快照后分别写，合起来违反不变量（如"至少留一个值班医生"被两人同时请假打破）。
+- 经验：默认 **Read Committed**；对"读后据此决定写"的关键判定（余额、库存、配额），升到 **Serializable** 或用显式锁，否则会有写偏斜/超卖。
+
+## 4. 乐观锁 vs 悲观锁
+
+| 维度 | 乐观锁 | 悲观锁 |
+|---|---|---|
+| 机制 | 版本号/时间戳，提交时 CAS 校验 | `SELECT ... FOR UPDATE` 先锁后改 |
+| 适用 | 冲突少、读多写少 | 冲突多、临界区短、必须串行 |
+| 失败处理 | 影响行数=0 → 重读重试（带上限） | 等待锁/超时 |
+| 风险 | 高冲突下大量重试 | 持锁久 → 死锁、吞吐下降 |
+
+- **乐观锁**：`UPDATE t SET val=?, version=version+1 WHERE id=? AND version=?`；影响行数为 0 表示已被他人修改，重读后按业务决定重试或放弃。**先查后写**前必须有这层校验，否则丢更新。
+- **悲观锁**：`SELECT ... FOR UPDATE` 锁定将要修改的行，确保串行。务必：① 加锁范围最小；② 设锁等待超时；③ **所有事务以相同顺序加锁**以避免死锁。
+- **原子写优先**：能用一条原子语句就别先查后写——如 `UPDATE stock SET qty=qty-1 WHERE id=? AND qty>=1`（影响行数=0 即库存不足），既无竞态又免去显式锁。
+
+## 5. 死锁与锁竞争
+
+- **死锁成因**：两个事务以**相反顺序**持有/请求锁。根治：固定全局加锁顺序（如总是按主键升序锁多行）。
+- 数据库会检测死锁并回滚其中一个事务——业务侧要**捕获死锁错误并重试**（幂等前提下，带退避）。
+- 减少锁竞争：缩短事务、降低隔离级别到够用、给热点行设计分桶/分片、把"读多"路径走快照读不加锁。
+- **连接池**：事务持有连接，长事务会拖垮连接池；设置语句/事务超时，杜绝"忘了提交"的悬挂事务。
+
+## 6. 读一致性
+
+- **读己之写（read-your-writes）**：用户写完立刻读应看到自己的写；主从架构下要把"刚写完的读"路由到主库或加版本校验，避免读到滞后的从库。
+- 报表/聚合类长读用**快照读**或专门的只读副本，别和 OLTP 写抢锁。
+- 需要"一批读相互一致"时，把它们放进同一个（Repeatable Read/Serializable）事务的同一快照里。
+
+## 7. 反模式（出现即不合格）
+
+1. **事务里做外部 IO**：在事务内发 HTTP/MQ，长持锁、易死锁。
+2. **repository 各自提交**：一个用例多个事务，失败留下半截数据。
+3. **先查后写无并发保护**：丢更新、超卖（缺乏唯一约束/乐观锁/原子写）。
+4. **隔离级别不假思索**：关键判定用 Read Committed 出现写偏斜。
+5. **金额用浮点 / 计数器读改写**：精度丢失、并发丢更新。
+6. **长事务 + 大锁范围**：吞吐塌方、死锁频发、连接耗尽。
+7. **不处理死锁/锁超时**：偶发死锁直接变成用户报错。
+
+## 8. 最低交付 checklist
+
+- [ ] 事务边界在服务层、对齐用例；事务短小、无内部外部 IO。
+- [ ] 隔离级别按场景显式选择；关键"读后写"判定有写偏斜防护。
+- [ ] 并发写有保护：原子写 / 乐观锁（版本号）/ 悲观锁，三选一且最小化。
+- [ ] 多行加锁顺序固定；捕获死锁与锁超时并安全重试。
+- [ ] 不变量尽量落 DB 约束（唯一/外键/check），不只应用层校验。
+- [ ] 金额用整数/定点；计数器用原子更新而非读-改-写。
+- [ ] 有并发场景的自动化测试（并发下单/扣减/转账不出错）。

package/cicd/cicd-blueprint-deep-dive.md

@@ -1,16 +1,14 @@
 ---
 id: cicd-blueprint-deep-dive
-title: cicd-blueprint-deep-dive
+title: CI/CD 环节深度知识库
 domain: cicd
-category: cicd-blueprint-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [blueprint, cicd, deep, dive, 环节深度知识库]
+tags: [cicd, 流水线, pipeline, 持续集成, 持续交付, 发布, devops]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## CI/CD 环节深度知识库
+# CI/CD 环节深度知识库
 
 ### 目标
 - 让每次发布都具备可重复、可审计、可回滚能力。

package/cicd/release-readiness-gate.md

@@ -1,37 +1,88 @@
 ---
 id: release-readiness-gate
-title: release-readiness-gate
+title: 发布就绪门禁规范（每次发布的 pass/fail 闸门：阻断高风险变更，商业级必读）
 domain: cicd
-category: release-readiness-gate.md
-difficulty: intermediate
-tags: [cicd, gate, readiness, release, 发布就绪门禁清单]
-quality_score: 70
-last_updated: 2026-06-15
+category: cicd
+difficulty: advanced
+tags: [release-gate, readiness-gate, ci-cd, quality-gate, go-no-go, blocking-criteria, change-management, rollback, canary, post-deploy-verification, build-provenance, 发布门禁, 就绪门, 阻断, 灰度, 回滚, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
 ---
-# 开发：Excellent（11964948@qq.com）
+# 发布就绪门禁规范（商业级必读）
 
-## 发布就绪门禁清单
+> "构建绿了"不等于"能发"。CI 通过只证明代码编得过、测试跑得过；它不证明这次变更**可控、可观测、可回滚**。把"绿色流水线"直接当成放行信号，是大量线上事故的起点。
+> 发布就绪门禁是发布管线里一道**确定性的 pass/fail 闸门**——**每一次**进入生产的变更都必须穿过它，任一必过项不满足就**自动阻断**，不靠人情、不靠"这次先放一下"。它和一次性的服务级生产就绪审查不同（服务能否被运维见 `operations/01-standards/production-readiness-review`，逐条自检见 `development/03-checklists/release-readiness-checklist`）：本规范定义的是**每次发布都重复执行**的机器可判定闸门。
 
-### 目标
-- 用统一发布门禁阻断高风险变更，保证发布可控。
+## 1. 门禁的三条铁律
 
-### 必过门禁
-- 代码质量：lint、类型检查、静态分析通过。
-- 测试质量：核心回归通过、阻断缺陷清零。
-- 安全质量：高危漏洞清零，密钥泄露检查通过。
-- 构建质量：制品可追溯、版本标签一致。
-- 运维质量：发布与回滚脚本可执行。
+| 铁律 | 含义 | 违反的后果 |
+|---|---|---|
+| 确定性可判定 | 每个必过项是机器可判定的 pass/fail，不是"看着差不多" | 门禁形同虚设，靠主观放行 |
+| 强制不可绕过 | 门禁是合并/发布的硬阻断，绕过需留痕审批且属例外 | "临时跳过一下"成为常态，门禁名存实亡 |
+| 既看构建也看运行 | 不止"构建成功"，还要发布后验证"运行健康" | 部署成功但服务已坏，靠用户投诉才发现 |
 
-### 发布前检查
-- 是否完成变更影响评估与回滚预案。
-- 是否完成灰度策略与阈值配置。
-- 是否完成关键指标基线确认。
+核心判据：**门禁的价值在于敢说 fail。** 一个从不阻断任何发布的门禁等于没有门禁。
 
-### 发布后检查
-- 错误率、时延、成功率是否在阈值内。
-- 告警是否异常增加。
-- 关键业务链路是否连续成功。
+## 2. 必过门禁（任一不过即阻断）
 
-### 常见失败模式
-- 只检查构建成功，不检查运行质量。
-- 门禁定义存在但未强制执行。
+每一类给出**机器可判定**的通过条件，全部满足才进入发布阶段。
+
+| 门禁类别 | 通过条件（pass） | 失败即阻断（fail） |
+|---|---|---|
+| 代码质量 | 格式化/lint/类型检查/静态分析全过，无新增告警 | 存在 error 级问题或新增告警 |
+| 测试质量 | 关键路径回归全绿，覆盖率不低于基线，无阻断缺陷开放 | 测试红、覆盖率回退、存在未关阻断缺陷 |
+| 安全质量 | 依赖/镜像无未处理的 Critical/High 漏洞，密钥扫描无泄露 | 高危漏洞未分诊、检出明文密钥 |
+| 构建可信 | 制品可追溯（版本↔commit SHA 一一对应）、已签名验签、来源可证 | 制品来源不明、版本与代码对不上、未签名 |
+| 配置就绪 | 目标环境配置键齐全、启动校验通过、与制品版本绑定记录 | 缺配置、配置漂移、来源含糊（见 `architecture/01-standards/configuration-and-environment-management`） |
+| 可回滚 | 回滚方案存在且**已验证可执行**（应用/配置/数据） | 无回滚路径或从未验证 |
+| 可观测 | 本次变更涉及路径有监控指标与告警，发布后看得见 | 关键路径无遥测，出事不可见 |
+
+## 3. 发布前检查（pre-deploy）
+
+进入放量前必须确认，缺一不可：
+
+- **变更影响评估**：本次改了什么、影响哪些上下游、风险等级是多少，已记录。
+- **回滚预案就位**：回滚步骤明确且演练过；高风险变更预先准备好"一键回退"。
+- **灰度策略与阈值**：放量批次、观察窗口、自动回退触发阈值（错误率/延迟/成功率）已配置，不全量瞬时生效。
+- **指标基线确认**：发布前抓取关键指标基线（错误率、P95/P99 延迟、关键交易成功率），作为发布后对比的锚点。
+- **数据库变更安全**：Schema 变更前向兼容、可回滚，先迁移后发布、扩展式变更（见 `development/01-standards/database-migration-strategies`）。
+- **发布窗口与值班**：避开高风险时段，值班与升级路径在线、可响应。
+
+## 4. 发布后验证（post-deploy gate）
+
+部署完成**不是**发布成功——必须用运行信号确认。这是门禁的"后半扇"：
+
+- **黄金指标在阈值内**：错误率、延迟、饱和度、关键交易成功率在发布前基线的容忍带内。
+- **告警无异常抬升**：发布后未触发新的 P0/P1，告警量无异常飙升。
+- **关键链路连续成功**：核心业务链路（登录/下单/支付等）端到端连续成功，而非仅健康检查返回 200。
+- **观察窗口达标后才扩量**：每批灰度都要过观察窗口再放下一批；指标越界**自动回退**，不等人决策。
+- **失败即回滚并复盘**：触发回退条件就执行已验证的回滚，事后归档"为什么发坏了"。
+
+## 5. 例外与放行口径
+
+- **门禁是默认拒绝**：必过项有一项 fail，默认结果就是 no-go。
+- **例外必须留痕**：极少数业务紧急情况下的带条件放行，需要明确审批人、原因、补救项与期限，并归档可审计——而不是悄悄跳过。
+- **绝不降低红线**：可回滚、可观测、无高危漏洞、无明文密钥属硬红线，任何"紧急"都不豁免。
+- **门禁结果可追溯**：每次发布留下门禁判定记录（哪些过、哪些放行、谁批的），出事能反查。
+
+## 6. 反模式（出现即不合格）
+
+1. **绿即放行**：把 CI 通过直接当成可发布信号，不查可回滚/可观测/运行健康。
+2. **只看构建不看运行**：部署成功就宣布完成，没有发布后验证步骤。
+3. **门禁可随意绕过**："这次先跳过一下"成为习惯，硬阻断变软建议。
+4. **主观判定**：通过条件不是机器可判定的 pass/fail，靠人眼"差不多"。
+5. **无回滚就发**：没有已验证的回退路径，出事只能向前硬修。
+6. **全量瞬时生效**：不灰度、不设自动回退阈值，一发就是全量。
+7. **无基线对比**：发布后没有基线可比，指标好坏全靠感觉。
+8. **门禁无留痕**：放行与例外没有审计记录，事后无法追责复盘。
+9. **为赶进度降红线**："紧急发布"时豁免高危漏洞/明文密钥/无监控。
+
+## 7. 最低交付 checklist
+
+- [ ] 门禁是发布管线里**强制、确定性、不可随意绕过**的 pass/fail 闸门。
+- [ ] 必过门禁齐备：代码/测试/安全/构建可信/配置/可回滚/可观测，任一 fail 即阻断。
+- [ ] 发布前完成影响评估、回滚预案、灰度阈值、指标基线、DB 变更安全、值班就位。
+- [ ] 发布后用黄金指标+告警+关键链路验证，过观察窗口再扩量，越界自动回退。
+- [ ] 可回滚、可观测、无高危漏洞、无明文密钥为硬红线，紧急也不豁免。
+- [ ] 例外放行有审批人/原因/补救/期限并归档；每次门禁判定可追溯。
+- [ ] 服务级一次性就绪见 `operations/01-standards/production-readiness-review`；逐条自检见 `development/03-checklists/release-readiness-checklist`。

package/cloud-native/01-standards/container-security.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：容器安全完整标准
-# 作用：为容器镜像、运行时、编排提供安全规范
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 容器安全标准
 
 ## 目标
 

package/cloud-native/01-standards/kubernetes-complete.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 完整开发与运维标准
-# 作用：为 K8s 集群管理、应用部署、安全治理提供统一规范
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# Kubernetes 完整标准
 
 ## 目标
 

package/cloud-native/02-playbooks/gitops-with-argocd.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：GitOps 与 ArgoCD 实施作战手册
-# 作用：指导使用 ArgoCD 实现声明式持续部署
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# GitOps ArgoCD 作战手册
 
 ## 目标
 

package/cloud-native/02-playbooks/k8s-troubleshooting-playbook.md

@@ -1,20 +1,16 @@
 ---
 title: Kubernetes 故障排查作战手册
 version: 1.0.0
-last_updated: 2026-03-28
+last_updated: 2026-06-29
 owner: platform-team
 tags: [kubernetes, troubleshooting, diagnostics, pod, network, storage, node]
 status: production
 domain: cloud-native
 difficulty: intermediate
-quality_score: 70
+quality_score: 91
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 全场景故障排查作战手册
-# 作用：指导 K8s 集群各类故障的诊断、根因分析与修复
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
+# Kubernetes 故障排查作战手册
 
 ## 目标
 

package/cloud-native/02-playbooks/multicloud-governance.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：多云环境治理作战手册
-# 作用：指导多云架构的统一管理、成本优化和风险控制
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 多云治理作战手册
 
 ## 目标
 

package/cloud-native/02-playbooks/serverless-patterns.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Serverless 架构模式作战手册
-# 作用：指导 Knative、云函数等 Serverless 实践
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# Serverless 模式作战手册
 
 ## 目标
 

package/cloud-native/02-playbooks/service-mesh-playbook.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：服务网格实施与运维作战手册
-# 作用：指导 Istio/Linkerd 服务网格的部署、配置和运维
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 服务网格作战手册
 
 ## 目标
 

package/cloud-native/03-checklists/container-security-checklist.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：容器安全全面检查清单
-# 作用：确保容器镜像和运行时满足安全标准
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 容器安全检查清单
 
 ## 概述
 

package/cloud-native/03-checklists/k8s-production-readiness-checklist.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 生产环境部署前检查清单
-# 作用：确保应用具备生产环境运行条件
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# Kubernetes 生产就绪检查清单
 
 ## 概述
 

package/cloud-native/04-antipatterns/container-antipatterns.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：容器常见反模式识别与修正
-# 作用：帮助团队避免容器化常见错误
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 容器反模式库
 
 ## 反模式分类
 

package/cloud-native/04-antipatterns/k8s-antipatterns.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 常见反模式识别与修正
-# 作用：帮助团队避免常见错误，建立正确实践
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# Kubernetes 反模式库
 
 ## 反模式分类
 

package/cloud-native/05-cases/case-k8s-migration.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 迁移实战案例
-# 作用：分享传统应用到 Kubernetes 的迁移经验
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 案例：Kubernetes 迁移
 
 ## 背景
 

package/cloud-native/05-cases/case-k8s-scaling.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 自动扩展实战案例
-# 作用：分享 K8s 弹性伸缩的实践经验
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 案例：Kubernetes 扩展
 
 ## 背景
 

package/cloud-native/05-cases/case-k8s-security-incident.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：Kubernetes 安全事件响应实战案例
-# 作用：分享 K8s 安全事件的处理经验
-# 创建时间：2025-03-20
-# 最后修改：2025-03-20
+# 案例：Kubernetes 安全事件
 
 ## 背景