数据源接口 GFI

GFI（Game Feed Interface）v1 是本平台唯一接受的牌局数据格式，也是对外开放的标准数据源入口。任何能提供真人百家乐、龙虎或牛牛牌局的系统，例如官方供应商、自营现场的荷官或数据员系统、中继站、图像辨识系统，都以 GFI 把「开局、停止下注、发牌、结果、修正、作废」等事件推送给本平台。

这一章写给谁

这一章给数据源开发者。如果你是运营商、要把游戏串到自己的网站，请看快速开始。

来源（source）：在本平台注册、持有凭证的一个数据提供者，以 sourceId 识别（以小写英文字母开头，2–32 个小写字母或数字、_ 或 -，例如 acme-live）。来源代号与密钥由平台创建，请向平台申请。
来源桌：来源自己命名空间中的桌号，例如 B001（[A-Za-z0-9_.:-]，最多 64 个字符），由平台绑定到公开桌号。
视频流（stream）：一个 (sourceId, 来源桌) 的事件串行。顺序、去重、续传都以视频流为单位。
规格的单一真相：JSON Schema（2020-12）与本章；可以用 GFI 事件验证器在浏览器中检查事件。

传输

三种传输方式的事件格式完全相同：

方式	端点	适用
WebSocket（建议）	`wss://{ingest-host}/ingest/v1/stream`	长时间在线的来源，延迟最低
HTTPS 批量	`POST https://{ingest-host}/ingest/v1/events`	无法维持长连接、或需要补送时
Service Binding	平台内部	只供与本平台同一个 Cloudflare 账号的 Worker

{ingest-host} 使用独立的主机名称：

环境	主机
正式	`elite-ingest.ewin888.com`
测试	`elite-dev-ingest.ewin888.com`

其他 HTTPS 端点：

方法与路径	用途	响应
`POST /ingest/v1/events`	送出一批事件，正文 `{"events": [...]}`	`{"acks": {...}, "nacks": [...], "resync": [...]}`
`POST /ingest/v1/validate`	干跑：与 `events` 相同的检查，但不写入、不套用	同上
`GET /ingest/v1/resume?tables=B001,B002`	查询每条视频流已确认的最后 `seq`	`{"resume": {"B001": 1530, "B002": 0}}`
`POST /ingest/v1/heartbeat`	心跳（HTTPS 来源），正文 `{"ts": "…", "tables": {"B001": "ok"}}`	`{"ok": true, "serverTime": "…"}`

每个来源可以使用哪些传输方式由平台设置；使用未开放的方式会回 403。

认证

所有 HTTPS 请求与 WebSocket 握手都带下列头部，签名规则与租户 API 相同：

text

X-Source-Id:  <sourceId>
X-Timestamp:  <Unix 秒>                 与本平台时间差 ≤ 300 秒
X-Nonce:      <16–64 个字母或数字>           10 分钟内不可重复
X-Signature:  hex( HMAC-SHA256( secret,
                METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + hex(SHA-256(body)) ) )

PATH 是路径加上查询字符串，例如 /ingest/v1/resume?tables=B001,B002。
WebSocket 握手的 METHOD 是 GET，正文是空字符串。
可选的加强：IP 白名单（依来源 IP 判断）。
错误响应的格式是 {"code": "…", "message": "…"}：

HTTP	`code`	原因
401	`UNAUTHORIZED`	缺少或格式错误的认证头部、来源不存在、签名错误、时间窗外、nonce 重复
403	`SOURCE_DISABLED`	来源已禁用
403	`UNAUTHORIZED`	未开放这种传输方式，或来源 IP 不在白名单
400	`INVALID_EVENT`	正文不是 JSON
404	`NOT_FOUND`	端点不存在
405	`METHOD_NOT_ALLOWED`	方法错误（例如以 GET 调用 `events`）
413	`LIMIT_EXCEEDED`	超过批量限制
426	`UPGRADE_REQUIRED`	`/ingest/v1/stream` 没有以 WebSocket 升级

限制

项目	值
单批事件数	≤ 500 笔，且 ≤ 1 MiB
单一事件	≤ 64 KiB
单一视频流未确认事件（in-flight）	≤ 2,000 笔，超过就必须等待 ack
心跳间隔	5 秒
判定失联	15 秒内没有心跳也没有事件
签名时间窗	±300 秒
nonce 不可重复期间	10 分钟

WebSocket 上超过批量限制时，连接以关闭码 4008 结束；HTTPS 回 413。

接下来

事件与数据模型：事件信封、事件目录、百家乐、龙虎与牛牛的结果格式（牛牛的暗发与逐家开牌）、时间与下注时窗。
可靠性、健康与错误：ack、去重、缺口与 resync、续传、心跳、错误码、信任等级与 WebSocket 对话示例。
GFI 事件验证器：在浏览器中检查一批事件。

数据源接口 GFI ​

传输 ​

认证 ​

限制 ​

接下来 ​

数据源接口 GFI

传输

认证

限制

接下来