首次接入流程与验收

从判断是否需要插件，到一次性授权、启动握手、清理引导配置和 Bundle 联调的完整交付流程。

本页是新插件首次受管接入的操作主线，适用于直接实现协议的服务和独立 Adapter。命令参数以当前 CLI 的分级 --help 为准，协议细节见首次握手与凭据轮换。

先判断是否需要插件

普通后端只提供 API，或 Module 只调用后端接口时，不要求注册插件。需要随业务 Bundle 的 INSTALL / UPGRADE / CONFIGURE / DETACH 开通租户、更新配置或解除业务绑定时，才需要显式声明生命周期插件。数据库绑定、Hosted Service Endpoint 和 Bundle 资源绑定都不会自动完成插件接入。

先选择独立 Adapter或直接实现协议。复用已接入的插件时，使用其登记身份、数据库、密钥与凭据。插件接入统一按下面的受管流程完成，Bundle 安装使用已接入的插件身份。

1. 准备程序、存储和回调载体

核实项目、工作区、目标 Environment 与插件所有者；后端 Environment 和 Bundle 安装 Runtime 分别记录。
准备插件自己的数据库、加密密钥及受保护备份。已有凭据库必须恢复原密钥，不能生成新密钥替换。
数据库绑定会按 Provider 默认配置生成变量；回读绑定和变量来源，确认应用要求的 DATABASE_URL 已指向正确绑定。自定义插件 Secret 仍需按环境配置绑定进程变量。
直接实现者使用协议库的类型和校验，实现受管会话的持久化、交换、确认、轮换和认证。
直接承载 HTTPS 协议入口时，从运行时正式端点元数据读取地址，再拼接真实 handler 路径。 Hosted Service 可使用 RUNTIME_ENDPOINTS_JSON，不要在源码里猜域名或要求操作者提前填写尚未生成的 URL。
采用 Runtime Gateway 的 Adapter 时，先按Adapter 接入顺序准备提供方调用 Bundle、真实网关地址和受保护调用配置。Adapter 自身初始化不得依赖尚未接入的业务插件。

2. 申请一次性授权

程序和部署配置准备好后，由插件所属工作区的授权管理者执行：

baijimu lifecycle-plugin register --help
baijimu lifecycle-plugin register \
  --workspace-id "$WORKSPACE_ID" \
  --plugin-id "$PLUGIN_ID" \
  --name "$PLUGIN_NAME" \
  --token-output "$BOOTSTRAP_TOKEN_FILE"

记录返回的 enrollmentId、基准 generation、有效期和状态。引导文件必须是新建的私密文件。授权有有效期，申请后及时交付并启动；结果不明时按原授权 ID 查询状态，不能反复注册。此时只完成授权申请，尚未完成插件握手。

3. 交付引导配置并部署

通过部署系统的 Secret 管理交付引导 Token、授权 ID 和基准代次，以及插件身份、数据库和加密密钥配置。本平台 Adapter 的变量名及来源见注册与管理；自建插件使用自己的配置契约。不要把秘密写进命令参数、普通配置、Git 或日志。

通过正式发布入口部署准确项目版本。已运行的服务新增引导配置后，也需通过受支持的重启或重新部署取得新配置；服务启动后连接数据库并启动 listener，提供进程健康检查；随后读取正式执行地址，在后台持久化交换状态、完成握手并保存双向凭据。接入确认后，生命周期接口接受通过鉴权的调用。部署工具交付配置，插件程序执行握手，平台管理授权和对端凭据，三者不能互相代替。

4. 确认握手与调用边界

baijimu lifecycle-plugin complete-enrollment \
  --workspace-id "$WORKSPACE_ID" \
  --plugin-id "$PLUGIN_ID" \
  --enrollment-id "$ENROLLMENT_ID"
baijimu lifecycle-plugin get "$PLUGIN_ID" --workspace-id "$WORKSPACE_ID"

确认授权已消费且未撤销，回读插件身份、执行地址、协议与资源阶段；再通过插件受保护的管理入口确认持久化代次已生效、没有未完成交换。 complete-enrollment 是只读确认，不替插件完成交换、不修改部署配置。验证缺失、错误凭据被拒绝，管理操作不能从公开业务入口调用。检查 CModel 的 errorCode，不能只看 HTTP 200。

5. 清除引导配置并验证恢复

确认成功后，移除本次引导 Token、授权 ID、基准代次的变量绑定和 Secret，并删除本地引导文件。保留插件身份、数据库、加密密钥及备份。按配置工具的版本校验执行，避免覆盖其他配置。

重新部署同一已发布版本或使用正式重启入口，确认无引导配置时仍从数据库恢复当前代次并接受获授权调用。通过正式受保护入口验证轮换和代次推进。响应丢失、并发交换、过期和撤销的故障验证应在隔离验收环境完成，不为测试随意撤销正在服务的生产插件。

6. 完成业务 Bundle 联调并交付证据

插件接入完成后，按Bundle 绑定声明资源授权，创建不可变版本并在授权目标安装、升级、配置和解除，验证实际业务效果。已有插件使用者直接复用登记身份。不能把后端上线或握手成功报告为完整 Bundle 产品交付完成。

验收层级	必须留存的证据
后端部署	项目版本、源码提交、构建/制品、Deployment、Endpoint 和数据库健康
插件接入	pluginId、enrollmentId、平台确认结果、执行地址、协议和有效凭据代次
凭据恢复与安全	无引导配置重启、轮换、错误凭据拒绝；隔离环境的响应丢失、并发、过期及撤销结果
Bundle 业务	Bundle 版本、目标 Runtime、安装操作与业务结果，以及幂等和安装归属隔离结果

AI（包括 WorkBuddy）必须分别报告每层的已通过、未执行和失败项，并标明测试环境。缺少哪层证据就说明哪层尚未完成；不得用健康检查替代插件验收、用插件验收替代 Bundle 业务验收。详细用例见验证与发布。

常见阻塞如何归因

现象	检查与处理
启动报缺少 `DATABASE_URL`	检查数据库分配、绑定和变量来源，以及当前部署是否使用新修订；不直接归因于计算 Slot
部署成功但插件未接入	按原 enrollmentId 回查授权状态，检查配置是否进入新进程、握手日志和数据库会话状态
引导已过期或状态未知	先查询原授权，不盲目重复注册；按正式重新授权流程恢复并保留数据库密钥
健康通过但 Bundle 安装失败	检查插件认证、执行地址、绑定授权及业务回调错误；分别报告部署与安装结果

首次接入流程与验收

本页内容