SAP BTP Cockpit 常见问题：五个故障及其修复方法

如果 SAP BTP Cockpit 给您报错，多半是五种情况之一。服务密钥返回的 401，几乎总是 OAuth 请求的问题，而不是凭据的问题。Integration Suite 上的内部服务器错误，通常意味着缺少角色集合或会话已过期。失效的链接，来自在子账户发生变化之前就设置好的 Booster。CAP 的 destination 失败，通常是名称不匹配或缺少绑定。而在试用账号上昨天还能用的应用，可能已经一夜之间丢了它的数据库。本指南写给在 Cloud Foundry 子账户中工作的开发人员和集成顾问。下面的分诊表告诉您首先该检查什么。

第一次在 SAP BTP Cockpit 里看到红色的错误横幅时，我以为是自己哪里做错了。链接不对，会话过期。

遇到第三次、第四次之后，就清楚了，不是只有我一个人这样。

接下来的几周，我准备了一个笔记本，每次出问题都记下来。打开 Integration Suite 时出现内部服务器错误。看起来有效、却拒绝连接的 destination。昨天还能用、今天卡住的应用。规律逐渐浮现。很少有哪里把这些记录得有用，而 Cockpit 本身几乎没给您任何可以依据的线索。

症状	最可能的原因	首先检查
用服务密钥调用 API 时返回 401 Unauthorized	授权类型不对、令牌 URL 不对或缺少权限	解码令牌，查看 aud 和 scope
打开 Integration Suite 时出现内部服务器错误	缺少角色集合，或会话已过期	您用户名下的角色集合，然后完全注销
Booster 或磁贴打开的是空白页或错误页面	Booster 运行之后，子账户发生了变化	改为通过 Cockpit 目录树导航
CAP 应用：“destination not found”或认证错误	名称不匹配、缺少绑定、OData 的 kind 不对	把 cds.requires 和 xs-app.json 与 Cockpit 中的名称对照
应用昨天还能用，今天卡住（试用版）	HANA Cloud 实例一夜之间停止了	SAP HANA Cloud Central 中的数据库实例状态

Cloud Foundry、Kyma 和 ABAP 环境，都运行在 SAP 的多云基础之上，自 2020 年起，这就是新客户的默认选择。较早的 Neo 环境只提供安全和合规更新，SAP 已将其终止日期定为 2028 年 12 月 31 日。下面几乎每一个问题，都是 Cloud Foundry 的问题。

有两处更名，仍会让阅读旧指南的人困惑。SAP Launchpad service 在 2023 年 1 月更名为 SAP Build Work Zone, standard edition。而且随着 SAP Build 的发展，许多磁贴和 Booster 被重新构建，所以 2022 年的截图常常与您现在看到的不再一致。

在 RISE with SAP 下，BTP 通常以基于额度的权益形式，包含在合同中。Cockpit 是一样的。不同的是，贵组织里是谁在掌管全局账户，所以要在需要新权益之前，先找到这个人。

您创建了一个服务实例，生成了服务密钥，把 client ID 和 secret 复制到 Postman，加上令牌 URL，然后发送请求。401。没有任何细节。

您再复制一遍 secret。还是失败。服务本身没问题。OAuth 流程有问题。

按顺序检查：

1. 授权类型。 对大多数 BTP 服务 API 的技术访问，使用 client_credentials。在 Postman 中明确设置它。不要信任默认值。
2. 令牌 URL。 从服务密钥中获取。有些密钥给出的是 tokenurl；另一些给出的是 XSUAA 的 url，需要在后面加上 /oauth/token。切勿借用另一个子账户的。
3. 请求头。 对于直接的令牌调用，发送 Content-Type: application/x-www-form-urlencoded 和 Authorization: Basic <base64(clientid:clientsecret)>。
4. 权限。 使用客户端凭据时，令牌只携带授予该服务实例的范围（scope）。如果 API 需要的角色，这个实例没有，您仍然能拿到令牌，API 仍然会拒绝。要在实例参数中修复（例如 Integration Suite API 计划实例上的角色），而不是在请求里。
5. 受众（audience）。 如果您拿到了令牌，API 却拒绝，就解码令牌，读取 aud 声明。如果它与您调用的 API 不匹配，说明您用的是来自错误服务实例的密钥。

