插件宿主生命周期、范围与数据

这页说明安装插件会开放什么，以及停用、更新或卸载时会保留什么。日常操作入口见插件管理指南。

页面位置与业务作用

public、account、admin 表示公开端、用户端、管理端页面位置，不等于业务权限。插件也可以只提供后台服务；没有公开页面不代表不能参与登录、后台任务或提供方集成。

所需能力会显示在安装预览与插件详情中。页面、指定位置组件及声明的 HTTP 路由只有在对应插件启用、通过宿主校验时才可用。

宿主准入与核心策略

安装时校验签名、内容摘要、平台、清单结构与能力。每次调用继续校验当前账户、页面范围、插件状态和版本。能力来自签名包并由宿主约束，管理员不能通过勾选或修改请求绕过规则。

扩展范围	主要限制
页面、组件与路由	只开放清单声明且宿主支持的位置和路径，不注入宿主 DOM，也不覆盖核心路由。
配置与私有存储	只访问本插件的数据，读写可分别授权；不提供 SQL 或核心数据表。
第三方身份	插件验证外部身份，账户、注册开关、绑定与会话由核心控制。
账户、订阅和消息	用户范围与管理员范围分别校验；订阅配置读取、配额调整、延长期限和取消需要相应专用能力。
用量与订单	页面可读取获准的本人数据；支付写入不提供给浏览器插件会话。
任务、DNS 与证书	只执行声明的任务或提供方契约，不获得任意宿主命令权限。

同邮箱不自动绑定账户，关闭注册也不能被身份插件绕过。插件拥有某项只读能力，不代表能执行相应写操作。完整能力名以当前清单校验和SDK为准。

这些是宿主接口边界，不能代替原生程序的操作系统隔离。服务端插件仍可能使用部署账号的文件和网络权限，请先阅读安装信任。

生命周期事务

• 首次安装：校验包并准备配置、准入与数据，成功后保持停用。失败不留下半完成的有效安装。
• 启用：检查包、数据、配置和进程健康，成功后才发布入口。
• 停用：撤销插件会话、停止运行与相关任务，保留配置和数据。
• 更新或切换发布版本：先准备候选数据和运行时，通过后切换；成功保留原启停状态，失败保留原安装与数据。
• 卸载：自动停止运行、撤销入口并移除程序包，保留自身配置、私有数据和记录。

当前只保留已提交的当前包，旧包和历史版本元数据会被清理，不支持本地历史回滚。重新安装发布者提供的其他版本仍须通过数据与配置校验；不能代替一致备份恢复。操作失败时查看详情页“操作记录”，不要手动拼接数据库状态。

私有数据

插件私有存储是按插件 ID 隔离的加密 JSON 数据。单插件最多 128 个键、总计 256 KiB，单值最多 32 KiB。配置和私有数据不等于核心账户、订单、订阅或凭证。

私有存储读写可分别授权。页面桥只向获准的管理端页面开放这项存储；原生进程使用自身私有认证连接，不能指定其他插件的命名空间。写入使用修订号检测并发冲突，冲突后需重新读取和决定，不能盲目覆盖。

备份时保留数据库、插件目录及既有加密密钥。仅复制 .zbplugin 安装包不包含站点中保存的配置或数据。

声明式迁移

安装或更新时，宿主根据包内声明自动准备数据，不需要管理员手工执行迁移。失败会阻止切换；数据未准备好时不能启用。

贡献者只能声明自身配置或私有存储的补默认值、改名和删除操作，并申请对应写权限。不得运行迁移 SQL、脚本或自定义迁移回调；已发布步骤必须保持不变。完整限制见数据清单校验。

当前不自动执行向下迁移。更新前备份，尤其不要把“能下载旧包”当成“能恢复旧数据”。

卸载与清理

操作	配置与私有数据	核心账户、身份绑定、订阅与订单
停用	保留，可再次启用	保留
卸载	保留，重新安装后可继续使用	保留
卸载后“清除保留数据”	清空，重新安装时重新初始化	保留

清除保留数据不会移除操作及迁移记录，也不会解除原插件的发布者与签名密钥约束。执行前确认有备份或确实不再需要数据；不要直接删除宿主的数据表。