06 · 多租户 SaaS(CAP):完整图文教程
目标:把 Sustainable SaaS(SusaaS)示例完整跑一遍——准备提供方子账户 → 构建并部署基础版本(mtar)→ 订阅第一个租户 → 升级与回滚,最后清理干净。 预计:1–2 天 | 难度:高 | 前置课程:CLD200、BTP200、KYM400
阅读方式:本篇以 SAP BTP, Cloud Foundry 运行时为主线(
mbt build→.mtar→cf deploy),命令均可在你本机直接复制。同一个仓库也支持 Kyma 路线(构建 Docker 镜像 → Helm 部署),等价命令与完整章节放在文末「其他场景索引」,建议先把主线跑通再切换。
你会做出什么
你会得到一个真正能对外卖的多租户 SaaS 应用骨架:它以 Sustainable SaaS(可持续性 SaaS)为业务主题,让企业客户在自己的项目里评估产品的循环性(circularity)指标——包括循环性得分、销售拆分(sales splits)、材料拆分(material splits)等。技术上看,它由四类可独立伸缩的组件组成:
Application Router(应用路由器):所有租户流量的唯一入口,按 URL 子域识别租户,把请求转发到后端服务与 HTML5 静态资源。
SaaS 业务服务(srv):CAP 实现的 OData 服务,提供 Fiori Elements 界面所需的数据与注解,并承载订阅回调、租户开通自动化。
SaaS API 服务(api):给消费方(客户)用的多租户 REST/OData 接口,客户的 SAP S/4HANA 或任何第三方系统可以往里推数据。
API Service Broker(broker):一个符合 OSB 标准的服务代理,订阅时为每个租户注册,让客户能创建「Sustainable SaaS API」服务实例并拿到访问凭据。
跑通后,你会在 SAP BTP Cockpit 里看到这样的完整链条:提供方子账户里部署着一套应用与一组服务实例;消费方子账户里出现了一条 Subscribed 状态的订阅;每个租户都有自己专属的应用 URL;HANA Cloud 里每个租户都有自己的 HDI 数据库容器,数据互不可见。下面几张截图就是这个应用的最终样子:




你会交付的东西 |
在哪里看 |
通过标准 |
|---|---|---|
一套 CAP 多租户应用(router + srv + api + broker) |
提供方子账户 → Cloud Foundry → 应用列表 |
应用全部 |
SaaS 供品(Sustainable SaaS) |
消费方子账户 → Instances and Subscriptions → Create |
下拉列表里能看到该服务,计划为 |
租户专属 URL 与数据容器 |
消费方子账户 → 订阅详情 |
状态 |
多租户 API 的访问凭据 |
消费方子账户 → 服务实例 → 服务绑定 |
拿到 |
可升级、可回滚的版本基线 |
提供方子账户 → 部署历史 / HANA 容器 |
新版本部署后老租户数据仍在,回滚路径明确 |
走完这一篇,你会亲手验证下面这些「多租户必备能力」,而不只是读概念:
订阅即开通:客户点一次订阅,后端自动建数据库、注册 API、开通访问入口。
租户识别:同一个应用、同一套凭据,靠 URL + token 就能定位到具体租户。
数据隔离:两个租户的业务数据物理上在不同容器,逻辑上互相不可见。
自助用 API:客户在自己的子账户里创建服务实例、拿凭据、调 API,不需要提供方手工发密钥。
可演进:应用能持续发新版,存量租户的数据库也能按需、逐个升级。
架构与原理
多租户是 SaaS 产品的分水岭:单租户部署时,每个客户独占一套运行时和数据库,卖得越多、成本越高;多租户部署时,一套应用服务所有客户,租户之间靠逻辑隔离(身份区域 + 数据库容器)而不是物理隔离来保证安全。这个示例把「一套应用服务众多客户」所需的租户开通、隔离与升级机制完整实现了一遍,所以它值得花两天认真走一遍。
业务场景:把可持续性评估做成 SaaS
SaaS 的提供方(也就是你)开发了一套可持续性评估应用,客户订阅后,可以用它扩展自己的 SAP S/4HANA 等系统:把产品主数据、销售订单、回收数据通过 API 推进来,然后在网页上为产品建立循环性评估、维护销售拆分与材料拆分,得到循环性得分。示例刻意保持业务简单,因为真正的看点在多租户机制:怎么让 100 个客户共用一套应用,却谁也看不到谁的数据。
四个角色与关键术语
术语 |
含义 |
在本教程中的对应物 |
|---|---|---|
提供方(Provider) |
开发并运营 SaaS 的软件供应商 |
你的 提供方子账户:部署应用、持有 SaaS Registry 与全部服务实例 |
消费方(Consumer) |
使用 SaaS 的客户公司/团队 |
你的消费方子账户(也可叫租户子账户) |
租户(Tenant) |
某个消费方在某个 SaaS 应用上的一个具体实例 |
一次订阅 = 一个租户 = 一个 HANA HDI 容器 |
开通(Onboarding) |
从客户注册到能使用应用的端到端流程 |
建子账户 → 订阅 → 初始化管理员 |
预配(Provisioning) |
订阅过程中后端自动创建资源(数据库 schema、路由/API Rule、服务代理注册、Destination) |
由 |
租户感知(tenant-aware) |
应用能从请求的 token 中识别租户,并只访问该租户数据 |
Application Router + XSUAA |
MTXS |
CAP 的多租户扩展包 |
提供订阅回调、租户部署、Feature Toggles 等服务 |
统一账户模型如下图所示:一个全局账户下有一个提供方子账户(放应用和 SaaS Registry),以及 N 个消费方子账户(各自订阅、各自拥有身份区域)。注意:示例中消费方子账户位于提供方的全局账户之下,这是为了便于教学与测试;真实生产里消费方是独立公司,通常有自己的全局账户,通过订阅流程跨账户开通。

基础版本到底跑了什么
如果你选 Cloud Foundry 路线,基础版本(Basic Version)部署后,提供方子账户的 CF 环境里会长出下面这些进程与实例(图里也标注了 Kyma 路线会换成什么):