您打开 Integration Suite，出现红色的“Internal Server Error”横幅。没有日志。重新加载、换一个浏览器，结果相同。

这通常发生在服务闲置一段时间之后：早上打开，放了几个小时，之后再次使用。SAP 社区的帖子和知识库指向两个常见原因：缺少角色集合和过期会话。

通常能解决问题的做法：

1. 检查角色集合。 您的用户需要 Integration_Provisioner 来设置租户，还需要相应的 PI_ 角色集合（管理员、集成开发人员、业务专家）才能在其中工作。在子账户的 Security 下分配它们。
2. 彻底注销。 角色变更只有在重新登录后，才会作用到您的会话。关闭所有 BTP 和 Integration Suite 标签页，注销，再重新登录。
3. 如果重新登录后错误依旧，就清除 BTP 域名的 cookie。 过期的会话 cookie 可能比会话本身活得更久。
4. 只用一个 Cockpit 会话。 在同一个子账户上开多个标签页或浏览器配置文件，会造成会话冲突，看起来和这个错误一模一样。

真正的问题在于可见性。Cockpit 对哪里出了问题只字不提，所以您只能靠猜。按顺序逐项排查吧。关于集成项目为什么会停滞的更广泛视角，请参阅我那篇关于 SAP Integration Suite 交付延误的文章。

您点击“Go to Application”，得到的是空白屏幕、通用的落地页，或者莫名其妙的重定向。

这有规律可循：

1. Booster 运行之后，如果子账户的设置发生变化，Booster 的链接就会失效。重定向指向的地方已经不存在了。
2. Integration Suite 的磁贴有时能用，有时报错，有时超时，通常是因为上面讲的会话原因。
3. 当订阅存在、而您的用户缺少该站点的角色集合时，SAP Build Work Zone 的链接会显示“connection denied”。
4. 多个标签页或浏览器配置文件，会在已过期的上下文中打开链接。

有效的做法：通过 Cockpit 的目录树导航（子账户，然后是 Services，再是 Instances and Subscriptions），并为 Integration Suite、destination 和 Work Zone 的直接 URL 添加书签。在干净的浏览器配置文件里只用一个会话。当一个链接每三次就失败一次，您就不再信任这个平台，开始搭建各种变通办法。书签是最便宜的变通办法。如果您还在摸索如何使用，我的 BTP Cockpit 入门指南讲了基本的导航。

您部署了一个 CAP 应用，在 Cockpit 里配置了 destination，请求却仍然失败，报“destination not found”或认证错误。destination 就列在那里。应用也在运行。错误信息没有指向任何有用的地方。

SAP 的 CAP 文档对这应该如何连接讲得很清楚：远程服务在 package.json（或 .cdsrc.json）的 cds.requires 下声明，带有一个 kind，destination 名称放在 credentials.destination 下。应用还需要同时绑定 Destination 服务和 XSUAA。大多数失败，都是这条链上某个地方断了。

1. 01cds.requires声明远程服务、它的 kind 和 destination 名称
2. 02生产配置部署之后保存 destination 凭据
3. 03服务绑定应用绑定到 Destination 和 XSUAA
4. 04Cockpit 中的 destination与 cds.requires 和 xs-app.json 中的名称相同，大小写也要一致
5. 05远程服务V2 服务用 odata-v2，V4 用 odata

请求到达远程服务

症状	修复
destination 已列出，但应用找不到它	把 cds.requires 和 xs-app.json 路由中的名称与 Cockpit 逐字符对照，包括大小写
本地能运行，部署后失败	检查 [production] 配置是否真的包含 destination 凭据，以及应用是否已绑定 Destination 和 XSUAA
远程 OData V2 服务返回错误	V2 服务把 kind 设为 odata-v2，V4 则设为 odata。只要双方允许，就用 V4
UI5 应用需要 V2，但您的 CAP 服务是 V4	添加 @cap-js-community/odata-v2-adapter 插件。较早的 @sap/cds-odata-v2-adapter-proxy 已被弃用
凭据有效，认证却失败	先从 OAuth2ClientCredentials 或 BasicAuthentication 开始。只有在场景需要时，才用 SAML 或主体传播
不确定目标是否可达	在调试应用之前，先在 Cockpit 的 destination 上使用“Check Connection”

