Flarum Pusher 扩展实时更新机制深度解析:从 CHANGELOG 到源码架构

原创2026-10-10 23:58:141,979 阅读
文章标签:后端前端

Flarum Pusher 扩展实时更新机制深度解析:从 CHANGELOG 到源码架构

导读

本文以 extensions/pusher/CHANGELOG.md 的版本演进为主线,结合仓库内该扩展的完整源码,系统讲解 Flarum Pusher 扩展如何借助 Pusher 服务实现讨论区新帖/新讨论实时推送:包括公开频道与私有用户频道的双通道模型、服务端事件监听与推送、前端订阅与"显示更新"按钮的实现,以及从旧版 jQuery 时代演进到 TypeScript 现代前端的技术脉络。读完本文,你将掌握该扩展从安装配置、参数含义到底层推送链路的完整实战知识。


一、扩展定位:实时更新讨论区

Pusher 扩展(flarum/pusher,composer 包名见 composer.json)是 Flarum 生态中一个典型的托管式实时推送方案:它借助 Pusher 云服务(或任何兼容 Pusher 协议的服务器,如 soketi),在浏览器与服务器之间建立 WebSocket 长连接,让用户无需手动刷新页面即可看到新帖子和新讨论的出现。

它在 Flarum 扩展生态中的定位与另一个扩展 realtime(见 extensions/realtime/README.md)形成对照:realtime 是自托管 WebSocket 服务(需自行部署守护进程),而 pusher 走的是第三方托管服务,配置与部署成本更低,二者互不冲突,可根据部署环境二选一。

从 CHANGELOG.md 可以看到这个扩展的核心能力演进脉络:

版本 关键变化 技术意义
0.1.0-beta.8.1 修复失效功能 早期稳定性修复
0.1.0-beta.9 用监听器替换事件订阅者 修复服务过早解析问题,是架构上最重要的一次重构
0.1.0-beta.13 更换 CDN、更新 JS 依赖 前端资源加载策略调整
0.1.0-beta.14 升级 mithril 2、修正语言包加载 前端框架升级
0.1.0-beta.15 适配新版后台、使用最新 extenders 跟随 Flarum 后台体系演进
0.1.0-beta.16 locale 文件迁入扩展自身 语言包从翻译包迁移到扩展内
1.0.0 非公开讨论也支持实时推送、兼容 Flarum v1.0 功能与兼容性的双里程碑
1.1.0 无变化 版本占位
1.2.0 迁移 TypeScript、去 jQuery 改用原生 JS、修复分页更新按钮 前端现代化重构

二、扩展装配:extend.php 揭示了完整的集成面

扩展的入口文件 extend.php 以 Flarum Extender 的方式声明了全部集成点,是理解该扩展的最快路径:

return [
    (new Extend\Frontend('forum'))
        ->js(__DIR__.'/js/dist/forum.js')
        ->css(__DIR__.'/less/forum.less'),

    (new Extend\Frontend('admin'))
        ->js(__DIR__.'/js/dist/admin.js'),

    (new Extend\Routes('api'))
        ->post('/pusher/auth', 'pusher.auth', AuthController::class),

    new Extend\Locales(__DIR__.'/locale'),

    (new Extend\Notification())
        ->driver('pusher', PusherNotificationDriver::class),

    (new Extend\Settings())
        ->serializeToForum('pusherKey', 'flarum-pusher.app_key')
        ->serializeToForum('pusherCluster', 'flarum-pusher.app_cluster')
        ->serializeToForum('pusherHostname', 'flarum-pusher.server_hostname'),

    (new Extend\Event())
        ->listen(Posted::class, Listener\PushNewPost::class),

    (new Extend\ServiceProvider())
        ->register(PusherProvider::class),
];

