290 lines
17 KiB
Markdown
290 lines
17 KiB
Markdown
# Ywxapp 插件使用说明
|
||
|
||
> 适用框架：Ywxapp（基于 ThinkPHP 8 的多应用框架）
|
||
> 本文逐一说明 `addon/` 目录下**全部 6 个插件**的功能、安装、配置与使用方法。
|
||
> 插件机制与开发规范详见同级《插件开发指南.md》。
|
||
|
||
---
|
||
|
||
## 插件清单
|
||
|
||
| 插件 | 标题 | 版本 | 状态 | 形态 | 一句话简介 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| `blog` | 博客应用 | 1.0.0 | 启用 | 完整业务 | 多用户博客（前台展示 / 会员中心 / 后台管理） |
|
||
| `mqttbroker` | MQTT代理 | 2.1.0 | 启用 | 常驻进程 | 基于 Workerman 自研的 MQTT 3.1.1/5.0 Broker |
|
||
| `haonav` | 网址导航 | 1.0.0 | 启用 | 完整业务 | 网址分类与站点收录、展示、后台管理 |
|
||
| `wxchat` | 聊天应用 | 1.0.0 | 启用 | 常驻进程 | 仿微信的移动端 IM 社交（GatewayWorker） |
|
||
| `smsbao` | 短信宝 | 1.0.0 | 启用 | 事件订阅 | 对接短信宝网关发送验证码（半成品） |
|
||
| `demo` | 演示插件 | 1.0.0 | 启用 | 脚手架 | 插件开发规范示例骨架（仅返回一句话） |
|
||
|
||
---
|
||
|
||
## 通用：安装 / 启用 / 卸载
|
||
|
||
所有插件遵循同一套生命周期，详见《插件开发指南.md》第 4 节。常用操作：
|
||
|
||
```bash
|
||
# 开发者模式（本地已放好源码时，免打包、可反复执行，幂等）
|
||
php think addon:manage <name> -a develop
|
||
|
||
# 后台操作
|
||
# 插件管理 → 离线安装（上传 zip）→ 启用 / 禁用 / 卸载
|
||
```
|
||
|
||
- **安装**：写入 `info.php`（`state`）、执行 `install.sql` 建表、注入 `menu.json` 菜单、调用 `Addon::install()` 钩子。
|
||
- **启用 / 禁用**：仅切换 `info.php` 的 `state`，并联动菜单显隐；`enable/disable` 钩子存在默认空实现。
|
||
- **卸载**：调用 `Addon::uninstall()`（清理数据表与菜单），再删除插件目录。生产环境操作前务必备份。
|
||
|
||
> 安装 / 启动命令需在**项目根目录**执行；常驻进程（Broker、IM 服务）建议在 Linux 上以 `nohup php think xxx &` 或 `supervisor` 守护。
|
||
|
||
---
|
||
|
||
## 1. blog（博客应用）
|
||
|
||
### 1.1 功能简介
|
||
一个多用户博客平台，提供三套界面：
|
||
- **前台展示（公开）**：首页（最新/热门/推荐文章、分类、标签云、最新评论）、文章详情、分类/标签筛选、搜索、作者主页、关于/联系页、RSS 订阅。
|
||
- **会员中心（需登录）**：发布/编辑/删除自己的文章、自建分类、个人资料。
|
||
- **后台管理（需管理员登录）**：仪表盘统计、文章审核、全局分类/标签、评论审核、用户管理、统计分析、站点/SEO/邮件设置。
|
||
|
||
### 1.2 数据表（安装时自动创建，`wxapp_blog_*`）
|
||
| 表 | 用途 |
|
||
| --- | --- |
|
||
| `wxapp_blog_article` | 文章（标题/正文/封面/作者 uid/分类/状态/置顶/计数） |
|
||
| `wxapp_blog_category` | 分类（全局共享 uid=0，或会员自建） |
|
||
| `wxapp_blog_tag` | 标签 |
|
||
| `wxapp_blog_article_tag` | 文章-标签关联 |
|
||
| `wxapp_blog_comment` | 评论（支持盖楼、审核） |
|
||
| `wxapp_blog_like` | 点赞 |
|
||
| `wxapp_blog_favorite` | 收藏 |
|
||
| `wxapp_blog_user` | 博客用户（映射表名 `user`） |
|
||
| `wxapp_blog_visit` | 访客记录 |
|
||
|
||
### 1.3 入口与菜单
|
||
- **前台入口**：`/blog`（首页）、`/blog/article/:id`、`/blog/category/:id`、`/blog/tag/:id`、`/blog/rss` 等。
|
||
- **会员中心**：`/blog/member`（强制登录）。
|
||
- **后台**：已注入菜单「博客管理」，含 仪表盘 / 文章管理 / 分类管理 / 标签管理 / 评论管理 / 用户管理 / 统计分析 / 系统设置。
|
||
|
||
### 1.4 配置说明
|
||
- 插件 `config.php` 与 `info.php['config']` 均为空，**无独立配置项**。
|
||
- 站点 / SEO / 邮件配置通过后台「系统设置」直接写入应用级 `config/site.php`、`config/seo.php`、`config/email.php`。
|
||
|
||
### 1.5 使用要点
|
||
- 文章由**会员在会员中心发布**，后台仅做管理与审核（不发布新文章）。
|
||
- 后台「系统设置」可配置站点信息、SEO 与邮件（发信）参数。
|
||
- 前台文章评论带敏感词过滤；互动（点赞/收藏）需登录。
|
||
|
||
### 1.6 注意事项
|
||
- 后台路由挂载 `AdminAuth` 中间件（未登录跳转 `/admin/login`）；会员路由挂载 `MemberAuth`（未登录跳 `/member/login`）。
|
||
- 自带 `READMD.md` 描述的是独立 ThinkPHP 应用形态（表名、登录账号与实现不符），**以本插件实际代码为准**。
|
||
|
||
---
|
||
|
||
## 2. mqttbroker（MQTT 代理）
|
||
|
||
### 2.1 功能简介
|
||
基于 Workerman 自研的 MQTT 3.1.1 / 5.0 Broker（类 EMQX 轻量版）：
|
||
- 协议：CONNECT/PUBLISH（QoS0/1/2）/SUBSCRIBE/PING/DISCONNECT/AUTH。
|
||
- 传输：TCP（默认 1883）、WebSocket（8083，浏览器/小程序）、可选 TLS。
|
||
- 认证 / ACL、保留消息、遗嘱、离线消息持久化、共享订阅（`$share/{group}/{filter}`）。
|
||
- `$SYS/broker/#` 系统指标、`/static/addon/mqttbroker/` 实时监控仪表盘。
|
||
- 基于 Redis Stream 的多进程/WS 桥接、规则引擎转发到外部 Broker（如 EMQX）。
|
||
- 手动发布走 DB 出站队列（零外部依赖）。
|
||
|
||
### 2.2 启动命令（常驻进程）
|
||
```bash
|
||
php think mqttbroker:start # 启动 Broker（Linux 建议守护）
|
||
php think mqttbroker:acltest # ACL 规则测试工具
|
||
```
|
||
> Windows 下单进程调试模式，WebSocket 多监听在 Windows 不支持；生产请使用 Linux。
|
||
|
||
### 2.3 数据表（`wxapp_mqttbroker_*`）
|
||
连接、消息日志、订阅关系、认证账号、ACL 规则、保留消息、离线消息、实时指标、转发规则、出站队列（共 11 张，`stats` 表有代码自愈建表）。
|
||
|
||
### 2.4 后台入口与菜单
|
||
已注入菜单「MQTT代理」：概览 / 客户端连接 / 消息日志 / 发布消息 / 认证账号 / ACL规则 / 实时监控 / 转发规则 / 服务设置（均在 `/mqttbroker/backend/...`）。
|
||
|
||
### 2.5 配置说明（后台「服务设置」）
|
||
配置项存于数据库 `wxapp_addon_config`（每个配置独立成行），由后台「插件管理 → 配置」或插件内「服务设置」页写入，读取走缓存（键 `addon_config_mqttbroker`）。表单字段由 `config.php` 定义，运行期默认值在 `Broker::loadConfig()` 中（`array_merge($defaults, $saved)`）。**两处默认值应保持一致**。关键项：
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `port` | 1883 | TCP 监听端口 |
|
||
| `host` | 0.0.0.0 | 绑定地址 |
|
||
| `ws_port` | 8083 | WebSocket 端口，0=关闭 |
|
||
| `ssl_enabled` | 0 | 对 TCP 启用 TLS |
|
||
| `ssl_cert` / `ssl_key` | 空 | PEM 证书/私钥绝对路径 |
|
||
| `allow_anonymous` | 1 | 允许匿名连接；设为 0 时需在「认证账号」维护账号 |
|
||
| `acl_enabled` | 0 | 开启后按「ACL规则」校验发布/订阅 |
|
||
| `acl_default` | allow | 规则未命中时的兜底策略 |
|
||
| `max_keepalive` | 60 | 最大保活间隔（秒） |
|
||
| `sys_enabled` / `sys_interval` | 1 / 10 | `$SYS` 指标开关与发布周期 |
|
||
| `persist_retain` / `persist_offline` | 1 / 1 | 保留消息 / 离线消息持久化 |
|
||
| `offline_limit` | 1000 | 单客户端离线消息上限 |
|
||
| `cluster_enabled` | 0 | 集群桥接（需 Redis） |
|
||
| `rule_enabled` | 1 | 转发规则引擎开关 |
|
||
| `redis_*` | 127.0.0.1:6379 | 集群桥接用 Redis 连接 |
|
||
| `log_level` | 1 | 日志级别（0 关 / 1 仅错误 / 2 详细） |
|
||
|
||
### 2.6 使用要点
|
||
1. 启动 Broker 进程（命令见 2.2）。
|
||
2. 后台「服务设置」按需配置端口、匿名/认证、ACL、TLS、持久化。
|
||
3. 客户端连接：`tcp://<host>:1883` 或 `ws://<host>:8083`；认证在「认证账号」维护，权限在「ACL规则」维护。
|
||
4. 后台「发布消息」可手动向主题推送；「实时监控」查看连接与吞吐；「转发规则」可将消息桥接到外部 Broker。
|
||
|
||
### 2.7 事件与扩展点
|
||
- 业务侧在 `service/Broker.php` 预埋了 `mqtt_message_published` 事件（参数：`topic/payload/qos/retain/clientId`；`$SYS/` 主题不触发，qos2 在 PUBREL 后触发，确保每消息一次）。插件可监听此事件做业务联动。
|
||
|
||
### 2.8 注意事项
|
||
- 单进程内存态（`worker->count=1`），会话/订阅在内存，保留/离线消息落库。
|
||
- 卸载会 DROP 全部 11 张表，操作前备份。
|
||
|
||
---
|
||
|
||
## 3. haonav（网址导航）
|
||
|
||
### 3.1 功能简介
|
||
网站 / 网址导航系统（类 hao123）：
|
||
- 网址分类管理（预置 11 个分类：社交、视频、购物、办公 AI、金融等）。
|
||
- 网址收录与展示（预置约 138 条国内外站点），前台展示首页分类列表 + 热门站点 + 分类/站点详情。
|
||
- 后台分类、网址、配置可视化 CRUD（含回收站 / 还原）。
|
||
- 网址模型可**自动抓取目标页 meta 信息**（标题/关键词/描述，基于 Guzzle + DOMDocument）。
|
||
|
||
### 3.2 数据表（`wxapp_haonav_*`）
|
||
| 表 | 用途 |
|
||
| --- | --- |
|
||
| `wxapp_haonav_category` | 网址分类（树形 pid） |
|
||
| `wxapp_haonav_links` | 网址信息（含全文索引、点击/热门/推荐/状态） |
|
||
| `wxapp_haonav_config` | 系统配置 KV（初始化为空，需后台添加） |
|
||
|
||
> 该插件**无 `Addon.php`**，安装时由框架直接执行 `install.sql`（建表 + 预置分类/站点种子数据）。
|
||
|
||
### 3.3 入口
|
||
- **前台**：`/haonav`（首页，按分类展示）、`/haonav/category/:id`（分类详情）、`/haonav/site/:id`（站点详情）。均免登录。
|
||
- **后台**：控制器位于 `controller/backend/`（Category / Links / Configs）。
|
||
|
||
> ⚠️ **菜单未注入**：`menu.json` 三套均为空数组，后台左侧**没有菜单入口**。需直接通过 URL 访问后台控制器（如 `haonav/backend.category`），或自行在 `menu.json` 补充菜单后再 `addon:manage <name> -a develop` 重注入。
|
||
|
||
### 3.4 配置说明
|
||
- 无 `config.php`；配置通过数据库 `wxapp_haonav_config` 表 + 后台「Configs」控制器以 KV 形式维护。
|
||
|
||
### 3.5 使用要点
|
||
- 前台直接访问即可浏览分类与站点。
|
||
- 后台「网址」可新增/编辑站点，保存时若填写了 URL 会自动抓取目标页 meta（需安装 `guzzlehttp/guzzle`）。
|
||
|
||
### 3.6 注意事项
|
||
- **安全**：所有前台/后台控制器当前 `noNeedLogin = ['*']`、`noNeedVerify = ['*']`（未强制登录与鉴权），**上线前务必补充权限校验**。
|
||
- **依赖**：`Links::fetchMeta` 依赖 `guzzlehttp/guzzle`，缺失会抛异常，需 `composer require guzzlehttp/guzzle`。
|
||
- 存在调试遗留：`Index::read()` 含 `dump();die;`，`Category::updateRolePowers()` 引用了不存在的关联表，建议清理。
|
||
|
||
---
|
||
|
||
## 4. wxchat（聊天应用）
|
||
|
||
### 4.1 功能简介
|
||
仿微信风格的移动端 IM 社交后端（GatewayWorker）：
|
||
- 实时聊天：单聊/群聊，文本/图片/语音/视频/文件，心跳、认证、撤回、已读回执、敏感词过滤。
|
||
- 用户体系：短信验证码登录、一键登录、完善资料、邀请码、`TokenService` 鉴权。
|
||
- 社交关系：好友、关注/粉丝/互关、亲密度等级。
|
||
- 动态（朋友圈）：发布、评论、点赞、收藏、话题、浏览历史。
|
||
- APP 版本管理（`AppVersionCheck` 中间件：强制/可选更新）。
|
||
- 启动配置下发：`appConf` / `launchData` 返回聊天/广告/服务器地址等。
|
||
|
||
### 4.2 启动命令（常驻进程）
|
||
```bash
|
||
php think wxchat:server # 启动 GatewayWorker 聊天服务
|
||
```
|
||
> `common.php` 注册了指令 `wxchat:server`；WebSocket 实际地址由 `appConf` 的 `socketUrl`（默认 `wss://dev.xixingwl.cn:2346`）下发。
|
||
|
||
### 4.3 数据表（`wxapp_wxchat_*`）
|
||
共 20 张，含：app_versions、follow、friend、group_members、groups、intimacy、messages、message_recalls、moments（动态）、moment_comments/likes/collects/shares/medias、moment_hashtags（话题）、unread_counts、view_history 等。
|
||
|
||
### 4.4 入口与菜单
|
||
- **前台/API**：控制器继承 `Frontend`，对外 URL 带层前缀 `/wxchat`：对外 API 为 `/wxchat/api/*`（如 `/wxchat/api/login/smsLogin`、`/wxchat/api/index/appConf`），会员中心为 `/wxchat/member/*`，后台为 `/wxchat/backend/*`。插件接口统一返回 JSON。
|
||
- **后台菜单**：`Addon::install()` 注入**空菜单数组**，且**无 `menu.json`**，因此后台不显示入口。
|
||
|
||
### 4.5 配置说明
|
||
- 已新增 `config.php`，约 34 项配置（功能开关、业务限制、广告、服务器地址、第三方 AppId、版本兼容）现由后台「插件管理 → 配置」（`/backend/addon/setting?addon=wxchat`）可视化维护，实际值存于数据库 `wxapp_addon_config`（独立项 + 缓存）。
|
||
- `appConf()` 接口以硬编码数组作为默认值，运行时通过 `AddonService::config('wxchat')` 读取数据库配置并按类型（bool/int/string）还原后覆盖默认值下发给端。
|
||
- 数组类配置（`supportedPlatforms`）保持代码默认值，未纳入后台表单。
|
||
- **默认值一致性**：`config.php` 中声明的 `value` 应与 `appConf()` 的 `$defaults` 保持一致（开关为 `1/0`、数字为字符串形式）。
|
||
|
||
### 4.6 事件与扩展点
|
||
- `info.php` 声明了事件订阅 `addon\wxchat\subscribe\User`，用于对接会员体系（注册/登录等系统事件），在会员注册/登录后同步 IM 账户或下发通知。
|
||
- 声明了中间件 `AppVersionCheck`（版本检查）与服务 `service\Service`。
|
||
|
||
### 4.7 注意事项
|
||
- **登录校验**：大量控制器标注 `noNeedLogin = ['*']`，当前几乎全部接口放行，**属开发/调试状态**，上线前需开启登录与签名校验。
|
||
- `Login::index()` 含直接调用短信宝接口发短信的测试代码（含明文账号密码），上线前删除。
|
||
- 根目录 `README.md` 实为「消息协议结构设计草稿」，并非使用说明。
|
||
|
||
---
|
||
|
||
## 5. smsbao（短信宝）
|
||
|
||
### 5.1 功能简介
|
||
对接「短信宝」第三方短信网关（`https://api.smsbao.com/sms`）的短信发送插件。属于**事件订阅 + 短信发送**型插件：
|
||
- 通过 `subscribe/Smsbao.php` 监听 `SmsSend` 事件，向短信宝接口发送验证码短信。
|
||
- 短信模板固定：`【妙趣横生】您的短信验证码为：{code}, 五分钟有效，请勿告诉他人`。
|
||
|
||
### 5.2 数据表 / 菜单 / 路由
|
||
- **无 `install.sql`**：不创建任何数据表。
|
||
- **无 `menu.json`**：`Addon::install()` 注入空菜单，后台无入口。
|
||
- **无 `route/` 目录**：不提供 HTTP 接口。
|
||
|
||
### 5.3 配置说明
|
||
- 已新增 `config.php` 定义账号(`u`)、密码(`p`)、签名(`sign`)、模板(`template`)四个配置项；实际值存于数据库 `wxapp_addon_config`，可在后台「插件管理 → 配置」中修改，不再硬编码。默认值为迁移占位，请替换为自有账号与签名。
|
||
|
||
### 5.4 使用要点（如何触发发短信）
|
||
在业务侧主动触发自定义事件即可调用本插件发送验证码：
|
||
```php
|
||
// 业务代码（如注册/找回密码流程）
|
||
event('SmsSend', [
|
||
'mobile' => '13800138000',
|
||
'code' => '123456',
|
||
]);
|
||
```
|
||
订阅器 `Smsbao` 的事件前缀为 `Sms`（方法 `onSend` → 事件 `SmsSend`）。`SmsGet` / `SmsNotice` / `SmsCheck` 方法当前为占位（直接 `return true`）。
|
||
|
||
### 5.5 注意事项（重要）
|
||
- 短信宝账号/密码、短信签名均为**测试硬编码值**，使用前必须替换为自己的账号/签名，并建议改为从配置项读取（新增 `config.php` 与 `.addonrc` 读写）。
|
||
- 本插件**不主动监听** `user_register_after` 等系统事件，必须由业务侧显式 `event('SmsSend', $sms)` 触发。
|
||
- 当前为**半成品**状态：无表、无菜单、无配置、控制器为空壳。
|
||
|
||
---
|
||
|
||
## 6. demo（演示插件）
|
||
|
||
### 6.1 功能简介
|
||
插件开发规范示例骨架。唯一实际能力：`controller/Index.php::index()` 返回字符串 `这是一个addon\demo 插件应用`，访问 `/demo` 可见。其余控制器/路由/视图均为空占位。
|
||
|
||
### 6.2 安装与结构
|
||
- 无 `Addon.php`（用系统默认 install/uninstall 钩子），无 `install.sql`（不建表）。
|
||
- 含示例 `menu.json`（frontend/member/backend 均为「一级/二级」占位菜单）、`route/app.php`（仅引入 `Route` 门面占位）。
|
||
|
||
### 6.3 用途
|
||
- 作为新插件脚手架参考；可基于 `php think addon:make <name> -a build` 生成更完整的骨架。
|
||
|
||
---
|
||
|
||
## 附：命令速查
|
||
|
||
| 命令 | 归属 | 作用 |
|
||
| --- | --- | --- |
|
||
| `php think mqttbroker:start` | mqttbroker | 启动 MQTT Broker（常驻） |
|
||
| `php think mqttbroker:acltest` | mqttbroker | ACL 规则测试 |
|
||
| `php think wxchat:server` | wxchat | 启动 GatewayWorker 聊天服务（常驻） |
|
||
| `php think workerman:gateway` | 框架 | GatewayWorker 通用网关 |
|
||
| `php think addon:manage <name> -a develop` | 框架 | 开发者模式安装（建表+菜单+启用，可重跑） |
|
||
|
||
## 附：状态与风险提示
|
||
|
||
| 插件 | 成熟度 | 上线前需处理 |
|
||
| --- | --- | --- |
|
||
| blog | 完整可用 | 无需特殊处理 |
|
||
| mqttbroker | 完整可用 | 生产用 Linux 守护；按需配置认证/ACL/TLS |
|
||
| haonav | 基本可用 | 后台菜单未注入；补登录鉴权；装 guzzle |
|
||
| wxchat | 开发态 | 开启登录/签名校验；删除测试发短信代码；补后台菜单 |
|
||
| smsbao | 半成品 | 替换硬编码账号/签名；改为配置驱动；补触发逻辑 |
|
||
| demo | 脚手架 | 仅作示例，不用于生产 |
|