PXWEBPLAY / 信令与 Web 架构 v3 · 2026-11-20 · 待确认

三服务信令系统方案

账号与权益在 PHP,连接与 relay 在信令,设备与 P2P 在网关。页面按产品路径、架构、验收与风险展开,供产品负责人、工程和验收者共用。

服务
3
在线角色
2
契约面
4
环节
16
里程碑
6
PHP 接口
7
01

系统是什么

用户在网页登录后即可查看自家在线网关报告的设备,并在权益有效、设备可用且 ICE 建连成功时观看 P2P 画面。

账号和权益归 PHP,设备归网关,连接归信令,每个账号至多一个在线 agent 和一个在线 web。三件事各有唯一事实源,跨服务只通过四个契约面交接。

服务职责明确不做
PHP七个接口、账号与会话、权益、配对、签票、发起 kick① 不维护设备清单
② 不判设备忙闲
③ 不处理媒体或 ICE
Go 信令验票与防重放、连接表、relay、kick① 不判账号权益
② 不解析设备或 relay 业务内容
③ 不保存串流记录
Go 网关配对与凭据、上线重连、设备发现与忙闲、P2P① 不验证用户登录
② 不判订阅权益
③ 不查询其他账号的设备
验收主线:注册、登录、配对、看列表、出画面、结束释放和强制下线端到端跑通;断网和重复登录也须有可验证的结果。
角色上限:每个账号至多一个在线 agent 和一个在线 web。agent 重复上线被拒,web 重复上线由新连接接管;两条规则分别由信令连接表执行。
02

三服务怎么连

四条链路合起来才是完整系统:登录取票走 HTTPS,控制与 relay 走 WSS,媒体走 P2P,强制下线走本机 kick。

控制面经过 PHP 与信令,媒体面只经浏览器和网关。P2P 那条虚线不穿过任何服务节点,这是整套架构的成本边界,也是故障边界。

浏览器、PHP、信令、网关与数据库的架构拓扑 浏览器 设备页 · web 角色 WSS / WebRTC 客户端 PHP px-web-app · 7 接口 账号 · 权益 · 配对 · 签票 Go 信令 WSS /ws · relay 连接表 · kick · jti Go 网关 设备发现 · 忙闲 P2P 媒体 SQLite users · 5 新增列 HTTPS · 端口待定 登录 / web 票 WSS · /ws 端口待定 POST /kick 127.0.0.1 · 端口待定 WSS · /ws 端口待定 HTTPS · /api/agent/ticket 端口待定 P2P · 媒体不过云 WebRTC · UDP · 端口待定 判定 · 钱 → PHP 判定 · 在线 → 信令 判定 · 设备 → 网关 控制面 HTTP / WS P2P 媒体,不经服务 未指定端口统一标「待定」
图 1 / 三服务拓扑与四条链路实线=控制面 · 虚线=P2P 媒体
链路走法协议与端口约束
登录取票浏览器 ↔ PHP;网关 ↔ PHPHTTPS · 端口待定web ticket 有效期 60 秒;agent ticket 由 POST /api/agent/ticket 换发
WSS relay浏览器 / 网关 ↔ 信令WSS · /ws · 端口待定首帧 hello 5 秒内;单帧 relay ≤256 KiB;ticket 不放 URL
P2P 媒体浏览器 ↔ 网关WebRTC · UDP · 端口待定候选直连,不经任何服务;媒体不过云;转发媒体和 TURN 不在本轮
强制下线PHP → 信令127.0.0.1 · 端口待定独立 Bearer KICK_TOKEN;PHP 2 秒截止
PLAN 未固定部署端口,图中统一标 待定;127.0.0.1 是 D 契约的同机回环监听地址。数据库走本地 SQLite 文件,不占网络端口。
03

谁来做判定

判定只有三处:PHP 判登录和签票权益,网关收 offer 时判设备归属与忙闲,信令以当前连接表判在线和投递目标。

判定权跟着事实源走,避免同一条规则在两个服务各写一遍。信令不判权益,也不解析设备或 relay 业务内容;PHP 不维护设备状态与在线连接;网关不验证用户登录,也不判订阅权益。

判定归属触发点依据不归谁
登录 · 签票权益PHP登录成功、渲染设备页、签发 web ticket已识别付费 plan、plan_expires_at > now、status='active'信令不判账号权益
设备归属 · 忙闲Go 网关收到 offer 时原子判定并占用设备存在、可用、未占用;只有此条件允许 idle → busy信令不解析设备或 relay 业务内容
在线 · 投递目标Go 信令每次 relay、接管、kick单实例当前连接表;每个账号至多一个在线 agent 和一个在线 webPHP 不维护在线连接
三个事实源:账号行是 PHP 的持久事实源;设备状态是网关内存的媒体所有权,不随信令断线清除;连接表是信令单实例内存,连接断开即摘除。
04

