---
docStatus: current
---

# 首次接入流程与验收

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

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

## 先判断是否需要插件

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

先选择[独立 Adapter](/development/lifecycle-plugin-development/integration-runtime/)或
[直接实现协议](/development/lifecycle-plugin-development/develop-plugin-service/)。复用已接入的插件时，
使用其登记身份、数据库、密钥与凭据。插件接入统一按下面的受管流程完成，Bundle 安装使用已接入的插件身份。

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

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

## 2. 申请一次性授权

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

```bash
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 的变量名及来源见[注册与管理](/development/lifecycle-plugin-development/registration-management/#一次性接入与自动轮换)；
自建插件使用自己的配置契约。不要把秘密写进命令参数、普通配置、Git 或日志。

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

## 4. 确认握手与调用边界

```bash
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 绑定](/development/bundle-development/advanced/lifecycle-plugins/)声明资源授权，
创建不可变版本并在授权目标安装、升级、配置和解除，验证实际业务效果。已有插件使用者直接复用登记身份。
不能把后端上线或握手成功报告为完整 Bundle 产品交付完成。

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

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

## 常见阻塞如何归因

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