c.Apps.Realtime(ctx, appID) 打开一个包含应用日志、状态和系统事件的实时流,并返回一个 *squarecloud.Realtime。它是一个迭代器:在循环中调用 Next,直到它返回错误为止,并且务必调用 Close 关闭它。
Realtime 的 ctx 控制整个流:Next 不接受任何参数。要从另一个 goroutine 停止阻塞在 Next 中的循环,请取消该 ctx。
事件
每个RealtimeEvent 都有 Event、Data(原始帧文本)和 ID(最后一个事件 ID,没有时为 "")。
Status 结构体
结束流
在以下情况下,Next 返回 io.EOF:
- 服务器正常关闭连接(每个连接最长持续 10 分钟);
- 服务器发送了
REALTIME_DISCONNECTED(先投递该事件,然后返回io.EOF); - 你调用了
Close。
Realtime 的 ctx 被取消或其截止时间已过时,Next 直接返回 ctx.Err()(context.Canceled 或 context.DeadlineExceeded),而不是 *APIError。要自行退出循环,只需 break:延迟执行的 Close 会释放连接。
如需在 10 分钟后继续观察,请在循环结束时再次调用 Realtime。
重新连接
连接断开,或服务器将重新连接交由客户端处理(REALTIME_RECONNECT)时,流会自行重新打开:
- 最多连续 3 次;任何
logs或status事件都会重置计数; - 每次重新打开距上一次打开至少 5.5 秒,以保持在 API 每个应用每 5 秒打开一次的速率之内。
Status 在重新连接后依然保留。重新连接失败超过 3 次后,Next 会返回带有 NETWORK_ERROR(状态 0)的 *APIError。
限制和错误
- 每个账户 5 个并发连接,每个应用 30 个(涵盖所有用户)。超出时返回 429
REALTIME_MAX_CONNECTIONS或REALTIME_MAX_CONNECTIONS_APP。 - HTTP 状态会在开始流式传输之前检查,因此这些错误(以及未知应用的 404)由
Realtime本身返回,早于第一次Next。 - 当
ctx没有截止时间时,WithTimeout的截止时间只覆盖打开阶段,直到响应头到达为止(未到达则返回TIMEOUT)。除ctx外,流本身没有截止时间。
后续步骤
Snapshots
备份和恢复应用与数据库。
实时 API 参考
这个流背后的 REST 端点。
用 CLI 查看日志
在终端中查看同样的流。