从注册到关页

16 个环节按主路径从上到下排列:注册、登录、开页、连信令、列表、offer、answer、ICE、首帧、释放;配对、重连、强制下线和会话失效作为支线插在同一张泳道图里。

四条竖泳道分别是浏览器、PHP、信令、网关;编号与 PLAN 的 16 环节一致。箭头只表示消息方向,右侧警示方块给出该步的失败态,步骤名下方是验收截止。

16 环节四泳道时序,含失败态与截止时间 16 环节 · 主路径 + 配对 / 重连 / 下线支线 箭头=消息方向;右栏=失败态;步骤下方=截止 浏览器 / WEB PHP / 账号 信令 / 连接 网关 失败态 01 注册 5s POST /register 400 BAD_REQUEST 409 EMAIL_EXISTS 02 登录 每请求 5s GET/POST /login → 303 / 401 BAD_CREDENTIALS 409 SESSION_ACTIVE 03 打开页面 5s · 票 60s GET / · web ticket + ICE 303 /login 200「未订阅」无票 04 连信令 Upgrade 5s / 握手 5s WSS Upgrade · hello · ready 票无效 → 断连回登录 启动冷却 → 提示刷新 05 问设备列表 请求回包共用 5s list_req(经信令转发) TARGET_OFFLINE 「设备未连接」 06 回设备列表 同第 5 步 list_resp(经信令转发) LIST_TIMEOUT 可重试 07 点串流 30s answer 截止 offer(device_id) TARGET_OFFLINE 立即提示 08 判忙 计入 30s 判忙 占用 DEVICE_NOT_FOUND DEVICE_BUSY DEVICE_UNAVAILABLE 09 回 answer 同第 7 步 answer / 业务 error MEDIA_FAILED ANSWER_TIMEOUT 10 交换 ICE 30s 未 connected ice ⇄ ice(经信令转发) ICE_FAILED 可手动重发 11 出画面 首帧 10s P2P 视频首帧(不经信令) MEDIA_FAILED 关闭本地 P2P 12 结束 关页 5s 释放 stop(不等 ACK) stop 失败也关本地 网关按媒体终态释放 13 首次上线 5s · 5min · 60s POST /api/pairing POST /api/agent/ticket hello PAIRING_INVALID 请求新码或重输 14 网关重连 每段 5s secret → 新 ticket hello SECRET_INVALID 回待配对 / 退避 15 强制下线 kick 2s / 请求 5s POST /api/force-logout POST /kick KICKED · 4410 401 BAD_CREDENTIALS 403 FORBIDDEN 503 KICK_FAILED 16 会话失效 30min 受保护请求 · session_seen_at 303 /login 401 SESSION_EXPIRED P2P 阶段(步骤 10–12)· 浏览器 ⇄ 网关 媒体不过云 · 不经任何服务 · UDP 端口待定
图 2 / 16 环节泳道时序警示方块=该步失败态 · 蓝色虚线=P2P
截止点数值约束对象
web / agent ticket 入场60 秒从签发计;只限制建连,已建立连接不随 ticket 到期断开
列表请求与回包5 秒list_req 与 list_resp 共用;超时显示 LIST_TIMEOUT
offer 到有效 answer30 秒约束浏览器操作;超时关闭本地 P2P 并显示 ANSWER_TIMEOUT
ICE connected 到视频首帧10 秒待首帧;失败显示 MEDIA_FAILED,关闭本地 P2P
正常关页到网关释放5 秒测试目标;断网按媒体库报告终态验收,记录实测时间
两个易错点:显式 stop 不等 ACK,投递失败也关闭本地 P2P;正常关页依赖网关检测媒体断开,5 秒释放是测试目标而不是协议保证。
05

服务间说什么

四个契约面首尾相接:A 定义入场资格,B 定义连接控制与 peer 消息,C 让网关换票,D 让 PHP 断开指定角色。

契约只交换必要字段。票、连接、配对、kick 各自闭环,任何一方都不靠读取对方内存或数据库来补状态。

Aticket 入场资格 · 60 秒 · 一次性

票是 kid.payload.mac。payload 是 UTF-8 JSON 字节的无填充 base64url,mac 是无填充 base64url 的完整 HMAC-SHA-256,输入为 ASCII kid.payload。v3 固定算法,以恒定时间比较 MAC,对原始编码串验签。

payload 字段类型与约束
substring,users.id 的十进制写法,正整数、无前导零,范围和数据库一致
rolestring,枚举 web、agent
expinteger,UTC Unix 秒,PHP 签发时的整秒加 60,now >= exp 即过期
jtistring,16 个密码学安全随机字节的 base64url 无填充形式,按全局唯一处理

