diff --git a/docs/08-development-plan.md b/docs/08-development-plan.md index f3a19d5..7613258 100644 --- a/docs/08-development-plan.md +++ b/docs/08-development-plan.md @@ -61,7 +61,7 @@ P4/P5定时等待与后续查询轮次的实现及回归记录见[时钟报告]( 1. 已补[首批可复现故障工具](reports/phase-6-fault-boundaries.md):A04“派发已提交但消息尚未送达”、W01/W13事务提交结果不明,以及W16最终回执/旧PENDING结果重放/下一轮竞争。迁移器同时提供当前版本无外键新装基线;每个切点必须有实际数据库或进程证据,不能用响应错误推断事务是否已提交,也不能用普通SIGNAL竞争替代最终查询场景。 2. 已实现[基础运行观测](api/observability.md)及[有界业务状态与事件采样](reports/phase-6-business-observability.md):HTTP/WS、数据库连接池、后台批次、固定任务/交付/流程/Inbox状态计数、最近事件类别、终态耗时样本、固定事件阶段耗时、最早年龄、截断/新鲜度指标和可离线验证的告警规则;独立采集监听默认关闭,固定指标目录拒绝动态标签;发布前只读结构核验由[`orbit-admin verify`](api/operations.md)提供,运维人员也可用 `orbit-admin observe snapshot` 获取同一有界单节点快照。仍需端到端外部效果延迟、全局持久吞吐、Inbox从事件产生到推进完成的精确阶段延迟、全局发送队列、多节点聚合及生产采集/通知验证;SDK受控重连风暴和真实慢消费者背压已补[边界回归](reports/phase-6-reconnect-storm.md)与[慢消费者报告](reports/phase-6-slow-consumer.md),跨节点重连仍待目标拓扑。 3. 已补齐受保护管理环境中的固定凭据操作文件、轮换、撤销、提交不明故障切点、幂等回执和脱敏管理审计;轮换保留授权绑定并要求新令牌重新建立会话,旧 Worker 会话被排空且立即过期,撤销允许在停用范围内执行且不改写历史记录。已用一次性 MySQL 定向验证旧令牌失效、新令牌重绑和零外键;仍需多节点安全重绑演练、凭据最小权限配置核对和生产密钥托管/审计演练。 -4. 已补[`orbit-admin retention inventory`](api/retention.md)只读盘点和[阶段报告](reports/phase-6-retention-inventory.md),能区分过期幂等、确定终态、未知效果、未终结流程、已确认/未确认交付、已消费/未消费Inbox、事件和审计规模;它不执行归档或删除。后续仍需评审各类保留周期、归档格式、受保护记录核对,再执行备份恢复、兼容升级和六类容量负载。未确认交付、有效幂等身份、当前/历史执行证据和未终结流程不能被普通清理破坏。生产HA及RPO/RTO继续按实际拓扑验证,不缩减为本机多进程检查。 +4. 已补[`orbit-admin retention inventory`](api/retention.md)只读盘点和[阶段报告](reports/phase-6-retention-inventory.md),能区分过期幂等、确定终态、未知效果、未终结流程、已确认/未确认交付、已消费/未消费Inbox、事件和审计规模;它不执行归档或删除。已补[容量模型](19-capacity-model.md),把企业数转换为任务、流程、事件、连接、写放大和保留期输入;仍需评审各类保留周期、归档格式、受保护记录核对,再执行备份恢复、兼容升级和六类容量负载。未确认交付、有效幂等身份、当前/历史执行证据和未终结流程不能被普通清理破坏。生产HA及RPO/RTO继续按实际拓扑验证,不缩减为本机多进程检查。 5. 已补[`orbit-load`](api/load.md)有界受理负载工具及24次/1000次隔离样本,见[受理报告](reports/phase-6-load.md)。新增独立[`orbit-exec-load`](api/execution-load.md),通过真实Worker、任务结果和尝试历史核对,提供短/混合/中长任务的受理、排队、授权执行及完成耗时分布;具体环境、原始JSON和失败分母见[执行测量报告](reports/phase-6-execution-load.md)。新增[`orbit-workflow-load`](api/workflow-load.md),用本次发布版本的双分支并行流程,逐个核对不同任务、唯一尝试、来源、精确输出与本地调用;24/100实例及24实例截止负例已重新构建回归并绑定源码/二进制哈希,见[流程测量报告](reports/phase-6-workflow-load.md)。新增[`orbit-schedule-load`](api/schedule-load.md),已完成24/128次定时集中触发与24次计划量的截止负例,保存实际分母、唯一任务/尝试、来源与暂停收尾证据,见[定时测量报告](reports/phase-6-schedule-load.md)。Go 1.27.1 模块级门禁、MySQL 存储集成、关键 SDK/Orbit 进程故障组、24个可运行 SDK 示例真实服务串跑和 result-inbox/task-outbox 真实业务集成已复跑通过。已补[长期积压与资源曲线样本](reports/phase-6-backlog.md):32×8 共256个触发点,在1个Worker/容量1和180秒截止下保留173个成功、83个未核验任务,并以独立数据库读取记录等待积压曲线;该单节点样本不替代目标拓扑容量。SDK受控重连风暴及[真实慢消费者背压](reports/phase-6-slow-consumer.md)已补边界回归;下一步补指标采集对照、长期存储增长、跨节点重连与目标数据库拓扑容量。 6. 已补[隔离备份恢复演练](api/backup-restore.md):源库和恢复库均为一次性 MySQL 容器,逻辑备份恢复后核对迁移账本、核心记录数量、固定索引和零外键;证据见[恢复报告](reports/phase-6-backup-restore.md)。该演练不替代生产备份介质、复制切换、跨版本恢复或 RPO/RTO 验收。 7. 已补[A18 数据库短暂不可用恢复演练](api/db-recovery.md):readiness 在数据库停止期间返回 503,同卷恢复后返回 200,并用原权限范围继续受理任务;证据见[数据库恢复报告](reports/phase-6-db-recovery.md)。该演练不替代主从切换、复制确认、跨故障域或 RPO/RTO 验收。 diff --git a/docs/19-capacity-model.md b/docs/19-capacity-model.md new file mode 100644 index 0000000..a0ada06 --- /dev/null +++ b/docs/19-capacity-model.md @@ -0,0 +1,131 @@ +# Orbit 容量模型与验收方法 + +版本:0.1 · 2026-09-20 +状态:容量推导方法;不是生产容量结论 + +本文把“企业数量”转换为可测的任务、流程、事件、连接和数据库负载。所有示例数字都是演算用假设,不能直接作为上线承诺。生产容量必须用目标硬件、目标 MySQL 拓扑、实际保留周期和隔离业务数据重新测量。 + +## 1. 输入参数 + +容量评估至少固定下面这些输入,并将它们保存到每次负载报告的环境 JSON 中: + +| 符号 | 含义 | 说明 | +| --- | --- | --- | +| `E` | 企业总数 | 用于规模推导,不等于连接数或队列数 | +| `a` | 日活跃企业比例 | 0 到 1,按实际业务日历取值 | +| `t` | 每个活跃企业每日提交任务数 | 任务提交和计划触发分开统计 | +| `B` | 每日业务窗口秒数 | 夜间批处理必须单独建峰值窗口 | +| `p` | 峰值放大倍数 | 由历史曲线或集中申报窗口确定 | +| `d` | 一次任务平均执行秒数 | 同时提供 p50/p95/p99,不用单一平均值替代长尾 | +| `r` | 平均总尝试次数 | 包含自动重试,不包含人工关联新任务,后者单独计数 | +| `s` | 每个任务产生的持久化事件数 | Pulse、Weave、结果交付分别统计 | +| `h` | 平均任务/结果/事件有效字节数 | 只计业务字段,索引和页开销另加 | +| `R` | 保留天数 | 幂等、审计、执行历史、结果交付不能共用一个未经评审的周期 | +| `c` | 每个 Worker 连接的有效并发 | 由容量、心跳、续租和处理器延迟共同决定 | + +还要记录流程实例数、每实例步骤数、并行度、等待实例比例、信号速率、定时计划数、触发分布、查询轮次和外部请求峰值。单独记录 `E` 而不记录这些输入,不能推出服务器规格。 + +## 2. 基础推导 + +每日可靠受理量为: + +```text +Qday = E × a × t +``` + +业务窗口内的平均受理速率和设计峰值为: + +```text +λavg = Qday / B +λpeak = λavg × p +``` + +任务执行并发的近似下界为 Little 定律: + +```text +Wactive ≈ λpeak × d +``` + +实际容量还要加上租约续租、重试、流程内部任务、定时集中触发和恢复补偿的余量。应分别计算: + +```text +Wtotal = Wbusiness + Wretry + Wworkflow + Wschedule + Wrecovery +``` + +Worker 数量的初步估计为: + +```text +Nworker ≥ ceil(Wtotal / c) × safety_factor +``` + +`safety_factor` 只是规划余量,不能替代节点故障、滚动升级和积压清空实验。Worker 的连接数应按 `Nworker × 每实例连接数` 计算,并与 MySQL 最大连接、服务端连接池和 WebSocket 文件描述符上限分别核对。 + +## 3. 数据库写放大与存储 + +任务量不是数据库写入量。每个任务至少可能涉及任务主记录、幂等身份、尝试、执行历史、状态事件、审计和结果交付;Weave 还会增加实例、步骤、等待、信号、内部结果和时间线记录。应按实际状态路径统计行数: + +```text +RowsPerTask = task_rows + idempotency_rows + attempt_rows × r + + event_rows × s + audit_rows + delivery_rows +``` + +每日新增行数和保留期行数为: + +```text +RowsDay = Qday × RowsPerTask + schedule_rows + workflow_rows + inbox_rows +RowsRetention = RowsDay × R +``` + +存储估算至少拆分数据页、二级索引、Undo/Redo、临时空间、备份和复制日志: + +```text +DataBytes ≈ RowsRetention × (h + row_overhead + index_overhead) +``` + +`row_overhead` 和 `index_overhead` 必须从目标 MySQL 版本的真实表、索引和字符集测得。不能用 Go 结构体大小或 JSON 字符串长度替代 InnoDB 页空间。未知效果、未确认交付、未终结流程和审计记录不能为了缩小容量而提前清理。 + +## 4. 演算示例(非验收) + +下面只说明推导方法:假设 `E=1,000,000`、`a=0.10`、`t=20`、`B=36,000` 秒、`p=6`,则: + +```text +Qday = 2,000,000 个任务/日 +λavg ≈ 55.6 个任务/秒 +λpeak ≈ 333.3 个任务/秒 +``` + +如果一次任务平均总执行时间为 2 秒,单看业务任务会得到约 667 个同时执行任务;若重试、流程、定时和恢复再增加 60% 的并发余量,则规划值约为 1,067。这个结果只用于确定下一轮实验规模,不能推出节点数量、MySQL 规格或可用性。 + +若每个任务路径暂按 8 行、每行数据及索引平均 2 KiB 的假设演算,30 天会得到约 480,000,000 行、约 916 GiB(约 983 GB 十进制)的逻辑页空间;该假设对实际 JSON、索引、压缩、历史和业务结果极其敏感,必须以真实采样替换。 + +## 5. 测试矩阵 + +每个目标版本至少执行以下六组,并保存参数、源码/二进制哈希、MySQL 版本、拓扑和资源曲线: + +1. **短任务基线**:空处理器或固定极短处理器,测框架受理、排队、派发和完成开销。 +2. **混合执行**:短、中、长任务按生产比例混合,包含续租和有限重试。 +3. **集中触发**:定时计划在同一窗口到期,核对触发唯一性、计划进度和积压。 +4. **流程推进**:顺序、分支、有限并行、等待和信号混合,逐个核对内部任务、结果和版本。 +5. **长期积压**:固定 Worker/容量下持续输入,记录等待曲线、锁等待、磁盘、内存和积压清空时间。 +6. **故障恢复**:服务节点、Worker、WebSocket、数据库连接在不同切点退出,记录重新授权、未知结果、恢复扫描和数据核对时间。 + +负载工具使用 [任务执行测量](api/execution-load.md)、[流程测量](api/workflow-load.md) 和 [定时测量](api/schedule-load.md)。每组都要记录 p50/p95/p99、成功和未核验分母;任何截止或资源不足导致的未核验项都不能计入成功吞吐。 + +## 6. MySQL 与部署边界 + +- 状态转换、幂等提交、租约和恢复以 MySQL 主库为权威;只读副本不能承载需要最新状态的核对或控制操作。 +- 复制确认、主从切换、RPO/RTO、备份介质和跨故障域部署必须在目标拓扑实测。一次性单节点容器只证明功能和故障注入逻辑。 +- 服务端节点可以横向扩展,但必须测量锁等待、扫描批次、连接池、复制延迟和节点间重连;多节点数量不能从单节点吞吐线性外推。 +- 不引入 Redis、消息队列或独立协调服务作为容量假设。若未来改变依赖范围,必须重新评审数据权威、故障边界和运维责任。 + +## 7. 通过条件 + +容量报告只有同时满足下面条件,才能进入生产发布评审: + +- 目标峰值下,受理、派发、流程推进和结果交付的 p99 在已批准的延迟预算内; +- 故障组仍保持幂等、审计、未知效果核查和可恢复,未核验项有明确处置; +- 数据库 CPU、锁等待、连接、磁盘、Redo/Undo、复制滞后和备份窗口均保留经评审的余量; +- 节点滚动升级、单节点故障和主库切换后的积压能在批准的恢复窗口内清空; +- 负载和故障结果绑定不可变提交、工具链、迁移版本和参数,报告中明确未覆盖项。 + +当前仓库已有隔离单节点样本和 Go 1.27.1 的可运行场景证据,但没有目标硬件、复制切换或百万企业规模的生产容量结论;这些项目仍见 [生产验收](05-production-acceptance.md) 和 [首版交付清单](release-checklist.md)。 diff --git a/docs/README.md b/docs/README.md index 882af6e..0c8556a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,7 @@ | [06 Weave 流程设计](06-workflow-spec.md) | 已确认的首版功能、研发定义发布、持久化等待、有界查询、暂停恢复与模块协作 | | [07 数据模型](07-data-model.md) | 当前 Go 实体、数据库约束、存储约定与实现边界 | | [08 持续开发计划](08-development-plan.md) | 开发、测试回归、阶段验收与最终交付目标 | +| [19 容量模型](19-capacity-model.md) | 企业规模到任务、流程、数据库与连接负载的推导及生产验收方法 | | [09 可靠结果订阅](09-result-subscription-core.md) | 提交水位、冻结结果与可靠交付 | | [10 Weave决策与交付](10-workflow-engine-core.md) | 有限步骤决策和内部结果Inbox | | [11 Weave实例受理](11-workflow-admission.md) | 固定版本、初始图和首批任务事务 | diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 8c27309..c3a5351 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -39,7 +39,7 @@ | 项目 | 必须提供的证据 | 状态 | | --- | --- | --- | | 受理、派发、流程推进和恢复吞吐 | 固定硬件、数据量、任务/流程混合模型,p50/p95/p99和资源曲线 | 已有受理样本、[真实Worker短/混合/中长执行样本](reports/phase-6-execution-load.md)、[Weave双分支流程样本](reports/phase-6-workflow-load.md)及[定时集中触发/积压曲线样本](reports/phase-6-backlog.md);目标硬件资源曲线、生产容量和HA仍未验收 | -| 100万+企业规模推导 | 租户、队列、连接、事件、索引和保存周期的容量模型 | 未验收,不能由租户数直接推导 | +| 100万+企业规模推导 | [容量模型](19-capacity-model.md):租户、队列、连接、事件、索引和保存周期的参数化推导 | 已建立计算方法和演算样例;目标业务数据、硬件、拓扑和生产容量仍未验收,不能由企业数直接承诺 | | MySQL 复制、切换、RPO/RTO | 目标拓扑上的实际切换、复制确认、恢复点和恢复时间 | 未验收 | | 慢消费者、重连风暴、磁盘和锁等待 | 受控故障负载及积压清空证据 | SDK 受控连续断线和真实 HTTP/WebSocket 容量1慢消费者已回归(见[重连报告](reports/phase-6-reconnect-storm.md)、[慢消费者报告](reports/phase-6-slow-consumer.md));跨节点风暴、磁盘和锁等待未验收 | | 跨版本 SDK/服务端 | 至少一个正式旧标签与候选版本的双向矩阵 | 当前仓库无正式标签,未验收 |