cdnca

开发者平台 · 9 / 9

升级、隐藏、停用和卸载怎么配合

开发者只能上传新版本和隐藏版本；升级、停用和卸载由客户的安装管理者在主控里操作。每个版本都写清迁移说明，客户才能放心升级。

← 全部教程

谁在什么时候做什么

操作发起者什么时候用之后要验证
上传新版本开发者代码、内容、配置模型或权限变化新版本号、重新签名、审核
隐藏版本开发者主账号不再推荐或提供该版本现有客户的安装与支持安排
升级安装客户安装管理者应用已授权且兼容的新版本确认新增权限，检查配置与真实调用
停用安装客户安装管理者（需填写原因）暂停该安装提供的能力页面移除、页面代理调用拒绝、绑定该安装的新事件停止；专用 API Key 与测试订阅另行撤销
卸载安装客户安装管理者（需填写原因）撤销该安装授权失效，回调与数据按约定处理；专用 API Key 与测试订阅另行撤销

发布一个升级版本

  1. 递增 metadata.version，并且高于所有已审核版本。
  2. 确认 spec.compatibility.control_api 覆盖目标主控版本；不满足的主控不能安装或升级到这个版本，已安装的保留最近的兼容版本。
  3. 权限有变化时版本一律进入人工审核，客户升级时也要重新确认新增权限。
  4. 更新说明写清：改了什么、最低主控版本、是否新增权限、原配置如何迁移、失败怎么恢复。

升级失败时安装进入 upgrade_failed_lkg_preserved，保留最近一次有效版本。这个机制不能代替你自己的数据迁移和回退方案；回退方式取决于插件类型与平台支持的版本，请在插件说明里写清恢复步骤，不要让客户直接改数据库。

停用与卸载后的处理

停用或撤销权限后，新的业务事件和回放也会经过授权检查。外部服务要能识别授权已被撤销，停止使用已撤销的 API Key 和安装身份，不要无限重试被拒的请求，并按与客户的约定处理已持有的数据。

停用或卸载只改变安装本身：页面移除，绑定这个安装的业务订阅不再收到新事件和回放。客户为你的服务单独创建的 API Key 和只选测试事件的订阅不归安装管理，不会自动撤销，要由客户逐项处理。请把下面的清单写进插件说明，交给客户照做：

  1. 你先暂停外部服务的定时任务和对客户主控的写入。
  2. 客户在“API Key”页（/dashboard/account/api-key）撤销专供本插件的 Key。先确认没有其他业务共用；有共用时，先给保留的业务换独立 Key，不要直接删共用 Key。
  3. 客户在“插件 Webhook 订阅”页（/dashboard/sys/plugin-webhooks）撤销不再需要的业务订阅和测试订阅；测试订阅不绑定安装，停用卸载不会影响它。
  4. 客户的安装管理者停用或卸载插件并填写原因，刷新确认状态。
  5. 你删除服务中不再需要的 Key、Webhook secret 和安装签名公钥配置，按约定处理已持有的数据。
  6. 一起核对：插件页面已不可用，旧 Key 调用返回 401，业务事件已停止，测试订阅已撤销，其他插件和共用 Key 不受影响。

紧急停止接入时，先撤销专用 Key 再停用安装。外部服务要能识别授权已被撤销，不要无限重试被拒的请求。一次完整交付至少验证：新客户首次安装、老客户升级、普通用户与管理员分别使用、依赖不可用、权限收回、重复请求、升级失败后保留最近有效版本，以及按上面清单停止接入后页面、调用与事件都已停止。

常见问题先这样排查

现象先检查下一步
进不了“我的插件”入驻状态、当前主体、团队权限由主账号核对申请和成员权限
公钥验证失败挑战是否过期、是否复制完整、私钥是否对应重新获取挑战再签名
命名空间冲突是否已被其他发布者认领、是否用了保留前缀使用自己的命名空间
签名或摘要不符文件是否来自同一次打包、签名后是否改过从源文件重新打包签名
工具退出 0 却没有产物终端是否打印了预检与产物行用 pwd -P 得到的真实路径重新执行并核对文件
提示版本已存在版本列表与详情已创建就继续处理；要改文件就递增版本
审核通过但客户看不到是否公开、渠道、兼容范围、价格计划逐项核对，不要重复改文件
已获取但没有功能是否确认安装、启用、完成配置，当前角色用目标角色在实际挂载位置验证
免费插件只有资料不能获取是否有金额为零的生效价格计划主账号在“定价”里添加
调用被拒绝安装是否有效、批准的权限、凭据类型与作用域按接口的认证方式处理，不要换更高权限账号

联系支持时提供：插件 ID、版本、操作时间、request_id、错误码和脱敏截图。不要提交密码、私钥、API secret、Webhook secret 或原始客户数据。