验签与密钥轮换

  • 拒绝未知 kid、重复或未知 JSON 字段、非法类型,以及 exp > now + 62;票总长上限 2 KiB。
  • PHP 和信令从各自受权限保护的服务环境读取 TICKET_HMAC_KEYS(kid 到 base64 编码的 32 字节随机密钥映射),PHP 另读 TICKET_ACTIVE_KID。浏览器和网关仅持有 ticket。
  • 轮换先让信令同时接受新旧 kid,再切换 PHP 签发,最后一次旧签发满 62 秒后移除旧键。两端同步 UTC 时钟,验收时偏差不超过 2 秒。
  • ticket 不放 URL;浏览器 Origin 必须匹配当前部署的 Web origin,原生 agent 可无 Origin,验票后仍校验浏览器来源与角色。
  • 签发有效期只限制建连,已建立连接不随 ticket 到期而断开。

jti 防重放与容量

  • 信令单实例内存维护 jti → exp;验签、检查过期后,在同一临界区检查并占用 jti、裁决角色、登记连接。
  • 验签合法的票通过占用后即作废,包括 agent 冲突。jti 保留到 exp,每秒和入表前清理已过期条目。
  • 容量 65,536,满时拒绝新票并返回 SIGNAL_BUSY;存量记录不得提前淘汰。
  • 每次信令进程启动先拒绝握手 62 秒,返回 SIGNAL_WARMING_UP。冷却后任何重启前使用过的票都已过期,存活的未用票可正常验签。

BWSS 握手、控制与 relay /ws · 6 类消息

帧或阶段方向字段和约束
HTTP Upgrade两端 → 信令GET /ws,WSS。浏览器 Origin 必须匹配当前部署的 Web origin,原生 agent 可无 Origin,验票后仍校验浏览器来源与角色。ticket 不放 URL。
首帧两端 → 信令5 秒内发送文本 JSON {"type":"hello","ticket":"<ticket>"},首帧最大 3 KiB。
握手成功信令 → 发起端{"type":"ready"},收到后才允许 relay。
连接错误信令 → 发起端或被踢端文本 JSON {"type":"error","code":"<CODE>"}。验票、握手、接管、kick 和超限关闭码见失败态矩阵。
投递结果信令 → relay 发送端目标缺失时返回带 TARGET_OFFLINE 的连接错误帧,连接继续。信令不提取业务 ID。浏览器同一时刻只等待一个列表或 answer 响应,等待期间暂停列表刷新;进入 ICE 阶段后依媒体状态与本地截止时间收敛。
心跳信令 ↔ 两端WebSocket Ping 每 10 秒,无 Pong 达 20 秒回收连接,浏览器用 WebSocket 协议层自动回复。

relay 限额

  • relay 为 UTF-8 JSON 文本,单帧最大 256 KiB。信令检查连接身份、帧类型与大小,原样投递字节。
  • 每端每秒 50 帧、突发 100;连接表最多 4,096 条;未完成握手最多 256 条。
  • 单连接待发队列最多 8 帧且最多 512 KiB;单次写截止 2 秒。慢端队列满则关慢端,向发送端返回 TARGET_OFFLINE;入站调用顺序在同一个发送端保持。
type谁发必填字段(除共同的 string type)处理或错误
list_reqweb → agentid string,当前连接内唯一请求 ID网关返回同 id 的 list_resp;目标缺失为 TARGET_OFFLINE
list_respagent → webid string、devices array,可为空与待完成的 id 匹配后刷新列表,忽略迟到的旧响应
offerweb → agentid string,本次串流 ID;device_id string;sdp string,WebRTC offer SDP网关原子判定并占用,失败用同 id 回 DEVICE_NOT_FOUND、DEVICE_BUSY、DEVICE_UNAVAILABLE 或 MEDIA_FAILED
answeragent → webid string,对应 offer;sdp string,WebRTC answer SDP只接受当前 offer;30 秒未收到有效 answer 则关闭本地 P2P 对象并显示 ANSWER_TIMEOUT
ice双向id string;candidate string 或 null;sdpMid string 或 null;sdpMLineIndex 非负整数或 null;usernameFragment string 或 nullcandidate 非 null 时两个 SDP 定位字段至少一个非空;null 表示候选结束,其余字段填 null。收到远端 SDP 前按 id 暂存,过时 id 丢弃
stopweb → agentid string,对应 offer只释放 ID 匹配的占用;重复或过时 stop 无副作用

