外观
概念总览(从零理解)
本页是概念篇的入口。这一篇回答一个问题:这套平台由哪几块概念拼起来, 每块各自解决什么麻烦。读完它你应该能拿着地图往下走,知道下一步读哪页、 那页会讲清什么。这里假设你不需要任何微服务平台或 Service Mesh 的背景, 每页开头都从非专业读者能懂的动机讲起,再逐步进入机制细节。
学习路径
建议按顺序读。前两页建立全局图景,后面九页每页讲透一个概念域, 页与页之间出现的交叉引用会指回具体页面的具体小节。
text
what-is-rustsvc 平台底座是什么,交付物有哪几类,边界在哪
multi-tenant 租户、主体与信任链:数据隔离如何被强制执行
metadata 元模型与动态数据:建模如何变成运行时能力
orchestration 持久化编排:跨服务长流程为什么不会丢、不会重
metering 计量与配额:谁在用、用了多少、超了怎么办
gis 空间检索与矢量瓦片:两个引擎如何协作
service-mesh 服务网格:Istio 做什么、平台自己做什么
admin-authz 管理面授权:从平台管理员角色到 iam 策略裁决的灰度
identity-sources 身份源:口令之外,OIDC 联邦登录如何接入
plugin-host 插件宿主:外部能力如何被登记、放行、调用与降级读完概念篇,接下来可以去两处:要动手跑通整个平台,读第一次请求; 要看更严格的分层与组件口径,读架构总览。
五分钟版(先给结论)
企业应用有一类成本与业务无关,却每个系统都要重付一遍:身份与权限、 多租户数据隔离、动态表单数据、审批流、用量计量、审计合规。这些地基 质量参差是常态,租户隔离与审计尤其容易出事。rust_svc 用纯 Rust 把这块 地基做成可复用的平台底座,让业务开发者只写业务。
落到机制上是四句话:
- 业务开发者做声明式建模(不写建表 SQL),得到的是自带租户隔离的 物理表,隔离由数据库行级安全强制,不依赖应用代码自觉;
- 一切北向请求从唯一的 svc-gateway 进入,认证、限流、配额、审计、 计量在中间件链里自动发生,业务服务拿到的上下文是网关重建的可信上下文;
- 跨服务、跨小时的长流程交给持久化编排引擎,宕机后凭事件日志续跑, 副作用靠幂等键做到恰好一次;
- 云化形态运行在 Kubernetes 与 Istio ambient 之上,但 Istio 只承担 L4 传输加密与工作负载准入,治理逻辑全部在应用层,单机一体化形态 没有网格也能跑出同一套行为(边界详见 service-mesh)。
概念地图
六个概念域不是并列的孤岛,数据与控制的流向把它们连成一张网。 下图是骨架版,箭头表示主要的数据或控制依赖方向:
读图三个要点。第一,网关是唯一的北向入口,所有对外流量经它进出, 信任链在那里重建(multi-tenant)。第二,服务间协作 大量走事件总线而非点对点调用:路由表、配额快照、计量窗口、索引变更 都是广播消费,这让消费方可以崩溃重启而不影响生产方。第三, PostgreSQL 是几乎全部逻辑数据的事实源,五库各自 RLS 强制。
三个反复出现的设计主题
概念篇各页内容各异,但有三条设计思路贯穿全书。先在这里点名, 后文每页都会撞见它们。
事实源与派生物分离。一份逻辑数据只有一个权威存储(PostgreSQL, 个别场景是对象存储),其余全部是派生物:Tantivy 全文索引派生自 PostGIS 事实源,网关动态路由表派生自编排触发器,网关配额快照派生自 metering 的配额规则。派生物允许短暂滞后,但必须可观测、可重建。 这解释了为什么项目里到处是事件广播与快照替换,而不是双向同步。
声明式配置先编译后执行。元模型把建表编译成 DDL,编排 DSL 编译成 步骤图,瓦片配置在装载期做 z 级折叠编译。共同点是把校验尽量前移到 提交时刻(编译期拒绝非法输入),执行期只跑确定性的、可单测锁定的 产物。你在各页会看到大段的拒绝项清单,那是这个主题的具体形态。
fail-closed 优先。任何一层拿不到确定结论时选择拒绝而不是放行: RLS 变量缺失时数据库返回零行,认证面故障时写请求返回 503 而不是 降级为未认证放行,全文索引快照缺失时查询返回 503 而不是静默少结果。 可用性让位于正确性,是这套底座反复做的取舍。
按角色选读
不同角色可以裁剪路径:
- 后端业务开发者:multi-tenant、metadata 必读,orchestration 的 触发器与模板两节、metering 的配额一节按需;
- 平台与运维工程师:八页全读,service-mesh 与部署侧文档衔接;
- 技术评审与架构对接方:what-is-rustsvc 的边界一节、service-mesh 的两张清单(用了与没用)、本页的概念地图通常够支撑一轮评审;
- 新入职成员:按顺序通读,配合第一次请求 动手走一遍,比只读文档有效得多。
常见误读澄清
三个高频误读,先在这里拆掉:
误读一:有网关就不用数据库隔离了。网关认证挡住未认证流量, 但应用代码的 bug(漏带租户条件)网关管不着,所以还有 RLS 这第二道 数据库层防线。两道防线针对不同的失效模式,缺一不可。
误读二:计量是事后统计,不影响请求。配额执行在网关的请求路径上 (并发段与日额度段),超限请求会被延迟或拒绝。计费是事后的, 控制是事中的,两件事共用一套用量数据。
误读三:Istio 负责服务间安全,平台不用操心。本项目云化形态里 Istio 只做 L4 加密与准入,认证、授权、租户隔离全部在应用层。单机 一体化形态甚至没有网格,治理照样完整工作。边界详见 service-mesh。
阅读约定
本站严格区分三类内容,概念篇同样遵守:
- 项目已实现能力:带 已实现 徽章, 或正文明确说明当前状态;
- 架构概念背景(如 Istio 的通用能力介绍):标注为概念背景, 不代表本项目使用;
- 生产建议:标注为建议,不等于当前已内置。
概念篇引用决策编号时(形如 D-MA01、D-TR01),编号统一登记在设计文档集 的架构决策记录一节,那里可以查到每条决策 的当前状态(有效、被取代或带偏差登记)。正文中出现编号时会附带一句 它决定了什么。
本篇不覆盖什么
概念篇讲心智模型,以下主题有专门章节,不要在这里找:
- 怎么装、怎么跑:部署与启动见部署与 本地开发;
- 运维与排障:告警、指标、故障处置在可观测性 与排障各页;
- 错误码、事件主题、环境变量等查询型内容:见 reference 目录;
- 代码结构与贡献流程:见架构手册与开发指南。
判断标准很简单:概念篇回答为什么这样设计,别处的文档回答怎么操作。 概念页允许出现单个自包含的配置片段或请求样例——那是机制讲解的 具体化;一旦开始出现成段的命令输出、多步骤操作流程与参数对照表, 内容就该搬去 guide 或 operations,而不是留在概念篇。