事件触发任务 AI 编程指南 ZH
面向 AI 编程工具的 PHPTS 「事件触发任务」PHP 脚本编写与「Server → Client 主动推送」规范:五类事件脚本模板、PHPTS_EVENT_* 元数据、输出与关闭约定、共用推送接口及完整调用示例。教 AI 编程工具如何去写对应的 PHP 代码,并让用户了解整个「事件触发任务」的生命周期流程。
Markdown 原文下载: event-ai-guide-zh.md(可直接交给 AI 编程工具阅读)
读者:AI 编程工具(Trae / Claude Code / Cursor / Codex / opencode 等)。
目标:让 AI 在看不到 PHPTS 源码、甚至不在 PHPTS 服务器上的情况下,也能正确编写「事件触发任务」的 PHP 脚本,并实现 Server → Client 主动推送。
适用版本:PHPTS 2.0.13.1(2026-11-20)。更早版本请先看文末「版本与特性时间线」。
本文只描述对外契约(脚本入参、输出语义、推送接口),不依赖本仓库路径与内部实现。
0. 先读这一节:使用本文档的正确姿势
0.1 三条硬事实
-
PHP 不持有长连接。WebSocket / TCP / MQTT / 串口的长连接全部由 Rust 网关
phpts-event.exe持有;PHP 只是一次事件一次执行的无状态逻辑单元。 -
事件脚本的「输出」就是业务数据,不是网页、不是 HTTP 响应。
echo什么,网关就把什么回给客户端(WebSocket 文本帧 / TCP 原始字节 / MQTT 消息 / 串口字节)。 -
主动推送不是 PHP 直接写 socket,而是调用网关的共用 HTTP 推送接口(默认
http://127.0.0.1:3379),由网关投递给在线连接。
0.2 本文档可能不在 PHPTS 服务器上被读取
因此:
- 文中所有路径、端口、Token 都是占位符,必须向用户确认或在目标环境读取,禁止猜测。
- 不要假设 PHPTS 安装在某个固定盘符;脚本路径以PHPTS 安装目录(base)为基准的相对路径配置,代码内部用
__DIR__定位同目录文件。 - 如果 AI 无法访问 PHPTS 安装目录,就只输出脚本内容 + 配置项 + 自检命令,并在交付说明里列出「需要人工在界面确认的项」。
- 运行在另一台服务器上的 PHP 代码,只能走网络调用推送接口;
phpts_kv_*扩展在那台机器上不可用(见 §6.7)。
0.3 环境探测命令(Windows PowerShell / curl)
# 任务池是否在监听(事件脚本实际由它执行)
Test-NetConnection 127.0.0.1 -Port 6285
# 推送接口是否可达(未设 Token 时直接返回客户端列表)
curl.exe -s "http://127.0.0.1:3379/ws/clients"
curl.exe -s "http://127.0.0.1:3379/tcp/clients"
curl.exe -s "http://127.0.0.1:3379/serial/ports"
# 确认 PHP 8.5 任务池加载了 phpts_kv(php.ini 在 data\conf\php8.5-task\php.ini)
Select-String -Path "data\conf\php8.5-task\php.ini" -Pattern "extension=phpts_kv"
0.4 配置从哪来
推送接口地址/端口/Token:「事件触发任务」页 →「全局委托配置与推送服务」Tab →「(Server → Client)主动推送接口」卡;落盘在 data\conf\phpts-event\event.conf 的 [pushapi]
WebSocket 端口:「WebSocket 服务器」Tab(默认 3380,TLS 3343)
TCP 监听端口:「TCP 服务器」Tab 的端口规则(默认从 59301 起)
事件脚本:规则表里的「PHP 脚本」;相对路径以 PHPTS 安装目录为基准
超时:全局 [server] fcgi_timeout(默认 300 秒)+ 单规则 timeout(0 = 继承)
没有拿到 Token 时,不要把 Token 写成空字符串后当作“无需鉴权”。先问用户;用户确认未配置 Token 才可以留空。
1. 运行模型(必须先理解)
设备 / 浏览器 / MQTT 客户端 / 串口设备
│ 长连接(WS / TCP / MQTT / COM)
▼
┌──────────────────────────────┐
│ phpts-event.exe │ 长连接、分帧、心跳、路由、注册表
│ WebSocket / TCP / MQTT / │
│ 串口 / 定时器 / 推送接口 │
└──────────────┬───────────────┘
│ 每个事件一次 FastCGI 委托(127.0.0.1:6285)
▼
┌──────────────────────────────┐
│ PHP FastCGI (任务) 进程池 │ phpts-php-task.exe × N
│ 执行你的 PHP 脚本 │ 无状态、可并发复用
└──────────────┬───────────────┘
│ 脚本输出
▼
原路回写:WS 文本帧 / TCP 字节 /
MQTT 应答主题 / 串口字节 / 日志
任意普通 PHP(Nginx Web、CLI、定时脚本)
│ HTTP POST
▼
http://127.0.0.1:3379/ws/send
http://127.0.0.1:3379/tcp/send
http://127.0.0.1:3379/serial/send
│
▼
phpts-event.exe 按 client_id / 串口名投递给在线连接
1.1 必须记住的 8 条行为
一次事件一次请求 :每次消息/帧/定时触发都会重新执行整个 PHP 文件;不要依赖进程内全局变量跨事件保存状态
无 Session、无 Cookie、无 HTTP 头
:不要用 $_SESSION、$_COOKIE、getallheaders()、$_FILES
请求方法是 POST
:正文用 file_get_contents('php://input') 读取;只有定时器的「附加参数」能通过 $_GET 拿到
单连接串行委托 :同一条 WS/TCP 连接,上一条在途时不会读下一条;脚本慢会直接降低该连接吞吐
超时双层 :全局默认 300 秒,单规则可覆盖;超时后网关丢弃本次结果(WS 不回帧但不断连,TCP 不写回但不断连)
不自动拉起任务池 :任务池没启动时,委托直接失败;先启动「PHP FastCGI (任务)」
输出即协议数据
:任何 PHP 警告、var_dump、BOM 都会混进业务数据,可能直接破坏客户端协议
脚本路径相对 base
:规则里填 wwwroot/event/ws.php 等价于 <PHPTS安装目录>/wwwroot/event/ws.php;绝对路径也可
1.2 脚本运行环境
- PHP 8.5(任务池当前只支持 8.5)。
- 独立的任务池
php.ini:data\conf\php8.5-task\php.ini。 -
phpts_kv默认已开启;用function_exists('phpts_kv_set')做能力探测。 -
任务池 php.ini 种子的
display_errors = On。这是最容易踩的坑:一条 Warning 就会混进 WS 帧/TCP 字节里。每个脚本开头必须关掉(不要依赖服务器配置):
ini_set('display_errors', '0');
error_reporting(E_ALL);
- 没有设置
date.timezone时 PHP 默认按 UTC。需要本地时间就显式设置:
date_default_timezone_set('Asia/Shanghai');
- 工作目录不保证;所有文件操作都用
__DIR__拼接,不要依赖getcwd()。 -
DOCUMENT_ROOT恒为<base>/data/wwwroot,与脚本真实位置无关,不要用它拼脚本路径。
2. 事件脚本通用模板
所有事件脚本都建议从下面这个骨架开始:
<?php
// 1) 输出就是协议数据:关闭 PHP 错误直出,错误走日志
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');
// 2) 原始输入(二进制安全),不要用 $_POST
$raw = file_get_contents('php://input');
// 3) 网关注入的元数据
$type = $_SERVER['PHPTS_EVENT_TYPE'] ?? ''; // websocket|tcp|mqtt|serial|timer
$name = $_SERVER['PHPTS_EVENT_NAME'] ?? ''; // 规则名
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? ''; // WS/TCP 连接 ID;MQTT 为订阅 Client ID;串口/定时器为空
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? ''; // WS/TCP 对端 IP(不含端口);其余为空
$timeout = (int)($_SERVER['PHPTS_EVENT_TIMEOUT'] ?? 300); // 本次生效超时(秒)
// 4) 业务处理:任何异常都自己兜住,返回可识别的错误数据
try {
$result = ['ok' => true, 'echo' => $raw];
echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
} catch (Throwable $e) {
error_log('[event] ' . $e->getMessage());
echo json_encode(['ok' => false, 'error' => 'internal error'], JSON_UNESCAPED_UNICODE);
}
2.1 元数据变量对照表
PHPTS_EVENT_TYPE
WebSocket:websocket
TCP:tcp
MQTT:mqtt
串口:serial
定时器:timer
PHPTS_EVENT_NAME
WebSocket:规则名
TCP:规则名
MQTT:规则名
串口:规则名
定时器:规则名
PHPTS_EVENT_PATH
WebSocket:命中的握手路径
TCP:空
MQTT:空
串口:空
定时器:空
PHPTS_EVENT_PORT
WebSocket:空
TCP:监听端口
MQTT:空
串口:串口名(如 COM3)
定时器:空
PHPTS_EVENT_TOPIC
WebSocket:空
TCP:空
MQTT:实际命中主题
串口:空
定时器:空
PHPTS_EVENT_CLIENTID
WebSocket:连接 ID
TCP:连接 ID
MQTT:订阅 Client ID
串口:空
定时器:空
PHPTS_EVENT_CLIENTIP
WebSocket:客户端 IP
TCP:客户端 IP
MQTT:空
串口:空
定时器:空
PHPTS_EVENT_TIMEOUT
WebSocket:本次超时秒数
TCP:同左
MQTT:同左
串口:同左
定时器:同左
2.2 输出约定
WebSocket:作为 text 帧回送同一条连接;输出为空也会回一个空文本帧
TCP:原始字节原样写回同一条连接;输出为空则不写回
MQTT:输出发布到规则的「应答主题」;未配置应答主题或输出为空则不发布
串口:仅当规则开启「应答写回串口」时,输出原样写回串口
定时器:输出只写入网关日志 logs/phpts-event-YYYY-MM-DD.log
补充:脚本里的 header() 调用没有意义(FastCGI 的 CGI 头块会被网关剥掉),不要用它设置 Content-Type;直接输出正文即可。
2.3 主动关闭连接(仅 WS / TCP)
脚本输出恰好等于
__PHPTS_CLOSE__(首尾 ASCII 空白不计)时:
- WebSocket:网关回
close 1000并关闭连接,该文本不发送; - TCP:网关直接断开连接,不写回任何字节。
if (trim($raw) === 'QUIT') {
echo '__PHPTS_CLOSE__';
return;
}
以下都不算约定值,会当普通业务输出处理:
echo '"__PHPTS_CLOSE__"'; // 带引号
echo json_encode(['t' => '__PHPTS_CLOSE__']); // JSON 包装
echo "__PHPTS_CLOSE__\nextra"; // 拼接了其它内容
2.4 日志与调试
- 用
error_log()或写文件,不要echo/var_dump调试。 - 写文件用
__DIR__定位,并加LOCK_EX防止并发写坏:
file_put_contents(__DIR__ . '/event.log', date('c') . ' ' . $line . PHP_EOL, FILE_APPEND | LOCK_EX);
- 网关日志:
logs/phpts-event-<本地日期>.log;PHP 的 stderr 也会进这里。 - 修改脚本不需要重启网关或任务池,下一次事件即生效。
3. 五类事件脚本
3.1 WebSocket 服务器
绑定关系:客户端握手 URL 的 path 与规则「路径」精确匹配(查询串不参与匹配)。路径不匹配返回 404 并关闭连接。
输入:一条完整的 WebSocket 消息(text 或 binary 的载荷原始字节);单条消息上限 1MB,超限网关回 close 1009。
输出:一条 text 帧。注意:即使客户端发的是 binary,网关回包也固定是 text 帧;二进制业务请在 PHP 里做 base64/hex 编码后再输出。
客户端身份:握手可带 ?client_id=<id>(也接受 ?id=),白名单 [A-Za-z0-9_.:-]{1,64};不带则网关自动分配 ws-xxxxxxxx。同 ID 新连接会顶掉旧连接(旧连接收到 close 1000)。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
$raw = file_get_contents('php://input');
$name = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$path = $_SERVER['PHPTS_EVENT_PATH'] ?? '';
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';
if (trim($raw) === 'QUIT') {
echo '__PHPTS_CLOSE__';
return;
}
$data = json_decode($raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
$data = $raw; // 不是 JSON 就保留原文
}
echo json_encode([
'ok' => true,
'type' => 'ack',
'rule' => $name,
'path' => $path,
'client' => $clientid,
'ip' => $clientip,
'recv' => $data,
'time' => date('c'),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
要点:
- 网关负责协议层 Ping/Pong 与心跳;业务脚本无需处理 ping 帧。
- 浏览器原生 WebSocket 会自动回 Pong;自研客户端必须实现 Pong,否则一个心跳周期后会被 close 1001。
- 业务协议建议统一 JSON 信封,见 §6.8。
3.2 TCP 服务器
绑定关系:每个 [tcp.<规则名>] 是一个独立监听端口,绑定各自的脚本。所有端口共用 [tcpserver] listen 地址。
分帧(关键):
idle(缺省)
行为:连续静默满 idle_ms(缺省 50ms)后,把缓冲合并成一帧
适用:一次写入一帧、无分隔符的透传设备
line
行为:按分隔符切帧,载荷不含分隔符
适用:行协议(\r\n 结尾的 JSON、AT 指令等)
none
行为:每次读到的 TCP 数据段直接成一帧
适用:协议自带长度字段,脚本自己切帧
输入:一帧原始字节。
输出:原样写回同一条 TCP 连接;输出为空不写回。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
$frame = file_get_contents('php://input');
$port = $_SERVER['PHPTS_EVENT_PORT'] ?? '';
$name = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';
// 文本协议才 trim;二进制协议(Modbus RTU 等)绝不能 trim
$cmd = trim($frame);
if ($cmd === 'QUIT') {
echo '__PHPTS_CLOSE__';
return;
}
if ($cmd === 'PING') {
echo "PONG\r\n";
} elseif ($cmd !== '') {
echo "OK\r\n";
}
file_put_contents(
__DIR__ . '/tcp.log',
date('c') . " {$clientip} {$port} {$cmd}" . PHP_EOL,
FILE_APPEND | LOCK_EX
);
要点:
-
line模式已经剥掉分隔符;如果客户端协议要求回包也带分隔符,脚本自己补。 - 二进制回包直接
echo原始字节,例如echo "\xAA\x55\x01\x00";,不要经过 JSON。 - 空输出是合法的(例如只做入库、不需要应答),客户端要能接受无回包。
- 单连接串行:脚本执行期间的后续字节会排队,慢脚本会让
idle的帧边界变粗。
3.3 MQTT 订阅
绑定关系:消息主题与规则「订阅主题」按 MQTT 通配符匹配(+ 一层、# 多层)。
输入:消息体原始字节。QoS 1 的 PUBACK 由网关自动回,脚本不用管。
输出:发布到规则的「应答主题」;应答主题同样支持 +/#,按实际命中主题展开。未配置应答主题或输出为空则不发布。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
$payload = file_get_contents('php://input');
$topic = $_SERVER['PHPTS_EVENT_TOPIC'] ?? '';
$name = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$client = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? ''; // 订阅用的 Client ID,不是每台设备
$data = json_decode($payload, true);
if (!is_array($data)) {
$data = ['raw' => $payload];
}
// 业务处理:入库、报警、联动等
file_put_contents(
__DIR__ . '/sensor.log',
date('c') . " {$topic} {$payload}" . PHP_EOL,
FILE_APPEND | LOCK_EX
);
// 有应答主题时,这段输出会被发布出去
echo json_encode([
'ok' => true,
'rule' => $name,
'topic' => $topic,
'data' => $data,
], JSON_UNESCAPED_UNICODE);
要点:
-
PHPTS_EVENT_CLIENTID是订阅客户端自己的 ID,所有消息都一样,不能拿它区分设备;设备身份应从 payload 或主题层级里取。 - MQTT 没有「客户端断开」联动,
phpts_kv登记要么设 TTL,要么业务主动清理。
3.4 串口监听
绑定关系:每个 [serial.<规则名>] 独立占用一个 COM 口,独立线路参数(波特率/数据位/停止位/校验位)与脚本。
分帧:与 TCP 同名但有一处关键差异:
-
idle:静默窗口冲刷,缺省 50ms; -
none:每次读到即成一帧; -
line:按分隔符切帧,帧内包含分隔符本身(与 TCP 剥分隔符不同),脚本需要自己rtrim。
输入:一帧原始字节。
输出:仅当规则「应答写回串口」开启时,输出原样写回串口。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
$frame = file_get_contents('php://input');
$port = $_SERVER['PHPTS_EVENT_PORT'] ?? '';
$name = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
// line 模式帧内含分隔符;文本协议这里剥掉。二进制协议不要 rtrim
$cmd = rtrim($frame, "\r\n");
if ($cmd === 'PING') {
echo "PONG\r\n";
} elseif ($cmd !== '') {
echo "OK\r\n";
}
要点:
-
不要在脚本里用
phpts_serial_open()再打开同一个 COM 口:网关已独占打开(共享位 0),必然失败。 - 半双工 485 设备靠
echo=1把应答写回同一条线。 - 需要主动写串口(不是应答)时,走推送接口
/serial/send,见 §6。 - Modbus RTU 是二进制协议:绝不能用
line(数据区和 CRC 可能含0x0A/0x0D);用idle配小窗口(9600 波特约 10ms),或让脚本按功能码自己切帧。
3.5 定时器
触发方式(每条规则独立):
interval(缺省)
字段:every
说明:间隔秒(1-86400),防漂移
daily
字段:at
说明:每天本地时刻 HH:MM
weekly
字段:at + weekdays
说明:1=周一 … 7=周日,留空=全周
monthly
字段:at + days
说明:每月几号(1-31),留空=全选
输入:请求体为空;规则的「附加参数」作为 QUERY_STRING,脚本用 $_GET 读取。
输出:只写入网关日志,不返回任何客户端。
防重入(no_reentry,缺省开):上一轮未返回时跳过本轮。关闭后同一脚本可能并发多份,必须自己保证幂等。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');
$job = $_GET['job'] ?? 'daily';
$keep = (int)($_GET['keep'] ?? 7);
// 示例:清理本目录 tmp 下过期文件
$dir = __DIR__ . '/tmp';
foreach (glob($dir . '/*') ?: [] as $file) {
if (is_file($file) && filemtime($file) < time() - $keep * 86400) {
@unlink($file);
}
}
// 输出只进网关日志
echo "job={$job} keep={$keep}" . PHP_EOL;
要点:
- 定时器最适合做「服务端主动推送」的定时任务,例如每天 08:30 给登记过的用户推送提醒(见 §7.4)。
- 单轮执行时间不要超过触发周期;如果会超,保持
no_reentry=1,或把脚本改成投递任务后立即返回。
4. 事件脚本的硬性禁止清单
用 $_POST / $_GET 读事件正文:事件走 FastCGI,正文在 php://input;$_GET 只有定时器附加参数
echo / print_r / var_dump 调试:输出就是协议数据,会破坏 WS/TCP/串口报文
文件开头有 BOM、?> 后有空白:BOM 会进入首帧;还会让 __PHPTS_CLOSE__ 精确匹配失败
依赖 $_SESSION / $_COOKIE / 请求头:事件不是 HTTP 请求,没有这些
依赖全局变量跨请求保存状态:每个事件都是新的请求上下文
依赖 getcwd()
:工作目录不保证,统一用 __DIR__
在 WS 文本帧里发非 UTF-8 二进制:文本帧要求 UTF-8;二进制请 base64/hex 后传输
认为 echo 空字符串 = 关闭连接:WS 空输出会发空帧;关闭连接必须输出 __PHPTS_CLOSE__
在串口脚本里重复打开同一 COM 口:网关已独占,必然失败
用 line 分帧处理 Modbus RTU:二进制里会出现假分隔符,帧随机错位
在事件脚本里 new WebSocket() / fsockopen 连客户端:PHP 不持有长连接;主动推送只能走推送接口
硬编码 Token / 端口 / 路径:不同安装必然不同;必须向用户确认或读配置
假设推送返回 ok 等于客户端已收到:接口只保证「已入队」,没有端到端 ACK
5. 主动推送:先分清两件事
应答式(脚本 echo)
是谁在发:当前事件脚本
能发给谁:只能回当前这条连接
适用:请求-响应、ACK
主动推送(HTTP 接口)
是谁在发:任意 PHP(Web 页、定时脚本、CLI、甚至另一个事件脚本)
能发给谁:任意在线 WS 客户端 / TCP 连接 / 已打开串口
适用:通知、告警、指令下发、广播
需要「服务端在任意时刻主动找客户端」时,一律用主动推送,不要试图让事件脚本长时间挂着。
6. 共用推送接口(Server → Client)
6.1 基本参数
监听地址
默认值:127.0.0.1
说明:只允许本机;跨机推送需改为 0.0.0.0 或 [::]
端口
默认值:3379
说明:不能与 WS/TCP 端口重复
鉴权
默认值:[pushapi] token
说明:非空时,请求必须带 ?token= 或请求头 X-PHPTS-Token
请求体上限
默认值:1MB
说明:Content-Length 超过返回 413
请求头上限
默认值:64KB
说明:超过返回 431
连接超时
默认值:服务端 3 秒读写
说明:客户端也应设短超时(建议 3 秒)
名称大小写
默认值:端点与参数名区分大小写
说明:路径写 /ws/send,不要写成 /WS/send
URI 前缀决定投递目标:/ws/ → WebSocket 文本帧;/tcp/ → TCP 原始字节;/serial/ → 串口原始字节。
推送接口与子服务生命周期解耦:WebSocket / TCP / 串口子服务停止时,对应注册表清空,该前缀端点回 404(client not found / port not found),其它前缀不受影响;推送接口本身也可在界面「(Server → Client)主动推送接口」卡上独立启动/停止/重启。
6.2 端点总表
WebSocket
GET
路径:/ws/clients[?limit=N]
说明:在线客户端列表:{"ok":true,"clients":["a","b"],"total":N},最新连接在前
POST
路径:/ws/send?client=<id[,id...]>[&key=<kv键[,键...]>]
说明:请求体作为 text 帧发送;单目标命中回 {"ok":true},多目标回 sent/missing
GET
路径:/ws/send?client=<id>&text=<数据>
说明:便捷 GET;有请求体时请求体优先
POST
路径:/ws/broadcast
说明:请求体发给全部在线客户端,回 {"ok":true,"sent":N}
TCP
GET
路径:/tcp/clients[?limit=N]
说明:在线连接:{"ok":true,"clients":[{"id":"tcp-...","port":59301}],"total":N}
POST
路径:/tcp/send?client=<id[,id...]>[&key=<kv键>]
说明:请求体原始字节写入目标连接
GET
路径:/tcp/send?client=<id>&data=<内容>
说明:便捷 GET
POST/GET
路径:/tcp/broadcast[?port=N]
说明:发给全部连接;带 port 只发该监听端口
串口
GET
路径:/serial/ports
说明:已打开串口:{"ok":true,"ports":["COM3"]}
POST
路径:/serial/send?port=COM3[,COM4]
说明:请求体原始字节写入指定串口
GET
路径:/serial/send?port=COM3&data=<内容>
说明:便捷 GET
POST/GET
路径:/serial/broadcast
说明:写入全部已打开串口,回 {"ok":true,"sent":N}
6.2.1 参数与边界(按网关实现核对)
正文来源:有请求体时用请求体;请求体为空时取查询串 text=,再退到 data=(三个前缀都接受这两种便捷参数)
空正文:send 与 broadcast 一律返回 400 {"ok":false,"error":"empty payload"};GET 便捷形式必须带 text= 或 data=
目标参数别名:client= 也接受 client_id=;串口 port= 也接受 client=
多目标:client= / key= / port= 均支持逗号分隔,网关去空白、去重、保序
单目标响应:只给一个 client= 且未给 key= 时,命中回 {"ok":true}(兼容旧调用方)
多目标响应:{"ok":true,"sent":N,"missing":[...]};missing 项带 client: / kv: / port: 前缀
全部未命中:404,body 带 "sent":0 与 missing;phpts_kv 整体不可用时额外带 "kv":"unavailable"
广播:回 {"ok":true,"sent":N};一个目标都没有时 sent:0 仍是 200,不算错误
Token 优先级:配置了 Token 时先看查询串 token=,没有再取请求头 X-PHPTS-Token
send端点没有“空消息”语义:空正文直接 400。确实要给客户端发空文本帧时,发一个空格或业务心跳字段(如{"type":"ping"}),不要留空。
6.3 身份与目标
WebSocket
目标 ID:客户端 ID
怎么来:握手 ?client_id= 自报,或网关自动分配
是否自动前缀:自报存原值;自动为 ws-xxxxxxxx
TCP
目标 ID:连接 ID
怎么来:网关自动分配
是否自动前缀:tcp-xxxxxxxx
MQTT
目标 ID:订阅 Client ID
怎么来:配置里自命名
是否自动前缀:无前缀
串口
目标 ID:串口名
怎么来:规则里的 COMx
是否自动前缀:无
-
client=支持逗号分隔多个 ID,也接受别名client_id=; -
key=支持逗号分隔多个phpts_kv键,网关按键读出登记的客户端 ID 再投递; -
client=与key=可以同时给,取并集; - 串口不支持
key=,只认port=。
6.4 响应口径
200
body:{"ok":true}
含义:单目标命中并入队(旧格式)
200
body:{"ok":true,"sent":N,"missing":[...]}
含义:多目标/key= 形式;missing 项带 client: / kv: / port: 前缀
200
body:{"ok":true,"sent":N}
含义:广播
400
body:{"ok":false,"error":"missing client"}
含义:没给 client= 也没给 key=
400
body:{"ok":false,"error":"missing port"}
含义:串口没给 port=
400
body:{"ok":false,"error":"empty payload"}
含义:send / 广播正文为空(GET 便捷形式未带 text=/data=)
403
body:{"ok":false,"error":"invalid token"}
含义:Token 不匹配
404
body:{"ok":false,"error":"client not found","sent":0,"missing":[...]}
含义:目标全部未命中(离线 / ID 不存在 / 子服务已停)
404
body:{"ok":false,"error":"port not found","sent":0,"missing":[...]}
含义:串口全部未打开
404
body:{"ok":false,"error":"unknown endpoint"}
含义:路径或前缀不对
405
body:{"ok":false,"error":"method not allowed"}
含义:端点存在但方法不对
413
body:{"ok":false,"error":"body too large"}
含义:Content-Length 超过 1MB
431
body:{"ok":false,"error":"header too large"}
含义:请求头超过 64KB
200 ok只代表已投进连接的发送队列,不代表客户端业务层已处理。需要可靠送达时,业务协议自己做 ACK/重试。
6.5 推荐封装:phpts_push()
把下面这段放进一个公共文件(例如 wwwroot/event/push.php),其他脚本 require_once __DIR__ . '/push.php';。
<?php
/**
* 调用 PHPTS 共用推送接口。
*
* @param string $channel ws|tcp|serial
* @param string $payload 原始字节(WS 按 UTF-8 文本帧发送)
* @param array $opts client/key/port/broadcast/port_filter/base/token/timeout
* @return array{ok:bool,status:int,body:string,json:?array}
*/
function phpts_push(string $channel, string $payload, array $opts = []): array
{
$base = rtrim((string)($opts['base'] ?? (getenv('PHPTS_PUSH_BASE') ?: 'http://127.0.0.1:3379')), '/');
$token = (string)($opts['token'] ?? (getenv('PHPTS_PUSH_TOKEN') ?: ''));
$timeout = (int)($opts['timeout'] ?? 3);
$broadcast = !empty($opts['broadcast']);
$path = '/' . $channel . ($broadcast ? '/broadcast' : '/send');
$query = [];
foreach (['client', 'key', 'port'] as $k) {
if (!empty($opts[$k])) {
$query[$k] = implode(',', (array)$opts[$k]);
}
}
if (!empty($opts['port_filter'])) {
$query['port'] = (string)$opts['port_filter'];
}
$url = $base . $path . ($query ? '?' . http_build_query($query) : '');
$headers = ['Content-Type: application/octet-stream'];
if ($token !== '') {
$headers[] = 'X-PHPTS-Token: ' . $token;
}
$status = 0;
$body = '';
if (function_exists('curl_init')) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => $timeout,
CURLOPT_CONNECTTIMEOUT => min(2, $timeout),
]);
$res = curl_exec($ch);
$status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = is_string($res) ? $res : '';
} else {
$ctx = stream_context_create(['http' => [
'method' => 'POST',
'header' => implode("\r\n", $headers) . "\r\n",
'content' => $payload,
'timeout' => $timeout,
'ignore_errors' => true,
]]);
$res = @file_get_contents($url, false, $ctx);
$body = is_string($res) ? $res : '';
foreach ($http_response_header ?? [] as $line) {
if (preg_match('#^HTTP/\S+\s+(\d{3})#', $line, $m)) {
$status = (int)$m[1];
}
}
}
$json = json_decode($body, true);
return [
'ok' => $status >= 200 && $status < 300,
'status' => $status,
'body' => $body,
'json' => is_array($json) ? $json : null,
];
}
说明:
- 优先用 cURL,未启用时退回
allow_url_fopen流封装(PHPTS 任务池默认allow_url_fopen = On)。 - Token 放在请求头,避免出现在 URL 与访问日志里。
-
status = 0表示连不上:推送接口没启动、地址/端口错、被防火墙拦截。 - 多目标与
key=用逗号分隔;http_build_query会百分号编码,网关会自动解码。 - 键名里不要带空格(
http_build_query会把空格编成+,网关按字面解析)。业务键建议只用字母 数字 : _ - .。
6.6 客户端 ID 登记:phpts_kv
WebSocket/TCP 连接建立后,脚本可以把「业务身份 → 连接 ID」登记到进程间共享内存,之后任意 PHP 都能凭业务身份找到连接。
phpts_kv_set(string $key, string $value, int $ttl_seconds = 0): bool
:写入/覆盖;ttl=0 永不过期
phpts_kv_get(string $key): ?string
:读取;不存在/过期返回 null
phpts_kv_del(string $key): bool
:按键删除
phpts_kv_del_by_value(string $value): array
:按值删除全部命中,返回被删键列表
phpts_kv_exists(string $key): bool
:是否存在
phpts_kv_list(): array
:全部未过期条目
phpts_kv_count(): int
:条目数
phpts_kv_clear(): bool
:清空
限制与语义:
- 键 ≤ 64 字节,值 ≤ 64 字节;共 10 万条;按字节计,中文一个字 3 字节。
- 失败抛异常,文案前缀
phpts_kv:。 - TTL 惰性过期,没有后台清扫。
-
存
PHPTS_EVENT_CLIENTID原值,不要自己加ws-/tcp-前缀:自动 ID 本身已带前缀,自报 ID 存原值。 - WebSocket / TCP 断开时,网关自动删除所有指向该 client_id 的登记;MQTT / 串口没有断开联动,靠 TTL 或手动删除。
- 网关被独立启动(非 PHPTS 派生)时联动删除静默降级,不影响业务。
- PHPTS 主程序退出时整区清零;重启后是空表,客户端重连必须重新登记。
登记示例(WebSocket 脚本内):
if (!empty($clientid) && function_exists('phpts_kv_set')) {
// 业务键建议:user:<id> / device:<sn> / room:<no>
phpts_kv_set('user:1001', $clientid, 3600);
}
TCP 脚本内:
if (!empty($clientid) && function_exists('phpts_kv_set')) {
// 真实设备身份通常来自首帧鉴权,例如 "AUTH <sn>"
if (preg_match('/^AUTH\s+([A-Za-z0-9_-]{1,40})$/', trim($frame), $m)) {
phpts_kv_set('device:' . $m[1], $clientid, 0); // 0 = 不自动过期,靠断开联动删除
echo "AUTH OK\r\n";
}
}
phpts_kv只在本机 PHPTS 派生进程间共享。跨机器请改用 Redis / MySQL 存业务身份 → client_id,或让 WebSocket 客户端直接用稳定业务 ID 作为client_id(§6.7)。
6.7 三种推送拓扑
A. 本机 Web 页面 → WebSocket 客户端(最常见)
<?php
require __DIR__ . '/event/push.php'; // phpts_push()
$user = '1001';
$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:' . $user) : null;
if (!$cid) {
http_response_code(409);
exit('client offline');
}
$r = phpts_push('ws', json_encode([
'type' => 'notify',
'data' => ['title' => '新订单', 'order' => 'A20261119001'],
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
if (!$r['ok']) {
// 404 = 已离线;0 = 推送接口不可达
error_log('push failed: ' . $r['status'] . ' ' . $r['body']);
}
B. 跨机器 / 不共享 phpts_kv
让 WebSocket 客户端使用稳定业务 ID 作为握手 client_id:
// 浏览器端
const uid = 'user-1001'; // 只允许 [A-Za-z0-9_.:-]{1,64}
const ws = new WebSocket(`ws://192.168.1.10:3380/chat?client_id=${uid}`);
远端服务器无需查询 KV,直接推:
phpts_push('ws', $json, [
'client' => 'user-1001',
'base' => 'http://192.168.1.10:3379',
'token' => '从 PHPTS 界面复制',
]);
TCP 不支持自定义连接 ID,远端只能:
- 通过 PHPTS 本机脚本把
tcp-xxxx写进 Redis/MySQL 再共享; - 或调用
/tcp/clients拉列表后按业务字段(需要你在首帧里带设备号并自行维护); - 或改成 WebSocket 接入(可直接用稳定 ID)。
C. 事件脚本 → 另一个客户端(联动)
例如设备 A 上报报警,事件脚本把通知推给值班人员的 WebSocket:
// tcp.php 内
if (str_starts_with($cmd, 'ALARM')) {
$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:oncall') : null;
if ($cid) {
phpts_push('ws', json_encode([
'type' => 'alarm',
'from' => $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '',
'msg' => $cmd,
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
}
echo "ALARM ACK\r\n";
}
注意:向当前正在处理的同一条连接推送也可以,但该帧会排在本次应答之后;不要用这种方式实现「推送先于应答」的协议。
6.8 业务协议建议(强烈推荐)
WebSocket / TCP / MQTT 都建议用统一信封,避免客户端无法区分「应答」和「主动通知」:
{ "v": 1, "type": "ack", "seq": 12, "ts": 1760000000, "data": { } }
{ "v": 1, "type": "notify", "seq": 13, "ts": 1760000001, "data": { } }
{ "v": 1, "type": "error", "seq": 14, "ts": 1760000002, "data": { "code": "E_AUTH" } }
-
type区分ack/notify/alarm/error; -
seq由服务端单调递增(可放 KV 或由客户端回带); -
ts统一 Unix 秒; - 二进制协议用「长度前缀 + 类型 + 序号 + 载荷」,不要用文本分隔符。
6.9 跨机部署清单
- 「(Server → Client)主动推送接口」把监听地址改成
0.0.0.0或[::]; - 必须设置 Token(32 位十六进制,界面可一键生成);
- Windows 防火墙放行该端口(仅限可信网段);
- 公网暴露时不要直接开 3379:用 Nginx 反代加 HTTPS、IP 白名单、限流;推送接口本身是明文 HTTP;
- 远端代码设置 3 秒超时并处理
status=0(网络不可达); - 远端不要调用
phpts_kv_*;用 Redis/MySQL 或稳定client_id。
7. 完整闭环示例
7.1 WebSocket 登记 + Web 推送
规则配置(「WebSocket 服务器」Tab):
路径:/chat
PHP 脚本:wwwroot/event/ws.php
超时:0(继承全局)
wwwroot/event/ws.php:
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
require_once __DIR__ . '/push.php';
$raw = file_get_contents('php://input');
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';
if (trim($raw) === 'QUIT') {
echo '__PHPTS_CLOSE__';
return;
}
$msg = json_decode($raw, true);
if (!is_array($msg)) {
$msg = ['raw' => $raw];
}
// 登录/订阅:客户端发 {"type":"bind","uid":"1001"}
if (($msg['type'] ?? '') === 'bind' && !empty($msg['uid']) && function_exists('phpts_kv_set')) {
phpts_kv_set('user:' . preg_replace('/[^A-Za-z0-9_-]/', '', (string)$msg['uid']), $clientid, 3600);
}
echo json_encode([
'v' => 1,
'type' => 'ack',
'from' => $clientid,
'ip' => $clientip,
'recv' => $msg,
'ts' => time(),
], JSON_UNESCAPED_UNICODE);
wwwroot/send.php(Nginx 站点里的普通页面):
<?php
require __DIR__ . '/event/push.php';
$uid = preg_replace('/[^A-Za-z0-9_-]/', '', $_POST['uid'] ?? '');
$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:' . $uid) : null;
if (!$cid) {
exit(json_encode(['ok' => false, 'error' => 'offline'], JSON_UNESCAPED_UNICODE));
}
$r = phpts_push('ws', json_encode([
'v' => 1,
'type' => 'notify',
'data' => ['text' => $_POST['text'] ?? 'hello'],
'ts' => time(),
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
exit(json_encode(['ok' => $r['ok'], 'upstream' => $r['status']], JSON_UNESCAPED_UNICODE));
浏览器端:
const ws = new WebSocket('ws://127.0.0.1:3380/chat?client_id=user-1001');
ws.onopen = () => ws.send(JSON.stringify({ type: 'bind', uid: '1001' }));
ws.onmessage = (e) => {
const msg = JSON.parse(e.data);
if (msg.type === 'notify') console.log('通知', msg.data);
};
7.2 TCP 设备命令下发
TCP 脚本 wwwroot/event/tcp.php:
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
require_once __DIR__ . '/push.php';
$frame = file_get_contents('php://input');
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$cmd = trim($frame);
if (preg_match('/^AUTH\s+([A-Za-z0-9_-]{1,40})$/', $cmd, $m)) {
if (function_exists('phpts_kv_set')) {
phpts_kv_set('device:' . $m[1], $clientid, 0); // 断开由网关自动删
}
echo "AUTH OK\r\n";
return;
}
if ($cmd === 'QUIT') {
echo '__PHPTS_CLOSE__';
return;
}
if ($cmd === 'PING') {
echo "PONG\r\n";
return;
}
echo "OK\r\n";
Web 端下发命令:
$r = phpts_push('tcp', "SET 1\r\n", ['key' => 'device:sn-001']);
// 或直接:['client' => 'tcp-0000000a']
7.3 串口主动写入
// 已由「串口监听」规则打开 COM3 时才能推
$r = phpts_push('serial', "\xAA\x55\x01\x00", ['port' => 'COM3']);
if (!$r['ok'] && $r['status'] === 404) {
error_log('COM3 未打开或规则未启动');
}
7.4 定时器定时推送
规则:mode=daily,at=08:30,脚本 wwwroot/event/morning.php,附加参数 job=morning。
<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');
require_once __DIR__ . '/push.php';
$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:1001') : null;
if ($cid) {
$r = phpts_push('ws', json_encode([
'v' => 1,
'type' => 'notify',
'data' => ['text' => '早上好,今日待办已生成'],
'ts' => time(),
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
error_log('morning push: ' . $r['status'] . ' ' . $r['body']);
} else {
error_log('morning push: user:1001 offline');
}
echo 'done' . PHP_EOL; // 只进网关日志
7.5 客户端侧最少要做什么
WebSocket:用稳定业务 ID 作 client_id;浏览器会自动回 Pong,自研客户端必须实现 Pong;断线后指数退避重连,并在重连后重新 bind/拉取缺失数据
TCP:连接后先发鉴权帧(如 AUTH <sn>);网关没有应用层心跳,长连接建议自己加 PING/PONG;重连后重新鉴权登记
串口:设备侧按约定帧格式解析;推送写入与事件应答共用同一条串口,设备要能区分主动下发与应答
MQTT:客户端自行订阅;reply_topic 的通配展开由网关完成,客户端只需订具体主题
推送接口没有离线队列:客户端离线期间的消息不会补发。重连后的数据一致性由业务自己保证(推荐「重连 → 拉快照 → 再增量」)。
8. 自检与排障
8.1 上线前自检
# 1) 语法检查(在 PHPTS 安装目录执行;php.exe 在 apps\php8.5\)
"apps\php8.5\php.exe" -l "wwwroot\event\ws.php"
# 2) 任务池端口
Test-NetConnection 127.0.0.1 -Port 6285
# 3) 推送接口与 Token
curl.exe -s "http://127.0.0.1:3379/ws/clients"
curl.exe -s -H "X-PHPTS-Token: <token>" "http://127.0.0.1:3379/ws/clients"
# 4) 定向推送(在线返回 ok;离线返回 404)
curl.exe -s -X POST -H "X-PHPTS-Token: <token>" --data-binary "hello" "http://127.0.0.1:3379/ws/send?client=user-1001"
# 5) 查看网关日志
Get-Content "logs\phpts-event-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50
8.2 症状 → 原因 → 处理
客户端发消息后没有任何回包
常见原因:任务池未启动 / 脚本路径错 / 脚本 fatal
处理:启动任务池;确认脚本相对 base 的路径;看网关日志
WS 收到空帧
常见原因:脚本没有任何 echo
处理:明确输出内容;要关连接用 __PHPTS_CLOSE__
WS 收到乱码/JSON 解析失败
常见原因:PHP Warning/Notice 混入输出、文件有 BOM
处理:脚本头 ini_set('display_errors','0');文件存为 UTF-8 无 BOM
__PHPTS_CLOSE__ 不生效
常见原因:输出被 JSON 包装、拼接或加了引号
处理:只输出该字符串本身
推送返回 404
常见原因:客户端已离线 / ID 错 / 子服务已停
处理:先 /ws/clients 或 /tcp/clients 核对;等待重连
推送返回 403
常见原因:Token 错或没带
处理:用 X-PHPTS-Token 头,值与界面一致
推送返回 0(连不上)
常见原因:推送接口停止 / 地址端口错 / 防火墙
处理:启动推送接口;核对 [pushapi];本机先用 127.0.0.1
推送返回 400 empty payload
常见原因:正文为空;GET 便捷形式没带 text=/data=
处理:传非空正文,或补 text=/data=
推送返回 413
常见原因:请求体 > 1MB
处理:拆包或改走文件/对象存储,只推 URL
TCP 一帧被拆成两帧
常见原因:idle 窗口小于帧内停顿
处理:调小 idle_ms,或改用 line/none
TCP 两帧被合并
常见原因:对端连发快、无静默;或用了 none
处理:改用 line;idle 下无法区分无静默的连续帧
串口收到的数据带 \n
常见原因:串口 line 模式帧内含分隔符
处理:脚本 rtrim($frame, "\r\n")
串口打不开 / 启动即异常
常见原因:COM 口被调试助手或其它程序占用
处理:关闭占用程序;或换 COM 口
定时器不触发或重复触发
常见原因:mode/at/weekdays/days 配错;防重入关闭
处理:核对规则;保持 no_reentry=1 或做幂等
跨机推送不通
常见原因:监听仍是 127.0.0.1 / 防火墙未放行
处理:改 0.0.0.0 或 [::];放行端口;设 Token
跨机调 phpts_kv_get() 报主程序未运行
常见原因:非 PHPTS 派生进程
处理:改用 Redis/MySQL 或稳定 client_id
8.3 日志位置
网关日志(含 PHP stderr):<base>/logs/phpts-event-YYYY-MM-DD.log
任务池 PHP 错误:同上(stderr 被网关收集);也可在脚本里 error_log()
脚本自定义日志:建议放脚本同目录,用 __DIR__ 拼
9. 安全清单
-
Token 必须设,尤其是监听地址不是
127.0.0.1时。 - 推送接口不要直接暴露公网;必须跨公网时用 HTTPS 反代 + IP 白名单 + 限流。
- WebSocket 可在首条消息里做鉴权:客户端带 token,脚本校验失败就输出
__PHPTS_CLOSE__。 - TCP 首帧鉴权:校验设备 SN/密钥后再登记
phpts_kv,未通过直接断开。 - 所有外部输入都要限长、限字符集;不要
eval、不要拼接 shell 命令。 - 文件路径必须由服务端白名单生成,禁止把客户端传来的路径直接拼进
__DIR__。 - 日志写入注意并发与轮转,不要把用户输入原样写进可执行上下文。
-
phpts_kv键值都有 64 字节上限;业务 ID 先哈希或截断,避免异常。
10. AI 交付物模板
当用户要求「实现一个事件触发任务」时,最终回答应包含以下五部分:
- 脚本文件清单:每个文件的完整路径(相对 PHPTS base)与完整代码。
- 规则配置表:
WebSocket 服务器
规则名:chat
路径/端口/主题/COM:/chat
PHP 脚本:wwwroot/event/ws.php
分帧:—
超时:0
其它:心跳默认开
TCP 服务器
规则名:device
路径/端口/主题/COM:59301
PHP 脚本:wwwroot/event/tcp.php
分帧:idle / 50ms
超时:0
其它:—
-
客户端示例:浏览器/设备端如何连接、如何带
client_id、如何重连。 -
自检步骤:
php -l、端口探测、curl推送、日志路径。 - 需要人工确认的项:任务池是否启动、子服务是否启动、推送 Token、监听地址、防火墙。
不要只给代码而不给规则配置;事件脚本离开规则配置无法运行。
11. 版本与特性时间线
共用推送接口 /ws/send、/tcp/send
:2026-11-10
PHPTS_EVENT_CLIENTIP 客户端 IP:2026-11-12
phpts_kv 断开自动清理:2026-11-12
推送接口独立启停 + /serial/ 端点:2026-11-13 / 2026-11-14
多目标推送、key= 直达、limit/total
:2026-11-15
__PHPTS_CLOSE__ 主动关闭连接:2026-11-16
定时器 daily/weekly/monthly + no_reentry
:2026-11-16
全局 fcgi_timeout 默认 300 秒:2026-11-17
如果目标环境早于上表,先做能力探测:
- 推送:
curl /ws/clients是否 200; - 关闭约定:脚本输出
__PHPTS_CLOSE__后客户端是否收到 close; - KV:
function_exists('phpts_kv_set'); - 多目标/
key=:响应里是否出现sent/missing。
12. 一页速查
事件正文 file_get_contents('php://input')
定时器参数 $_GET
规则名 $_SERVER['PHPTS_EVENT_NAME']
连接 ID $_SERVER['PHPTS_EVENT_CLIENTID']
客户端 IP $_SERVER['PHPTS_EVENT_CLIENTIP']
本次超时 $_SERVER['PHPTS_EVENT_TIMEOUT']
关闭连接 echo '__PHPTS_CLOSE__';
错误日志 error_log() / 文件,禁止 echo 调试
WS 回包 text 帧;空输出=空帧
TCP 回包 原始字节;空输出=不写回
MQTT 回包 发布到 reply_topic
串口回包 仅 echo=1 时写回
主动推送 POST http://127.0.0.1:3379/{ws|tcp|serial}/send
目标参数 client= / client_id=(逗号多值);串口 port=(别名 client=)
空正文 400 empty payload(GET 便捷形式用 text= 或 data=)
广播 POST /{ws|tcp|serial}/broadcast
在线列表 GET /ws/clients GET /tcp/clients GET /serial/ports
鉴权 ?token= 或 X-PHPTS-Token
业务 ID 登记 phpts_kv_set('user:1001', $clientid, 3600)
断开自动清理 WS/TCP 由网关自动按 client_id 删除登记
Markdown 原文下载: event-ai-guide-zh.md
Comments 0 comments
No comments yet. Be the first to comment.