应用层约束

  • id 使用 128 位随机值的 base64url 无填充格式。SDP 必须非空且帧大小符合上限。应用端可回 {"type":"error","id":"<id>","code":"BAD_MESSAGE"},有可识别 id 时回发,无法关联的畸形帧丢弃。网关的业务失败也走这个错误帧,它是六类正常消息的公共反馈格式。
  • devices 每项三列:device_id 为网关负责稳定分配的非空不透明 ID(≤128 UTF-8 字节),name 为非空显示名(≤128 UTF-8 字节),state 为 idle|busy|unknown。同一列表 ID 唯一。前端依次显示「可用」「使用中」「状态未知」,仅 idle 可点;离线显示「设备未连接」,在线空列表显示「未发现设备」。
  • 网关只有在设备存在、可用且未占用时才能 idle → busy,接受 offer 时占用,建立媒体后仍为 busy。匹配 stop、媒体建立失败或 P2P 终态释放后按设备发现结果回 idle 或 unknown。设备暂不可判定则 unknown,重新确认可用则回 idle;已占用优先显示 busy。此状态是网关内存的媒体所有权,不随信令断线清除。
  • PHP 渲染设备页时把部署环境的公开 STUN URL 注入页面 bootstrap 的 ice_config.iceServers(元素为 {"urls":["stun:主机:端口"]})。网关启动时独立加载同一部署配置给媒体层。ticket 四字段固定,ICE 配置在 ticket 外。双方候选直连,失败显示「无法建立直连」并允许用户重新发起一次新的 offer。转发媒体和 TURN 不在本轮。
  • web 接管会原子换表并停止接收旧连接的新 relay,旧页收到 WEB_REPLACED 后以 4409 关闭,销毁本地 P2P,提示「设备页已在另一个标签页打开」,禁止自动重连,显式刷新可接管回来。若错误帧丢失,4409 也触发同样界面。kick 对 web 用同样的媒体清理流程,但回登录页。

CPOST /api/agent/ticket 网关换票

模式JSON 请求(恰好一项)HTTP 200 JSON 响应
首次或换机{"pairing_code":"014257"}{"gateway_secret":"<43 字符 base64url>","ticket":"<agent ticket>"}
连接或重连{"gateway_secret":"<43 字符 base64url>"}{"ticket":"<agent ticket>"}

配对码与 secret

  • HTTPS + Content-Type: application/json,请求最大 1 KiB,响应 Cache-Control: no-store。
  • 配对码是含前导零的六位数字字符串,页面经 POST /api/pairing 发放,5 分钟有效,生成新码覆盖本账号旧码。全局唯一索引处理随机碰撞,过期码仅在生成碰撞时按有效期条件清理并重试。以行锁再检查有效期,消费配对码、写新 secret hash、清码同事务提交,一次成功。
  • secret 是 32 随机字节的无填充 base64url,不定期过期,重新配对使旧 secret 后续换票失效。PHP 以解码后字节的 SHA-256 原始 32 字节作索引查找。网关原子落盘凭据后再连 WSS,本地文件权限 0600。首次提交成功但响应丢失时请用户生成新码,旧码无法再次取回 secret。

统一错误形状

HTTPcode触发
400BAD_REQUEST字段、类型或编码无效;超过请求上限返回 413 BAD_REQUEST
409PAIRING_INVALID错码、已用、过期
401SECRET_INVALIDsecret 未登记或已换
429RATE_LIMITED额度耗尽;附整数秒 Retry-After
503TEMP_UNAVAILABLE短暂不可用

限额

  • 每 IP 每分钟 5 次配对兑换,全站每分钟 30 次配对兑换,每 IP 每分钟 60 次 secret 换票,配对码发放每账号每分钟 3 次。
  • 由部署入口和 PHP 应用限流,按实际可信代理链取 IP,状态可放单机共享内存;拒绝请求不延长配对码期限。
  • 限额以 429 验收,日志不得写明文码、secret 或 ticket。

DPOST /kick 断开指定角色

项目定义
监听同机独立 HTTP 监听 127.0.0.1,外部反代无此路由
鉴权Authorization: Bearer <KICK_TOKEN>,32 随机字节的 base64url,与票签名密钥独立,PHP 和信令通过服务环境配置,恒时比较
请求Content-Type: application/json,{"sub":"42","role":"web"},两字段必填,约束同 A,最大 1 KiB
响应204(目标已摘除或原本离线),401 UNAUTHORIZED,400 BAD_REQUEST,信令临时不可用为 503 TEMP_UNAVAILABLE
效果在连接表中原子摘除当前角色连接,尽力写 KICKED 后以 4410 关闭。断开清理按连接身份比较。相同请求在目标未重连时可重复;若已出现新连接,下一次请求会摘除新的当前连接
调用规则PHP 强制下线清目标 session 并调用 web kick。PHP 设 2 秒截止,失败向调用者显示 KICK_FAILED,不自动补发;同账号持正确密码可显式重试。agent kick 用于验收角色重连
60 秒窗口:kick 以接收时的在线连接为作用范围。已发出未使用的 ticket 仍可在原有效期内入场一次;强制下线后旧会话后续请求无法再签票。发布验收须显式核对这个 60 秒窗口。
06

账号数据存哪里

