研究报告SaaS 与云原生平台

SaaS 与云原生平台架构：从多租户到生产治理

这篇把 Bite、CosX、K12、Sure、Xeni Legal 和云服务架构材料整理成 SaaS 与平台工程方向的知识页。它关注一个问题：平台怎样在业务变化、租户隔离、安全治理和生产稳定性之间保持可演进？

比起罗列技术栈，这一页更想把几段真实经历里反复出现的架构判断连成线：多租户隔离不是一条 SQL 条件、认证不等于授权、权限计算要下沉、服务发现要服从生产拓扑、本地开发体验是云原生落地最大的摩擦点、交付要可审计可回滚。

SaaS 的第一性问题

SaaS 架构的核心不是“把系统部署到云上”，而是持续回答几个基础问题：

  • 每一次数据访问如何自动限定在当前租户范围内？
  • 租户、用户、组织、角色、权限和资源之间如何建模？
  • 不同租户的配置、套餐、功能开关和集成差异如何表达？
  • SSO、OAuth2、OIDC、MFA 和内部授权如何协作？
  • 系统怎样在快速交付时仍然保持可审计、可回滚和可观测？

Bite 阶段的材料把这些问题集中到多租户数据隔离、权限体系、动态配置和 SSO 方案上；到了 CosX 的通用 Agent 平台，同一套判断被落成了 Gateway / Identity / Workspace 三件套。

多租户数据隔离

多租户隔离的本质是：每一次数据库操作都不能越过当前租户边界。

一种可推广的轻量思路是：借助 ORM 或框架内置的过滤能力 + AOP，做“零侵入”的租户过滤，而不是让每个 repository 和 service 手写租户条件。它的价值在于显著减少重复代码，也降低“忘记加 tenantId”的风险——把租户这个横切关注点集中到框架层和网关层，而不是散落在业务代码里，是控制复杂度的关键。

但多租户不只是一条 SQL 条件。真正的平台能力还要覆盖：

  • 租户生命周期：创建、停用、恢复、销毁。
  • 资源初始化：默认角色、配置、存储空间、集成密钥。
  • 租户级审计：谁访问了什么资源，什么时候发生了变化。
  • 数据迁移：租户字段补齐、历史数据校验、跨区域迁移。
  • 隔离策略：共享库、独立 schema、独立数据库或独立环境的取舍。

还有一类容易被忽略的场景：跨租户共享数据。当租户之间存在分销、代销这类协作关系时，一方产生的订单、收款、转账需要按规则被另一方看到。这不能靠“把隔离边界加宽”来解决，而要在隔离规则之外单独建模一层“可见性授权”——隔离回答“默认谁看不到谁”，可见性授权回答“在什么协议下例外地互相可见”。把这两件事混在一起，是多租户模型最常见的失控点。

身份、授权与 Gateway

Bite 的 SSO 材料里有一个重要边界：外部身份认证不等于内部权限授权。

LP portal 可以允许 Google 等外部账号登录，GP portal 可以接入第三方 AD 或企业身份源，但用户登录成功后，仍然必须回到应用自己的授权模型里判断能看什么、能做什么。认证（你是谁）与授权（你能做什么）要解耦。

认证模式本身也要分场景：Web 端用 OAuth2 Authorization Code（叠加 OIDC）、服务间调用用 Client Credentials、社交与企业登录叠加 OIDC 联邦身份。网关则做无状态 JWT 校验 + 撤销令牌的缓存同步，把权限计算下沉，而不是在每个下游服务里各自实现。

因此 Gateway 的职责不只是转发请求。它至少要承担：

  • JWT 验证和 revoked token 缓存同步。
  • Token 解析和用户上下文注入。
  • 与授权服务协作完成权限判断。
  • Rate limit、API versioning、参数校验、payload size limit。
  • CORS、缓存、路由和响应治理。

一套可继承的权限模型

Bite 的投资人档案权限体系提供了一个可以反复借用的结构：资源树 + 主体树 + 操作级权限。

  • 资源侧按树状组织（例如“产品 → 营销 → 文档”这样的层级）；主体侧也按树状组织（例如“集团 → 渠道 → 市场”这样的层级）。
  • 每一对“主体—资源”上挂操作级权限（无权限 / 可见 / 可见且可下载），并带有效期——权限可以“到期自动收回”。
  • 权限支持继承、在多条路径冲突时合并取更严格值、以及链式校验（父级链路上任一环节无权限，则整体无权限）。
  • 文件树类资源与非文件树类资源用两套不同的构建算法。
  • 关键是权限计算集中在一处下沉的权限服务里，主体来源与资源来源各由对应服务提供，网关只消费结果。

