--- docStatus: current --- # 推荐架构：独立 Hosted Service 插件适配器 Bundle Plugin Adapter 以独立 Hosted Service 实现公共插件协议，Bundle 提供 Runtime 网关与标准 Module 方法，业务后端保留业务与数据库。 推荐将公共插件协议放在 **Bundle Plugin Adapter Hosted Service** 中。它有独立项目、版本、Environment、 Endpoint 和凭据存储；业务 Hosted Service 保留业务接口、实例归属、事务和幂等。 Application Runtime 安装公共 Adapter Bundle 后获得生命周期 Gateway 和 Adapter Module 标准方法， 由网关接收平台回调、由独立 Adapter 后端处理公共协议，降低业务后端接入平台的复杂度。 ## 后端部署与 Bundle 安装 Adapter 和业务后端都遵循[独立后端接入 Runtime](/development/backend-development/#接入-application-runtime)的流程： 先部署后端，再通过 Module 和 Bundle 交付调用能力。 | 对象 | 含义 | | -------------------------- | ------------------------------------------------------- | | Application Runtime | 安装 Adapter Bundle 或业务 Bundle，提供已生效的网关、模块方法与配置 | | Hosted Service Environment | 某个后端项目的一套部署配置，管理自己的 Endpoint、Secret 与数据库绑定 | | Bundle 安装实例 | 某个 Bundle 在目标 Runtime 中的安装记录，不代表创建了一套 Hosted Service 部署 | 安装 Adapter Bundle 不会自动创建或部署 Adapter 后端，也不会为每次安装分配独立数据库。 需要独立部署和存储时，先通过 Hosted Service 与数据库能力完成配置，再将对应 Endpoint 和授权 配置给已安装的 Module。Bundle 升级与后端版本发布分别验证；卸载调用 Bundle 不自动停止后端或删除数据库。 > **实现与上线状态分别验收** > > 公共 Adapter Bundle 0.2.0 包含 Module 0.2.0 与 Gateway 0.1.0，配套 Adapter Hosted Service 0.2.0。 > 目标平台必须支持 GATEWAY 资源登记与安装执行。Hosted Service 版本、Module 编译、Bundle 市场发布、 > Runtime 安装、环境部署及真实业务联调分别验收；市场已发布不代表目标 Runtime 已安装或后端已升级。 > 安装时从正式版本目录解析 Bundle 和 Module 身份，部署时从环境登记解析 Endpoint 和授权绑定。 ## 调用关系 ```text 使用方 Runtime 安装、升级、配置或卸载业务 Bundle → 平台插件管理服务 → 提供方 Application Runtime 中 Adapter Bundle 的 /bundle-lifecycle 网关 → authorizeGateway 调用 Adapter 后端，在线验证插件 caller Token → executeGatewayLifecycle 通过 Hosted Consumer 授权调用 Adapter api Endpoint → 验证生命周期协议和授权范围 → 业务 Hosted Service 执行业务方法 → 通过自己的 Database Capability 访问业务数据库 业务回调中需要解析服务引用或事件访问时 → 业务 Hosted Service 使用获授权的 Runtime 调用身份 → Adapter Bundle 中的标准 Module 方法 → Adapter Hosted Service 的 api Endpoint → 按本次回调授权调用平台公开解析协议 ``` 平台插件管理服务仍是公开协议的调用方。复用 Adapter 不要求平台识别提供方 Runtime， 也不需要新增专用安装状态查询或内部凭据接口。插件登记的 `executeUrl` 指向 Runtime Gateway 的完整公开执行地址。 平台只登记地址和插件协议身份，不保存提供方 Hosted Service、Environment 或 Runtime 的部署绑定。 Gateway 随 Bundle 安装生效；协议处理、握手调度和持久化由独立 Hosted Service 执行。 这里的业务生命周期管理租户、业务配置和资源绑定，不负责安装或卸载 Adapter 自身的后端程序。 ## 各方承担什么 | 责任方 | 拥有的职责 | | ------------------------------- | --------------------------------------------------------------- | | 平台插件目录与安装器 | 插件登记、逐资源授权、使用方安装状态、活动版本、操作与失败恢复 | | Adapter Hosted Service | 双向插件凭据、首次握手、轮换、撤销校验、协议转换、业务调用、输出校验与引用访问解析 | | Adapter Bundle、Gateway 与 Module | 在 Application Runtime 中提供公开生命周期路由、Token Service 对接、标准方法和受保护调用配置 | | 业务 Hosted Service | 业务实例与安装归属、业务授权、数据库迁移、事务、幂等、执行顺序和业务结果 | | Database Capability | 分别为 Adapter 和业务后端解析各自获授权的数据库绑定 | 使用方安装身份来自经校验的生命周期请求。提供方 Runtime、Adapter Environment 和使用方 Runtime 是不同对象，不能用提供方身份替换请求中的安装身份，也不能将两个安装的业务数据混在一起。 ## Adapter 自己需要存储 Adapter 使用自己的 Database Capability 和独立逻辑数据库，保存凭据代次、加密的平台 Token、 caller Token 验证材料、未完成交换，以及短期回调解析授权的摘要与期限。 这些数据用于重启恢复、多副本一致性、轮换和授权撤销，不是使用方的 Bundle 安装账或业务结果缓存。 加密密钥由 Secret 提供，不和密文一起存入数据库。迁移随 Hosted Service 项目版本执行。 业务 Hosted Service 继续使用自己的 Database Capability 与业务数据库。Adapter 不代理普通 SQL， 不接管业务表、业务事务或业务幂等。数据库资源与迁移流程见 [Hosted Service 数据库](/development/backend-development/hosted-services-and-databases/)。 ## 标准方法 下面是 Adapter Module 的方法合同；调用前仍应从目标 Runtime 读取正式方法定义。 | 方法 | 参数 | 用途 | | ------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | `getAdapterStatus` | 无 | 查询本地凭据代次、期限和候选状态，不返回 Token 明文 | | `authorizeCaller` | `token` | 逐次验证平台调用插件的 caller Token，返回验证结果 | | `executeLifecycle` | `token`、`request` | 验证 caller Token 后执行标准生命周期请求 | | `resolveServiceReference` | `token`、`resource`、`propertyKey` | 在当前业务回调范围内解析服务引用 | | `resolveEventAccess` | `token`、`resource`、`eventName` | 在当前业务回调范围内解析事件访问 | | `authorizeGateway` | `token`、`applicationRuntimeId`、`gatewayBusinessId`、`targetBusinessId`、`targetMethodName`、`httpMethod`、`path` | Gateway Token Service 在线鉴权，返回 `allow` 决策 | | `executeGatewayLifecycle` | `pluginId`、`installation`、`operation`、`stage`、`executionSequence`、`configuration`、`resources` | 接收网关已鉴权的标准生命周期请求，委托 Adapter 后端执行 | | `rotatePluginCredentials` | 无 | 使用后端受控配置主动轮换凭据，并通过交换与确认更新公开执行地址 | 前两个带 `token` 的执行/校验方法使用插件 caller Token；两个解析方法的 `token` 使用当前业务回调的 `context.token`。短期回调 Token 不是平台长期凭据，不能持久保存或记录。 `authorizeCaller` 的布尔结果也不是通用 API Gateway Token Service 决策。 Module 使用受保护的 `adapterBaseUrl` 和 `adapterAuthorization` 调用 Adapter 的 `api` Endpoint。 它们从正式 Endpoint 与 Hosted Consumer 授权取得，不能写入 Bundle 源码。配置须明确指定提供方 Application Runtime，并通过受保护的安装配置交付；敏感值使用权限受控的临时文件传入并在交付后清理。 Adapter 0.2.0 的 `api` 与 `lifecycle` Endpoint 均由 Hosted Runtime 校验 Consumer Token。 平台 caller Token 交给公开 Gateway，由 `authorizeGateway` 每次在线校验；它不能代替 Hosted Consumer Token 直连后端。`executeGatewayLifecycle` 是受保护的委托执行方法，不再次接收 caller Token， 只能向可信 Runtime 授予该方法及后端 Consumer 的调用权限。 `authorizeCaller` 仍是单独的插件 Token 校验方法，不能作为网关 Token Service 的替代合同。 ## 业务处理合同与生命周期回调 平台协议按[权威规范](/development/lifecycle-plugin-development/reference-protocol/#协议选择与环境边界)和注册声明选择。Adapter 将已验证的请求转换为业务合同 `1.0.0`， 向受控配置中的业务 Endpoint 发送请求。请求包含 `contractVersion`、`context`、`configuration` 和 `resources`； 上下文保留插件、安装、操作、阶段与执行顺序，并交付本次回调的短期解析授权。 后端地址和独立业务 Token 由 Environment 配置与 Secret 提供，不能由请求正文指定。 业务后端按 `INSTALL`、`UPGRADE`、`CONFIGURE`、`DETACH` 和 `BEFORE_RESOURCES`、`AFTER_RESOURCES` 处理领域逻辑，使用标准 CModel 返回结果。Adapter 校验允许输出的资源属性，并从原请求组装协议关联字段。 未知业务效果返回 `UNKNOWN`，不能伪造成功；Adapter 不自动重试有副作用的业务请求。 引用解析只在获授权的当前回调中执行。Adapter 校验短期授权、资源范围和平台返回的关联身份， 回调结束后撤销解析授权。业务 Owner 校验并成组保存解析所得的选择关系、URL、Token 和期限； 日常业务调用及重试读取已生效配置，不重新解析，也不保存 `context.token`。 解绑与 REMOVE 资源不能领取新访问材料。完整边界见 [引用协议](/development/lifecycle-plugin-development/reference-protocol/)和 [失败与重试](/development/lifecycle-plugin-development/failure-and-retry/)。 ## 接入顺序 通用授权、启动握手、引导清理和完成证据遵循[首次接入流程与验收](/development/lifecycle-plugin-development/first-enrollment/)；下面补充 Adapter 的 Runtime Gateway 准备顺序。 Adapter 启动后提供进程健康检查并执行后台握手；网关对每次业务调用校验有效凭据。 1. 发布并验证 Adapter Hosted Service 的精确项目版本，以及 Module、Gateway、Bundle 的不可变版本引用。 2. 在提供方自己的工作区创建 Application Runtime，从市场安装公共 Adapter Bundle；确认目标平台已登记 GATEWAY 执行能力。 3. 从安装后的正式网关记录取得完整 `/bundle-lifecycle` 地址，将其写入 Adapter Environment 的 `BUNDLE_PLUGIN_EXECUTE_URL`。不从 Hosted Endpoint 或域名命名规则推导网关地址。 4. 独立部署 Adapter 后端，绑定自己的数据库、加密密钥、业务 Endpoint 和独立业务访问凭据；将 API Endpoint 与 Hosted Consumer 授权配置给 Module，配置网关鉴权和委托调用。业务后端取得所需 Runtime 调用权限；握手前验证未授权拒绝，握手后验证获授权调用。 5. 新插件通过通用注册命令申请一次性授权，经独立部署配置交付给 Adapter，完成[首次握手与凭据轮换](/development/lifecycle-plugin-development/credential-enrollment/)。一个 Adapter 实例配置一个插件身份与业务绑定；这是 Adapter 的配置范围，不是平台插件实体的部署绑定。 6. 清除一次性引导变量后验证重启恢复，再发布带显式插件绑定的业务 Bundle 并验证安装全过程。 ### 已有直连入口切换到 Runtime Gateway 已有插件保留数据库、加密密钥、插件身份和当前凭据代次，不重新注册或重新分配凭据库。 先确认没有未完成的候选握手，再升级提供方 Runtime 的 Adapter Bundle、准备网关地址和调用授权。 配套后端部署将旧直连入口改为 Hosted Token 保护，应安排切换窗口：后端就绪后验证网关拒绝缺失或错误 Token， 随后调用受保护的 `rotatePluginCredentials`，用现有凭据完成交换与确认，将平台登记的 `executeUrl` 更新为配置中的网关地址。 方法不接受请求临时传入新地址。部署与地址轮换不是原子操作，切换窗口内旧地址可能拒绝回调。 最后回读平台地址、凭据代次和候选状态，执行一次真实业务 Bundle 生命周期操作，并从资源 Owner 和业务后端读回属性、引用访问与业务结果。 网关返回 HTTP 200 不等于业务成功，仍须检查 CModel `errorCode`；路由不存在或资源执行策略未登记时不能切换地址。 Adapter 自身的部署与调用 Bundle 初始化必须独立完成，不能依赖尚未可用的自身插件入口安装自己。 业务后端直接实现协议的方式仍受支持，见[直接实现插件协议](/development/lifecycle-plugin-development/develop-plugin-service/)。 ## 验收重点 - 独立验收 Hosted Service 部署、Module 编译、Bundle 安装、插件登记和真实生命周期业务效果。 - 验证首次握手、响应丢失后的恢复、重启、多副本、Token 轮换、过期与撤销；本地状态查询不能代替平台当前授权。 - 验证回调内引用解析、回调结束后拒绝、越权资源拒绝，以及业务访问材料的正确保存和停用。 - 业务事务绑定操作身份和执行顺序，重复请求恢复同一结果，迟到请求不能覆盖新状态。 - Adapter 发布和业务后端发布分别验证合同兼容性，不能假定它们原子升级。