YwxApp/YwxAppThink
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
303f5486643983f7a595c18bf7300de01ea84219
YwxAppThink/docs/插件使用说明.md
T

17 KiB
Raw Blame History

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 节。常用操作：

# 开发者模式（本地已放好源码时，免打包、可反复执行，幂等）
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 启动命令（常驻进程）

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 启动命令（常驻进程）

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 使用要点（如何触发发短信）

在业务侧主动触发自定义事件即可调用本插件发送验证码：

// 业务代码（如注册/找回密码流程）
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 脚手架 仅作示例，不用于生产
Reference in New Issue View Git Blame Copy Permalink