跳到主要内容
万能墙开放平台
插件开发教程

能力、权限与风险

全部内容基于万能墙真实的插件平台(清单 + 钩子 + 接口 + 后台页 + 数据 + 定时任务),示例可直接复制运行。

能力就是权限

插件运行在站长的服务器上,能做什么由 plugin.json 的 capabilities 声明决定:

  • 只有声明过的能力才被放行,越权调用会被核心拒绝;
  • 市场详情页会把能力、风险等级与用途展示给站长,装之前就能看清;
  • 平台按能力做安全边界与自检提示,声明错(拼写、未声明先用)会在自检里报出来。

能力清单(由契约生成)

| 能力 | 名称 | 风险 | 什么时候必须声明 | 说明 |

| --- | --- | :---: | --- | --- |

| db | 自建数据表 | 低风险 | 调用 pluginCreateTable() / pluginTableName() 建表或读写自己的数据表时 | 用 pluginCreateTable() / pluginTableName() 建表读写。表名固定带 plugin_<slug>_ 前缀,不会碰核心表。 |

| files | 文件与静态资源 | 中等风险 | 用 pluginUploadDir() 存上传文件,或用 pluginAssetUrl() 输出自己的 assets/ 时 | 用 pluginUploadDir() 存上传文件、用 pluginAssetUrl() 暴露自己的 assets/ 目录(只读白名单)。 |

| http | 外部网络请求 | 中等风险 | 用 pluginHttp() 请求站外接口时 | 用 pluginHttp() 请求站外接口(有超时与体积上限)。自己写 curl 也能跑,但自检会提示且不受平台超时/体积保护。 |

| mail | 发送邮件 | 高风险 | 用 sendEmailTracked() / sendEmail() 发信时 | 调用 sendEmailTracked() 走站点已配置的发件通道(会记入发件台账、失败自动入队重试)。 |

| admin_ui | 后台页面 | 低风险 | 用 registerAdminPage() 添加后台管理页时 | registerAdminPage() 在后台「插件」分组下加一个管理页;不声明会被平台拒绝注册。 |

| front_ui | 前台页面与钩子注入 | 低风险 | 用 registerFrontView() 提供前台页面、addShortcode() 提供短代码,或用 plugin_render_* 注入 HTML 时 | registerFrontView() 提供前台页面,addShortcode() 提供短代码,或用 plugin_render_* 过滤器往页面注入 HTML(含个人中心/设置页槽位)。 |

风险等级怎么看

  • 低风险(low):影响范围限制在插件自己的目录与自己的数据表/页面里,出问题停用即可;
  • 中等风险(medium):会碰站点文件或把数据发往站外(files / http),需要留意数据范围与外部服务是否可信;
  • 高风险(high):会消耗站点资源或代表站点对外发信(如 mail),可能触发服务商限流,站长最关心用途。

一个插件的整体风险取所有已声明能力里的最高值(high > medium > low);没有声明任何能力时市场页会提示「功能可能受限」。

不声明 / 声明错会怎样

自检(lint.php 与 php backend/plugin_lint_cli.php)会给出这些规则,规则号与提交审核一致:

  • CAP_UNKNOWN(阻断项)—— capabilities 里出现平台不认识的能力
  • CAP_MISSING(警告)—— 用了某项能力却没在清单里声明

提交时还有一道硬性门槛:声明了 files / http / mail 等中等/高风险能力,必须填写「权限用途说明」(用途、场景与数据范围),否则会被拒绝提交。

主动声明数据收集范围(data_collection)

在 plugin.json 里额外写一个 data_collection 字段(字符串或字符串数组),把你的数据收集范围讲清楚,市场详情页会原样展示给站长:

json
{
  "capabilities": ["db", "http"],
  "data_collection": [
    "用户 ID 与签到时间(存在插件自建表里)",
    "订单号(仅用于同步到自建 ERP,不含手机号)"
  ]
}

没有声明时,市场详情页会显示「开发者未声明数据收集范围」,并提示站长向你确认——主动写清楚更容易过审,也更让人放心。