文档首页 / HareAdmin 开发手册

插件通道驱动

业务代码不要写死某个厂商。具体实现通过 AddonDriver 通道注册;业务侧只调用通用 API / 钩子。

通道说明

  • editor — 富文本(页面使用 class="editor")
  • sms — 短信验证码 / 通知
  • payment — 支付网关
  • oauth — 第三方登录
  • storage — 上传存储
  • ai — 大模型对话(Hub:llmhub)
  • map — 地图 / 地理编码(Hub:maphub)

短信 / 支付 / 编辑器 / 存储 / AI / 地图的当前驱动:优先读 site.driver_{通道} 或 yetuadmin.driver_{通道};未配置时取 priority 最高的已启用插件。OAuth 可多选并存——已配置的提供商都会显示登录按钮。

短信 SMS

  • 钩子:sms_send、sms_notice、sms_check。非当前驱动应返回 null,保证只有生效通道真正发信。
  • 在 configInit / appInit 中注册:AddonDriver::register('sms', $name, …)
  • 官方商店插件:alisms(阿里云)、tencentsms(腾讯云)、huaweisms(华为云)、twilio、vonage
  • 注册验证码:当 yetuadmin.user_register_captcha = mobile 时,站点必须已启用短信插件。未安装时注册页会提示前往插件应用商店安装;接口 api/sms/send 同样返回该错误。
  • 页面文案要区分「发到邮箱」与「发到手机」,不要在目标不同时共用笼统的「验证码」标签。
  • 配置 mode=dryrun 可本地校验、不调远程短信接口;上线改为 live 并填写真实密钥。

支付 Payment

  • 注册:AddonDriver::register('payment', $name, ['gateway' => Gateway::class, 'class' => Client::class])
  • Gateway 实现 app\common\library\payment\GatewayInterface。业务站使用 payment\Manager;商店 API 使用 GatewayManager。
  • 官方商店插件:alipay(支付宝)、wechatpay(微信)、douyinpay(抖音)、stripe、paypal
  • 异步通知地址:/addons/{name}/notify/index。验签成功后触发钩子 payment_notify_success。
  • mode=dryrun 会返回模拟支付链接,不发起真实下单。

第三方登录 OAuth

  • 通道 oauth。登录 / 注册模板通过钩子 user_third_login 输出按钮。
  • 注意:hook() 返回的是监听结果数组,输出前必须拼接:
    $html = hook('user_third_login');
    echo is_array($html) ? implode('', array_map('strval', $html)) : (string) $html;
    不要直接 echo hook('user_third_login'),否则会出现 “Array to string conversion”。
  • 核心:app\common\library\oauth\Manager,绑定表 yt_user_third(安装 / 启用时由 Manager::ensureTable() 创建)。
  • 提供商包括:wechatlogin、qqlogin、weibologin、douyinlogin、googlelogin、applelogin、facebooklogin、xlogin、tiktoklogin、microsoftlogin
  • 流程:/addons/{name}/index/connect → 授权页 → callback。dry-run 会跳过真实跳转。
  • 插件设置:只需配置 Mode + 厂商密钥(微信:AppID / AppSecret;QQ:APP ID / APP Key;……)。只读的 Callback path 用于复制到控制台。
  • 厂商控制台(Live 必做):登记完整回调 {站点域名}{Callback path},须完全一致且无 .html。例:https://example.com/addons/wechatlogin/index/callback。
  • Mode=dryrun 无需真实密钥,可本地验证安装 / 绑定 / 写 Cookie 登录。密钥与控制台回调就绪后再切 live。

人工智能(大模型中心)

  • 模型行:一行对应供应商真实 model id(生产环境建议钉死版本)。可选 family 归组系列;version_label 仅展示;调用传 family 时取 is_latest。可用 capability 过滤(如 vision)。
  • 提供商:OpenAI、Anthropic、Google AI、DeepSeek、Qwen、DashScope、Doubao、Kimi、GLM、自定义 OpenAI 兼容。
  • 通道 ai。官方 Hub 插件:llmhub(商店分类 AI)。
  • 业务调用 new \addons\llmhub\library\Client() → chat([...])。应用内不要写死 OpenAI / Anthropic 等 SDK。
  • Hub 内提供商:OpenAI、Anthropic、Google AI、DeepSeek、DashScope(通义)、自定义 OpenAI 兼容。密钥在插件设置;模型可设可选 标签(空=通用)。
  • 路由:始终默认 / 按标签 / 调用方指定编码(route_mode)。
  • 多语言:lang/zh|en|es.php;模型标题走 ContentLang;对话默认可附带当前界面语言提示(可用 lang=>false 关闭)。
  • 多 AI Hub 时可用 site.driver_ai / yetuadmin.driver_ai 指定。

地图(地图中心)

  • 通道 map。官方 Hub 插件:maphub(商店分类 Maps)。
  • 界面:class="map-picker" → YetuDrivers.bindMap → 模块 map/maphub。
  • 提供商:Google Maps、Mapbox、高德、百度——在设置中选择(不按国家锁定)。
  • 地图/地理编码语言:默认跟随界面语言,或固定语言代码。
  • PHP:geocode() / reverse();后台 AJAX maphub.api/geocode、reverse。

语言包(必填)

每个新插件必须提供 lang/zh.php、lang/en.php、lang/es.php,且 key 一致。英文为源文案,其它语言可后补。优先复用平台短词(如 Operate success、Are you sure?)。

建议与禁忌

  • 建议:一家厂商一个插件;走官方 HTTP / 签名;在插件设置里写明回调地址与 dry-run 说明。
  • 建议:面向全球用户撰写文案——直接写厂商 / 产品名,不要按市场或地域划分来写产品文案。
  • 建议:上架驱动时,只把对接必需、易踩坑的说明写入手册,不要堆砌琐碎实现过程。
  • 禁忌:业务模块里写死支付宝 / Twilio / Google 等类名。
  • 禁忌:为驱动配置页单独加后台 JS/CSS 文件(用插件 Settings)。