单个账号行承载持久状态:设备与占用在网关,连接与票消费在信令,PHP 只在 users 一行里维护会话、配对和权益。

PHP 通过 px-web-app/app/db.php 使用 SQLite,沿用 pxcloud/data/psweb.db 中的 users 表及原有账号 ID、登录凭据和权益字段。登录继续调用 user_login(),支持 username=? OR lower(email)=lower(?)。PHP 仅对已识别的付费 plan、plan_expires_at > now 且 status='active' 的账号签发 web 票。

列类型可空索引及约束
session_idTEXT是保存随机 cookie token 的 SHA-256 十六进制摘要,非空值唯一
session_seen_atINTEGER是Unix 秒,和 session_id 同时为空或非空
gateway_secret_hashTEXT是保存网关 secret 的 SHA-256 十六进制摘要,非空值唯一
pairing_codeTEXT是六位 ASCII 数字,非空值唯一
pairing_expINTEGER是Unix 秒,和 pairing_code 同时为空或非空

M5 在 SQLite 数据库副本上演练迁移,切生产时对现有 users 原地加列;现有行的五个新增列初始均为 NULL。迁移放在同一事务内执行。

BEGIN IMMEDIATE;

ALTER TABLE users ADD COLUMN session_id TEXT;
ALTER TABLE users ADD COLUMN session_seen_at INTEGER;
ALTER TABLE users ADD COLUMN gateway_secret_hash TEXT;
ALTER TABLE users ADD COLUMN pairing_code TEXT;
ALTER TABLE users ADD COLUMN pairing_exp INTEGER;

CREATE UNIQUE INDEX uq_users_session_id ON users (session_id)
  WHERE session_id IS NOT NULL;
CREATE UNIQUE INDEX uq_users_gateway_secret_hash ON users (gateway_secret_hash)
  WHERE gateway_secret_hash IS NOT NULL;
CREATE UNIQUE INDEX uq_users_pairing_code ON users (pairing_code)
  WHERE pairing_code IS NOT NULL;

COMMIT;

SQLite 无法通过 ALTER TABLE 给既有表后加表级 CHECK,由 PHP 写入层在同一事务内保证 session_id 与 session_seen_at、pairing_code 与 pairing_exp 分别成对写入或清空,并验证配对码恰为六位 ASCII 数字及新增时间值为整数 Unix 秒。

设备及占用在网关,连接和票消费记录在信令,单账号的其余持久状态由 users 一行承载。登录、续期、强制下线和配对更新均对账号行原子校验再写入。Cookie 使用随机 32 字节 token,设 Secure、HttpOnly、SameSite=Lax;修改状态的浏览器 POST 校验同源 Origin,缺失或不匹配拒绝。

M5 旧表清理

旧表v3 接替方式
devices网关本地设备发现与忙闲状态,经信令转发 list_resp
stream_logs网关以媒体生命周期管理串流,信令以本地滚动日志记录控制事件,历史串流记录按既有留存需求处理
session_leasesusers.session_id 与 users.session_seen_at 管理 PHP 会话,网关本地媒体状态管理设备占用和释放
ws_ticketsPHP 签发短效 HMAC 票,信令验签并在内存记录已消费的 jti
signal_revocations/kick 摘除当前连接,PHP 会话清除后停止续签;已签票仍受原定有效期及单次消费约束
agent_secrets网关重新配对后在本地保存 secret,PHP 在 users.gateway_secret_hash 保存对应摘要
切换验收通过、旧单体下线、回滚窗口结束,并确认账单、后台和历史记录留存等依赖已处理后,才可删除这些旧表中实际存在的表。保留旧表也不影响 v3 运行。
07

状态如何推进

三张状态机各自推进:信令连接表、网关凭据与 PHP 会话,状态只能由各自的事件更新。

下面先看网关生命周期和连接表替换规则,再给出三张状态机的完整转移明细。任何一张表都不替另一张表改状态。

网关生命周期状态机与连接表替换规则 网关生命周期 / GATEWAY 事件驱动 · 退回未配对只由凭据失效触发 未配对 等待六位码 已配对 secret 已落盘 在线 ready · 媒体可用 断线重连 退避取票 有效码 / 落盘 secret ready / 重置退避 断开 / 失败 ready 连接失败 401 SECRET_INVALID → 未配对 重连退避:1 → 2 → 4 → 8 → 16 → 30 秒,各加 0–0.25 秒抖动 429 至少等 Retry-After;TICKET_EXPIRED 丢票现取,首次立即 已配对 / 重连遇 401 均清本地凭据,回未配对 连接表替换规则 AGENT 重复 当前 agent 新 agent 旧连接:继续在线 新连接:ALREADY_ONLINE · 4409 WEB 重复 当前 web 新 web 旧连接:WEB_REPLACED · 4409 新连接:成为当前 web 仅当前连接可发 relay 对端缺失 → TARGET_OFFLINE 旧连接断开只在表项 仍指向自己时删除 所以新连接继续在线
图 3 / 网关生命周期与连接表替换amber=拒绝 · 蓝=接管