可以拆解出五条集成链路:

  1. 前端资源:论坛端与后台端分别注入编译后的 JS 与论坛端样式;
  2. API 路由:注册 POST /api/pusher/auth,用于浏览器向 Pusher 私有频道发起订阅时所需的鉴权(对应 AuthController);
  3. 通知驱动:注册名为 pusher 的 PusherNotificationDriver,与核心 framework/core/src/Extend/Notification.php 的驱动注册机制对接;
  4. 设置序列化:把后台存储的 flarum-pusher.app_key、flarum-pusher.app_cluster、flarum-pusher.server_hostname 序列化为前端可读的 pusherKey、pusherCluster、pusherHostname 属性;
  5. 事件监听:监听核心的 Posted(新帖发布)事件,触发 PushNewPost 推送逻辑。

CHANGELOG 中 0.1.0-beta.15 提到的"updated to use newest extenders"正是这种 Extend\ 声明式装配形态的体现,相比早期直接在服务提供者里手动挂路由、事件的方式,声明式 extenders 更易维护。


三、服务端架构:一条完整的实时推送链路

3.1 依赖注入:PusherProvider 组装客户端

src/Provider/PusherProvider.php 负责向容器绑定 Pusher\Pusher 客户端实例:

$this->container->bind(Pusher::class, function () {
    $settings = $this->container->make(SettingsRepositoryInterface::class);
    $options = [];
    if ($cluster = $settings->get('flarum-pusher.app_cluster')) {
        $options['cluster'] = $cluster;
    }
    if ($host = $settings->get('flarum-pusher.server_hostname')) {
        $options['host'] = $host;
    }
    return new Pusher(
        $settings->get('flarum-pusher.app_key'),
        $settings->get('flarum-pusher.app_secret'),
        $settings->get('flarum-pusher.app_id'),
        $options
    );
});

注意 cluster 与 host 都是可选的:默认使用 Pusher 托管服务并按 cluster 选择就近接入点;若配置了 server_hostname,则 host 被覆写为自托管服务器地址(soketi 等 Pusher 兼容实现),这正是 locale/en.yml 中 server_hostname_help 所描述的用法。

3.2 核心推送:PushNewPost 监听器

src/Listener/PushNewPost.php 是实时推送的核心,完整实现了 CHANGELOG 1.0.0 中"非公开讨论实时化"这一特性:

public function handle(Posted $event): void
{
    $channels = [];

    if ($event->post->isVisibleTo(new Guest)) {
        $channels[] = 'public';
    } else {
        // 对每个用户私有频道逐一做可见性检查
        $response = $this->pusher->getChannels([
            'filter_by_prefix' => 'private-user'
        ]);
        ...
        foreach ($response->channels as $name => $channel) {
            $userId = Str::after($name, 'private-user');
            if (($user = User::find($userId)) && $event->post->isVisibleTo($user)) {
                $channels[] = $name;
            }
        }
    }

    if (count($channels)) {
        $tags = $this->extensions->isEnabled('flarum-tags') ? $event->post->discussion->tags : null;
        $this->pusher->trigger($channels, 'newPost', [
            'postId' => $event->post->id,
            'discussionId' => $event->post->discussion->id,
            'tagIds' => $tags ? $tags->pluck('id') : null
        ]);
    }
}

其设计要点:

  • 可见性优先:先以 Guest 身份调用 isVisibleTo,公开可读的帖子推送到 public 频道;否则视为受限内容,查询所有 private-user 前缀的在线私有频道,再逐个按用户可见性过滤。这保证只有有权看到帖子的人才收到推送,这是 1.0.0 版本的关键新增能力。
  • 事件负载:newPost 事件携带 postId、discussionId,若启用了 flarum-tags 扩展还附带 tagIds 用于前端按标签过滤——对应 CHANGELOG 0.1.0-beta.14 修复的"flarum/tags 未安装时不应发布标签事件"问题(isEnabled('flarum-tags') 判断正是该修复在源码中的落点)。
  • 与 0.1.0-beta.9 重构的呼应:该监听器通过构造函数注入 Pusher 与 ExtensionManager,由容器在事件触发时才解析依赖,避免了事件订阅者在启动阶段过早解析服务的问题——这正是 CHANGELOG 中那次"以监听器替换事件订阅者"重构的直接成果。

3.3 私有频道鉴权:AuthController

浏览器订阅 private-user{id} 频道时必须先通过鉴权。 src/Api/Controller/AuthController.php 实现该逻辑:

$userChannel = 'private-user'.RequestUtil::getActor($request)->id;
$body = $request->getParsedBody();

if (Arr::get($body, 'channel_name') === $userChannel) {
    $pusher = new Pusher(/* 从设置读取 app_key / app_secret / app_id ... */);
    $payload = json_decode($pusher->socket_auth($userChannel, Arr::get($body, 'socket_id')), true);
    return new JsonResponse($payload);
}
return new EmptyResponse(403);

安全要点:频道名由服务端根据当前登录用户 ID 拼装,不接受客户端任意指定频道名;只有请求的频道与当前用户匹配时才调用 socket_auth 签发签名,否则直接返回 403。这与前端设置中的 app_secret 描述"仅服务端使用、务必保密"(见 locale/en.yml)相印证——签名由服务端私钥完成,浏览器只持有公开的 key。

3.4 通知驱动:PusherNotificationDriver

除了新帖推送,该扩展还通过通知驱动把"新通知"实时送达用户。 src/PusherNotificationDriver.php 实现了核心的 framework/core/src/Notification/Driver/NotificationDriverInterface.php:

public function send(BlueprintInterface $blueprint, array $users): void
{
    if (count($users)) {
        $this->queue->push(new SendPusherNotificationsJob($blueprint, $users));
    }
}

它遵循核心接口约定(send 按需入队、registerType 注册通知偏好类型),把发送工作放入队列异步执行。src/SendPusherNotificationsJob.php 在 handle 中对每个接收者检查 $user->shouldAlert($this->blueprint::getType())(用户是否开启该类型的弹窗提醒),然后向 private-user{id} 频道触发 notification 事件:

$pusher->trigger('private-user'.$user->id, 'notification', null);

双通道模型小结:

频道 事件 用途
public newPost 公开讨论的新帖/新讨论提示
private-user{id} newPost 受限讨论按可见性定向推送
private-user{id} notification 用户新通知数实时+1

四、前端实时机制:TypeScript 化的订阅与更新 UI

CHANGELOG 1.2.0 的两项变更("Convert to TypeScript"、"Replace jQuery with vanilla JS")集中体现在前端入口 js/src/forum/index.tsx 中,全部逻辑以 mithril 组件扩展(extend)方式挂载,不再有 jQuery 痕迹。

4.1 建立连接与频道订阅

app.pusher = (async () => {
  const socket: Pusher = new Pusher(app.forum.attribute('pusherKey'), {
    authEndpoint: `${app.forum.attribute('apiUrl')}/pusher/auth`,
    cluster: app.forum.attribute('pusherCluster'),
    auth: { headers: { 'X-CSRF-Token': app.session.csrfToken } },
    httpHost: app.forum.attribute('pusherHostname'),
    wsHost: app.forum.attribute('pusherHostname'),
  });
  return {
    channels: {
      main: socket.subscribe('public'),
      user: app.session.user ? socket.subscribe(`private-user${app.session.user.id()}`) : null,
    },
    pusher: socket,
  };
})();

关键细节:pusherKey/pusherCluster/pusherHostname 正是后台设置经 serializeToForum 序列化而来的前端属性;wsHost/httpHost 同时设置为 pusherHostname 以支持自托管服务器;鉴权请求附带 X-CSRF-Token 头,与后端 AuthController 配合完成私有频道签名。源码注释还解释了为何在 mount 生命周期中创建连接而非 initializer 阶段——此时 app.forum 尚未填充,读取属性会抛错。

4.2 通知事件处理

用户频道收到 notification 事件后,前端递增 unreadNotificationCount 与 newNotificationCount 并清空通知列表缓存后重绘,实现角标实时+1。

4.3 讨论列表更新与"显示更新"按钮

newPostListHandler 处理 newPost 事件时:

  • 若当前有搜索词、排序或过滤条件则跳过(避免干扰用户当前视图);
  • 若处于标签页且事件中的 tagIds 不包含当前标签则跳过;
  • 若讨论不在当前页且尚未记录,则加入 app.pushedUpdates 数组并在标题上累计未读数;
  • 通过 contentItems 注入一个 Button,文案使用 locale/en.yml 中的 show_updates_text(支持 {count, plural} 复数翻译:1 条为 "Show # updated discussion",多条为 "Show # updated discussions");
  • 点击按钮刷新讨论列表、清空计数并重绘。

