外观
设计决策总览
这一篇回答一个问题:这个平台为什么长成现在这样。每个重大选择都按同一结构展开:要解决的问题是什么、备选方案在真实维度(性能、生态、MSRV、维护成本、供应链)上如何比较、选了什么、为此付出什么代价、代价如何缓解、最终落在哪些代码落点上。已写成正式裁决记录的决策收在 ADR 体系(索引与摘要见ADR 索引),其余决策登记在设计文档集的架构决策记录章节;本站在两者基础上做导航与推理。
决策地图
| 主题 | 页面 |
|---|---|
| 全部技术栈的选型、版本与 feature | 技术选型总表 |
| 为什么是 Rust 而不是 Go 或 Java | 为什么是 Rust |
| 为什么 Istio 只用 ambient 的 L4 能力,L7 治理留在应用层 | 为什么是 Istio ambient |
| 为什么不是自研 mesh、Kafka、每服务独立数据库集群等备选架构 | “为什么不是”系列 |
| 正式 ADR 的索引与撰写规范 | ADR 索引 |
服务边界与职责约定(十服务——九数据面加告警桥接——的职责表、平台 crate 分工、依赖方向红线)不在本篇重复,权威文本是架构收敛与职责约定文档,站内导读见架构手册。
裁决优先级
交付物料对事实冲突的裁决顺序是固定的:
text
REQUIRE.md(需求事实源)
> 设计文档集(入口为总体架构文档)
> 历史归档快照(仅参考)设计文档集里的每条决策都带状态标记,含义固定:确认表示用户已拍板,默认表示沿用推荐默认值,REQUIRE 表示由需求文档驱动的新决策,取代表示被后续决策覆盖(原编号保留可追溯)。代码与文档冲突时以代码为准。本站所有页面的表述都遵循同一原则:版本号、feature 名、默认值逐个对照过根 Cargo.toml 与各服务源码;推断性内容(物料未留下正式裁决记录的部分)会显式标注为分析推导,不冒充原作者的决策记录。
关键决策速查
决策编号体系定义在设计文档集:D-XX01 形式的编号是需求驱动或用户确认的架构决策,后接 B 或 A 的(如 D-TR01-B)表示该决策下的某个具体方案分支。下表摘录影响面最大的决策,每条编号后紧跟一句话决策内容。
| 编号 | 决策内容 | 权威文本 |
|---|---|---|
| D-DE01 | 平台拆为五个微服务(iam、metadata、orchestrator、metering、gis)加网关与 operator | 总体架构文档 |
| D-MA01 | 多租户采用共享表加 tenant_id 列,RLS 兜底隔离 | 同上 |
| D-TR01 | Tantivy 为全文检索强制主引擎,PG tsvector 降为可选辅助;方案分支 D-TR01-B 锁定 tantivy =0.22.1 | 同上 + ADR-D-TR01-B |
| D-EV01 | 事件基础设施选 NATS JetStream,Kafka 适配器列为可选扩展 | 同上 |
| D-WS01 | WebSocket 是一等公民:网关进程内独立 ws 层,目标 10 万并发连接 | 同上 |
| D-PLG01 | 插件化取三层形态:编译期 trait 注册、外部 gRPC 插件进程(plugin.v1 契约)、rhai 沙箱脚本 | 同上 + ADR-D-PLG01 |
| D-RLM01 | 对象存储具备版本控制、生命周期与 STS 临时凭证;方案分支 D-RLM01-B 锁定 aws-sdk-s3 对接 RustFS | 同上 + ADR-D-RLM01-B |
| D-CB01 | 授权内核自研,保持 casbin 语义等价(因 rhai feature 冲突,casbin-rs 不可共存) | ADR-D-CB01-A |
| D-AUT01 | 外部身份源分期接入:OIDC 一期先行,LDAP 二期,MFA 三期 | ADR-D-AUT01 |
| D-DB01 | 数据库为 PostgreSQL 17,Patroni 高可用,pgBackRest 备份 | 总体架构文档 |
| D-CP01 | 容量按大规模基准:网关集群 5 万 QPS、PG 单实例 2 万 TPS、10 万 WebSocket 连接 | 同上 |
| D-SEC01 | 全平台默认拒绝,仅显式放行例外 | 同上 |
| D-SCH01 | 编排内嵌脚本走 rhai 沙箱,上限 API 必须可用 | 接口编排引擎设计文档 |
| D-INF01 | 基础设施自建 IDC、云无关技术栈;多云诉求按可移植性满足,跨云多活不立项 | 部署运维与灾备设计文档 |
| D-MC01 | 多云等于可移植性:Helm profile(idc/aws/aliyun),无厂商专有服务依赖 | 同上 |
| D-PLN01 | 计划基线 12 个月、10-15 人;人力不足 5 人时启用 24 个月应急轨 | 分阶段实施计划 |
历史上被取代的决策同样留痕:D-FTS01(PG FTS 起步)被 D-TR01 取代;D-TM01(团队 1-2 人)被 D-PLN01 取代。取代机制说明所有决策都可追溯,不会静默变卦。
架构形态速览
决策落在一个固定的服务集合上。九个部署单元与职责(权威职责表见架构收敛与职责约定文档):
| 部署单元 | 职责一句话 |
|---|---|
| svc-gateway | 北向入口:认证、限流、配额、静态与动态路由、审计、计量边缘聚合、WebSocket 订阅面 |
| svc-iam | 身份与权限:登录令牌、AppToken、RBAC 与 ABAC 决策(ResolveRowScope 下推行列权限) |
| svc-metadata | 元模型与动态数据:DDL 协议、版本演化、查询构建、版本中心、附件中心 |
| svc-orchestrator | 接口编排:流程定义与实例、事件溯源、补偿、定时器与 cron |
| svc-metering | 资源计量:两级计量、配额、阶梯计价 |
| svc-gis | 空间搜索与瓦片:空间查询、混合检索、矢量瓦片、快照分发消费侧 |
| svc-gis-tantivy-indexer | 全文索引单写者:消费索引操作流、commit、快照发布(leader election 保证单写者) |
| svc-operator | 常驻运维任务:聚合滚加、retention、巡检、审计哈希链校验 |
| svc-all-in-one | 单机一体化形态:上述全部装配进一个进程 |
两种形态共用同一批服务代码:云化形态九个 Deployment 各自独立伸缩,单机形态一个进程加回环互访(装配覆写机制见配置装载机制)。这个“一套代码两种形态”是多个决策(网关治理在应用层、事件总线 mem 与 nats 双后端、存储 mem 与 local 双后端)共同的出发点。
性能预算与部署基线(决策的验收面)
决策不是孤立的口号,它们钉在同一组数字上。
延迟预算
(REQUIRE 2.3.1 原值,口径定义与预算分解见总体架构文档的性能预算章节)延迟预算:
| 操作 | P50 | P99 | P999 |
|---|---|---|---|
| 简单查询(主键点查,缓存命中) | <5ms | <10ms | <50ms |
| 复杂查询(列表、聚合、混合搜索) | <50ms | <200ms | <500ms |
| 写操作(单行,含乐观锁) | <10ms | <50ms | <100ms |
| 权限检查(内存决策) | <1ms | <5ms | <10ms |
| 流程编排(同步触发至首步完成) | <100ms | <500ms | <1s |
| GIS 查询(空间或混合) | <100ms | <300ms | <800ms |
吞吐与并发:API 不低于 5 万 QPS(16C/64G 测试条件),数据库不低于 2 万 TPS(PG 单实例,简单写入路径),消息不低于 10 万 msg/s(JetStream 承接),WebSocket 并发连接不低于 10 万。资源利用率红线:CPU 不高于 70%、内存不高于 80%、网络不高于 60%、存储不高于 80%。
部署规格基线(起步副本与 HPA 上限,详表见总体架构文档的部署规格章节):网关 HTTP 面 4 至 20 副本、ws 层独立 Deployment 4 至 16 副本(按连接数伸缩)、metadata 3 至 16、其余服务 2 至 8、tantivy indexer 1 写者加 1 热备(leader election 保证单写者)、operator 2。这组数字是上面所有技术选型的共同约束:选型页里的每个“为什么”最终都要在这张预算表前站得住。
需求如何被追踪与豁免
决策不是单向服从需求。REQUIRE 的每一条条款都映射到设计位置,满足或偏差都登记在需求追踪矩阵;有意识地按另一种口径解释的条款,登记为“解释性偏差”而不是悄悄改需求。现成的例子:D-ME01(两级计量模型)与 REQUIRE 3.4 把配额放进 JWT 的示例存在口径差,登记为解释性偏差;REQUIRE 6.1 的“单实例 5 万 QPS”按网关轻路径解释,事务型路径的物理上限差异同样登记。
偏差登记之外还有两层保障机制(定义在生产保障与风险登记文档):证据等级(对每条生产声明标注证据强度)与风险登记册(R1 到 R11,逐项含缓解动作)。这套机制回答的问题是:当文档说“已满足”时,凭什么信。
决策的事实从哪来
本篇各页引用的事实有四类来源,可靠性从高到低:
- 代码:根
Cargo.toml与Cargo.lock的版本与 feature、各服务 config.rs 的默认值、Helm chart 模板、CI 门禁。代码是最终事实。 - 正式 ADR:六份(对象存储路线、tantivy 版本锁定、授权内核、身份源分期、插件宿主、OTLP 双轨),每份含实测数据与否决方案对照,摘要见ADR 索引。
- 设计文档集:18 个设计文档(编号 00-11 与 13-18,编号 12 从未设立),是需求到设计的权威映射。
- 需求事实源
REQUIRE.md:技术栈下限、性能预算、团队与工期约束的最终出处。
站内配套阅读:架构手册 讲结构是什么,实现状态矩阵 讲哪些已落地,本篇讲为什么这样定。
本篇的写作约定
本篇各页遵循统一结构:先摆要解决的问题,再给备选方案在真实维度上的对比表(性能、生态、MSRV、维护成本、供应链,按决策相关的那几列),然后是选择与理由、代价与缓解,最后落到站内对应页与代码落点。两类内容有显式标记:直接陈述的事实都给组件落点或文档出处;没有正式裁决记录、由现状反推的部分,标注“分析推导”。加粗只用于表格列头与极少数关键结论,论证靠表格加结论段完成,不靠语气词。
数字类事实(版本号、默认值、路径数、副本数)全部对照代码核实过;文档断言与代码冲突时,页面按代码写,并在架构证据链口径下处理差异。
阅读路径建议
按角色选入口。新加入的开发者从技术选型总表开始,它给出全平台的依赖地图与“为什么锁这个版本”的共同模式;再读为什么是 Rust 理解语言约束的兑现与代价。做部署与运维的读者直接看为什么是 Istio ambient,它讲清网格边界与 Helm 模板的对应关系,配合部署文档使用。做架构评审或写新 ADR 的读者读ADR 索引,规范与六份实例的摘要都在那里。想质疑某个现状(为什么不用 Kafka、为什么单数据库集群),“为什么不是”系列按备选逐条回答,每条都附现状证据与已知代价。
对决策本身有异议时的正确动作:先查本页速查表里对应编号的权威文本,再看代码现状是否已偏离文档;若偏离,按裁决优先级以代码为准并考虑更新文档或按 ADR 撰写规范起草新 ADR 推翻旧决策。