信令连接表

当前事件下一状态与动作
无对应角色合法 hello登记当前连接并回 ready
agent 已登记同账号新 agent 合法 hello旧连接继续在线,新连接 ALREADY_ONLINE 并关闭
web 已登记同账号新 web 合法 hello新连接成为当前 web,旧连接 WEB_REPLACED 并关闭
已登记收 relay仅当前连接可发,查找对侧;对端缺失返回 TARGET_OFFLINE
已登记kick、断线或心跳失败摘除对应连接,两个角色都为空时清账号键
已被替换旧连接断开仅在表项仍指向自己时删除,因此新连接继续在线

网关生命周期

当前事件下一状态与动作
未配对输入有效码已配对,先安全落盘 secret,再用返回的 ticket 握手
已配对ready在线,重置退避
已配对或在线连接失败或断开重连,正常第一次立即现取票;之后 1、2、4、8、16、30 秒,各加 0–0.25 秒随机抖动,总上限 30 秒;429 至少等 Retry-After
重连TICKET_EXPIRED丢票并现取新票,首次立即尝试,再失败走退避
重连ALREADY_ONLINE 或临时错误按退避现取票重试;启动冷却、心跳回收和旧连接存续由信令处理
已配对或重连401 SECRET_INVALID清理失效本地凭据,回未配对并提示输新码
重连ready在线,重置退避;已有媒体按自身生命周期推进

PHP 会话生命周期

当前事件下一状态与动作
无有效会话或已过期正确账号密码登录签发新 cookie,写 session_id 与当前 UTC 时间,进入活跃
活跃受保护 HTTP 请求携匹配 cookie,距离上次活动 <30 分钟PHP 原子校验并更新时间戳,进入页面后另判权益
活跃另一登录请求携正确账号密码保持原会话,返回 SESSION_ACTIVE;登录冲突页可提交同一身份验证信息强制下线
活跃30 分钟无受保护 HTTP 活动逻辑过期,下一请求拒绝旧 cookie,允许重新登录;WebSocket 心跳、relay、媒体流均不续 PHP 会话
活跃或已过期同账号有效会话请求,或登录冲突页重新提交并通过同账号密码验证,发起强制下线清 session,调用 web kick,页面回登录。若清 session 已成功而 kick 不可达,凭同账号密码显式重试
已过期旧 web 仍在线PHP 拒绝续签,已建 WSS 可持续到自然断线、新 web 接管或 kick;30 分钟是 PHP 会话判据
08

怎么验收到上线

从 mock 到真机,再到生产切换,M0–M5 每一级都有可独立运行的验证入口和出口判据。

台阶高度表示依赖与验收门槛的累积,不是工期。M1 用 mock agent 做第一次整体竖切,先证明 PHP、信令、浏览器能跑通列表与 relay,再接真网关。

M0 到 M5 六级里程碑阶梯,含新增能力与出口判据 M0 → M5 · 台阶高=依赖与验收门槛 时间 / 依赖 → M0 骨架 + 契约 新增能力 三服务骨架 A–D 契约 e2e 框架 出口判据 make e2e 启动 A–D 用例命名 未实现断言标红 职责 / 契约评审 M1 假网关竖切 假网关竖切= 第一次证明整体能跑 新增能力 PHP 注册/登录 权益 / 签票 信令 + mock 列表 + relay 出口判据 CASE=mock 通过 付费见 mock 设备 免费账号无票 offer/answer 回显 关页后 web 表项 移除可观测 M2 真网关 新增能力 真网关云连接 配对 / 列表 忙闲 / kick 出口判据 CASE=gateway 配对收到 ready 3s 内 list_resp agent kick 3s 恢复 ready 忙设备 BUSY web kick 回登录 M3 媒体 + P2P 新增能力 网关媒体路径 浏览器 P2P 出口判据 真 PS5 ≥5 分钟 关页 5s 释放 刷新见 idle 信令短断 不杀健康 P2P M4 边界 + 故障 新增能力 边界 / 并发 故障演练 出口判据 CASE=boundaries 30 分钟边界 异地登录 断网恢复 / 票复用 同票并发 最多一次消费 重启冷却拒握手 旧票冷却后过期 第二 web 接管 第一 web 不自动 重连 M5 7 天 + 切生产 新增能力 test 环境 7 天 导入 / 回滚演练 发布窗口切生产 连续 7 天验证 旧入口保留 出口判据 7 天无 P0 账号映射 权益抽样 回滚一次可恢复 复验登录 / 配对 与串流 账单 / 后台处理 下线旧单体 每个里程碑一个 issue、一个 PR 和 CHANGELOG,版本从 0.0.1 起 M5 之前生产仍由 px-prod 的 pxcloud 在 127.0.0.1:8081 服务
图 4 / M0–M5 竖切里程碑M5 环境 test.pxwebplay.com(198.27.69.59)· 连续 7 天