到了通用 Agent 平台阶段，这套判断进一步落成三层：

  • Identity 只做认证：基于授权服务器的 OAuth 2.1，叠加 MFA / Passkey(WebAuthn) / 邮箱 OTP，以及社交与企业联邦登录、动态客户端注册。
  • Gateway 做 BFF 与粗粒度鉴权：无状态 JWT 校验、令牌黑名单、工作区级 RBAC、限流与 lb:// 路由、分布式追踪上下文注入。
  • Workspace 管租户内的层级权限（Owner → Admin → Member → Advisor → Assistant）、邀请系统与按工作区的 AI 模型策略。

为访客与共享访问场景，还扩展了一种自定义的 Share-Code 授权模式——它和 Bite 时代“按有效期收回权限”的思路同源：把“临时、可撤销、可过期”的访问当作一等公民来设计，而不是事后打补丁。

这类边界也适用于 CosX、K12 和 Sure：平台入口要统一，业务服务内部要保持清晰职责。

领域建模与历史包袱：投资人档案案例

多租户和权限之外，SaaS 平台最难的往往是领域模型的历史包袱。

Bite 的投资人档案服务是一个典型样本：它历史上横跨两个数据库，把“人 / 机构”“档案资料”“认购档案”三类关注点混在同一套不断迭代的 ER 里，实体关系错综成“蜘蛛网状”。

处理它的方法不是推倒重写，而是先做认知分层，再决定要不要动表结构：

  • 用 DDD 把它重划成几个子域（人与机构 / 文档 / 档案），画出“蜘蛛网状”ER 图，讲清复杂度是从哪一层长出来的。
  • 对照历史版本理解演进：早期版本用多张分散的文档表（地址、银行信息、证件等各一张），后来泛化为一个统一的文档实体——这是已经发生的历史演进，而不是拍脑袋的重构决策。
  • 结论先给到“认知”而非“动刀”：把服务先讲明白，团队才有共识去判断哪些该合并、哪些该泛化。

这条经验可以推广：面对一个纠缠的遗留领域模型，第一步是用子域和历史版本视角把它讲清楚，而不是急着重建。

服务发现与本地开发工作流

云原生落地里，一个反复出现的判断是：本地开发体验是云原生落地最大的摩擦点。

Bite 阶段做过一次一手判断：基于注册中心的服务发现，在本地开发环境难以复现、云原生程度也不够；K8s 原生 Service 把负载均衡放到服务端，配合 Spring Cloud Kubernetes 更贴近生产拓扑。于是牵头验证并推广了一套本地工作流：

  • JIB 分层构建，只重建发生变更的层。
  • Skaffold 自动化本地的构建—推送—部署。
  • Cloud Code + IDE 打通本地到集群的开发闭环，自建本地镜像仓库提速。
  • 本地环境去掉对注册中心的依赖，改用 K8s Service 做服务端负载均衡。

但迁移是有风险的，所以结论是渐进而非一刀切：在本地环境的复现问题解决之前，生产侧继续用注册中心仍然合适，服务发现方案逐步评估。对分布式事务同样保持克制——它未必适合当前的微服务拓扑，因此没有急于在网关层引入，而是留作后续评估。调试灰度路由时也踩到过真实的坑：metadata 里 version 字段为空、灰度策略本不该触发，而灰度过滤器可能破坏客户端负载均衡——这类隐患要在下一个迭代里正面修，而不是绕过。

同一套“降低本地复现成本”的方法论，可以在不同技术栈之间复用：无论是 K8s 栈，还是 docker-compose 加注册中心的栈，做法都是一致的——把配置、数据库结构与种子数据导出为仓库内可复现的目录，按依赖顺序分阶段启动服务，并定义分层的本地验收标准（从最小可用到接近生产）。技术选型可以随平台的历史包袱不同，但“让本地能一键复现”的判断不变。

云原生生产治理

CosX 和云服务架构材料把关注点推进到生产治理：

  • Kubernetes、AKS、Kustomize 和 ArgoCD 负责声明式交付。
  • NetworkPolicy、Workload Identity、Key Vault 和 SecretProviderClass 负责安全边界。
  • HPA、resource requests/limits 和队列化 worker 负责容量弹性。
  • Prometheus、ServiceMonitor、日志、Trace 和告警负责可观测性。
  • Blue/Green、RC、release tag 和 GitOps promotion path 负责发布治理。

这里的关键不是列技术栈，而是让生产状态可解释。GitOps 仓库应该是 desired state 的来源；生产事故应该能从日志、指标、事件和发布记录里复盘；资源配置应该能从 staging 逐步验证到 production。

交付治理：主干开发与门禁

