第41章 Flarum Realtime扩展：基于WebSocket的实时功能配置指南

版本：2.x 实时功能（Realtime） Realtime 扩展（flarum/realtime）通过 WebSocket 将活动实时推送到论坛，让用户无需刷新页面即可看到最新动态。它是内置扩展，默认处于关闭状态。 启用后： * 随着讨论被开启或回复，讨论列表会自动更新，同时尊重每位查看者的权限和订阅设置。 * 包括点赞、回复和举报在内的通知无需刷新即可到达。 * 新帖子会直接出现在用户正在阅读的讨论中。 * 输入指示器会显示当前有多少人正在编写回复。 访客和会员均可接收这些更新。 这不仅仅是一个开关 Realtime 需要一个独立且长期运行的进程，就像论坛需要数据库服务器、Web 服务器和队列工作进程一样。这意味着你需要一台能够保持进程运行并进行监控的机器。在共享主机上几乎不可能实现，因此该扩展在那里无法工作。 如果在未配置守护进程（daemon）的情况下启用它，论坛虽然能正常运行，但上述功能均不可用，且不会有任何错误提示来解释原因。 前置要求 * 一个可以运行并维持持久化进程的环境：如自有服务器、虚拟机、Droplet 或容器平台。 * 一个正在运行且带有工作进程（worker）的队列系统。默认的 sync 驱动程序不适用，因为那样每次推送都会在触发它的 Web 请求中执行。Redis 通常是首选。 * 一个供守护进程监听的端口，默认为 6001。 安装 该扩展随 Flarum 一起提供。请在管理面板的扩展页面中启用它，然后按下方说明配置守护进程。 如果你的安装中未包含此扩展，请像其他包一样安装： composer require flarum/realtime
php flarum migrate
php flarum cache:clear
运行 WebSocket 服务器 为了验证其基本功能，可以在前台运行守护进程： php flarum realtime:serve -vvv --debug
它会持续运行，直到你停止它或关闭终端，并打印当前的执行情况。这仅用于测试：一旦终端关闭，实时功能也随之停止。 对于生产环境，进程需要受到监控（supervised），以便在启动时自动运行，并在意外退出后自动恢复。 使用 supervisor # Debian / Ubuntu
apt install supervisor

# Red Hat / CentOS
yum install supervisor
systemctl enable supervisord
创建 /etc/supervisor/conf.d/realtime.conf 文件，并将其中的 /var/www/flarum 替换为你的 Flarum 目录，将 www-data 替换为你的 Web 服务器运行用户： [program:realtime]
command=/usr/bin/php flarum realtime:serve
directory=/var/www/flarum/
numprocs=1
autostart=true
autorestart=true
user=www-data
stdout_logfile=/var/www/flarum/storage/logs/realtime.log
stderr_logfile=/var/www/flarum/storage/logs/realtime-error.log
然后加载配置并检查状态： sudo supervisorctl update
sudo supervisorctl status
使用 systemd 创建 /etc/systemd/system/flarum-realtime.service 文件： [Unit]
Description=flarum-realtime
StartLimitIntervalSec=0

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/flarum
ExecStart=/usr/bin/php flarum realtime:serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
调整 WorkingDirectory 为你的 Flarum 目录，将 User 设置为站点运行用户，如果路径不同，还需调整 ExecStart 中的 PHP 路径（可通过 whereis php 查看）。然后执行： sudo systemctl daemon-reload
sudo systemctl start flarum-realtime.service
sudo systemctl status flarum-realtime.service
sudo systemctl enable flarum-realtime.service
最后一行命令确保服务在重启后自动启动。 配置 Realtime 无需任何配置即可工作：它会从论坛自身的 URL 和数据库凭据中获取设置。若要覆盖这些设置，可在 config.php 中添加 websocket 配置块： return [
// ..
'websocket' => [
'server-port' => 6001,
],
];
选项默认值说明server-host0.0.0.0守护进程监听的主机。server-port6001守护进程监听的端口。js-client-host你的论坛主机浏览器连接的主机。js-client-port6001浏览器连接的端口。js-client-secure取决于论坛 URL 是否为 https浏览器是否通过 TLS 连接。php-client-host你的论坛主机Flarum 后端发送事件到的主机。php-client-port6001Flarum 后端发送事件到的端口。php-client-secure取决于论坛 URL 是否为 https后端与守护进程通信是否走 TLS。php-client-timeout3后端发送事件的超时秒数。max-connections1000最大并发连接数。如果守护进程给服务器造成压力，可以调低。max-channels-per-connection100单个连接最多可订阅的频道数。真实客户端通常只需要几个，所以这是针对异常或恶意客户端的安全上限；只有正当场景超出限制时才调高。app-key由论坛主机名生成浏览器和后端用于认证的公钥。app-secret由数据库密码生成用于私有频道鉴权和发送事件的密钥。 这三组配置值得分清楚：server-* 是守护进程绑定用的，js-client-* 是浏览器被告知去连接的，php-client-* 是你的 PHP 后端把事件递交给守护进程的方式。 显式设置密钥 app-key 和 app-secret 默认由论坛主机名和数据库密码派生。能用，但问题在于一旦你改了数据库密码，secret 也会跟着变，而且把两个凭据无谓地绑在了一起。更妥当的做法是在 config.php 里显式设置这两项。 降低延迟 如果守护进程和论坛跑在同一台机器上，让后端指向 localhost 可以避免 Flarum 为了递交一个事件而绕到公网域名再回来：'websocket' => [
'php-client-host' => 'localhost',
],