谁能独立验证

里程碑验证入口谁能独立验证
M0make e2e 启动测试运行器,A–D 用例已命名,未实现断言标红非实现工程师
M1make e2e CASE=mock 通过,付费账号见 mock 设备,免费账号无票QA,无需真网关
M2make e2e CASE=gateway 配对收到 ready,3 秒内发现上线,kick 后 3 秒恢复非实现工程师,有测试网关
M3真 PS5 连续出画面 ≥5 分钟,关页 5 秒内释放,刷新见 idle有真机的验收人
M4make e2e CASE=boundaries 通过 30 分钟边界、异地登录、断网恢复、票复用QA 或非实现工程师
M5test 环境连续 7 天无 P0,回滚演练一次且可恢复旧入口,切生产后复验发布负责人和独立 QA,产品负责人确认权益
M5 环境:test.pxwebplay.com(198.27.69.59),连续验证 7 天,演练数据导入和回滚,再由发布窗口切生产。M5 之前生产仍由 px-prod 的 pxcloud 在 127.0.0.1:8081 服务。
09

出错时会看到什么

PHP 的错误决定页面和凭据处理,信令的错误决定连接处理,网关的错误决定是否可以发起串流。

同一个错误码只对应一种处理动作。前端展示与自动恢复分开写,避免把「可以重试」误当成「已经恢复」。

错误码触发条件前端或网关表现自动恢复
BAD_REQUEST / BAD_MESSAGEHTTP 或 relay 字段非法,含超尺寸 HTTP 请求显示输入错误或结束对应操作否
EMAIL_EXISTS规范化邮箱重复注册页提示已注册否
BAD_CREDENTIALS / FORBIDDEN密码错误、状态修改请求同源校验失败或无调用权限登录页提示凭据无效,拒绝修改否
SESSION_ACTIVE账号仍有活跃会话登录冲突页提供强制下线入口否
SESSION_EXPIRED会话缺失、被清除或 HTTP 闲置达到 30 分钟跳登录或 JSON 401 后引导登录否
无票无付费权益展示「未订阅」权益生效后重新打开页面
TICKET_INVALID / TICKET_EXPIRED / TICKET_REPLAY验签失败、过期、jti 已消费信令关闭 4401;浏览器回登录入口,agent 过期或复用时现取新票agent 可;无效票持续出现则报配置异常
BAD_HANDSHAKE首帧错误或超时信令关闭 4400;客户端提示连接失败格式错误否,传输超时按重连流程
SIGNAL_WARMING_UP / SIGNAL_BUSY启动冷却、握手或连接容量、票消费容量已满握手后发错误并关 1013;当 HTTP Upgrade 前拒绝时为 503,浏览器按暂时不可用展示agent 退避,web 提示刷新
SIGNAL_LIMITrelay 限速或服务端拒绝慢端超速关 4429,帧类型违规关 1003,超大帧关 1009,待发队列或写超时关 1013,页面显示连接中断agent 退避,web 提示刷新
ALREADY_ONLINE同账号已有 agent 在线信令关闭新连接 4409,新网关提示已有网关在线,原网关继续工作可退避等待原连接离线
WEB_REPLACED新 web 接管旧页关闭 4409,显示另一个标签页已打开设备页否
KICKEDPHP 或内部验收调用 kick 命中连接关闭 4410;web 回登录,agent 重连仅 agent 自动
TARGET_OFFLINE / LIST_TIMEOUT对端不在线或列表 5 秒未到分别显示「设备未连接」「设备列表加载超时」用户可刷新或重试
DEVICE_NOT_FOUND / DEVICE_BUSY / DEVICE_UNAVAILABLE设备不存在、已占用或状态未知提示设备不可用或「使用中」否
ANSWER_TIMEOUT / ICE_FAILED / MEDIA_FAILEDanswer 超时、ICE 失败或媒体建立/播放失败关闭本地媒体,提示「连接失败」或「无法建立直连」用户可重新发起
PAIRING_INVALID / SECRET_INVALID配对码过期、错误或已用;secret 失效重输或生成新码;secret 失效回待配对否
RATE_LIMITED / TEMP_UNAVAILABLE请求额度耗尽或暂时服务异常提示等待;secret 换票可重试,首次配对等用户确认码是否仍有效agent 按 Retry-After 或退避
UNAUTHORIZED / KICK_FAILED内部 kick 鉴权失败或投递结果不明旧会话已清时,页面显示「强制断开暂未确认」否,允许显式重试
TRANSPORT_LOST异常断线或心跳超时,可能没有应用错误帧浏览器显示连接中断并可刷新;agent 退避agent 自动
HTTP_TIMEOUT页面或取票 HTTP 请求超时网页提示超时;首次配对遇提交结果不明时生成新码secret 换票可自动
关闭码映射:4400 BAD_HANDSHAKE · 4401 TICKET_* · 4409 ALREADY_ONLINE / WEB_REPLACED · 4410 KICKED · 4429 SIGNAL_LIMIT 超速 · 1003 帧类型 · 1009 超大帧 · 1013 容量 / 队列 / 写超时。
10

