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

# WebSocket 调试

> 查明连接到 OrbitFlare 的 Solana WebSocket 为何被拒绝、没有消息或频繁断开：握手错误、从不触发的订阅、空闲断开以及保活。

大多数 WebSocket 问题可以分为三类：连接被拒绝、连接成功但收不到任何消息，或者正常工作一段时间后断开。先弄清您遇到的是哪一类。

## 从一个确定可用的订阅开始

`slotSubscribe` 每个槽都会触发，大约每秒五次，因此几乎可以立即看出连接本身是否正常。使用 `npm install -g wscat` 安装 [wscat](https://github.com/websockets/wscat)，然后：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
wscat -c "wss://fra.rpc.orbitflare.com?api_key=$ORBITFLARE_LICENSE_KEY"
> {"jsonrpc":"2.0","id":1,"method":"slotSubscribe"}
```

正常的连接会先返回一个订阅 ID，然后是一连串通知：

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
{"jsonrpc":"2.0","result":332807,"id":1}
{"jsonrpc":"2.0","method":"slotNotification","params":{"result":{"slot":459760339,"parent":459760338,"root":459760337},"subscription":332807}}
```

如果这里正常而您自己的订阅不正常，问题出在订阅上，而不是连接上。请直接跳到[已连接但收不到更新](#已连接但收不到更新)。

## 连接被拒绝

身份验证发生在 WebSocket 握手阶段。验证失败时，服务器不会切换协议，而是用普通的 HTTP 错误和 JSON 响应体回应升级请求。许多 WebSocket 库只会报告 "unexpected server response: 403" 并丢弃响应体，因此请用 curl 检查握手，查看真正的原因：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -i --http1.1 \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://fra.rpc.orbitflare.com/?api_key=$ORBITFLARE_LICENSE_KEY"
```

`HTTP/1.1 101 Switching Protocols` 表示身份验证已通过。否则：

| 状态码 | 响应体 | 解决方法 |
| - | - | - |
| `401` | `{"code":-32401,"message":"missing API key"}` | 在 URL 中添加 `?api_key=YOUR_LICENSE_KEY`。浏览器无法为 WebSocket 设置请求头，因此查询参数是可靠的方式 |
| `403` | `{"code":-32402,"message":"invalid API key"}` | 密钥错误或已被重新生成。请从控制面板重新复制 |
| `403` | `{"code":-32404,"message":"IP not whitelisted"}` | 您的许可证不允许这台机器的 IP 或此区域。请在控制面板中添加该 IP，或连接到许可证包含的区域 |

其他需要检查的事项：

* **主机能否解析。** WebSocket 运行在 RPC 主机上：`wss://{region}.rpc.orbitflare.com`。不存在 `wss://mainnet.rpc...` 或 `wss://global.rpc...` 这样的主机。完整列表请参阅[全球基础设施](/cn/infrastructure)。
* **URL 是否使用 `wss://`。** 将 `https://` URL 传给 WebSocket 客户端会在请求到达 OrbitFlare 之前就失败。
* **仅限 TypeScript：** `Cannot find package 'ws'` 表示缺少可选的 peer 依赖。请运行 `npm install ws`。

## 已连接但收不到更新

服务器会为每个订阅返回一个数字 ID 作为确认。如果始终没有收到 ID，说明请求被拒绝了，回复中会说明原因：

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid Request: Invalid pubkey provided"},"id":1}
```

调试时请记录服务器发送的每一条消息，而不仅仅是通知。错误会通过同一个套接字返回，很容易被忽略。

如果订阅已被接受但一直没有消息：

* **账户没有变化。** `accountSubscribe` 只在账户的数据或 lamports 发生变化时触发。请用一个确定很活跃的账户测试，例如每个槽都会变化的 `SysvarC1ock11111111111111111111111111111111`。
* **过滤条件没有匹配到任何内容。** 对于 `programSubscribe` 和 `logsSubscribe`，如果某个地址从未出现在任何交易中，就不会产生事件。请先在区块浏览器上检查该地址。
* **签名太旧。** `signatureSubscribe` 只知道最近的交易。对于几分钟以前的交易，请改用带 `searchTransactionHistory: true` 的 `getSignatureStatuses`。参见[等待交易确认](/cn/recipes#等待交易确认)。

## 连接断开

### 空闲连接会在没有任何提示的情况下关闭

没有流量的连接最终会被断开，而且是被直接切断而不是通过关闭帧关闭，因此您的客户端会看到关闭码 `1006`，原因为空。请每 20 到 30 秒发送一次 WebSocket **ping 帧**以保持连接：

```javascript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const ws = new WebSocket(`wss://fra.rpc.orbitflare.com?api_key=${process.env.ORBITFLARE_LICENSE_KEY}`);

const keepalive = setInterval(() => ws.ping(), 25_000);
ws.on("close", () => clearInterval(keepalive));
```

> [!WARNING]
>
> `{"method":"ping"}` 这样的 JSON-RPC 消息不能起到保活作用。Solana 没有 `ping` RPC 方法，因此服务器会返回 `-32601 Method not found`。请使用您所用库提供的协议层 ping 帧。

OrbitFlare SDK 每 10 秒发送一次 ping 帧，并在连续三次未收到 pong 后重新连接，因此使用 SDK 时无需自己处理。

### 重新连接后订阅消失

订阅属于某个连接。连接断开时，订阅也随之消失，新连接开始时没有任何订阅。请记录您订阅过的内容，并在重新连接后再次发送这些请求。注意订阅 ID 会发生变化。

SDK 会跟踪订阅并自动重新订阅。您的 `sub.next()` 循环在重连期间会继续运行。

### 取消订阅失败

`Invalid subscription id.` 表示该 ID 在此连接上不存在。通常是连接已被替换，而该 ID 属于旧连接。可以放心忽略。

### 连接过多

每个 IP 最多可以同时保持 50 个 WebSocket 连接，与 gRPC 共享这一额度。请打开一个连接并在上面放置多个订阅，而不是每个订阅使用一个连接。参见[连接限制](/cn/authentication#数据流连接限制)。

## 仍未解决

请收集您连接的区域、确切的订阅请求、服务器返回的每一条消息以及关闭码。然后在 [Discord](https://discord.gg/orbitflare) 中提问。有了这四项信息，大多数问题都能在一次回复中定位。


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