实时通讯插件

该插件是可本地部署的 Pusher 替代方案，功能更丰富且有持续的开发规划。它能为论坛动态提供实时推送，注册会员与访客均可使用。

功能特性

自动更新论坛首页（同步保留权限及订阅状态）
自动更新通知（点赞、回复、举报类通知均支持）
新帖子实时推送至对应讨论帖内
输入状态指示器：展示当前正在编辑回复的人数

运行要求

本插件需要在服务器环境中单独安装配套服务，类似 MySQL 数据库服务、Apache/Nginx 网页服务。因此你需要拥有独立云服务器、虚拟机，或是支持脚本常驻运行的环境。
同时还需启用队列服务，我们强烈推荐搭配 Redis 队列使用。

基于以上条件，虚拟主机（共享主机）基本无法使用本插件。

部署配置

方式一：使用默认配置

无需额外操作，WebSocket 会直接沿用论坛现有配置。

方式二：通过 `config.php` 自定义配置

新增 websocket 配置项，按需修改参数：

return [
    // 其他原有配置
    'websocket' => [
    
    ] 
];

配置项说明

完整可配置参数如下：

server-*：守护进程基础配置，指定监听IP/主机与端口
- server-host：守护进程监听地址，默认 0.0.0.0
- server-port：守护进程监听端口，默认 6001
js-client-*：论坛前端（JavaScript）连接 WebSocket 服务的配置
- js-client-host：前端连接服务端的地址，默认读取论坛配置网址
- js-client-port：前端连接服务端的端口，默认 6001
- js-client-secure：前端是否启用加密连接，默认根据论坛网址判断（HTTPS 则开启，HTTP 则关闭）
php-client-*：论坛后端向前端推送事件时使用的配置
- php-client-host：后端推送事件的目标地址，默认读取论坛配置网址
- php-client-port：后端推送事件的目标端口，默认 6001
- php-client-secure：后端与服务端通信是否加密，默认根据论坛网址判断
- php-client-timeout：后端推送请求超时时间（秒），默认 3
app-*：服务端、前端脚本、守护进程之间的授权配置
- app-key：公共验证密钥，默认由论坛网址哈希生成
- app-secret：私密密钥，用于访问私有通道、推送事件，默认由数据库密码哈希生成
max-connections：最大并发连接数，默认 1000。若服务负载过高，可适当调低该数值。

启动 WebSocket 服务

需要手动启动服务端程序。测试环境可使用以下命令：

php flarum realtime:serve -vvv --debug

执行后服务将启动，并输出完整调试日志。该窗口保持打开状态，服务才会持续运行。

上述命令仅适用于临时测试，关闭窗口或关机后服务就会停止。生产环境需将程序设置为系统守护进程，下文提供 Supervisor 和 systemd 两种部署方案。

方案一：基于 Supervisor 部署守护进程

生产环境需设置服务常驻运行，异常时自动重启，可使用 Supervisor 工具。

# Debian / Ubuntu 系统安装
apt install supervisor

# Red Hat / CentOS 系统安装
yum install supervisor
systemctl enable supervisord

在 /etc/supervisor/conf.d 目录新建配置文件 realtime.conf，内容如下：

注意：修改 command 中的路径为你的 Flarum 安装目录；修改 user 为网站运行账号（Apache/Nginx 运行用户）。

[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

更多 Supervisor 用法可查阅官方文档。

方案二：基于 systemd 部署守护进程

使用 vim、vi 等编辑器，在 /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 实际安装目录
ExecStart：填写 PHP 程序绝对路径（可执行 whereis php/whereis php80 查询）
User：改为网站运行账号

重新加载系统服务配置：

sudo systemctl daemon-reload

启动服务：

sudo systemctl start flarum-realtime.service

查看运行状态：

sudo systemctl status flarum-realtime.service

设置开机自启：

sudo systemctl enable flarum-realtime.service

自动重启机制

当检测到插件启用/禁用等变更时，守护进程会在10秒内自动停止。配置正常的情况下，服务重启后会加载最新插件配置并正常运行。

如需关闭该自动检测功能，启动命令追加参数：

php flarum realtime:serve --ignore-extension-toggles

手动强制重启

CI/CD 等场景下，可使用命令让服务在10秒内停止并触发重启：

php flarum realtime:halt

启用加密连接

如需对 WebSocket 连接加密，最简单的方式是通过 Nginx/Apache 反向代理端口实现。

Nginx 配置示例
引入插件自带配置文件，且需放在 Flarum 配置文件之前，配置写入 server 区块末尾：

server {
  # 原有PHP解析等配置
  
  include /var/www/flarum/vendor/blomstra/realtime/.nginx.conf;
	include /var/www/flarum/.nginx.conf;
}

暂无其他网页服务器配置示例，高级版可提供专属部署协助。

可选优化：为降低服务器开销，可让后端直接通过本地地址推送事件，修改 config.php：

return [
    // 其他原有配置
    
    // 本地访问降低延迟，后端WebSocket客户端使用本地地址
    'websocket' => [
        'php-client-host' => 'localhost'
    ]
];

常见问题

插件支持多少并发用户？

WebSocket 服务资源占用极低。仅分配1核CPU、1GB内存，即可支撑数千名用户同时在线。后续我们会根据大规模实际使用数据更新该说明。
建议：初期可适当调高资源限制，后续根据实际负载逐步下调。

队列任务 SendTriggerJob 执行失败/被终止

若队列任务 SendTriggerJob 反复失败，请延长队列工作进程超时时间。默认超时为60秒，可设置为360秒，命令如下：

php flarum queue:work --timeout=360

可查阅对应队列驱动文档将该命令设置为守护进程；测试时可追加 -vvv 参数输出详细日志。