三个产品和运维结论

三项施工结论可直接按此验收;如要改,只需改对应的一句话,不必改整套架构。

裁决 01未订阅能否看设备列表

我的建议
不能。设备页显示「未订阅」,PHP 无 web 票可签。
理由
列表和串流共用同一个 web 角色,PHP 在签票处一次裁决权益;把列表单独放行会多出第二个权益判定点。
你要翻的一句话
“PHP 仅对已识别的付费 plan、plan_expires_at > now 且 status='active' 的账号签发 web 票。”

裁决 02kick 鉴权

我的建议
同机回环监听 + 独立 Bearer token。监听 127.0.0.1,外部反代无此路由。
理由
调用者只有 PHP;回环限制可达面,独立 token 可单独轮换,不与票签名密钥耦合。
你要翻的一句话
“Authorization: Bearer <KICK_TOKEN>,32 随机字节的 base64url,与票签名密钥独立,PHP 和信令通过服务环境配置,恒时比较。”

裁决 03quota 与 audit

我的建议
接入连接数和帧速率限额。审计用非阻塞有界队列异步写本地滚动文件。
理由
保护连接表和转发队列,保留接管、拒绝、kick 的排查依据。审计只记时间、账号 ID、角色、事件、结果,队列满丢弃并计数。
你要翻的一句话
“每端每秒 50 帧、突发 100,连接表最多 4,096 条。”
“审计只记时间、账号 ID、角色、事件、结果,队列满丢弃并计数。”
三项均按 v3 施工结论执行 · 改动需同步契约与验收
11

范围与上线风险

本轮交付七个 PHP 接口、两个信令角色,以及网关云连接和媒体接入所需的行为;范围外的能力不进入本轮验收。

七个 PHP 接口是 POST /register、GET/POST /login、GET /、POST /api/pairing、POST /api/agent/ticket、POST /api/force-logout、POST /kick。两个信令角色是 web 与 agent。

不做清单

  • 不做设备表。
  • 不做串流表。
  • 不做租约、串流超时补偿或后台清扫任务。
  • 不做双协议兼容层。
  • 不做 watch 角色。
  • 不做 ticket 设备白名单。
  • 不做共享账号多 agent 在线。
  • 不做媒体面重写、TURN 或服务端媒体转发。
  • 不做后台管理、账单功能重写或 M5 前生产改动。

风险与缓解

风险缓解与验收
新协议要求网关升级并重新配对预告一次六位码配对,test 环境先验新版网关。过渡期新入口使用独立端口,网关启动开关选择单个协议路径
重新配对时旧 agent 可能仍在线secret 更换阻止后续取票,提示用户关掉旧网关;旧连接释放后新网关退避恢复。M2 同测此情形
票被复制、进程重启或签发时钟偏差WSS/HTTPS、日志脱敏、单实例有界 jti 记录、启动冷却,M4 演练密钥轮换和重放
强制下线与已签票窗口,以及 PHP 会话过期后 WSS 仍可存在票 60 秒、一次性,清会话后拒绝新签票;界面说明 kick 针对当前连接。验收分别记录 PHP 会话失效、在线 web 断开、旧票剩余窗口
关页与异常网络断开探测速度不同正常关页用真机验证 5 秒释放;断网按媒体库报告终态验收,记录实测时间。网关顺序处理占用和释放,旧 stop 不能释放新串流
部分网络无法 P2Ptest 隔网验证 ICE 成功和失败提示,失败时允许用户再次发起
六位配对码遭猜测或响应丢失全站和来源限流、短有效期、事务内单次消费,失败时由用户生成新码
切换牵动账单、后台和账号兼容性发布前核对外部依赖、做生产数据干跑。回滚演练须覆盖账号和权益写入,切换窗口冻结冲突写入并核对新增数据后再开启写入
初始容量过低或审计落盘抖动test 环境测满 jti、拥塞和慢端,按实测调限额;在审计写满情况下验证 relay 继续进行
上线门槛:连续 7 天无 P0;账号映射和权益抽样通过;回滚脚本演练一次且可恢复旧入口;切换后在 pxwebplay.com 复验登录、配对和串流;确认账单及后台依赖处理完毕再下线 px-prod 的旧单体。