处理得好的团队，会为每个应用保存一份简短的 destination 检查清单。不是因为配置有多复杂，而是因为在名称、绑定或 OData 的 kind 上的一个错误假设，会悄无声息地失败，找出它所花的时间，远比预防它要长。

一个昨天还能用的 CAP 应用，现在卡住了。没有报错。Cockpit 显示它在运行。您重启它。没有用。

先检查数据库。SAP 自己的 HANA Cloud 试用教程写明，免费层的实例每晚都会停止，在您工作的每一天都必须重新启动。如果您定期登录，试用账号本身可以持续最多 90 天。您的应用没有问题。是它的数据库睡着了。

有帮助的做法：

1. 在开始调试代码之前，先在 SAP HANA Cloud Central 中重启 HANA Cloud 实例。
2. 用命令行（cf apps、cf services）查看内存和服务使用情况。Cockpit 界面显示得少得多。
3. 创建新的服务实例之前，先删除不用的。试用版的配额适用于整个账号，而不只是某一个应用。
4. 把演示和测试的工作负载，放在不同的子账户里。

如果您需要多个应用和数据库稳定运行，或者演示时需要稳定的运行时间，就换到正式账户。正式账户中的免费层计划，可以升级为付费而不丢失您的工作，试用账号做不到这一点。

为什么 SAP BTP 的服务密钥凭据看起来是对的，却返回 401 错误？

几乎总是 OAuth 请求的问题，而不是凭据的问题。常见原因有：授权类型不对（技术访问请用 client_credentials）、令牌 URL 与服务密钥不匹配，或者令牌调用的请求头不对。

如果您拿到了令牌，API 仍然拒绝，就解码它。检查 aud 声明是否与 API 匹配，并检查范围（scope）。使用客户端凭据时，范围来自授予服务实例的权限，所以缺少的角色要在实例参数中修复。

是什么原因导致在 BTP Cockpit 中打开 Integration Suite 时出现内部服务器错误？

最常见的是缺少角色集合或会话已过期。确保您的用户拥有 Integration_Provisioner 和您需要的 PI_ 角色集合。然后关闭所有 BTP 标签页，注销，再重新登录，因为新角色只有在重新登录后才生效。

如果问题持续，就清除 BTP 域名的 cookie，并且只保持一个 Cockpit 会话。在同一个子账户上开多个标签页，会触发同样的错误。

为什么我的 CAP 应用连不上 Cockpit 里显示正常的 destination？

通常是命名不匹配。cds.requires 和 xs-app.json 路由中的 destination 名称，必须与 Cockpit 完全一致，包括大小写。

如果名称没错，就检查应用是否同时绑定了 Destination 服务和 XSUAA，[production] 配置是否带有凭据，以及 kind 是否与远程服务匹配：V2 用 odata-v2，V4 用 odata。使用 Cockpit 中的“Check Connection”确认目标可达。

为什么我的 SAP BTP 试用版应用一夜之间停止工作？

在试用版和免费层计划中，SAP HANA Cloud 实例每晚都会停止，以节省资源。您的应用仍在运行，但连不上它的数据库。每天开始工作之前，先在 SAP HANA Cloud Central 中重启实例。

用 cf apps 和 cf services 检查内存和服务使用情况，因为试用版配额在 Cockpit 里很难看到。创建新实例之前，先删除不用的。

为什么 Booster 和磁贴里的链接会通向空白页？

Booster 运行之后，如果子账户结构发生变化，Booster 的链接就会失效。重定向指向的位置已经不存在，或者从未完整配置过。

改为通过 Cockpit 的目录树导航，并为 Integration Suite、destination 和 SAP Build Work Zone 的直接 URL 添加书签。对于您每天使用的东西，不要依赖 Booster 生成的导航。

什么时候应该从 BTP 试用账号换到付费方案？

当这些限制开始耗费您的时间时。如果您运行多个应用或数据库，或者演示和测试需要稳定的运行时间，试用版造成的麻烦会比省下的更多。

主要的好处是稳定性和更清晰的资源可见性，而不是新功能。带有免费层计划的正式账户，是一个不错的中间步骤：您可以稍后把这些计划升级为付费，而无需重建任何东西。