设置

在后台管理面板的插件页面可以找到这些设置。

设置项	默认值	描述
输入指示器	开启	对于拥有“查看正在输入”权限的成员，在讨论中显示其他成员正在回复。关闭后，既不会显示也不会通过 WebSocket 发送输入状态。
讨论列表输入点	开启	在访客可见的讨论列表旁显示一个小图标，提示该讨论中有新回复。不显示具体名字。
受限标签下的讨论列表输入点	关闭	对于能查看受限标签的成员，也在这些讨论上显示图标。需要安装 Tags 插件。
讨论列表更新	开启	当讨论有新动态时，列表上方会出现一个按钮提示刷新，并且列表会在设定间隔后自动更新。关闭后，列表仅在手动重载时变化。
自动推送新讨论动态的间隔	10	单位为秒。设为 0 时，列表永不自动更新，读者需点击按钮手动显示新动态。
通知浮层持续时间	10	实时到达的通知在屏幕上停留的秒数。设为 0 则关闭此类弹窗。

拥有“查看正在输入”权限的成员，在其个人的设置页面会多出一个“显示正在输入”开关，用于选择显示具体名字或仅显示正在输入的人数。

权限

该插件会在后台的权限页面添加两个新权限。默认情况下，这两个权限未授予任何用户组，因此只有管理员拥有，除非你手动分配。

权限	板块	描述
查看正在输入	View	在讨论中看到输入指示器。可授予访客，若安装 Tags 插件，还可按受限标签单独授权。
查看全站的正在输入用户	Moderate	查看整个论坛的输入状态，例如在 Deck 插件的“正在输入”列中显示。

在 TLS 后运行

守护进程使用纯 HTTP 通信。在 HTTPS 论坛上，浏览器会拒绝从安全页面打开不安全的 WebSocket 连接，因此连接需由你的 Web 服务器终止并代理转发。 Realtime 为此提供了一个 nginx 配置文件。请将其包含在你的 server 块中，位于 Flarum 包含指令之前：

server {
  # 你的 php 匹配规则
  include /var/www/flarum/vendor/flarum/realtime/.nginx.conf;
  include /var/www/flarum/.nginx.conf;
}

顺序很关键：Flarum 的配置中有一个“全匹配”规则，如果它排在前面，会在实时规则生效之前就把 websocket 路径拦截掉。 重启守护进程 守护进程会在内存中加载已启用的扩展，因此当某个扩展被启用或禁用时，它会在十秒内自动停止自身。配合上文提到的 supervisor 或 systemd，它会立即重启并感知到变更。这是预期行为，并非崩溃。 如果要关闭此自动重启行为： php flarum realtime:serve --ignore-extension-toggles
如果要手动强制重启（这是部署脚本中常用的钩子），请让正在运行的守护进程停止，并交由 supervisor 将其拉起来： php flarum realtime:halt
故障排查 `php flarum realtime:info` 是首要排查工具。它会列出当前开启的频道，统计已登录成员的连接数，然后发送三个测试事件：一个直接发送，一个异步发送，一个通过队列发送。 这三类事件能反映出不同的状态。如果直接和异步事件都成功，说明后端能连通守护进程，`php-client-*` 配置和守护进程本身没有问题。如果前两个成功但队列事件始终未送达，问题出在队列 worker 而非实时功能本身。如果三者全部失败，则说明 PHP 根本无法连接守护进程。 如果内容没有更新且没有报错，请检查守护进程是否在运行（执行 `supervisorctl status` 或 `systemctl status flarum-realtime.service`），同时确认队列 worker 也在运行。实时功能将推送任务交给队列处理，如果没有 worker 在消费，事件就会堆积。上述 `realtime:info` 命令可以区分这两种情况。 如果 `SendTriggerJob` 每次都失败，请提高队列 worker 的超时时间。默认值是 60 秒，但在繁忙的论坛上，该任务可能超过这个时长： php flarum queue:work --timeout=360
能承载多少人？守护进程很轻量。为进程分配 1 个 CPU 和 1 GB 内存，应能支撑数千名并发用户。初期建议资源分配宽裕一些，待观察到实际使用情况后再酌情缩减。 面向开发者 扩展可以通过实时功能广播自定义事件。请参阅 Realtime extender 的开发者指南。