better-staridc-MNBT
1---
2title: 钩子与数据库
3description: MNBT 插件钩子一览、数据库（系统表与插件自建表）、生命周期、安全清单、常见问题、文件索引与版本路线
4---
5
6# 钩子与数据库
7
8本文是 [插件开发手册](./guide.md) 的扩展章节，涵盖钩子一览、数据库、生命周期、安全清单、常见问题、相关文件索引与版本路线。
9
10## 4. 钩子一览（核心触发点）
11
12| 钩子 | 类型 | 参数 | 触发位置（约） |
13|------|------|------|----------------|
14| `boot` | action | — | 全部插件 bootstrap 之后 |
15| `init.admin` | action | — | 管理员已登录 |
16| `init.user` | action | — | 用户已登录 |
17| `host.created` | action | `$host`, `$ctx` | 后台添加主机、外部 API 开通 |
18| `host.paused` | action | `$host`, `$ctx` | 后台改状态、API 暂停 |
19| `host.unpaused` | action | `$host`, `$ctx` | 后台恢复、API 解除暂停 |
20| `host.renewed` | action | `$host`, `$ctx` | 后台改到期、API 续费；`$ctx` 含 `old_date`/`new_date` |
21| `host.deleted` | action | `$host`, `$ctx` | 后台删除、API 删除 |
22| `order.paid` | action | `$order`, `$ctx` | 支付插件回调验签后调 `mnbt_pay_settle_order()` 时触发（V1.81 P3 起从 `notify_url.php` 迁移到支付插件） |
23| `cron` | action | `$info` | `jk_monitor.php` 末尾 |
24| `menu.admin` / `menu.user` | filter | `$items` | 渲染侧栏插件菜单前 |
25| `dashboard.admin.widgets` / `dashboard.user.widgets` | filter | `$items` | 渲染小部件前 |
26| `settings.admin.tabs` | filter | `$items` | 插件管理页快捷入口 |
27
28`$ctx` 常见字段：`source` = `admin` | `api` | `pay_plugin`。
29
30**主机 `$host` 敏感字段**（密码等）可能存在于数组中；对外推送时务必自行脱敏（参见 [webhook_notify](./builtin/webhook-notify.md)）。
31
32---
33
34## 5. 数据库
35
36### 系统表
37
38| 表 | 用途 |
39|----|------|
40| `MN_plugin` | 已安装插件：slug、name、version、enabled |
41| `MN_plugin_option` | 插件键值配置 |
42
43升级已有站点：执行 `update/update_v181_plugin.sql`，或首次访问时引擎 `CREATE TABLE IF NOT EXISTS`。
44
45### 插件自建表
46
47`install.sql` / `uninstall.sql` 在安装/卸载时执行。建议表名前缀：
48
49```sql
50-- install.sql
51CREATE TABLE IF NOT EXISTS `plg_my_plugin_log` (
52 `id` int(11) NOT NULL AUTO_INCREMENT,
53 `content` text,
54 `created_at` varchar(50) NOT NULL DEFAULT '',
55 PRIMARY KEY (`id`)
56) ENGINE=MyISAM DEFAULT CHARSET=utf8;
57```
58
59访问数据：
60
61```php
62global $DB;
63$rows = $DB->get_all_prepare("SELECT * FROM plg_my_plugin_log ORDER BY id DESC LIMIT 20") ?: [];
64```
65
66优先使用 `query_prepare` / `get_row_prepare` / `get_all_prepare`，避免拼接 SQL。
67
68---
69
70## 6. 生命周期：安装 / 启用 / 卸载
71
72| 操作 | 行为 |
73|------|------|
74| 安装 | 写 `MN_plugin` 行；执行 `install.sql` |
75| 启用 | `enabled=true`；下次请求加载 `bootstrap.php` |
76| 禁用 | `enabled=false`；不再加载 |
77| 卸载 | 执行 `uninstall.sql`；删除 `MN_plugin` 与该插件 option；**不删磁盘文件** |
78
79管理 AJAX（核心，勿占用）：
80
81- `plugin_list` / `plugin_install` / `plugin_enable` / `plugin_uninstall`
82
83---
84
85## 9. 安全清单
86
87- [ ] 所有写操作校验登录（`mnbt_plugin_require_admin` / `require_user`）
88- [ ] 用户输入长度与格式校验；输出 `htmlspecialchars`
89- [ ] AJAX `gn` 使用 `p_{slug}_` 前缀，避免与核心冲突
90- [ ] 不 `eval`、不远程下载执行 PHP
91- [ ] 不写核心目录；不改 `MN_config` 表结构
92- [ ] 出站 HTTP 用 `mnbt_http_*`，谨慎开启 `allow_private` / `insecure`
93- [ ] 推送外部时脱敏密码、API 密钥
94- [ ] 生产环境插件目录权限合理（Web 可执行 PHP，但勿对匿名可写）
95
96---
97
98## 10. 常见问题
99
100### 启用后没有菜单？
101
102整页刷新后台框架（`admin/index.php`）。菜单在框架页渲染，仅刷新 iframe 不够。
103
104### AJAX 返回「系统指令不存在」？
105
1061. 插件是否**已启用**（不是仅安装）
1072. `gn` 是否与 `mnbt_register_ajax` 完全一致
1083. 是否请求了正确侧：`admin/ajax.php` vs `user/ajax.php`
109
110### 页面 404 / 插件页面文件无效？
111
112- `mnbt_register_page` 的文件路径相对于插件根目录
113- 文件必须在 `app_plugins/{slug}/` 内（realpath 校验）
114
115### 钩子不触发？
116
117- 确认插件已启用
118- 确认走了对应代码路径（例如 API 开通才会 `source=api`）
119- 看 `runtime/logs/php-error.log` 是否有插件异常
120
121### 与在线更新冲突？
122
123插件放在 `app_plugins/`，官方更新包应避免覆盖该目录；自定义插件勿改核心文件。
124
125---
126
127## 11. 相关文件索引
128
129| 路径 | 说明 |
130|------|------|
131| [插件系统总览](./index.md) | 插件目录总览、快速启用 |
132| `MPHX/plugin.php` | 引擎实现（P0-P3 API 全部在此） |
133| `MPHX/lib/pay.function.php` | P3 支付公共函数（`mnbt_pay_settle_order`、`mnbt_pay_log`） |
134| `MPHX/common.php` | 启动 `mnbt_plugins_boot()` |
135| `admin/plugin.php` | 插件管理 + 插件页面入口 |
136| `admin/pay_settings.php` | P3 支付设置页（启用付款方式、显示名、排序） |
137| `admin/api/setting.php` | 含 `setpaymethods` AJAX 处理器 |
138| `admin/api/plugin.php` | 安装/启用/卸载 AJAX |
139| `user/plugin.php` | 用户端插件页面入口 |
140| `user/pay.php` | 创建订单后调 `mnbt_pay_dispatch_gateway()` 分发到支付插件 |
141| `user/ajax.php` / `admin/ajax.php` | 插件 AJAX 优先分发 |
142| `update/update_v181_plugin.sql` | 已有站点升级表结构（P0-P1） |
143| `update/update_v181_p3_pay.sql` | P3 支付字段迁移（`MN_config.pay_methods`） |
144| `home_demo/` | P2 示例：首页接管 + 通用路由 |
145| `webhook_notify/` | P1 示例：Webhook 推送 |
146| `epay/` | P3 示例：易支付插件（支付宝/微信/QQ） |
147| `alipay_official/` | P3 示例：支付宝官方 API（PC + 当面付） |
148| `user_info/` | 用户中心插件（独立账户系统、登录/注册/资料/密码） |
149| `balance/` | 余额插件（依赖 user_info；后台余额列表、用户充值/消费日志） |
150| `hosting_shop/` | 主机商店插件（依赖 user_info + balance；套餐下单、自动开通） |
151| `domain_shop/` | 域名商店插件：二级域名售卖 + DNSPod DNS 解析 + `host.created` 钩子自动建 A 记录；接管原核心 `ymgm` 业务与 `MN_ym` 表的售卖/绑定逻辑 |
152
153---
154
155## 12. 版本与路线
156
157| 版本 | 能力 |
158|------|------|
159| V1.81 P0 | 引擎、安装启用、AJAX/菜单/页面、host 钩子、cron、示例 |
160| V1.81 P1 | HTTP、widget、settings_tab、order.paid、host.renewed、用户菜单、Webhook 插件 |
161| V1.81 P2 | 首页接管（`mnbt_register_home`）、通用路由（`mnbt_register_route`）、路径参数匹配、`_router.php` 路由分发 |
162| V1.81 P3 | 支付插件系统（`mnbt_register_payment`、`mnbt_pay_settle_order`）、统一支付设置页、易支付/支付宝官方插件、旧 `notify_url.php`/`return_url.php` 完全废弃 |
163
164后续可能：zip 安装、`gn` 冲突检测 UI、SPA 菜单协议、细粒度能力 ACL。