> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oddspapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 上线检查清单 —— 从试用密钥到生产环境

> OddsPapi 集成的生产就绪清单：状态处理、重连与续传、staleOdds、速率限制、监控，以及联系支持时需要提供的信息。

试用验证的是数据。生产环境则要求集成在连接中断、博彩商静默或我们发布新版本时依然稳定。本页是接入真实流量之前需要逐项完成的清单，每一项都链接到对应的详细说明。

***

## 1. 状态：快照加实时流

* [ ] 先连接 WebSocket，再拉取 REST 快照并合并。按键比较，`changedAt` 较新的一方胜出。
* [ ] 以 `oddsId` 为键存储赔率。该键在 REST、WebSocket、历史与结算中完全一致，一份存储即可服务四处。
* [ ] 登录时用 `sportIds`、`tournamentIds` 和 `bookmakers` 过滤到您实际交易的范围。数据流越小，处理越快，也越不容易触发背压。
* [ ] 选定 `receiveType`。`zstd` 可将 `odds` 流量压到 JSON 的约五到六分之一，解码只需一行。

详见：[核心概念](https://docs.oddspapi.io/zh/api-reference/concepts.md)、[登录与过滤](https://docs.oddspapi.io/zh/websocket/auth.md)、[压缩](https://docs.oddspapi.io/zh/websocket/compression.md)。

***

## 2. 重连与续传

* [ ] 持久化 `serverEpoch` 以及每个频道最后处理的 `entryId`。
* [ ] 重连时携带 `serverEpoch` 和 `lastSeenId` 登录，并等待 `resume_complete`。
* [ ] 处理 `snapshot_required`：为所列频道重新拉取 REST 快照，清除其游标，继续消费。
* [ ] 收到 `reconnect` 控制帧后立即重连。每次发布前我们都会发送该帧，不要等到连接被关闭。
* [ ] 遇到关闭码 `1006` 和 `1011` 时短暂退避后重连。`4002`（背压）和 `4003`（连接数过多）是需要解决的问题，不应盲目重试。

上线前请各演练一次：断开几秒后无缺口续传；断开超过 `resumeWindowMs` 后以快照恢复。记录第二种情况的耗时，它就是您的最坏恢复时间。

详见：[续传与重放](https://docs.oddspapi.io/zh/websocket/resume-replay.md)、[故障排查](https://docs.oddspapi.io/zh/websocket/troubleshooting.md)。

***

## 3. 博彩商数据过期

* [ ] 在订阅 `odds` 的同时订阅 `bookmakers` 频道。
* [ ] 按 `fixtureId:bookmaker` 组合保存 `staleOdds`，在使用价格之前先检查它。
* [ ] 当其为 `true` 时，暂停该赛事上的该博彩商，或切换到其他博彩商。恢复为 `false` 后再继续。
* [ ] 将它与 `suspended`、`active`、`marketActive` 区分开。后三者是博彩商自身的停盘，`staleOdds` 反映的是我们对该博彩商的可见性。
* [ ] 博彩商整体故障会表现为每场赛事一条消息，而不是单独一条消息。

详见：[可靠性与运维](https://docs.oddspapi.io/zh/api-reference/reliability.md)。

***

## 4. 速率限制与连接数

* [ ] 赔率接口每个 `apiKey` 每秒 10 次请求，其余接口每分钟 200 次。
* [ ] 读取 `X-RateLimit-Remaining`，遇到 `429` 时按 `Retry-After` 给出的时间退避。
* [ ] 快照和回补用 REST，变更用实时流。循环轮询赔率是触发限流最常见的原因。
* [ ] 每个 `apiKey` 组的并发 WebSocket 连接不超过 8 个。如需更多，请在设计前联系我们。

详见：[速率限制](https://docs.oddspapi.io/zh/api-reference/rate-limits.md)、[WebSocket 概览](https://docs.oddspapi.io/zh/websocket/overview.md)。

***

## 5. 监控

* [ ] 跟踪传输延迟：您的接收时间减去消息的 `ts`。请先运行 NTP，否则 100 毫秒以下的读数意义不大。
* [ ] 按博彩商跟踪观测延迟：`changedAt − bookmakerChangedAt`，并与 `GET /bookmakers` 中的 `maxDelayLiveInSec` 和 `maxDelayPregameInSec` 对照。
* [ ] 对重连次数、`snapshot_required` 次数，以及每个博彩商被标记 `staleOdds` 的赛事占比设置告警。
* [ ] 订阅[状态页](https://oddspapi-v5.instatus.com)，获取故障与维护通知。
* [ ] 如果延迟重要，请部署在靠近我们的位置：德国中部或美国东部。

详见：[可靠性与运维](https://docs.oddspapi.io/zh/api-reference/reliability.md)、[核心概念](https://docs.oddspapi.io/zh/api-reference/concepts.md)、[延迟测量方法](https://docs.oddspapi.io/zh/guides/latency-methodology.md)。

***

## 6. 变更与支持

* [ ] 关注[更新日志](https://docs.oddspapi.io/zh/changelog.md)。标记为**重大变更**的条目需要您这边采取行动。
* [ ] 忽略响应中的未知字段。任何一次发布都可能新增字段。
* [ ] 用 `X-API-Key` 请求头而不是查询参数传递密钥，避免其出现在 URL 和日志中。
* [ ] 向 [contact@55-tech.com](mailto:contact@55-tech.com) 报告问题时，请提供受影响的频道或接口、UTC 时间戳，以及您的 `serverEpoch` 和 `entryId`。

***

## 满足以下条件即可上线

* 强制断线后能无缺口续传，长时间断线能通过快照恢复，且恢复耗时已经实测。
* `staleOdds` 标记能自动停止该博彩商在该赛事上的交易，无需人工介入。
* 遇到 `429` 时客户端会减速，而不是出错。
* 您自己的监控面板能看到每个博彩商的传输延迟、观测延迟和过期占比。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.