从左到右读这张图,一条请求的路径是:浏览器 → Application Router(校验登录、识别租户)→ 业务服务(OData/注解)→ HANA Cloud 中该租户的 HDI 容器。旁路还有两条:业务服务在订阅/取消订阅时调用平台 API 做自动化;API 服务被客户系统通过 API Broker 发放的 client credentials 直接调用。
组件 |
职责 |
订阅时是否变化 |
|---|---|---|
|
单点入口、静态内容、身份认证与租户识别 |
每个租户新增一条 CF Route(或 Kyma API Rule) |
|
OData 服务、Fiori Elements 注解、订阅回调、开通自动化 |
为租户创建 HDI 容器、注册 broker、建 Destination |
|
多租户入站 API(产品、销售订单、回收数据) |
随 broker 绑定被调用,token 决定写入哪个容器 |
|
OSB 服务代理( |
被注册进消费方子账户 |
|
共享数据模型部署器(Job),把共享表部署进共享 HDI 容器 |
不随租户变化 |
|
把 UI5 模块部署进 HTML5 Application Repository |
不随租户变化 |
HTML5 App Repository 实例 |
存放 Fiori Elements 静态资源 |
不随租户变化 |
XSUAA( |
业务用户认证、API 认证 |
订阅时把 scope/role collection 复制到租户子账户 |
HANA Cloud( |
持久化,共享容器 + 每租户容器 |
每个租户新建一个 HDI 容器 |
Service Manager( |
管理 HDI 容器生命周期、执行跨子账户操作 |
运行时临时实例,用完即删 |
为什么非要多租户:一笔账
SaaS 是从 IaaS、PaaS 一路演进过来的:越往 SaaS 走,客户要操心的事越少,但灵活度也越低——这正是它能做到低边际成本的原因。

单租户模式下,每个客户独占 HANA Cloud 实例与运行时内存:收 500 美元、成本 300 美元,利润 200 美元。

多租户模式下,100 个客户共用一个大型 HANA Cloud 实例与一份运行时:共收 10000 美元、成本 3000 美元,利润 7000 美元。

这就是为什么在 SAP BTP 上做 SaaS,一定要从第一天就把多租户设计进去:HANA Cloud 的 HDI 容器隔离、XSUAA 的身份区域共享、Destination、Event Mesh 等,都是为这个模式准备的基础设施。
一次订阅,后台到底发生了什么
这是本案例最值得吃透的部分。你在 Cockpit 里只点了一次 Create,后台其实跑完了一条长长的流水线。
第一层:SaaS Registry 与订阅回调。 提供方部署应用时会注册一个 SaaS 供品(供品由 SaaS Provisioning Service / SaaS Registry 管理)。租户在 Cockpit 订阅时,SaaS Registry 调用应用暴露的订阅回调 PUT /saas/subscriptions/:tenantId(由 CAP MTXS 提供),并把租户信息交给应用。应用必须在这个回调里把租户需要的东西都准备好,否则订阅会卡住或失败。CAP MTXS 替你处理了数据库容器、租户模型部署、依赖回调等重活;示例代码则在 provisioning.js 里补充了平台侧的自动化(注册 broker、建路由、建 Destination 等)。
第二层:Application Router 如何认出「你是哪个租户」。 每个租户访问的 URL 不同(订阅时生成的子域),Application Router 用环境变量 TENANT_HOST_PATTERN(一个带捕获组的正则)从 Host 中提取租户子域,再把这个子域拼成 XSUAA 的认证地址,从而进入该租户专属的身份区域(identity zone)。身份区域里的用户、IdP、组映射彼此独立,所以 A 租户的用户永远进不了 B 租户。

这张图展开后其实是 8 个步骤,值得逐条对着看:
Application Router 用
TENANT_HOST_PATTERN从 URL 推导身份区域标识符;每个消费方子账户对应唯一的身份区域与子域名。Application Router 调用租户感知的 XSUAA 服务,由它负责业务用户认证。
XSUAA 读取租户,并从该租户的身份区域里取出消费方特定的身份提供商(IdP)。
XSUAA 把认证委托给该 IdP,并签发一个 JWT,里面含租户、当前用户与用户授权范围。
JWT 回传给 Application Router,再由它传给应用。
应用要读写租户数据,就必须知道租户 ID。
应用从 JWT 里读出租户、用户与 scope。
租户信息挂在用户属性的
identityZone上(Java 里可用SecurityContext.getUserInfo().getIdentityZone()取)。
于是会出现一个很有意思的现象:同一套 client credentials,却签发出 zid(身份区域 ID)不同的 token。下面左图是提供方 XSUAA 实例的 client credentials,右图是为某个消费方租户签发的 token——client id 是同一个,但 token 的 zid 指向消费方身份区域。


能这样做的关键,是 XSUAA 的 tenant-mode shared:XSUAA 实例被所有租户共享,但只为「已订阅」的消费方身份区域签发 token,并且 tenant index 会体现在 scope 里(形如 dev-susaas!t134415.Admin)。这就是为什么示例需要 两个 XSUAA 实例:application 计划给业务用户用(租户感知、scope 按租户复制),broker 计划给 API 凭据用(服务代理为每个租户创建绑定)。
第三层:数据隔离靠 HDI 容器。 订阅时,后端通过 Service Manager 的 container 计划为新租户创建 HANA HDI 容器,并把 CAP 的租户数据模型部署进去。所有租户容器共享一个「共享数据库容器」里的主数据(通过跨容器访问 + synonyms),但业务数据各在各的容器里。

为什么用「每租户一个容器」而不是「一张表加租户列」?这是多租户设计里的经典取舍:
方案 |
隔离强度 |
运维成本 |
适用 |
|---|---|---|---|
共享表 + |
弱,完全靠代码保证不漏查条件 |
低,一套表结构 |
租户少、可信度高的内部 SaaS |
每租户独立 schema/容器 |
强,数据库层做隔离 |
中,容器数量随租户增长 |
标准 SaaS(本示例的选择) |
每租户独立数据库实例 |
最强 |
高,成本随租户线性增长 |
强监管、超大型客户 |
示例选中间方案:HANA HDI 容器天然支持「一个容器一套 schema、通过角色与 synonyms 做跨容器访问」,既保证隔离,又不用为每个租户付一份数据库实例的钱。代价是容器数量会随租户增长,所以工程上要配合 Service Manager 做生命周期管理,并定期清理已取消订阅的容器。
第四层:API 走 Service Broker。 客户想调用 API,需要凭据。凭据不是提供方手工发的,而是通过 API Service Broker 动态发放:订阅时,业务服务把 API 服务代理注册进消费方子账户;客户在消费方子账户里创建「Sustainable SaaS API」服务实例与服务绑定,平台向 broker 发 OSB 请求,broker 用 XSUAA broker 计划实例为该子账户创建客户端凭据。此后客户系统用这份凭据换 token 调用 API,CAP 从 token 里读出租户,把数据写进正确的容器。


第五层:自动化编排。 上面这些步骤分散在多个平台 API 里(Cloud Management Service、Service Manager、Destination Service、CF API / Kyma API),示例用一组辅助类把它们串成一条带步骤回滚的工作流:tenant-automator.js 负责编排,cloud-management-service.js 负责跨子账户建 Service Manager 实例,service-manager.js 负责注册/注销 broker,destination.js、token-helper.js、user-management.js、alert-notification.js 各管一摊。理解这条流水线,你才能在看部署日志、订阅状态卡住时知道该查哪一层。
第六层:两个 XSUAA 计划的分工。 很多人第一次看示例会被「两个 XSUAA 实例」绕晕,其实它们的职责完全不同:
实例 / 计划 |
服务的对象 |
关键配置 |
少配了会怎样 |
|---|---|---|---|
XSUAA |
租户的业务用户(浏览器登录) |
|
租户无法登录,或登录后拿不到租户内 scope |
XSUAA |
API 的客户端凭据(client credentials) |
供 Service Broker 创建绑定 |
客户创建 API 实例/绑定时失败,拿不到 client id |
application 计划还要求 xsappname 在应用部署到的每个子账户里唯一,所以示例会把 xsappname 与 Space/Org(或命名空间/集群)动态组合,这也是为什么你可以在同一环境里重复部署多套来做对比实验。订阅时,scope、role template、role collection 会被复制到消费方子账户,scope 形态变成 <xsappname>!t<tenant index>.<scope>——看到这个 !t 后缀,就说明租户已就位。
多租户编程的几条红线。 无论用什么框架,写租户感知应用都要守住下面几条,否则数据隔离会从代码层漏出去:
进程内共享的内存数据对所有租户都可见——不要把租户数据缓存进全局变量。
不要让应用用户执行自定义代码(这会绕过隔离,读到别的租户数据)。
不要让应用用户接触文件系统(同理)。
需要为租户创建数据库 schema 等内部活动时,必须实现 SaaS Provisioning 服务的订阅回调,从订阅事件里拿到租户信息,而不是自己猜。
如果应用依赖其他 SAP 重用服务,要实现 getDependencies 回调,让平台知道订阅时需要一并创建哪些依赖。
准备工作
账户与权益
推荐用 Pay-As-You-Go(PAYG) 或 CPEA 账户 + Free (Tier) 服务计划搭建;Trial 也能跑,但限制更多(比如 Kyma trial 集群只有 14 天寿命、CF trial 工作负载每天会被停止)。三种账户类型的差别值得先搞清楚,因为它直接决定你后面能怎么排错:
账户类型 |
免费层能力 |
主要限制 |
适合谁 |
|---|---|---|---|
Trial(试用) |
自带默认子账户与配额,开箱即用 |
运行时有额外限制;Kyma trial 集群 14 天;部分服务计划(如 Credential Store 的 |
只想快速看一眼效果 |
PAYG(按需付费) |
全部 Free Tier 服务计划,可随时升付费 |
需要绑定支付方式;付费计划会产生费用 |
长期验证、准备商用 |
CPEA(云平台企业协议) |
同 PAYG,走合同额度 |
需要企业协议与相应权限 |
企业/合作伙伴正式项目 |
选 Cloud Foundry 还是 Kyma
示例两套都支持,业务代码完全一样,差别只在部署工件与平台服务。做主线选择时按团队能力来:
维度 |
Cloud Foundry |
Kyma |
|---|---|---|
部署单位 |
MTA 归档( |
Docker 镜像 + Helm Chart,一条 |
上手成本 |
低: |
中高:需要 Kubernetes、kubectl、Istio 基础 |
网络与路由 |
平台托管路由,开箱即用 |
Istio + API Rule,控制力强但配置多 |
本教程中的差异 |
需要 Credential Store 存自动化凭据 |
用 Kubernetes Secret 替代 |
扩缩容 |
Application Autoscaler |
Horizontal Pod Autoscaler |
适合场景 |
传统企业应用、快速交付 |
云原生、多服务、需要精细网络控制 |
提醒:示例里所有与部署相关的工件都放在
deploy/下,code/目录与运行时基本无关。这意味着你可以先用 CF 跑通业务与订阅逻辑,再切 Kyma,而不用改业务代码。

Cloud Foundry 路线需要在提供方子账户中分配以下权益(括号内是免费层/试用计划):
服务 |
计划(Free Tier / Trial) |
用途 |
|---|---|---|
SAP BTP, Cloud Foundry Runtime |
Free / Trial: MEMORY |
跑 4 个应用,1 GB 足够 |
SAP HANA Cloud |
|
共享容器 + 每租户容器 |
SAP HANA Schemas & HDI Containers |
|
HDI 容器 |
SAP Authorization and Trust Management Service |
|
业务用户认证 + API 凭据 |
SAP SaaS Provisioning Service |
|
SaaS Registry / 订阅 |
SAP Service Manager |
|
容器生命周期、跨子账户操作 |
SAP Cloud Management Service |
|
跨子账户创建 Service Manager 实例 |
SAP HTML5 Application Repository Service |
|
存放 UI5 静态资源 |
SAP Destination Service |
|
租户侧 Destination |
SAP Credential Store |
|
自动化用的技术用户与 broker 密码 |
SAP Alert Notification |
|
部署/开通失败告警 |
Application Autoscaler |
|
按租户负载扩缩容 |
注意:Trial 子账户里 Credential Store 的
free计划不可用,必须用trial计划对应的 MTA 扩展描述文件(下文会用到trial-basic.mtaext)。
需要安装的工具
工具 |
用途 |
检查命令 |
|---|---|---|
Git |
克隆示例仓库 |
|
Node.js LTS + npm |
CAP 构建、 |
|
Cloud MTA Build Tool( |
把多模块项目打成 |
|
Cloud Foundry CLI v8 + multiapps 插件 |
|
|
SAP BTP CLI( |
处理 Service Broker 残留注册 |
|
REST Client(可选) |
执行仓库里的 |
— |
HANA Cloud 客户端工具(可选) |
用 Database Explorer 查看租户容器表结构 |
— |
开工前的检查清单
能登录 SAP BTP Cockpit,并在全局账户里看到提供方子账户。
提供方子账户里已分配上表的权益,且 SAP HANA Cloud 实例已创建(
hana-free)或已被映射进来。已创建 Cloud Foundry 组织(Org)与空间(Space),名称不含空格、特殊字符(
-除外)或大写字母。本机
cf login能登录到该 Org/Space,cf target显示正确。已确认
mbt与cf的 multiapps 插件是最新版本。手边有一个具备 Subaccount Administrator + Space Developer 的账号(用于自动化,后续要放进 Credential Store)。
有一个能收邮件的邮箱(Alert Notification 确认信)。
有一个可用的 SAP ID Service 用户邮箱(后续创建第一个租户管理员必须用它)。
操作步骤
主线选择说明:多租户示例同时支持 Cloud Foundry 与 Kyma,两条路线的业务代码完全一致,差异只在部署工件。本篇把 Cloud Foundry(mtar) 写成可照做的完整主线;Kyma 的构建/部署/Helm 细节见文末索引。
关于命名:仓库 README 里会把部署出来的应用叫
susaas-*,服务实例叫<SpaceName>-susaas-*。下文的命令里出现<...>的部分都要替换成你自己的值,替换后再执行。
步骤 1:认识仓库结构,建立代码地图
做什么。 先花 20 分钟把仓库目录与各组件的对应关系搞清楚,后面出问题时你才知道该看哪个目录、哪个日志。示例把「与运行时相关的部署工件」全部挪到了单独的 deploy 目录,code 目录基本与运行时无关——这是它在 CF 与 Kyma 两条路线上都能跑的原因。
怎么点/怎么看。 克隆仓库(建议先 Fork 到你自己的 GitHub,再用自己的 fork 克隆,方便后续改配置):
git clone https://github.com/SAP-samples/btp-cap-multitenant-saas
cd btp-cap-multitenant-saas
仓库顶层大致是这样:
目录 |
内容 |
你什么时候会碰它 |
|---|---|---|
|
CAP 源码(api、srv、broker、db、db-com、router、app) |
改业务、改数据模型、构建 mtar |
|
Cloud Foundry 的 MTA 描述文件与 mtaext |
本主线全部部署操作 |
|
Kyma 的 Helm 部署脚本与 values |
走 Kyma 路线时 |
|
官方文档与截图 |
对照细节时 |
code 目录内部的映射关系如下:

子目录 |
内容 |
关键点 |
|---|---|---|
|
多租户 API 的 CAP 服务 |
|
|
Fiori Elements UI 模块 + |
UI 构建时打包成 zip 交给 HTML5 App Repository |
|
API Service Broker(基于 |
|
|
租户数据模型 |
订阅时部署到每租户独立 HDI 容器,含 HANA 原生对象(synonyms、roles、procedures) |
|
共享数据模型 |
部署到共享 HDI 容器,所有租户可读 |
|
Application Router 配置 |
|
|
SaaS 业务服务 |
OData 服务、注解、 |
|
单元测试、示例 HTTP 请求、示例数据 |
|
下面按子目录看细节。先看 API 服务(api/):注意生产配置放在 srv/.cdsrc.json,本地/混合测试配置放在 api/.cdsrc.json,两者用途不同,别改错地方。

app/ 目录里除了 Fiori Elements 模块(ui-admin-projects、ui-admin-users、ui-public-assessments、ui-public-flp、ui-public-projects),还有 html5-deployer。ui-public-flp 就是登录后看到的沙盒启动台,Application Router 的 welcomeFile 指向它。

broker/ 目录就是整个 API Service Broker。注意 catalog.json 里的服务与计划 ID 不能手写死,后面要用 npx @sap/sbf gen-catalog-ids 生成唯一 ID。

db/ 是租户数据模型。除 CDS 模型外,src/ 里还有 HANA 原生对象(函数、存储过程、角色、synonyms),cfg/ 与 hana/ 负责生产构建时对共享容器的引用,sqlite/ 用于本地测试。

db-com/ 是共享数据模型,部署到一个专用容器,*_ACCESS.hdbrole 定义租户容器访问共享容器所需的角色。

router/ 只有几个文件:xs-app.json 是生产路由定义,index.js 做健康检查与 cookie 处理,Dockerfile 仅供 Kyma 使用。

srv/annotations/ 里的注解决定了 Fiori Elements 界面的能力与布局:capabilities.cds、fieldControls.cds、layouts_*.cds、labels.cds、valueHelp.cds。改注解 = 改界面,改完必须重新 cds build --production 再构建。

srv/ 的其余部分是业务核心:admin-service.cds/js、public-service.cds/js 提供 UI 用的 OData 服务;provisioning.js 是订阅/取消订阅的处理入口;utils/ 是各种自动化辅助类(automator、cloud-management、service-manager、destination、token、user-management、alert-notification、cf-utils/kyma-utils)。

test/ 里放本地测试用的示例数据、.http 请求与单测。记住 tenantUpgrade.http——升级租户数据库容器时会用到它。

验证。 你能在不看文档的情况下回答这几个问题,就算这一步达标:改数据模型要动 db/ 还是 db-com/?改订阅自动化动哪个文件?多租户 API 的凭据由谁发放?如果答不上来,回到上面的表里再过一遍。
步骤 2:准备提供方子账户与 SAP HANA Cloud
做什么。 把「账户、运行时、数据库」三件事准备好:分配权益、创建 Org/Space、把 SAP HANA Cloud 实例映射给 Cloud Foundry 环境。没有映射关系,后续 HDI 容器创建会失败。
怎么点/怎么填。
在 SAP BTP Cockpit 进入全局账户 → Entitlements,为提供方子账户分配上表里的权益。分配时可先只给
free/trial计划,避免产生费用。进入提供方子账户 → Cloud Foundry → 创建(或复用)Org 与 Space。名称不要含空格、大写字母或除
-之外的特殊字符(后面会拼进路由与服务实例名)。创建 SAP HANA Cloud 实例(
hana-free,Trial 用hana),或者复用同区域其他子账户里已有的实例。用 Instance Mapping 把该 HANA Cloud 实例映射到你的 CF 环境:可以映射到整个 Org,也可以只映射到某个 Space。在 SAP HANA Cloud Central 里选择对应的 CF 环境与 Space 即可。
下面是官方文档里「把 SAP HANA Cloud 实例映射到 Cloud Foundry 环境」的界面示意:

验证。 两条命令都要成功:cf login -a https://api.cf.<region>.hana.ondemand.com 能登录;cf target 显示的是你刚创建的 Org/Space。另外到 HANA Cloud Central 里确认实例状态是 Running(免费层实例每天会自动停止,开工前先确认)。
注意:免费
hana-free实例每天自动停止,且连续 30 天不重启会被删除;如果你隔天回来发现部署报 HDI 相关错误,先去 HANA Cloud Central 把实例启动,等几分钟再重试。
分配权益时有个实用习惯:先按「部署日志报什么缺什么」补齐,而不是一次全开。cf deploy 的失败信息通常会明确指出哪个服务的哪个计划没有权限(例如 Service broker error: Service [xsuaa] is not entitled),照它补即可。另外,免费层实例与配额是按子账户隔离的,同一个全局账户下多个子账户各开一套,容易撞上全局配额上限——先在全局账户的 Entitlements 里确认剩余配额,能省掉一次失败部署。
步骤 3:为部署准备代码与私有凭据
做什么。 示例代码是「干净」的:邮箱、密码、目录 ID 都是占位符。这一步要把它们换成你自己的值,并且保证这些值不会被提交到 GitHub——仓库统一用 -private 后缀 + .gitignore 来做到这点。
怎么点/怎么填。
进入 CF 部署目录:
cd deploy/cf
ls
# config/ mta.yaml mtaext/ ...
打开
config/alert-notif.json,把接收告警的邮箱填进receivers(或新建alert-notif-private.json,并在mtaext里用path指向它)。这是部署失败、租户开通出错时唯一会通知你的地方。

生成 Service Broker 的唯一 catalog ID 与凭据:
npx --yes -p @sap/sbf hash-broker-password -b
npx --yes -p @sap/sbf gen-catalog-ids ../../code/broker/catalog.json
第一条会输出 Plaintext password(明文密码)和 Hashed credentials(sha256 哈希);第二条会把 3 个唯一 ID 写进 code/broker/catalog.json。

重要:明文密码要立刻记到安全的地方(下一步要放进 Credential Store),哈希凭据要粘进 MTA 扩展描述文件。两者都不能提交到 Git。
复制一份 MTA 扩展描述文件,按目标环境选模板:PAYG/CPEA 用
free-basic.mtaext,Trial 用trial-basic.mtaext,复制后加-private后缀(例如free-basic-private.mtaext)。以-private结尾的文件已被.gitignore忽略。

把上一步的哈希凭据粘进
free-basic-private.mtaext(或 trial 版)里 broker 资源的参数中。片段形如:
SBF_BROKER_CREDENTIALS_HASH: >
{
"broker-user": "<粘贴你的哈希凭据 sha256:...>"
}

如果你还建了 alert-notif-private.json,同一份 mtaext 里要把它引用进去,例如:
resources:
- name: susaas-alert-notification
parameters:
service-plan: standard
path: ./config/alert-notif-private.json
Trial 环境的 mtaext 还会覆盖两个服务计划(Credential Store 与 Alert Notification),官方给出的示例片段是:
ID: susaas.trial
extends: susaas
resources:
- name: susaas-alert-notification
parameters:
service-plan: standard
- name: susaas-credstore
parameters:
service-plan: trial
验证。 git status 里不应出现任何 -private 文件;grep 一下你的 mtaext,确认 SBF_BROKER_CREDENTIALS_HASH 里的哈希以 sha256: 开头,且 catalog.json 里的 id 已被替换成 UUID 形态(不再是占位符)。
步骤 4:构建并部署基础版本(mtar)
做什么。 用 Cloud MTA Build Tool 把 CAP 项目、UI 模块、数据模型、router、broker 一起打成单个 .mtar 归档,再用 cf deploy 一次性部署到提供方子账户。这一步最耗时,也最容易因为权益或服务计划问题失败。
在敲命令之前,先把三件事弄清楚,能省掉大量返工:
deploy/cf里到底有什么。mta.yaml是「总装配图」,它声明了要部署哪些模块(router、srv、api、broker、UI deployer、共享数据模型 deployer)以及需要哪些服务实例(XSUAA、HANA、HTML5 Repo、Destination、SaaS Registry、Service Manager、Credential Store…)。mtaext/里是环境相关的覆盖项(服务计划、凭据、邮箱路径),config/里是服务配置文件。你改的几乎都应该是 mtaext,而不是 mta.yaml。构建前必须让 CAP 先产出生产工件。 如果你改过 CDS 数据模型或注解,构建镜像/归档前要先跑
cds build --production(或通过仓库的构建脚本触发),否则打包进去的还是旧的 CSN 与注解。官方文档反复强调这一点,因为它是最常见的「代码改了但部署没生效」原因。mbt build与cf deploy其实是两步。 前者只负责打包(在mta_archives/下产出.mtar),后者才真正与平台交互:创建/更新服务实例、上传应用、启动、跑一次性 Job。所以「构建成功」不等于「部署成功」,出问题要看cf deploy的日志而不是 mbt 的输出。
怎么点/怎么填。
在
deploy/cf目录执行构建。推荐构建时就引用 mtaext,这样部署命令更短:
mbt build -e ./mtaext/free-basic-private.mtaext
Trial 环境把文件名换成
trial-basic-private.mtaext。如果你在这步没引用 mtaext,也没关系,下一步部署时用-e补上即可。
部署生成的 mtar。归档文件名带版本号,示例是
susaas_0.0.1.mtar:
cf deploy mta_archives/susaas_0.0.1.mtar
如果构建时没带 mtaext,则:
cf deploy mta_archives/susaas_0.0.1.mtar -e ./mtaext/free-basic-private.mtaext
cf deploy会按mta.yaml的顺序创建服务实例、部署共享数据库模型、推送静态资源、启动应用。整个过程通常 10–20 分钟,终端会滚动输出每一步的状态(Creating service instance ...、Uploading application ...、Started)。不要中断,中断后重跑cf deploy会做增量续传。部署开始后不久,Alert Notification 会给你发一封确认邮件,必须点确认,否则后续收不到告警。

验证。 三处都要对:
cf apps里能看到 4 个应用(susaas-router、susaas-srv、susaas-api、susaas-broker),状态都是started。SAP BTP Cockpit → 提供方子账户 → Instances and Subscriptions 里能看到一整套服务实例,包括 Credential Store、XSUAA(application/broker)、HTML5 App Repository、Destination、Service Manager、SaaS Registry、HANA HDI 等。
在浏览器打开
susaas-router的路由,能看到登录页或启动台(此时还没订阅租户,登录后可能提示无权限,这是正常的)。

步骤 5:在 Credential Store 中写入自动化凭据
做什么。 订阅自动化过程中,后端需要两个「只有你知道」的凭据:一个是能管理子账户的技术用户,一个是 broker 用户的明文密码。它们不能写进代码或环境变量,示例的做法是放进 SAP Credential Store 的 susaas 命名空间。漏掉这一步,订阅会卡在预配阶段。
怎么点/怎么填。
提供方子账户 → Instances and Subscriptions → 找到
<SpaceName>-susaas-credstore实例 → 点它(或 Manage Instance)。

切到 Credential Store 菜单 → 点 Create Namespace。

命名空间必须和第一个凭据一起创建,所以凭据类型选 Password → Next。

填第一个凭据:命名空间
susaas,Namebtp-admin-user,Value 填该用户密码,Username 填该用户邮箱。这个用户必须在你提供方子账户里拥有 Subaccount Administrator 角色集合,并在对应 CF Space 里拥有 Space Developer 角色;自己测试时用当前账号即可(建议不要在生产用 P/S 用户跑技术任务)。

再建第二个 Password 凭据:Name
susaas-broker-credentials,Value 填步骤 3 里hash-broker-password输出的明文密码,Username 填broker-user。


验证。 Credential Store 的 susaas 命名空间下有两个名字完全一致的凭据:btp-admin-user、susaas-broker-credentials。名字错一个字母,自动化就会在后续订阅时报错找不到凭据。
步骤 6:创建租户子账户并订阅 SaaS 应用
做什么。 现在切换身份:你不再是提供方,而是第一个客户(消费方)。你要在同一个全局账户下建一个「租户子账户」,然后在它的 Cockpit 里点订阅。这一步会把前面准备好的所有自动化跑起来:建 HDI 容器、注册 API broker、创建 CF Route、把 scope/role collection 复制进租户。
怎么点/怎么填。
在全局账户 → Account Explorer → 创建子账户,作为你的第一个租户。区域必须与提供方子账户同区域(否则订阅不可见)。保留系统自动生成的子域(形如
tenant-a16ef7),不要图省事改成tenant——子域在每个区域内必须唯一,撞名后很难处理。

重要:租户子账户不需要启用任何运行时(Cloud Foundry 或 Kyma)。租户只是消费 SaaS,不跑工作负载。
进入租户子账户 → Instances and Subscriptions → 点 Create。

在服务下拉列表里选 Sustainable SaaS。
如果你在同一区域部署过多套(多个 Space 或多个 Kyma 命名空间),用 Service Id 区分:Cloud Foundry 下格式为
susaas-<Space>-<Organization>,Kyma 下格式为<ReleaseName>-<Namespace>-<ShootName>。

计划选
default(Kyma 路线此时还会让你填自定义子域,CF 路线直接跳过),点 Create。等待状态变成 Subscribed。这一步可能要几分钟:后台正在为该租户创建 HANA HDI 容器、部署租户数据模型、注册 API 服务代理、创建 CF Route。状态变成
Subscribed之后,路由和权限可能还要再多等几秒。
排查用的小技巧:订阅不是「一个动作」,而是一条链。大致顺序是——SaaS Registry 记录订阅 → 回调进入
susaas-srv→ 建 HANA 容器并部署租户模型 → 注册 API broker → 建 Destination → 建 CF Route/API Rule → 复制 role collection。所以当订阅卡住时,先判断卡在哪一环:susaas-srv日志里有 HDI 报错就是数据库层;有 broker 注册报错就是平台 API 层;状态是Subscribed但打不开 URL,多半是路由/Role 还没同步。

验证。 回到提供方子账户看三条线索:cf apps 里 susaas-router 多了一条新路由(形如 tenant-a16ef7-susaas-router-<space>.cfapps.<region>.hana.ondemand.com);HANA Cloud 里多了一个 HDI 容器;租户子账户的 XSUAA 里出现了新复制的 role collection。如果订阅一直是 Subscribing,先看提供方 susaas-srv 的日志(cf logs susaas-srv --recent),常见原因是 Credential Store 里的两个凭据、权益缺失或 HANA 实例已停止。
步骤 7:创建 API Service Broker 实例与服务绑定
做什么。 订阅成功后,Sustainable SaaS API 这个服务已经出现在租户子账户的服务目录里(因为订阅时 broker 被自动注册了)。现在以客户身份创建该 API 的实例与服务绑定,拿到调用 API 的 client credentials。这是后面推数据、以及客户 S/4HANA 集成的入口。
怎么点/怎么填。
租户子账户 → Instances and Subscriptions → Create,在列表里选 Sustainable SaaS API。
同样用 Service Id 区分多套部署:CF 下是
susaas-api-<Space>-<Organization>,Kyma 下是<Release>-api-<Namespace>-<ShootName>。

计划选
default,Runtime Environment 选 Other,实例名例如susaas-api,点 Create。

实例创建完成后,它出现在服务实例列表里。

选中该实例,创建服务绑定(名字例如
default)。绑定是「凭据的载体」,一个实例可以建多个绑定。

打开绑定查看 Client Credentials:里面有
apiUrl(API 端点)、uaa.url、uaa.clientid、uaa.clientsecret。

重要:client id / secret 对每个租户都是唯一的。用这份凭据换来的 token 里带着租户信息,CAP 据此决定把数据写进哪个 HDI 容器。所以这既是「认证凭据」,也是「租户路由凭据」,不要跨租户混用。
验证。 绑定状态为 Created,点开明细能看到非空的 apiUrl 与 clientid。把这四个值抄到一个临时文本里(下一步就要用),但不要提交到 Git。
步骤 8:初始化第一个租户管理员
做什么。 SaaS 应用有自己的应用内用户管理体系,但「第一个管理员」没法自己从应用里冒出来——必须由提供方在开通阶段临时提权、进应用创建、再撤回权限。这是整个流程里唯一一次需要在 Cockpit 里手工分配角色集合。
怎么点/怎么填。
在租户子账户里,把 Susaas Administrator 角色集合临时分配给你自己(执行开通的提供方用户)。如果有多次部署,注意选对角色集合(Kyma 里括号内容为
<ReleaseName>-<Namespace>,CF 里包含 Space 名)。

三个角色集合的分工:Susaas Administrator 能建项目、把成员分配到项目、建评估、给租户加用户;Susaas Member 只能在自己参与的项目里建评估;Susaas Extension 供租户开发者用 CAP 标准扩展机制扩展应用。
回到 Instances and Subscriptions,点开订阅,用无痕窗口打开应用(让刚分配的 scope 生效)。

用管理员账号登录后,进入 Manage Users。你会看到应用内用户管理界面——注意:这套用户列表与 BTP Cockpit 的 Users 是两套视图,手工在 Cockpit 里建的用户不会出现在这里。

点 Manage Users 磁贴进入用户管理。这是租户视角下管理成员的唯一正确入口。

点 Create 新建租户管理员。

填名、姓与有效邮箱。基础版本要求这个邮箱必须已存在于 SAP ID Service(例如有效的 S 用户或 P 用户),否则创建会失败。

在角色选择里选 Susaas Administrator,点 Create。这一步会同时在租户 HDI 容器里写入用户记录,并通过平台 API 在租户子账户里创建影子用户、分配角色集合。

返回用户列表,能看到刚创建的管理员。

回到租户子账户 → Users,确认该用户已存在且带有 Susaas Administrator 角色集合。

打开订阅详情,复制租户专属 URL,发给这位管理员。之后租户内的用户、角色都由管理员在应用内维护。

收尾:从你自己的用户上移除 Susaas Administrator 角色集合。临时提权只用于开通第一位管理员。
验证。 用管理员邮箱(或另一个普通用户)打开租户 URL,能进入启动台;用非管理员账号访问 Manage Users 时应被拒绝——这说明角色确实生效且隔离正确。
步骤 9:以租户身份向 SaaS API 推送数据
做什么。 应用刚建好时是空的,评估里选不到产品。这一步用租户的 API 凭据把示例产品、销售订单、回收数据推进该租户的 HDI 容器,顺便验证「API token → 租户容器」这条链路真的通了。
怎么点/怎么填。
先认识租户数据模型。下面这些表会随租户创建而部署到租户容器里,API 与 UI 都围绕它们工作;
Products、销售订单、回收数据是 API 可维护的主要实体,Roles表仅本地开发用(BTP 上角色来自 XSUAA)。

API 端点除了标准 CRUD,还提供了批量操作(批量插入、批量更新、Upsert、批量删除),以及一个用 HANA 存储过程实现销售订单 Upsert 的 OData Action 示例。


回到租户子账户,确认服务绑定的凭据可用(右上角可查看 Service Key)。

在本地仓库进入
code/test/http目录,新建.env文件,填入租户专属的客户端凭据:
xsuaaHostname=<<uaa.url in service key>>
btpXsuaaClient='<<uaa.clientid in service key>>'
btpXsuaaSecret='<<uaa.clientsecret in service key>>'
apiEndpointBtp=<<apiUrl (!not uaa.apiUrl!) - field from Service Binding>>

提示:
xsuaaHostname对应uaa.url,apiEndpointBtp对应apiUrl(不是uaa.apiUrl)。.env和任何.http文件都不要提交;建议把文件改名为*-private.http,仓库已用.gitignore排除。
先请求 OAuth token(VS Code 里用 REST Client 插件点 Send Request):
# @name getXsuaaToken
POST {{$dotenv xsuaaHostname}}/oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
client_id={{$dotenv btpXsuaaClient}}
&client_secret={{$dotenv btpXsuaaSecret}}
&grant_type=client_credentials
用拿到的 token 批量上传产品:
@access_token = {{getXsuaaToken.response.body.$.access_token}}
# @name uploadProductsBtp
POST {{$dotenv apiEndpointBtp}}/rest/api/bulkUpsertProducts
Authorization: Bearer {{access_token}}
Content-type: application/json
{
"products" : [
{"ID":"HT-1000","typeCode":"PR","category":"Notebooks","supplierId":"0100000046","taxTarifCode":1,"measureUnit":"EA","weightMeasure":4.2,"weightUnit":"KG","price":956,"text":"Notebook Basic 15","language_code":"E","currency_code":"EUR"},
{"ID":"HT-1001","typeCode":"PR","category":"Notebooks","supplierId":"0100000047","taxTarifCode":1,"measureUnit":"EA","weightMeasure":4.5,"weightUnit":"KG","price":1249,"text":"Notebook Basic 17","language_code":"E","currency_code":"EUR"},
{"ID":"HT-1002","typeCode":"PR","category":"Notebooks","supplierId":"0100000048","taxTarifCode":1,"measureUnit":"EA","weightMeasure":4.2,"weightUnit":"KG","price":1570,"text":"Notebook Basic 18","language_code":"E","currency_code":"USD"},
{"ID":"HT-1003","typeCode":"PR","category":"Notebooks","supplierId":"0100000049","taxTarifCode":1,"measureUnit":"EA","weightMeasure":4.2,"weightUnit":"KG","price":1650,"text":"Notebook Basic 19","language_code":"E","currency_code":"EUR"},
{"ID":"HT-1055","typeCode":"PR","category":"Multifunction Printers","supplierId":"0100000069","taxTarifCode":1,"measureUnit":"EA","weightMeasure":6.3,"weightUnit":"KG","price":99,"text":"Multi Print","language_code":"E","currency_code":"EUR"},
{"ID":"HT-1056","typeCode":"PR","category":"Multifunction Printers","supplierId":"0100000070","taxTarifCode":1,"measureUnit":"EA","weightMeasure":4.3,"weightUnit":"KG","price":119,"text":"Multi Color","language_code":"E","currency_code":"JPY"},
{"ID":"HT-1060","typeCode":"PR","category":"Mice","supplierId":"0100000071","taxTarifCode":1,"measureUnit":"EA","weightMeasure":0.09,"weightUnit":"KG","price":9,"text":"Cordless Mouse","language_code":"E","currency_code":"EUR"},
{"ID":"HT-1063","typeCode":"PR","category":"Keyboards","supplierId":"0100000074","taxTarifCode":1,"measureUnit":"EA","weightMeasure":2.1,"weightUnit":"KG","price":14,"text":"Ergonomic Keyboard","language_code":"E","currency_code":"BRL"},
{"ID":"HT-1120","typeCode":"PR","category":"Keyboards","supplierId":"0100000065","taxTarifCode":1,"measureUnit":"EA","weightMeasure":1,"weightUnit":"KG","price":29,"text":"Cordless Bluetooth Keyboard","language_code":"0","currency_code":"EUR"}
]
}
再补一次「扩展产品数据」,把销售拆分与可持续性字段写进同一条产品记录(这些字段不属于 EPM 模型,只用于演示循环性场景):
# @name uploadProductsExtendedBtp
POST {{$dotenv apiEndpointBtp}}/rest/api/bulkUpsertProducts
Authorization: Bearer {{access_token}}
Content-type: application/json
{
"products" : [
{"ID": "HT-1000","eolProductDesign": 43,"traditionalSalesShare": 82,"repairSalesShare": 8,"resellSalesShare": 10},
{"ID": "HT-1001","eolProductDesign": 38,"traditionalSalesShare": 97,"repairSalesShare": 3,"resellSalesShare": 0},
{"ID": "HT-1002","eolProductDesign": 35,"traditionalSalesShare": 87,"repairSalesShare": 5,"resellSalesShare": 8},
{"ID": "HT-1003","eolProductDesign": 42,"traditionalSalesShare": 74,"repairSalesShare": 20,"resellSalesShare": 6},
{"ID": "HT-1055","eolProductDesign": 56,"traditionalSalesShare": 98,"repairSalesShare": 1,"resellSalesShare": 1},
{"ID": "HT-1056","eolProductDesign": 49,"traditionalSalesShare": 95,"repairSalesShare": 3,"resellSalesShare": 2},
{"ID": "HT-1060","eolProductDesign": 25,"traditionalSalesShare": 99,"repairSalesShare": 0,"resellSalesShare": 1},
{"ID": "HT-1063","eolProductDesign": 34,"traditionalSalesShare": 97,"repairSalesShare": 1,"resellSalesShare": 2},
{"ID": "HT-1120","eolProductDesign": 28,"traditionalSalesShare": 95,"repairSalesShare": 2.5,"resellSalesShare": 2.5}
]
}
其余数据(销售订单、按国家回收、按材料回收)用同一目录下的
apiSalesOrders.http、apiRecyclingCountries.http、apiRecyclingMaterials.http,同样在文件顶部指定租户凭据即可。
为什么 API 要设计成「批量 Upsert」而不是逐条 POST?因为客户的数据通常来自 S/4HANA 等系统,一次同步可能几千上万条,逐条调用既慢又容易失败。批量接口由 CAP 的 upsert 能力或 HANA 存储过程实现,一次事务内完成,失败可以整体回退;示例还专门给销售订单做了一个调用 HANA 存储过程的 OData Action,用来演示「复杂业务逻辑下沉到数据库层」的写法。对 SaaS 来说这类设计很重要:API 是租户数据的入口,入口的吞吐与幂等性直接决定客户集成的体验。
验证。 上传成功后,回到应用里新建评估,产品的值帮助里应该能选到 HT-1000 等产品;基于 HT-1000 建的评估长这样:

如果 token 请求返回 Unauthorized,先把 client id/secret 做 URL 编码再试(有些工具不会自动编码)。
步骤 10:从租户视角端到端测试应用
做什么。 前面验证的都是「链路通」,这一步验证「业务通」:以租户管理员身份建项目、建评估、录循环性数据、加成员、加用户。也顺便把 UI 的 Fiori Elements 行为摸一遍。
怎么点/怎么填。
打开租户 URL 登录,看到首页。首页是启动台的入口,也是各应用的导航中心。

点 Manage Projects,进入项目列表。

点 Create,进入创建项目向导。

填写项目详情(例如项目名
My Test Project)后点 Create。

切到 Assessments 标签页,点 Create 创建评估。

从值帮助里选一个产品,点 Continue,项目会自动预填。

输入必填的说明,点 Create 完成创建。

切到 Circularity Metrics 标签页,点 Edit 录入循环性数值。

填入示例数值后点 Save。

切到 Sales Splits,点 Edit 录入销售拆分。

填入示例销售拆分后点 Save。

切到 Material Splits,点 Edit 录入材料拆分。

填入示例材料拆分后点 Save。

每个标签页都有 Prefill 按钮:如果你在步骤 9 推过数据,它会用 API 上传的数值自动填表。下面是三个摘要视图的效果。



回到首页,点 Manage Users 管理租户用户。

点 Create 新建一个普通成员用户。

填必填项。基础版本里这个邮箱同样必须已存在于 SAP ID Service,角色选 Susaas Member。

创建完成后在列表里确认。

回到 Manage Projects,选中刚才的
My Test Project。

在 Members 区域点 Edit 添加项目成员。

从值帮助里选刚创建的成员用户,点 Save。

验证。 用成员用户登录(无痕窗口),应能在被分配的项目里创建评估,但进不了用户管理;用管理员登录则两者都能做。这就验证了 XSUAA scope 在租户内生效。
步骤 11:订阅第二个租户,验证数据隔离
做什么。 多租户最核心的验收不是「能登录」,而是「租户之间真的看不见彼此」。方法很简单:再建一个租户子账户、再走一遍订阅与初始化,然后在两个租户里各建数据,交叉检查。
怎么点/怎么填。
重复步骤 6:在全局账户下再建一个租户子账户(同样保留自动生成的子域),订阅 Sustainable SaaS,等状态变成
Subscribed。重复步骤 7:在这个租户里创建 Sustainable SaaS API 实例与服务绑定。注意不要复用第一个租户的 client credentials——每个租户的
clientid/clientsecret都不同。重复步骤 8:临时提权 → 用该租户的 URL 打开应用 → 创建第二个租户的管理员 → 撤回提权。
在租户 B 里建一个项目
Tenant B Project,建一个评估,录几个不同的循环性数值;在租户 A 里也建一个Tenant A Project。交叉验证:
用租户 A 管理员登录租户 A 的 URL:项目列表里只有
Tenant A Project,看不到Tenant B Project。用租户 B 管理员登录租户 B 的 URL:项目列表里只有
Tenant B Project。在两个租户里分别访问对方的 URL:应被拒绝(用户不属于该身份区域)。
到 HANA Cloud Central 查看:应该有两个租户 HDI 容器,外加一个共享容器。
验证。 满足以下三条即通过:
两个租户的应用 URL 不同,且互相无法登录。
两个租户的业务数据互不可见(项目、评估、用户列表都是各自的)。
提供方自己登录
susaas-router的通用路由,看不到任何租户业务数据——提供方只有开通与运维权限,不是业务租户。
还可以从 API 层再验一次,这比看界面更有说服力:用租户 A 的 client credentials 换 token,调用读取产品的接口,返回的应该只有 A 推过的数据;换成租户 B 的凭据,应该完全看不到 A 的产品。如果两个 token 读到同一批数据,说明 token 里的租户信息没有被正确解析,或者你在 .env 里混用了凭据。这个实验也顺便证明了「API 凭据 = 租户身份」这条设计:客户不需要知道自己的容器名,凭据就代表了他的租户。
说明:共享数据库容器里的主数据(例如货币、国家)是故意让所有租户都看到的;业务数据永远在各自的租户容器里。如果两个租户能看到同一份业务数据,八成是租户识别没生效(
TENANT_HOST_PATTERN配置错误、订阅没有走完、或者你用了提供方的通用路由登录),先查 Application Router 的日志。
步骤 12:升级——发布新版本并升级租户数据库容器
做什么。 SaaS 的生命周期里,升级比首次部署更常见。这里要区分两层升级,很多人会混淆:
层级 |
升级内容 |
怎么做 |
影响范围 |
|---|---|---|---|
应用升级 |
代码、UI、依赖、服务配置 |
重新 |
所有租户立即生效 |
租户数据库升级 |
CDS 数据模型变更(加/删字段、改表) |
单独调用租户部署接口,把最新模型部署进每个租户容器 |
只影响被指定的租户 |
为什么数据模型要单独升级? 因为租户容器是在订阅时创建的,之后你在 CDS 里加的字段不会自动同步到已存在的容器。你部署了新版本,但老租户的数据库结构还是旧的,查询新字段就会报错。所以每次改数据模型,都要对存量租户执行一次「租户容器部署」。
模型变更的风险等级也值得心里有数,不是所有改动都一样危险:
变更类型 |
典型操作 |
风险 |
注意 |
|---|---|---|---|
加字段(可空) |
|
低 |
对存量数据无影响,最安全 |
加表/加视图 |
新增 |
低 |
记得同步注解,否则 Fiori 界面看不到 |
改字段类型/长度 |
|
中 |
HANA 可能要求重建列,先备份 |
加非空约束/唯一约束 |
|
中高 |
存量数据可能违反约束导致升级失败 |
删字段/删表 |
删除定义 |
高 |
数据不可恢复,务必先备份并确认没有代码引用 |
所以推荐的节奏是:先在测试租户上升级 → 检查容器里的表结构与应用功能 → 再对生产租户逐批升级。CAP 只保证「把最新模型部署进去」这个动作可用,不保证你的模型变更是向后兼容的。
怎么点/怎么填。
在本地给租户数据模型加一个示例字段(
code/db/data-model.cds的Users实体里):
context susaas.db {
...
@assert.unique : {email : [email]}
entity Users : cuid, managed {
@Core.Computed:true
fullName : String;
firstName : String;
lastName : String;
email : String;
shadowId : UUID;
iasLocation: String;
dummy : String; // new added column
// associations
role : Association to Roles;
}
...
重新构建并部署应用(Cloud Foundry):
## Run in ./deploy/cf ##
mbt build -e mtaext/free-basic-private.mtaext
cf deploy mta_archives/susaas_0.0.1.mtar
如果你当前部署在高级版本上,把 mtaext 换成对应的 free-advanced-private.mtaext。Kyma 路线的等价命令是:
## Run in ./code ##
make build
make pack IMAGE_PREFIX=<your-image-prefix>
make push-all IMAGE_PREFIX=<your-image-prefix>
helm upgrade susaas gen/chart -n mtenant
拿到提供方
susaas-srv的 XSUAA 客户端凭据(用于调用租户升级接口):
# Cloud Foundry
cf create-service-key <CfSpace>-susaas-uaa susaas-uaa-key
cf service-key <CfSpace>-susaas-uaa susaas-uaa-key

如果你走的是 Kyma 路线,等价命令是:
kubectl get secret <ReleaseName>-srv-xsuaa -o jsonpath='{.data.clientid}' | base64 --decode | awk '{print "Client-Id: "$1}'
kubectl get secret <ReleaseName>-srv-xsuaa -o jsonpath='{.data.clientsecret}' | base64 --decode | awk '{print "Client-Secret: "$1}'
kubectl get secret <ReleaseName>-srv-xsuaa -o jsonpath='{.data.url}' | base64 --decode | awk '{print "XSUAA-Url: "$1}'
把服务 Key 里的值填进
code/test/http/tenantUpgrade.http的占位符(建议先复制成tenantUpgrade-private.http)。左侧是变量,右侧是服务 Key 里对应的字段:

填入 SaaS 后端服务的 URL。Cloud Foundry 下在 Cockpit 的
susaas-srv应用路由里能看到:

填入消费方子账户的 Tenant Id(在租户子账户概览页):

先请求 XSUAA token,再调用租户部署接口:
##########################################
# Get SAP XSUAA token
##########################################
# @name getXsuaaToken
POST {{xsuaaUrl}}/oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {{xsuaaClientId}}:{{xsuaaClientSecret}}
?client_id={{xsuaaClientId}}
&client_secret={{xsuaaClientSecret}}
&grant_type=client_credentials
################################################
# Call CAP endpoint (BTP) For DB Model Upgrade
################################################
@access_token = {{getXsuaaToken.response.body.$.access_token}}
# @name upgradeTenantDBModel
POST {{srvUrl}}/-/cds/deployment/upgrade
Authorization: Bearer {{access_token}}
Content-type: application/json
{ "tenant": "{{tenantId}}" }
注意:请求里的
tenant只指定一个租户。多租户 SaaS 必须逐个升级存量租户(或自己写脚本批量调用),CAP 不会自动帮你把所有租户容器都刷一遍。
验证。 打开 HANA Cloud Central → 该租户的 HDI 容器 → 查看 USERS 表结构,应该多出 DUMMY 列;同时进入租户应用,用户管理页面仍能正常打开(说明新字段没破坏旧数据)。再对照没升级的第二个租户:它的 USERS 表里没有 DUMMY 列——这恰好证明租户容器的升级是逐租户、可控的。
步骤 13:回滚——应用版本与数据模型的退路
做什么。 升级出问题时,要能快速退回上一个可用状态。多租户场景下回滚分三层,越往下代价越大:
层级 |
回滚方式 |
代价 |
适用场景 |
|---|---|---|---|
应用/UI 回滚 |
还原代码 → 提高版本号 → 重新构建部署;Kyma 用 |
低,分钟级 |
新版有 bug、界面异常、接口报错 |
租户数据库回滚 |
恢复 HANA 容器备份 / 重建容器后重放数据 |
中高,需要备份 |
模型变更写坏了数据 |
整租户回滚 |
先取消订阅,再重新订阅(会新建空容器) |
高,数据丢失 |
租户容器彻底损坏且无备份 |
怎么点/怎么填。 在动手之前,先确认三件事,否则「回滚」可能变成「扩大事故」:
确认回滚目标版本是可部署的。 旧代码如果在依赖、服务计划或数据模型上与当前环境不兼容(例如新版已经给租户容器加了字段),直接回滚应用可能启动失败。必要时同时回滚数据模型或补兼容代码。
确认回滚不影响其他租户。 应用回滚是全局的(所有租户一起回到旧版),所以要么快速修复,要么用 Feature Toggle/灰度把影响面压小。租户数据库升级则可以逐租户控制,这正是它比应用回滚更安全的地方。
确认在租户身上动过什么。 如果事故源于某次租户模型升级,回滚应用只能止住新请求,已经写坏的数据要单独修;先把出问题的租户隔离出来(暂停其 API 调用或停掉路由),再评估恢复方案。
Cloud Foundry 路线:
用 multiapps 插件查看当前部署的 MTA 版本与模块状态:
cf mta susaas(命令名与输出字段以你安装的插件版本为准)。从 Git 回到上一个可用提交:
git checkout <上一个可用的 commit/tag>。在
mta.yaml里把version调高(例如从0.0.1调到0.0.2),然后重新mbt build+cf deploy。multiapps 插件对同版本/低版本会拒绝或告警,所以「用旧代码 + 新版本号」是最常用的应用回滚手法。如果部署本身已经损坏到无法增量回滚,才考虑
cf undeploy susaas --delete-services --delete-service-keys再重新部署——注意这会删掉服务实例与数据,执行前必须先取消所有租户订阅(见下一节)。
Kyma 路线则简单得多,Helm 天生带版本历史:
# 查看发布历史
helm history susaas -n mtenant
# 回滚到指定 revision
helm rollback susaas <revision> -n mtenant
验证。 回滚后:应用首页能打开、订阅状态仍是 Subscribed、租户能正常登录并看到原数据;用 cf mta susaas(或 helm history)确认当前版本号是回滚后的版本。
重要:租户数据库的模型升级不会自动回滚。回滚应用版本不会把已加上的列删掉,也不会把写坏的数据修回来。所以正确的做法是:先在测试租户上验证模型变更 → 对生产租户逐批升级 → 每个批次前确认 HANA 容器备份可用。租户容器备份的具体做法在专家特性「备份数据库容器」一节(见文末索引)。
验收与清理
验收清单
按顺序打勾,任何一项不通过都不要往下走:
提供方子账户里 4 个应用
started,cf apps输出无crashed。提供方子账户里服务实例齐全(XSUAA application/broker、HTML5 Repo、Destination、SaaS Registry、Service Manager、Credential Store、HANA)。
两个租户子账户各有且仅有一条
Subscribed状态的 Sustainable SaaS 订阅。两个租户的 URL 不同,互相登录被拒绝,业务数据互不可见。
每个租户都有自己的 API 服务实例与服务绑定,
apiUrl/clientid各不相同。每个租户都能通过 API 推送数据,并在 UI 里建评估、加成员。
每个租户的 HDI 容器独立,共享容器只含主数据。
至少完成一次应用升级 + 一次租户数据库升级,并验证回滚路径可用。
Alert Notification 已确认收件邮箱,能收到测试告警。
建议把这份清单复制成自己的验收记录,每次升级/新增租户后重跑一遍。多租户系统最怕「上线时是通的,三个月后某个租户的容器悄悄坏了没人知道」——定期巡检比事后救火便宜得多。
清理:先订阅、后应用、最后服务
清理顺序极其重要,顺序错了会在平台里留下无法删除的残留(尤其是 Service Broker 注册与 XSUAA 凭据克隆)。标准顺序是:服务绑定 → 服务实例 → 订阅 → 应用/服务实例 → 子账户。
在每个租户子账户里删除 API 的服务绑定。

删除 API 服务实例。

取消订阅 SaaS 应用。删除前该子账户的状态大致如下图(订阅 + API 实例都在)。


检查 API 服务代理是否已自动注销:再次点 Create 时,Sustainable SaaS API 不应再出现在列表里,只剩 SaaS 应用本身。

等所有租户都取消订阅后,再在提供方子账户取消部署应用:
cf login -a https://api.cf.<region>.hana.ondemand.com
cf undeploy susaas --delete-services --delete-service-keys
警告:务必使用最新版
cfCLI 与最新版 multiapps 插件,旧版插件没有--delete-service-keys选项。
删除租户子账户。如果报「仍有 Service Broker 注册」之类的错误,不要用强制删除。先去租户子账户里查并手动注销残留 broker:
btp list services/broker --subaccount <租户子账户ID>
btp unregister services/broker --name <broker名称> --url <broker URL> --user broker-user --password <broker密码> --subaccount <租户子账户ID>


删除失败时还有一个入口:Subscription Management Dashboard,可以用「跳过依赖回调」的方式删掉残留订阅。若 broker 应用已被卸载导致无法注销,只能先把应用重新部署回来,再按上面命令注销,最后重新清理。
验证。 全局账户 → Account Explorer 里租户子账户已消失;提供方子账户的 CF 环境里没有 susaas-* 应用、服务实例与密钥残留;HANA Cloud 里没有残留的租户容器;全局账户的用量(Usage)不再增长。
常见问题
多租户场景的报错有个规律:越靠前的环节越容易伪装成后面的问题。所以排错顺序建议是:先看权益与运行时是否可用(平台层)→ 再看部署日志与应用状态(应用层)→ 再看订阅状态与后端日志(开通层)→ 最后看凭据、路由与角色(访问层)。下面这张表按「现象 → 原因 → 处理」整理了这个案例里最常见的问题:
现象 |
原因 |
处理 |
|---|---|---|
|
提供方子账户没分配全部 entitlement(如 Credential Store、HTML5 Repo) |
回到步骤 2 按表补齐权益,再重跑 |
HDI 容器创建报错、部署卡在部署数据库模型 |
|
到 HANA Cloud Central 启动实例并等几分钟;确认 Instance Mapping 指向正确的 Org/Space |
Trial 环境部署时报服务计划不可用 |
用了 PAYG 的 |
改用 |
订阅一直 |
Credential Store 里两个凭据缺失或名字不对;broker 哈希凭据没粘对;HANA 实例已停止 |
看 |
租户打开应用 403 / 看不到磁贴 |
角色集合未分配,或 scope 未生效;也可能用了提供方通用路由登录 |
确认租户用户有 Susaas Administrator/Member;用无痕窗口重新登录;从租户专属 URL 进入 |
订阅成功但打开 URL 404 |
订阅状态先变 |
再等十几秒到几分钟;检查 |
应用里产品值帮助为空 |
没执行步骤 9 推数据,或 token 指向了错误的租户 |
重新执行 |
API 调用返回 Unauthorized |
client id/secret 含特殊字符未编码;或凭据来自别的租户 |
对 client id/secret 做 URL 编码后重试;用当前租户绑定里的值 |
租户升级后应用报「列不存在」 |
只升了应用、没升级租户数据库;或升级请求里的 tenant 填错 |
用 |
删除租户子账户失败 |
该子账户里还有 Service Broker 注册或残留订阅 |
先用 |
重复部署同一环境报冲突 |
XSUAA |
换 Space/命名空间或改前缀;租户子域保留自动生成值,不要改成 |
免费层资源莫名消失 |
Kyma trial 集群 14 天过期;CF trial 工作负载每天停止; |
用 PAYG/CPEA + free tier 做长期验证;每天开工先检查并启动运行时与数据库 |
订阅后 Cockpit 里看不到新复制的 role collection |
订阅尚未完全结束,或角色复制在依赖回调阶段失败 |
等订阅真正完成;若失败,检查 SaaS Registry 依赖配置与 |
部署成功但打开首页白屏/资源 404 |
UI 模块没被构建进 HTML5 App Repository,或 router 的 |
检查 |
修改 UI 后页面没变化 |
只改了 UI 源码但没重新构建部署,或浏览器缓存了旧资源 |
重新 |
其他场景索引
主线之外,这个示例仓库还有大量可单独成篇的场景。每个场景都对应一篇原文档,按需要点进去看:
阅读顺序建议:先看「认识篇」,再看与主线相关的两篇基础文档,最后按兴趣挑进阶/专家篇。进阶与专家篇默认你已经跑通主线,不再重复订阅、清理这类基础操作。
认识篇(SaaS 理念、BTP 账户模型、CAP 与 MTXS 概念):适合第一次接触多租户的人先读,解释提供方/消费方/租户/预配等术语 → 99-06-multitenant-saas-1-discover.md
基础实现全量(仓库结构、准备子账户、CF 构建部署、订阅租户、推送数据、测试、组件深潜):本篇主线的原始出处,含 Kyma 构建/部署、Helm Chart、Kyma 资源详解 → 99-06-multitenant-saas-2-basic-1.md
API 数据推送、应用测试、组件与服务代理原理:服务代理 OSB 流程、
@sap/sbf、XSUAAshared模式、CAP MTXS 深入解释 → 99-06-multitenant-saas-2-basic-2.mdKyma 路线:Helm Chart 与 Kyma 资源(Chart.yaml / values.yaml / templates、Umbrella Chart 与 Subchart) → 99-06-multitenant-saas-2-basic-3.md
Kyma 资源逐项拆解 + 取消订阅/取消部署:API Rule、Deployment、Istio、Network Policy、Job、Secret 等对象 → 99-06-multitenant-saas-2-basic-4.md
进阶:SAP IAS 集中用户管理、从 S/4HANA 推送数据、SAP API Management 集成(Cloud Foundry) → 99-06-multitenant-saas-3-advanced-1.md
进阶:Kyma 上的 API Management 集成与 SAP Cloud Logging 可观测性 → 99-06-multitenant-saas-3-advanced-2.md
专家:Redis 外部会话管理、SAP Cloud Transport Management、自定义域、多区域部署、多 HANA Cloud 实例、CI/CD(CF) → 99-06-multitenant-saas-4-expert-1.md
专家:SAP Theme Designer 多租户主题、Kyma 自定义域、CI/CD(Kyma) → 99-06-multitenant-saas-4-expert-2.md
专家:消费方 IdP 集成、本地与混合开发、Microsoft Graph 发邮件、更新租户数据库容器(本篇步骤 12 的完整版) → 99-06-multitenant-saas-4-expert-3.md
全量部署与任务收尾:把基础版 + 进阶 + 专家特性叠在一起部署的思路与收尾清单 → 99-06-multitenant-saas-5-complete.md
官方原文(参考)
本案例导读与总览(原始文档页):99-06-multitenant-saas.md
官方仓库(含全部代码、Helm Chart、MTA 部署描述与截图):https://github.com/SAP-samples/btp-cap-multitenant-saas
仓库 ISSUE(遇到本文未覆盖的问题时先搜这里):https://github.com/SAP-samples/btp-cap-multitenant-saas/issues
CAP 多租户(MTXS)官方文档:https://cap.cloud.sap/docs/guides/multitenancy/mtxs
CAP 官方文档总入口:https://cap.cloud.sap/docs/
SAP Help:开发多租户应用:https://help.sap.com/docs/btp/sap-business-technology-platform/develop-multitenant-application
SAP Help:SAP BTP 中的多租户与 SaaS 应用:https://help.sap.com/docs/btp/sap-business-technology-platform/multitenancy-and-saas-applications
本篇与官方原文的关系:主线(CF 部署 → 订阅 → 升级/回滚)是把官方 2-basic 系列与 4-expert 的「更新租户数据库容器」按可执行顺序重新编排的中文图文版,截图取自官方仓库文档目录并已本地化;Kyma 路线、进阶特性与专家特性只在「其他场景索引」列出入口,等你把主线跑通后再逐篇展开。