Troubleshooting and Development

English · 简体中文

排障与开发

发送报错

现象	首先核对
PacketHeaderError	消息是否非空且首字节为 0xfe，批量中是否每条均有效
PacketSizeExceedMTU	模式是否支持分片、协商 MTU、分片数量及预算
发送一直等待	对端是否读取，可靠帧是否确认，应用是否无限堆积任务
ConnectionClosed	对端退出、应用主动关闭、超限/无效接收状态或停滞分片
建立连接超时	地址、网络命名空间、UDP 端口、服务端 listen 状态、RakNet 版本

set_loss_rate() 是发送路径模拟丢包接口，不等价于 netem 的双向网络包/ACK 丢包；不要用它替代完整公平性能评估。

吞吐变差或延迟变高

1. 确认优化构建，记录确切库提交、锁文件和工具链。
2. 小包普通与批量分别测，新建连接；确认 MTU 能放下两条消息。
3. 看 UDP 接收错误和 qdisc 数据，不能把 socket 溢出视为健康无损网络。
4. 检查 CPU 热点、worker 数、接收分片分布、应用队列及慢接收端。
5. 比较持续负载与稀疏延迟；预热 RTT 不代表吞吐阶段 RTT。
6. 对照范围增加重复次数，再判断小幅变化是否有意义。

若有效 NACK/超时使批量合并退回单独发送，同一连接不会再次恢复合并。大量 800 B 消息无法在默认 MTU 下两条合并，批量 API 不保证更快。

Bedrock 连接超时

先直连后端，再连代理。如果直连也失败，先排查游戏版本、后端 transport=raknet、RakNet 版本、端口、账户/游戏服务和网络位置。仅凭客户端“NetherNet”错误标题不足以确定实际传输；记录完整错误详情与服务端日志。

如果只有代理失败，核对前端 MOTD 的游戏协议/版本、客户端是否连前端端口、上游连接日志及两个方向的转发。服务器列表拿到 MOTD 不等于已完成游戏登录。

开发流程

在隔离代码副本中编辑，使用任务专属 HOME、Cargo/Go 缓存、工具链、target 和网络命名空间。不要修改主机 shell 文件、全局 Git 配置、路由或 qdisc。

涉及 ARQ、ACK/NACK、排序、分片或批量的变更应关注：

• 五种模式的乱序/重复/丢失行为，序列号回绕与多通道。
• 原始 RakNet 帧格式、离线握手版本、MTU 协商及已有对端互通。
• 分片重组限制、发送背压、取消/关闭和并发 flush 唤醒。
• 普通与批量路径分别回归，丢包后的退回策略。
• 同一提交的吞吐、尾部延迟及 RSS；不要用单项提升替代完整评估。

仓库测试入口包括 src 单元测试、tests 和 互通说明。需要验证时，在隔离环境执行 cargo test，按互通说明准备第三方实现；网络测试不能退回主机。

真实 Bedrock 验证应包括直连、代理、进入世界、移动及方块操作，记录双方构建和 RakNet 握手版本。回显 benchmark 是性能实验，不能代替真实游戏兼容性结论。

提交问题时带上什么

库版本/提交、操作系统、Rust/Tokio 版本、协商 MTU/版本、接口和模式、最小复现，以及脱敏的错误日志。性能问题附完整参数、重复范围和网络计数器；不要上传账户令牌、密码或私有世界数据。

仓库 Issues · 性能评估

同步 API · API 索引 · 错误与超时

完整功能检查（1.4.0）

在隔离源码环境中，python scripts/test-features.py --list 列出矩阵；python scripts/test-features.py 对三个可选功能的八种组合逐一运行 cargo test --all-targets 和 doctest。tomllib 要求 Python 3.11+，CI 使用 3.12；仅当任务缓存已具备依赖时使用 --offline。

CI 还检查格式、默认/全功能代理测试、独立示例编译及打包。Linux 专属 API 需要 cfg 保护。平台调度适配仍须保留交付、恢复和关闭的回归断言；增加超时不能代替被验证的行为。