推荐架构：独立 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的流程：先部署后端，再通过 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 和授权绑定。

调用关系

使用方 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 数据库。

标准方法

下面是 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 的替代合同。

业务处理合同与生命周期回调

平台协议按权威规范和注册声明选择。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 资源不能领取新访问材料。完整边界见引用协议和失败与重试。

接入顺序

通用授权、启动握手、引导清理和完成证据遵循首次接入流程与验收；下面补充 Adapter 的 Runtime Gateway 准备顺序。 Adapter 启动后提供进程健康检查并执行后台握手；网关对每次业务调用校验有效凭据。

发布并验证 Adapter Hosted Service 的精确项目版本，以及 Module、Gateway、Bundle 的不可变版本引用。
在提供方自己的工作区创建 Application Runtime，从市场安装公共 Adapter Bundle；确认目标平台已登记 GATEWAY 执行能力。
从安装后的正式网关记录取得完整 /bundle-lifecycle 地址，将其写入 Adapter Environment 的 BUNDLE_PLUGIN_EXECUTE_URL。不从 Hosted Endpoint 或域名命名规则推导网关地址。
独立部署 Adapter 后端，绑定自己的数据库、加密密钥、业务 Endpoint 和独立业务访问凭据；将 API Endpoint 与 Hosted Consumer 授权配置给 Module，配置网关鉴权和委托调用。业务后端取得所需 Runtime 调用权限；握手前验证未授权拒绝，握手后验证获授权调用。
新插件通过通用注册命令申请一次性授权，经独立部署配置交付给 Adapter，完成首次握手与凭据轮换。一个 Adapter 实例配置一个插件身份与业务绑定；这是 Adapter 的配置范围，不是平台插件实体的部署绑定。
清除一次性引导变量后验证重启恢复，再发布带显式插件绑定的业务 Bundle 并验证安装全过程。

已有直连入口切换到 Runtime Gateway

已有插件保留数据库、加密密钥、插件身份和当前凭据代次，不重新注册或重新分配凭据库。先确认没有未完成的候选握手，再升级提供方 Runtime 的 Adapter Bundle、准备网关地址和调用授权。配套后端部署将旧直连入口改为 Hosted Token 保护，应安排切换窗口：后端就绪后验证网关拒绝缺失或错误 Token，随后调用受保护的 rotatePluginCredentials，用现有凭据完成交换与确认，将平台登记的 executeUrl 更新为配置中的网关地址。方法不接受请求临时传入新地址。部署与地址轮换不是原子操作，切换窗口内旧地址可能拒绝回调。

最后回读平台地址、凭据代次和候选状态，执行一次真实业务 Bundle 生命周期操作，并从资源 Owner 和业务后端读回属性、引用访问与业务结果。网关返回 HTTP 200 不等于业务成功，仍须检查 CModel errorCode；路由不存在或资源执行策略未登记时不能切换地址。

Adapter 自身的部署与调用 Bundle 初始化必须独立完成，不能依赖尚未可用的自身插件入口安装自己。业务后端直接实现协议的方式仍受支持，见直接实现插件协议。

验收重点

独立验收 Hosted Service 部署、Module 编译、Bundle 安装、插件登记和真实生命周期业务效果。
验证首次握手、响应丢失后的恢复、重启、多副本、Token 轮换、过期与撤销；本地状态查询不能代替平台当前授权。
验证回调内引用解析、回调结束后拒绝、越权资源拒绝，以及业务访问材料的正确保存和停用。
业务事务绑定操作身份和执行顺序，重复请求恢复同一结果，迟到请求不能覆盖新状态。
Adapter 发布和业务后端发布分别验证合同兼容性，不能假定它们原子升级。

推荐架构：独立 Hosted Service 插件适配器

本页内容