简介一份从业务到技术完整落地的SAAS平台架构设计文档面向系统架构师、后端开发及产品经理重点围绕权限管理和分布式服务平台建设给出可落地方案。文档核心分解为UPMS权限管理、账户中心、应用中心、订单中心、促销中心、消息中心、客服中心七大业务模块并对高并发下的性能、可靠性、安全性、可扩展性等非功能需求提出明确设计约束技术架构部分则展示了分层架构、微服务、分布式缓存、负载均衡等关键实现思路可直接用于企业级SAAS平台方案设计或作为架构评审参考。资源为单个docx文档压缩包约401KB内含完整目录、版本修订记录及业务/技术架构章节便于按模块查阅。已有489人学习下载适合正在规划或优化SAAS平台权限体系、账户体系与分布式服务架构的读者参考。1. 一份“能评审”的 SaaS 业务架构文档长什么样拿到一份「SAAS平台业务架构文档V1.1.docx」比拿到一堆接口文档要棘手。接口文档回答“系统怎么跑”业务架构文档回答的是“业务怎么被系统切分成可售卖、可计量、可扩展的单元”。V1.1 这个版本号说明它已经不只属于产品经理也不只属于架构师它是开发排期、售前应答、客户成功对客解释的共同基线。一份能拿去评审的业务架构文档至少要能回答四个问题谁在租、按什么边界隔离、功能按什么粒度售卖、将来加一个客户或加一条产品线要动几层代码。这篇就按我平时写这类文档的路径从分层模型、租户与计费、docx 交付与评审走查四个面把它讲透。新手可以照章节顺序搭出自己的第一版老手可以把重点放在第三章的隔离参数和第四章的版本冻结规则上。2. 先把 SaaS 业务架构的分层模型立住租户、产品线、能力域2.1 为什么单租户时代的模块图在 SaaS 里第一轮就会被推翻常见的企业应用架构图是“用户 → 权限 → 业务模块 → 数据库”画成一张树状图就完事。这套画法在 SaaS 里第一轮评审就会被推翻因为漏掉了两个维度租户边界和计价边界。单租户系统里“用户”属于公司内部权限是 RBAC 就够了SaaS 里一个用户隶属于某个租户而租户本身是有合同、有等级、有配额、有独立配置的商务实体。同样一个“订单管理”功能标准租户看到的是默认字段付费租户看到的是自定义字段和审批流不用租户标识去切功能就混成一片。另外模块图默认所有功能等价但 SaaS 的业务架构必须表达“哪些能力是打包卖的哪些是按调用量算钱的”。一个订单管理模块内部可以拆成订单录入、订单审批、订单导出三个能力对外可能是“基础版含录入、专业版含审批、导出按次计费”。模块图画不出这层关系能力域图可以。所以第一件事是把“系统模块”的思维切换成“业务能力 售卖策略”的思维架构文档的骨架要从这里开始定。2.2 分层模型从“系统模块”切换到“业务能力”2.2.1 五层业务架构模型含表格我写 SaaS 业务架构文档时默认用五层模型组织内容。这个分层不是标准定义但它在实际评审里最不容易被挑战因为它把“谁在用、卖什么、怎么实现、怎么扩展”拆开了。以下是我常用的分层及对应文档章节。分层文档里的名字核心要回答的问题典型产物L1 租户层租户与站点一个租户怎么被识别、怎么进入系统域名规则、租户唯一标识、隔离级别L2 产品线路由层产品与订阅客户买了哪个产品、什么版本、有效期产品树、SKU、订阅状态机L3 能力域层能力域业务被切成哪些独立能力、依赖关系能力地图、依赖矩阵L4 业务对象层核心对象订单、客户、账单长什么样、状态怎么流转对象模型、状态机L5 集成层对外接口与事件第三方怎么接入、事件怎么推送Open API 清单、事件表这五层不是五张孤立的图层与层之间要有明确的“锚点”租户层锚定产品线路由层这个租户的合同指向哪个产品产品线路由层锚定能力域层这个产品包含哪些能力能力域层锚定业务对象层这个能力操作哪些对象。文档只要能把三组锚点写清楚开发的数据库设计和前端的路由设计就都有了依据。2.2.2 用一份 YAML 把分层结果结构化成可评审的输入画图固然好但图没法进 diff也没法在代码评审时逐行核对。我一般会在文档里附一份 YAML把分层结果结构化。这个文件后续可以转成 JSON也可以喂给文档生成脚本做校验。这是一个示例片段platform: name: saas-platform version: 1.1 tenants: - tenant_id: t_001 site: acme.example.com plan: professional isolation: schema products: - product_code: CRM name: 客户关系管理 plans: - plan_code: basic capabilities: [crm_contact, crm_opportunity] price: 99 - plan_code: professional capabilities: [crm_contact, crm_opportunity, crm_approval] price: 299 capabilities: - capability_code: crm_approval name: 订单审批流 depends_on: [iam, workflow_engine] billable: true meter: per_execution这段 YAML 的逻辑说明tenants直接表达租户与站点的绑定关系plan字段指向产品下的版本products里每个plan列了包含的能力码能力码在capabilities里有定义depends_on写的是能力对底层服务的依赖评审的时候可以拿去对基础设施清单。参数上要注意三个点isolation的取值建议只用schema或database不要写shared这种模糊词billable: true的能力必须配meter字段plan的能力列表里不允许出现capabilities里未定义的能力码这个可以用脚本校验避免文档前后不一致。2.3 文档目录怎么跟分层对应结构化的 YAML 解决“内容对不对”目录解决“人找不找得到”。我见过大量架构文档内容很扎实但目录是“概述、总体设计、模块设计、数据库设计”评审人想问“计费怎么算”得翻半小时。按五层模型来组织目录评审效率会高很多。我一般建议章节目录固定为租户与站点接入、产品与订阅管理、能力域与业务对象、对外接口与事件、非功能性约束、附录。其中“非功能性约束”别把它写成“系统响应时间小于 2 秒”这种空话而是写清楚租户数量级100 个和 10000 个的隔离设计完全不同、单租户最大并发、数据保留策略。这些参数直接影响后面的技术选型。每章的篇幅建议有配比租户与站点 20%产品与订阅 15%能力域与业务对象 35%接口 15%NFR 10%附录 5%。能力域部分最厚但容易写飘控制它不飘的关键是每个能力必须绑定至少一个业务对象没有对应对象的“能力”是伪能力。3. 多租户和计费是文档里的“两道必答题”隔离、计量、订阅3.1 业务文档里怎么表达租户隔离而不只是画一个“多租户”三个字很多文档写“系统支持多租户”六个字就过去了。但多租户至少有三个维度要想清楚识别、隔离、配额。识别是“一个请求进来系统怎么知道它是哪个租户的”隔离是“租户之间的数据按什么粒度分开”配额是“超出限额之后系统怎么做”。三个维度里识别是落地第一关也是对接层最常出问题的地方。“解析到 saas 站点域名的逻辑”是每个做 SaaS 的团队都会撞上的问题租户访问时用的不只是www.example.com而是tenant-a.example.com或tenant-a.ourdomain.com网关要能从域名里解析出租户标识再把它注入后续请求的上下文。常见的做法是在接入层用正则解析域名取第一级子域作为租户标识。以下是我常用的一段 nginx 配置作为示意server { listen 443 ssl; server_name ~^(?tenant[a-z0-9-])\.example\.com$; location / { proxy_pass http://backend; proxy_set_header X-Tenant-Id $tenant; proxy_set_header Host $host; } }这段配置的关键是server_name里的命名正则捕获~^表示启用正则匹配(?tenant...)是命名捕获组匹配到的子域值会存到变量$tenant里通过proxy_set_header X-Tenant-Id $tenant传给后端。后端第一次拿到X-Tenant-Id后去查租户表确认它是否有效、是否欠费、当前订阅的产品码是什么。参数注意两个地方子域只允许小写字母、数字、连字符租户数超过千个之后不能把租户表每次都查一遍启动时要加载到缓存用这个 Header 直接命中缓存 key。隔离参数建议在文档里直接用表定义避免文字描述引起歧义。我的常用参数表如下隔离级别数据存储方式适合的租户规模运维成本典型场景共享表 tenant_id 字段一张表多租户共存数千到数万低标准化产品、租户数据量小共享实例 独立 schema一个数据库实例下多个 schema数百到数千中租户要求数据强隔离、可单独备份独立实例一个租户一套库数十到数百高大客户定制、合规要求高选型上我一般建议第一版用共享表但必须在所有核心表上强制 tenant_id 索引同时查询接口的第一个条件是租户标识不要在设计文档里把“共享表”和“租户独享备份”同时作为需求这会逼着运维实现单表抽数工作量远超预期。如果有客户坚持要独立备份直接按独立 schema 报价别在共享表上做兼容方案。3.2 订阅与计量把订单、用量、账单对应到业务对象业务架构文档里订阅模块最容易被写成“下单、支付、开通”的流程图。这个没错但漏掉了计量的部分。SaaS 的计费和传统软件不一样传统软件卖 licenseSaaS 卖的是“订阅 用量”的组合。所以业务架构里必须定义三个对象订阅Subscription、用量Usage、账单Bill。订阅描述客户买了什么用量描述客户用了多少账单描述按订阅和用量加总之后应收多少钱。这三个对象建议在业务对象层里显式建模。核心属性参考如下订阅包含subscription_id、tenant_id、product_code、plan_code、start_time、end_time、status用量包含usage_id、tenant_id、meter_type、quantity、occurred_at账单包含bill_id、tenant_id、period_start、period_end、line_items、total_amount、status。这些字段不是 DBA 设计的最终物理表但业务文档写清楚后DBA 建表时可以少开三次会。“用量”对象尤其容易被忽略很多团队第一版不做计量后面对客户说“按调用量收费”时发现根本没有数据可查只能回退到按套餐包一口价商务上很被动。计量口径也要在文档里定死是事件驱动计量还是定时汇总单位是什么。我建议第一版用“事件驱动 每日汇总”的写法业务侧在关键操作比如审批发起、导出生成时发一条计量事件写进用量表每日定时任务按租户类型汇总并落入账单明细。这样对账方便也不会让实时计量拖慢核心链路。“一次性买断”这种非订阅型售卖可以建模为subscription里period为null的特殊类型不要单独建一套订单逻辑。3.3 订阅状态机从“待支付”到“已过期”不许跳变订阅对象本身的流转规则是评审时最容易吵起来的部分。我的建议是直接在文档里定义最简单的状态机不允许状态跳变。参考如下pending_payment待支付、active生效中、suspended已暂停、expired已过期、cancelled已注销。其中active可以因欠费变成suspendedsuspended在补缴后变回activeexpired只能由active或suspended在到期后进入cancelled只接受pending_payment和active主动注销。这条规则背后有个常见的坑如果允许expired直接回到active就意味着过期后数据不用冻结那到期时就没法对客户形成约束。实际业务里允许过期续费恢复但技术上要走一遍「重新下单」而不是直接改状态文档里写清楚“续费不等于状态回改”能避免后续开发为省事直接 UPDATE 状态列。业务架构文档写到这个粒度评审的时候产品、开发、财务才能有共识。4. 把 docx 当成交付物来管版本、目录、制图规范与生成链路4.1 V1.1 不是文件名后缀是变更基线标题里的 V1.1 值得单独说业务架构文档是活的但它不能活到“每次评审都不一样”。V1.1 这个标识应该对应一套明确的变更基线。我给团队定的规则是架构文档大版本打满十次小变更或出现产品线级改动时递增小版本只允许三种变更新增能力域、调整计费口径、修订单个业务对象的字段定义。大版本变更必须重新全量评审小版本变更只需要走变更记录 增量评审。对应的文档第一页要放变更记录表格式不用复杂版本号、日期、变更人、变更摘要、对应评审结论。这本账是最容易被忽略的。很多人只改正文不改版本号和变更记录时间一长文档就沦为“好像没人看”的摆设。另外建议每个版本导出的 docx 文件名统一为SAAS平台业务架构文档V1.1.docx这种固定格式用_draft、_final这类后缀只会让文件越堆越乱根本分不清哪个是最新的。4.2 用 Markdown 维护、用 Pandoc 导出 docx业务架构文档的日常维护不该在 Word 里进行。Word 适合做展示和批注不适合做增量修改多个架构师并行维护一份 docx合并冲突能把人逼疯。我一般建议正文用 Markdown 维护评审前统一导出 docx。既然标题带了 docx那自然要解决“Markdown 怎么变成合规 docx”的问题。以下是一条我常用的转换命令pandoc saas_business_architecture.md \ -o SAAS平台业务架构文档V1.1.docx \ --toc \ --toc-depth2 \ --number-sections \ --reference-docsaas_template.docx这段命令把 Markdown 转成 docx 并自动生成两级目录、自动编号章节。参数含义--toc生成目录页--toc-depth2只收录到二级章节避免目录三页长--number-sections让章节自动编号不用手动敲“第 1 章”--reference-doc指定模板样式模板里定好了字体、标题颜色、表格边框每次导出都复用格式不会漂移。日常维护只在.md文件上操作评审前再导出 docx 给产品、销售、客户成功各一份。实际使用中三个高频问题第一Pandoc 导出的 docx 里表格默认样式要依赖模板如果不指定reference-doc表格可能不带边框第二图片最好全部用相对路径存放如果图片路径带空格转换时用引号包住整个路径第三--toc生成后目录页码不会自动更新需要在 Word 里全选目录按 F9 刷新一次这个细节在交付前一定要处理否则目录页码是错的。4.3 图表编号与冻结规则导出的 docx 通常还有图表编号的问题。Pandoc 导出的文档不会自动给图和表编号需要靠样式约定。我的做法是在 Markdown 里统一用“表 2-1”“表 3-2”这种带章节前缀的手工编号并在正文首次引用时写“见表 3-2”。这个规则不优雅但胜在稳定即使转换工具变了编号也不会乱。图与表的编号规则建议强制为“章节号-序号”不要用“图二十一”这类中文序号跨章引用时一眼看不出是第几章的图。代码块尽量压到最小docx 里代码的等宽字体靠模板控制没有模板就不用代码块改用表格替代。“冻结规则”指的是每个版本评审通过后正文必须打 tag之后的修改只能在下一个版本里进行。Git 上按版本号打 tagdocx 只是导出物。这样一旦客户对某一版内容有争议可以精确回溯到当时评审通过的那一版而不是掏出本地 “最终版”又发现对不上会议纪要。5. 评审前做一次“15 分钟走查”拿来验证文档而不是又开一次会5.1 走查清单评审会之前我一般会按下面的清单先过一遍文档这个过程控制在 15 分钟以内。走查不是通读是带着“文档能不能自洽”的问题去看不追求完整读每个字。第一查租户入口。从文档的“租户与站点”章节随机取一个示例域名顺着网关配置、租户识别、订阅有效性判断的链路走一遍看能不能走通。走不通的常见原因是“网关识别租户”和“业务侧验证租户”各写了一套逻辑租户标识字段名不一致。第二查计费闭环。找一个billable: true的能力检查它的计量事件是否在业务对象层有定义。很多文档会在能力层写“支持按次计费”但业务对象层根本找不到“用量”相关的对象这就是断链。第三查能力依赖。把 YAML 里所有capabilities的depends_on拉出来看有没有依赖不在平台能力清单里的服务。最常见的是依赖了某个中间件名称但 NFR 章节的基础设施清单里没有这个中间件。第四查版本一致性。翻到变更记录表对比 V1.0 到 V1.1 的变更摘要看看是否与正文实际修改点一致。不一致说明有人改了正文但没登记这类文档进入评审基本会被打回。5.2 一个反向检查技巧更狠的验证方式是“反向检查”把文档里所有肯定性的描述反着读一遍校验是否矛盾。比如文档写了“系统支持租户级自定义字段”反着问“不支持行不行”如果不支持会影响哪个核心流程如果影响的是边缘功能说明这条能力描述可能被夸大了——它在能力域里挂着但业务对象层没有对应的自定义字段模型。另一种做法是给文档里的“支持”做词频统计“支持”这个词如果出现超过几十次就要怀疑很多能力没有讲清楚边界因为真正定义清楚的功能不会用“支持”去描述而是直接写“在某条件下某角色能对某对象执行某操作”。走查时专门找“支持”后面没有条件状语的地方这些条目后续都会变成需求变更的争议点。把业务架构文档当成可运行的系统来对待版本、结构、依赖、计费每条都是可校验的链条。链上每处都能指回去评审就从“各说各话”变成了“对着同一份事实挑错”。能做到这一步V1.1 就真的是比 V1.0 更接近可交付的那个版本而不只是文件名变了一下。本文还有配套的精品资源点击获取