裁决 01未订阅能否看设备列表
- 我的建议
- 不能。设备页显示「未订阅」,PHP 无 web 票可签。
- 理由
- 列表和串流共用同一个 web 角色,PHP 在签票处一次裁决权益;把列表单独放行会多出第二个权益判定点。
- 你要翻的一句话
“PHP 仅对已识别的付费 plan、plan_expires_at > now 且 status='active' 的账号签发 web 票。”
账号与权益在 PHP,连接与 relay 在信令,设备与 P2P 在网关。页面按产品路径、架构、验收与风险展开,供产品负责人、工程和验收者共用。
用户在网页登录后即可查看自家在线网关报告的设备,并在权益有效、设备可用且 ICE 建连成功时观看 P2P 画面。
账号和权益归 PHP,设备归网关,连接归信令,每个账号至多一个在线 agent 和一个在线 web。三件事各有唯一事实源,跨服务只通过四个契约面交接。
| 服务 | 职责 | 明确不做 |
|---|---|---|
| PHP | 七个接口、账号与会话、权益、配对、签票、发起 kick | ① 不维护设备清单 ② 不判设备忙闲 ③ 不处理媒体或 ICE |
| Go 信令 | 验票与防重放、连接表、relay、kick | ① 不判账号权益 ② 不解析设备或 relay 业务内容 ③ 不保存串流记录 |
| Go 网关 | 配对与凭据、上线重连、设备发现与忙闲、P2P | ① 不验证用户登录 ② 不判订阅权益 ③ 不查询其他账号的设备 |
四条链路合起来才是完整系统:登录取票走 HTTPS,控制与 relay 走 WSS,媒体走 P2P,强制下线走本机 kick。
控制面经过 PHP 与信令,媒体面只经浏览器和网关。P2P 那条虚线不穿过任何服务节点,这是整套架构的成本边界,也是故障边界。
| 链路 | 走法 | 协议与端口 | 约束 |
|---|---|---|---|
| 登录取票 | 浏览器 ↔ PHP;网关 ↔ PHP | HTTPS · 端口待定 | 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 秒截止 |
判定只有三处:PHP 判登录和签票权益,网关收 offer 时判设备归属与忙闲,信令以当前连接表判在线和投递目标。
判定权跟着事实源走,避免同一条规则在两个服务各写一遍。信令不判权益,也不解析设备或 relay 业务内容;PHP 不维护设备状态与在线连接;网关不验证用户登录,也不判订阅权益。
| 判定 | 归属 | 触发点 | 依据 | 不归谁 |
|---|---|---|---|---|
| 登录 · 签票权益 | PHP | 登录成功、渲染设备页、签发 web ticket | 已识别付费 plan、plan_expires_at > now、status='active' | 信令不判账号权益 |
| 设备归属 · 忙闲 | Go 网关 | 收到 offer 时原子判定并占用 | 设备存在、可用、未占用;只有此条件允许 idle → busy | 信令不解析设备或 relay 业务内容 |
| 在线 · 投递目标 | Go 信令 | 每次 relay、接管、kick | 单实例当前连接表;每个账号至多一个在线 agent 和一个在线 web | PHP 不维护在线连接 |
16 个环节按主路径从上到下排列:注册、登录、开页、连信令、列表、offer、answer、ICE、首帧、释放;配对、重连、强制下线和会话失效作为支线插在同一张泳道图里。
四条竖泳道分别是浏览器、PHP、信令、网关;编号与 PLAN 的 16 环节一致。箭头只表示消息方向,右侧警示方块给出该步的失败态,步骤名下方是验收截止。
| 截止点 | 数值 | 约束对象 |
|---|---|---|
| web / agent ticket 入场 | 60 秒 | 从签发计;只限制建连,已建立连接不随 ticket 到期断开 |
| 列表请求与回包 | 5 秒 | list_req 与 list_resp 共用;超时显示 LIST_TIMEOUT |
| offer 到有效 answer | 30 秒 | 约束浏览器操作;超时关闭本地 P2P 并显示 ANSWER_TIMEOUT |
| ICE connected 到视频首帧 | 10 秒 | 待首帧;失败显示 MEDIA_FAILED,关闭本地 P2P |
| 正常关页到网关释放 | 5 秒 | 测试目标;断网按媒体库报告终态验收,记录实测时间 |
四个契约面首尾相接:A 定义入场资格,B 定义连接控制与 peer 消息,C 让网关换票,D 让 PHP 断开指定角色。
契约只交换必要字段。票、连接、配对、kick 各自闭环,任何一方都不靠读取对方内存或数据库来补状态。
票是 kid.payload.mac。payload 是 UTF-8 JSON 字节的无填充 base64url,mac 是无填充 base64url 的完整 HMAC-SHA-256,输入为 ASCII kid.payload。v3 固定算法,以恒定时间比较 MAC,对原始编码串验签。
| payload 字段 | 类型与约束 |
|---|---|
| sub | string,users.id 的十进制写法,正整数、无前导零,范围和数据库一致 |
| role | string,枚举 web、agent |
| exp | integer,UTC Unix 秒,PHP 签发时的整秒加 60,now >= exp 即过期 |
| jti | string,16 个密码学安全随机字节的 base64url 无填充形式,按全局唯一处理 |
| 帧或阶段 | 方向 | 字段和约束 |
|---|---|---|
| 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 协议层自动回复。 |
| type | 谁发 | 必填字段(除共同的 string type) | 处理或错误 |
|---|---|---|---|
| list_req | web → agent | id string,当前连接内唯一请求 ID | 网关返回同 id 的 list_resp;目标缺失为 TARGET_OFFLINE |
| list_resp | agent → web | id string、devices array,可为空 | 与待完成的 id 匹配后刷新列表,忽略迟到的旧响应 |
| offer | web → agent | id string,本次串流 ID;device_id string;sdp string,WebRTC offer SDP | 网关原子判定并占用,失败用同 id 回 DEVICE_NOT_FOUND、DEVICE_BUSY、DEVICE_UNAVAILABLE 或 MEDIA_FAILED |
| answer | agent → web | id 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 或 null | candidate 非 null 时两个 SDP 定位字段至少一个非空;null 表示候选结束,其余字段填 null。收到远端 SDP 前按 id 暂存,过时 id 丢弃 |
| stop | web → agent | id string,对应 offer | 只释放 ID 匹配的占用;重复或过时 stop 无副作用 |
| 模式 | JSON 请求(恰好一项) | HTTP 200 JSON 响应 |
|---|---|---|
| 首次或换机 | {"pairing_code":"014257"} | {"gateway_secret":"<43 字符 base64url>","ticket":"<agent ticket>"} |
| 连接或重连 | {"gateway_secret":"<43 字符 base64url>"} | {"ticket":"<agent ticket>"} |
| HTTP | code | 触发 |
|---|---|---|
| 400 | BAD_REQUEST | 字段、类型或编码无效;超过请求上限返回 413 BAD_REQUEST |
| 409 | PAIRING_INVALID | 错码、已用、过期 |
| 401 | SECRET_INVALID | secret 未登记或已换 |
| 429 | RATE_LIMITED | 额度耗尽;附整数秒 Retry-After |
| 503 | TEMP_UNAVAILABLE | 短暂不可用 |
| 项目 | 定义 |
|---|---|
| 监听 | 同机独立 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 用于验收角色重连 |
单个账号行承载持久状态:设备与占用在网关,连接与票消费在信令,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_id | TEXT | 是 | 保存随机 cookie token 的 SHA-256 十六进制摘要,非空值唯一 |
| session_seen_at | INTEGER | 是 | Unix 秒,和 session_id 同时为空或非空 |
| gateway_secret_hash | TEXT | 是 | 保存网关 secret 的 SHA-256 十六进制摘要,非空值唯一 |
| pairing_code | TEXT | 是 | 六位 ASCII 数字,非空值唯一 |
| pairing_exp | INTEGER | 是 | 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,缺失或不匹配拒绝。
| 旧表 | v3 接替方式 |
|---|---|
| devices | 网关本地设备发现与忙闲状态,经信令转发 list_resp |
| stream_logs | 网关以媒体生命周期管理串流,信令以本地滚动日志记录控制事件,历史串流记录按既有留存需求处理 |
| session_leases | users.session_id 与 users.session_seen_at 管理 PHP 会话,网关本地媒体状态管理设备占用和释放 |
| ws_tickets | PHP 签发短效 HMAC 票,信令验签并在内存记录已消费的 jti |
| signal_revocations | /kick 摘除当前连接,PHP 会话清除后停止续签;已签票仍受原定有效期及单次消费约束 |
| agent_secrets | 网关重新配对后在本地保存 secret,PHP 在 users.gateway_secret_hash 保存对应摘要 |
三张状态机各自推进:信令连接表、网关凭据与 PHP 会话,状态只能由各自的事件更新。
下面先看网关生命周期和连接表替换规则,再给出三张状态机的完整转移明细。任何一张表都不替另一张表改状态。
| 当前 | 事件 | 下一状态与动作 |
|---|---|---|
| 无对应角色 | 合法 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 | 在线,重置退避;已有媒体按自身生命周期推进 |
| 当前 | 事件 | 下一状态与动作 |
|---|---|---|
| 无有效会话或已过期 | 正确账号密码登录 | 签发新 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 会话判据 |
从 mock 到真机,再到生产切换,M0–M5 每一级都有可独立运行的验证入口和出口判据。
台阶高度表示依赖与验收门槛的累积,不是工期。M1 用 mock agent 做第一次整体竖切,先证明 PHP、信令、浏览器能跑通列表与 relay,再接真网关。
| 里程碑 | 验证入口 | 谁能独立验证 |
|---|---|---|
| M0 | make e2e 启动测试运行器,A–D 用例已命名,未实现断言标红 | 非实现工程师 |
| M1 | make e2e CASE=mock 通过,付费账号见 mock 设备,免费账号无票 | QA,无需真网关 |
| M2 | make e2e CASE=gateway 配对收到 ready,3 秒内发现上线,kick 后 3 秒恢复 | 非实现工程师,有测试网关 |
| M3 | 真 PS5 连续出画面 ≥5 分钟,关页 5 秒内释放,刷新见 idle | 有真机的验收人 |
| M4 | make e2e CASE=boundaries 通过 30 分钟边界、异地登录、断网恢复、票复用 | QA 或非实现工程师 |
| M5 | test 环境连续 7 天无 P0,回滚演练一次且可恢复旧入口,切生产后复验 | 发布负责人和独立 QA,产品负责人确认权益 |
PHP 的错误决定页面和凭据处理,信令的错误决定连接处理,网关的错误决定是否可以发起串流。
同一个错误码只对应一种处理动作。前端展示与自动恢复分开写,避免把「可以重试」误当成「已经恢复」。
| 错误码 | 触发条件 | 前端或网关表现 | 自动恢复 |
|---|---|---|---|
| BAD_REQUEST / BAD_MESSAGE | HTTP 或 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_LIMIT | relay 限速或服务端拒绝慢端 | 超速关 4429,帧类型违规关 1003,超大帧关 1009,待发队列或写超时关 1013,页面显示连接中断 | agent 退避,web 提示刷新 |
| ALREADY_ONLINE | 同账号已有 agent 在线 | 信令关闭新连接 4409,新网关提示已有网关在线,原网关继续工作 | 可退避等待原连接离线 |
| WEB_REPLACED | 新 web 接管 | 旧页关闭 4409,显示另一个标签页已打开设备页 | 否 |
| KICKED | PHP 或内部验收调用 kick 命中连接 | 关闭 4410;web 回登录,agent 重连 | 仅 agent 自动 |
| TARGET_OFFLINE / LIST_TIMEOUT | 对端不在线或列表 5 秒未到 | 分别显示「设备未连接」「设备列表加载超时」 | 用户可刷新或重试 |
| DEVICE_NOT_FOUND / DEVICE_BUSY / DEVICE_UNAVAILABLE | 设备不存在、已占用或状态未知 | 提示设备不可用或「使用中」 | 否 |
| ANSWER_TIMEOUT / ICE_FAILED / MEDIA_FAILED | answer 超时、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 换票可自动 |
三项施工结论可直接按此验收;如要改,只需改对应的一句话,不必改整套架构。
“PHP 仅对已识别的付费 plan、plan_expires_at > now 且 status='active' 的账号签发 web 票。”
“Authorization: Bearer <KICK_TOKEN>,32 随机字节的 base64url,与票签名密钥独立,PHP 和信令通过服务环境配置,恒时比较。”
“每端每秒 50 帧、突发 100,连接表最多 4,096 条。”
“审计只记时间、账号 ID、角色、事件、结果,队列满丢弃并计数。”
本轮交付七个 PHP 接口、两个信令角色,以及网关云连接和媒体接入所需的行为;范围外的能力不进入本轮验收。
七个 PHP 接口是 POST /register、GET/POST /login、GET /、POST /api/pairing、POST /api/agent/ticket、POST /api/force-logout、POST /kick。两个信令角色是 web 与 agent。
| 风险 | 缓解与验收 |
|---|---|
| 新协议要求网关升级并重新配对 | 预告一次六位码配对,test 环境先验新版网关。过渡期新入口使用独立端口,网关启动开关选择单个协议路径 |
| 重新配对时旧 agent 可能仍在线 | secret 更换阻止后续取票,提示用户关掉旧网关;旧连接释放后新网关退避恢复。M2 同测此情形 |
| 票被复制、进程重启或签发时钟偏差 | WSS/HTTPS、日志脱敏、单实例有界 jti 记录、启动冷却,M4 演练密钥轮换和重放 |
| 强制下线与已签票窗口,以及 PHP 会话过期后 WSS 仍可存在 | 票 60 秒、一次性,清会话后拒绝新签票;界面说明 kick 针对当前连接。验收分别记录 PHP 会话失效、在线 web 断开、旧票剩余窗口 |
| 关页与异常网络断开探测速度不同 | 正常关页用真机验证 5 秒释放;断网按媒体库报告终态验收,记录实测时间。网关顺序处理占用和释放,旧 stop 不能释放新串流 |
| 部分网络无法 P2P | test 隔网验证 ICE 成功和失败提示,失败时允许用户再次发起 |
| 六位配对码遭猜测或响应丢失 | 全站和来源限流、短有效期、事务内单次消费,失败时由用户生成新码 |
| 切换牵动账单、后台和账号兼容性 | 发布前核对外部依赖、做生产数据干跑。回滚演练须覆盖账号和权益写入,切换窗口冻结冲突写入并核对新增数据后再开启写入 |
| 初始容量过低或审计落盘抖动 | test 环境测满 jti、拥塞和慢端,按实测调限额;在审计写满情况下验证 relay 继续进行 |