平台能不能快而不乱，取决于交付纪律。

  • 主干开发（trunk-based development）：release 分支与 main 对齐，hotfix 与相关团队二次确认后再合入，避免“从错误分支拉出修复”这类事故。分支策略越简单，越不容易在紧急发布时出错。
  • CI 门禁固化为流水线必经步骤：单元测试覆盖率、静态扫描、密钥泄露扫描——把质量关卡前移到合并之前，而不是留到发布后救火。转测之前把代码 Review 作为一道独立的质量关卡，也属于同一思路。
  • AI 生成代码规模变大后，门禁要“机器可复算”：当越来越多代码由 AI 产出，“AI 不能自证有效”就成了硬约束——把“结论”和“可重算的证据”分成两个签名，脚本每次重算、撕掉旧签，语义类判断走“具结 + 人工抽查”。这条方法论的展开见 Harness Engineering。

Cloudflare 平台方向

Sure 和 K12 展示了另一种平台路线：把部分 Agent 产品运行在 Cloudflare 上。

Sure 使用 Worker、D1、R2、Queues、Durable Objects、Workflows、Workers AI 和 Sandbox runner，把写作 Agent 做成低运维成本的生产服务。K12 则在 RoboLabX 方向上探索 Cloudflare standalone，让垂直教育应用可以脱离复杂微服务平台先运行。

Xeni Legal 的英国移民法律案件 copilot 是这条路线更完整的一次落地（简历口径：签约英国、澳洲多家律所）。整套系统跑在 Cloudflare 之上（Worker、Durable Objects、D1、R2、Vectorize、AI Gateway），但它最值得记的是一次边界的收敛：

  • 最初的 MVP 让 Worker 承担了过多的业务编排，很快发现“边缘节点不该拥有业务大脑”。
  • 于是把真正的业务编排交给独立的 Agent Runtime：工作流状态由 Runtime 持有，工具（Tools）是 Agent 与系统能力之间唯一的业务能力边界，Worker 退回成边缘适配 + binding 网关。
  • 后续再把手写的流程状态机换成以“子 agent”编排的运行时（证据分析、档案抽取、法规检索、要件评估、复核包生成各司其职），并引入以“run”为中心的 API。

这套系统达到过单租户 200+ 文件同时 AI 分析、抽取准确率 90%+、AI 填表 P99 5 秒/页面的水平（简历口径）。

这条路线的取舍很清楚：

  • 优点是部署轻、边缘能力强、队列和对象存储组合简单、适合快速产品化。
  • 风险是平台边界更依赖 Cloudflare 生态，需要提前设计数据模型、后台任务、权限和可观测性。
  • 对 Agent 产品而言，Sandbox runner / Worker 与业务运行时之间的内部 API 边界必须非常清楚——谁持有状态、谁只做适配，一旦含糊，边缘层就会悄悄长成业务层。

平台模块地图

从 CosX、K12 和简历里的 AI 平台经验看，垂直 AI SaaS 平台通常会出现这些模块：

  • Gateway：统一入口、认证校验、限流和路由。
  • Identity：OAuth2/OIDC、组织、用户、角色和权限。
  • Workspace：租户空间、成员关系和协作上下文。
  • Storage：文件上传、对象存储、PDF 处理和权限控制。
  • Knowledge Base：文档解析、RAG、索引和引用。
  • Model Gateway：多模型接入、成本控制、路由和降级。
  • Agent Runtime：状态、工具、Workflow、日志和回放。
  • Observability：Trace、metrics、logs、Langfuse 和业务指标。

这些模块和 AI Agent 项目群 里的 Runtime、Tools、Safety、Knowledge、Evals、Observability 一一对应。一个反复验证的组织原则是：用可插拔的声明式配置承载易变的业务规则，用少量稳定的运行时承载不变的编排逻辑——在 Agent 平台上，它体现为“新增一条业务线只需加一个声明式的 Skill 定义 + 配置，而不改平台代码”。

生产事故视角

云原生平台的架构能力，经常是在事故里被验证的。

例如文件处理服务处理大 PDF 出现 OOM，不只是“内存调大”这么简单。它会牵连 JVM heap、container limit、HPA、readiness/liveness probe、依赖服务降级、上传大小限制、异步 worker、队列积压和告警阈值。

生产治理的成熟度体现在三个阶段：

  1. 定位：能从 pod event、previous logs、metrics 和 trace 快速确认故障事实。
  2. 止血：能通过副本、资源、限流、降级、回滚或开关控制影响范围。
  3. 根治：能把同步大任务改为异步 worker，把事故经验写进 runbook、压测和发布检查。

这类判断和支付账务里的教训同源：涉及资源与状态的操作要保证幂等；高频路径不要在 INFO 级别打大对象；怀疑内存问题就尽早 dump；核对指标单位不能想当然。

与个人知识图谱的连接

SaaS 与云原生平台架构连接了三类经验：

后续可以继续把这个方向拆成专题：多租户权限、SSO Gateway、Kubernetes GitOps、Cloudflare Agent 平台、Model Gateway、RAG Knowledge Base 和生产事故复盘。