这正是 CHANGELOG 1.2.0 修复的"点击更新按钮导致讨论列表分页被破坏"问题的对应实现:v1.x 时代直接改动 DiscussionList 的 vdom 结构来拼接横幅,而 2.x 改为在 IndexPage 的 contentItems ItemList 中插入元素,规避了分页重渲染时的结构冲突。源码注释也明确说明这一设计参考了 extensions/realtime 的做法。

4.4 讨论详情页的流式更新

在 DiscussionPage 上监听 newPost:若新帖属于当前讨论,则通过 app.store.find 拉取最新讨论数据并调用 this.stream.update() 刷新帖子流;若页面不在焦点,则在浏览器标题栏累计新帖数,并在页面重新获得焦点时清零。onremove 钩子负责解绑事件,避免页面切换后的重复监听。


五、后台配置:五个设置项逐项解析

后台设置界面由 js/src/admin/extend.tsx 声明,五个设置项全部以 flarum-pusher. 前缀存储在 Flarum 设置表,其含义与帮助文案完整记录在 locale/en.yml:

设置键 界面标签 说明 取值参考
flarum-pusher.app_id App ID Pusher 应用页面的数字 App ID 必填
flarum-pusher.app_key App Key 公开 key,会发送到浏览器,不保密 必填
flarum-pusher.app_secret App Secret 私有密钥,仅服务端使用,务必保密 必填
flarum-pusher.app_cluster Cluster 应用所在集群,如 eu、us2;配置了自定义 hostname 时留空 可选
flarum-pusher.server_hostname Server Hostname 覆写客户端连接的服务器地址,用于 soketi 等自托管 Pusher 兼容服务;留空则使用 Pusher 托管服务 可选

从 extend.php 可见,仅 app_key、app_cluster、server_hostname 三个设置被序列化到前端;app_id 与 app_secret 只存在于服务端,用于 PusherProvider 与 AuthController 中的客户端构造和签名。


六、安装与依赖要求

安装该扩展需满足 composer.json 的依赖:

composer require flarum/pusher
  • 运行时依赖 flarum/core: ^2.0.0(即面向 Flarum 2.x 的当前版本,对应 CHANGELOG 中 1.x 系列版本线);
  • 运行时依赖 pusher/pusher-php-server: ^7.2(服务端 SDK);
  • 前端依赖 pusher-js: ^8.4.0(见 js/package.json);
  • 开发依赖 flarum/tags: ^1.0,用于标签相关的联调测试——生产环境不强制安装,源码通过 isEnabled('flarum-tags') 做了可选兼容。

启用后在后台"Pusher Settings"填入上述五项配置,再在 Pusher 官方控制台 配合 monorepo 的 flarum-webpack-config,开发模式运行 yarn dev,生产构建运行 yarn build。


七、从 CHANGELOG 提炼的三条架构经验

结合 CHANGELOG 与源码,可以提炼出对 Flarum 扩展开发者极具参考价值的经验:

  1. 事件监听器优于事件订阅者(0.1.0-beta.9):早期用事件订阅者在容器解析阶段过早实例化服务,导致依赖链脆弱;改为懒解析的监听器后,服务在事件触发时才注入,PushNewPost.php 的构造函数注入即此模式的现代形态。

  2. 可选依赖要显式探测(0.1.0-beta.14):flarum/tags 未启用时不发布标签事件,源码通过 ExtensionManager::isEnabled('flarum-tags') 实现;任何"软依赖"扩展都应采用类似探测而非假设。

  3. 前端 UI 注入要避开生命周期脆弱的组件(1.2.0):讨论列表分页在 vdom 直改方案下易碎,最终改为在稳定页面容器(IndexPage)的 ItemList 中插入更新按钮,并在 oncreate/onremove 中成对绑定/解绑事件,保证导航切换后无残留监听。

这些经验同样适用于理解同仓库的 extensions/realtime(自托管实时方案)的架构选择。


参考文件索引

登录后查看全文
framework