深入 Hyperdrive：我们如何解决一个罕见的 Hyperdrive MySQL 缓存 bug
内容提要
Cloudflare 的 Hyperdrive 现已正式支持 MySQL。文章介绍其从测试版到正式版修复约 20 个漏洞的过程，重点分析一个罕见缓存 bug：当客户端与端点节点位于同一数据中心并共享缓存时，因 MySQL 能力协商差异导致缓存字节格式不一致，查询会返回空结果或挂起。修复方式是统一以 Hyperdrive 能力编码缓存结果，使连接成功率提升至 99.99%。
延伸解读
缓存共享的隐患：能力协商不一致
Hyperdrive 的 Client 和 Endpoint 节点在同一个数据中心时会共享 CDN 缓存，这原本是为了提升性能。但文章揭示，由于 MySQL 协议的能力协商差异，Client 面向 Worker 时可能使用不同的能力集，而 Endpoint 始终使用 Hyperdrive 的固定能力集。当一方缓存了另一方无法正确解析的字节格式时，就会导致查询返回空结果或挂起。这提醒我们，在分布式缓存设计中，必须确保缓存内容的格式与所有读取方的预期一致。
修复策略：统一缓存编码
问题的根源在于缓存了面向 Worker 的翻译后字节，而非 Hyperdrive 内部的标准格式。修复方法很简单：无论哪个节点写入缓存，都始终存储使用 Hyperdrive 能力编码的规范结果字节。这样，任何节点读取缓存时都能正确解析并翻译。这一改动消除了空行问题，并将客户端连接成功率提升至 99.99%。这说明在协议转换场景中，缓存层应保持内部一致性，避免混合不同编码格式。
从 Beta 到 GA：可靠性是打磨出来的
Hyperdrive 对 MySQL 的支持从 Beta 到正式可用，期间修复了约 20 个漏洞，包括字符集编码问题（如 utf8 别名导致 emoji 丢失）和连接重置后的编码回退。这些看似微小的 bug 在真实负载下可能影响可用性。文章强调，达到 99.99% 的可用性目标需要持续追踪错误率并深入排查罕见问题。对于依赖数据库连接池的开发者，选择经过充分测试的 GA 版本比尝鲜 Beta 更稳妥。
Q&A
Hyperdrive 是什么？它支持哪些数据库？
Hyperdrive 是 Cloudflare 为 Workers 提供的分布式数据库连接池器，最初仅支持 Postgres，现已正式支持 MySQL。它通过在全球网络中保持热 SQL 连接并在多个 Worker 请求间共享，同时利用 CDN 缓存常见查询来降低延迟和源数据库负载。
Hyperdrive 的 MySQL 支持从测试版到正式版经历了什么？
Hyperdrive 的 MySQL 支持从测试版到正式版（GA）期间，团队修复了约 20 个漏洞，目标是使 MySQL 处理的可靠性达到与 Postgres 支持相同的水平，并验证真实客户使用能达到 99.99% 的生产可用性目标。
Hyperdrive 的缓存架构是怎样的？Client 和 Endpoint 节点如何共享缓存？
每个 Hyperdrive 实例采用分离架构，包含 Client 和 Endpoint 两个节点。Client 节点与用户的 Worker 运行在同一台机器上，处理本地缓存（如果启用）并在需要时将查询转发给 Endpoint；Endpoint 节点持有连接池，位于离源数据库最近的数据中心。每个节点使用其所在数据中心的 Cloudflare CDN 缓存。如果两个节点运行在同一数据中心，它们会共享同一个缓存。
Hyperdrive 遇到的罕见 MySQL 缓存 bug 是什么？它会导致什么现象？
该 bug 发生在 Client 和 Endpoint 位于同一数据中心并共享缓存时。由于 MySQL 能力协商差异，Client 节点缓存的是翻译成 Worker 能力的响应字节，而 Endpoint 节点缓存的是使用 Hyperdrive 能力编码的响应字节。当一方读取另一方缓存的字节时，会导致返回空结果或查询挂起。
Hyperdrive 如何修复这个罕见的 MySQL 缓存 bug？
修复方法是确保无论哪个节点存储缓存，都始终以 Hyperdrive 能力编码的规范版本查询结果字节写入缓存。这样，Client 和 Endpoint 在读取缓存时都能正确解析。发布该修复后，空行问题消失，Client 连接成功率提升至 99.99%。
Hyperdrive 在 MySQL 支持中还修复了哪些编码相关的 bug？
修复了两个编码相关 bug：一是 emoji 写入数据库后无法正确返回，原因是握手时协商的 utf8 是 utf8mb3 的别名，仅支持 1-3 字节，改为 utf8mb4 后解决；二是添加 COM_RESET_CONNECTION 清理连接后，连接编码被重置为服务器默认（如 latin1），修复方法是在重置后始终执行命令将编码设为 utf8mb4。
