From 47be5972ec9cda5b31024a664d5b98bae43f2080 Mon Sep 17 00:00:00 2001 From: Kovawx Date: Tue, 4 Aug 2026 09:52:22 +0800 Subject: [PATCH] docs(core): sync sealed compatibility matrix --- .../core/control-plane/breaking-changes.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/projects/core/control-plane/breaking-changes.md b/docs/projects/core/control-plane/breaking-changes.md index 5e4634b..56d75d6 100644 --- a/docs/projects/core/control-plane/breaking-changes.md +++ b/docs/projects/core/control-plane/breaking-changes.md @@ -25,12 +25,46 @@ | 版本 | 影响面 | 迁移结论 | |------|--------|----------| -| `Unreleased` | 构建脚本、事件消费者、Webhook 接收端 | 公开 Cargo feature 改用 kebab-case；引擎生成的 `event_id` 增加每次启动唯一的随机 epoch；开发期固定中心 API 被撤销，Connector 收缩为通用 Webhook 事件投递；认证项速率改为 Zero 主体策略聚合 | +| `Unreleased` | - | No pending compatibility changes | +| `0.0.15` | - | No pending compatibility changes | +| `0.0.15-rc.4` | - | No pending compatibility changes | +| `0.0.15-rc.3` | Diagnostics API 消费者、Connector 运维与事件 Sink | `diagnostics.trace_route` 改为执行真实会话路由追踪；Connector 对事实事件施加有界内存与可选 outbox 背压，采样事件改为仅 best-effort 且不持久化；默认重试次数由 3 调整为 10 | +| `0.0.15-rc.2` | 构建脚本、事件消费者、Webhook 接收端 | 公开 Cargo feature 改用 kebab-case；引擎生成的 `event_id` 增加每次启动唯一的随机 epoch；开发期固定中心 API 被撤销，Connector 收缩为通用 Webhook 事件投递；认证项速率改为 Zero 主体策略聚合 | | `0.0.15-rc.1` | 进程内 Rust `EventSource`、事件 Sink | Rust 实现者必须迁移到实时 `EventStream`；IPC/HTTP/gRPC GUI wire 无变化 | | `0.0.15-rc` | GUI flow 生命周期 | 订阅 ACK 后以 `flow.snapshot` 建立活动连接基线，再合并 flow 增量 | ## Unreleased + + +## 0.0.15 + + + +## 0.0.15-rc.4 + + + +## 0.0.15-rc.3 + +### Diagnostics 路由追踪使用真实会话语义 + +`diagnostics.trace_route` 现在构造 TCP 或 UDP 会话并复用代理运行时的路由追踪路径。域名规则没有直接命中且路由需要解析 IP 时，会通过真实 DNS 解析结果再次匹配 IP 规则。响应中的 `effective_mode`、`route_action` 和 `matched_rule` 因此反映实际运行时决策，不再使用简化推断。依赖旧诊断结果的控制端应以新结果为准。 + +### Connector backlog 改为有界工作集 + +Connector 不再让慢速或失联 Sink 导致进程内待投递队列无界增长： + +- 配置 outbox 时，事实事件先写入持久化 journal，内存只保留有界工作集，其余记录按空位从磁盘分页恢复； +- 未配置 outbox 时，事实事件通过停止继续消费事件源施加背压，不会静默丢弃； +- `flow.updated` 与 `stats.sampled` 是可丢弃采样，只做 best-effort 投递、不会写入 outbox；工作集已满时优先替换同一 Sink 的旧采样，不驱逐事实事件； +- `api.dispatcher.max_in_memory_deliveries = 0` 表示 outbox-only 模式，因此必须同时配置 `api.outbox_path`； +- `max_retry_attempts` 默认值由 `3` 调整为 `10`，显式配置不受影响。 + +事件 Sink 不应把吞吐采样当作可靠事实流；需要恢复保证的消费者应使用事实事件并配置 outbox。 + +## 0.0.15-rc.2 + ### 撤销开发期固定中心 API 项目尚未发布 Connector 合同，因此开发期的节点注册、同步、traffic、presence、访问配置和私有命令设计直接撤销，不保留兼容层。 @@ -147,4 +181,4 @@ IPC、HTTP SSE 和 gRPC 的 wire 格式保持 `zero.api.v1` / `zero.event.v1`， - GUI/SDK/面板的明确迁移步骤； - 对应回归测试位置。 -开发期间只在版本矩阵和 `## Unreleased` 下登记，不预判最终发布版本，也不写入 Cargo 的 `-dev` 构建号。完整测试通过后，由 `scripts/release.ps1` 或 `scripts/release.sh` 将矩阵行、章节标题和 workspace 版本一起封板；禁止手工分别修改这些位置。 +开发期间只在版本矩阵和 `## Unreleased` 下登记，不预判最终发布版本，也不写入 Cargo 的 `-dev.N` 构建号。完整测试通过后，由 `Prepare Release` 工作流或 `scripts/release.sh` 将矩阵行、章节标题和 workspace 版本一起封板；禁止手工分别修改这些位置。