Cachey API完全参考：/fetch精确Range、C0-Bucket与C0-Config请求头逐项解析-北京尧图网络

【免费下载链接】cacheyRead-through cache for object storage项目地址https://gitcode.com/gh_mirrors/cac/cachey点击查看免费下载Cachey 是一个面向 S3 兼容对象存储的高性能读穿透read-through缓存服务核心入口是/fetchHTTP 接口。本文作为Cachey API 参考逐项解析/fetch请求中精确的Range写法以及C0-Bucket、C0-Config、C0-Object-Size、C0-Exact四个自定义请求头的用途与常见错误码帮助你在部署 Cachey 对象存储缓存时一次写对请求。Cachey 在架构中的位置Cachey 工作在客户端与 S3 之间命中缓存直接从内存/磁盘返回数据不触碰后端未命中向 S3 下载回填混合缓存foyer 内存磁盘再返回固定 16 MiB 页大小请求的字节范围会被映射到页对齐的缓存条目上定义见 src/service/mod.rs 的PAGE_SIZE与pagerange支持多桶副本选择、回退、对冲下载都由服务端自动管理设计前提缓存的是不可变immutable对象因此读多写少的 blob 场景收益最大。/fetch 请求格式总览HEAD|GET /fetch/{kind}/{object} Range: bytes1048576-18874367路径中两个参数共同构成缓存键参数含义约束kind桶集合标识bucket set1–64 字符不含控制字符objectS3 对象键object key1–1024 字符请求头一览请求头必填作用Range✅指定精确字节范围C0-Bucket❌声明对象所在的一个或多个桶C0-Config❌按请求覆盖 S3 超时/重试配置C0-Object-Size❌声明对象总字节数C0-Exact❌true时按精确范围缓存≤16 MiB路由注册与参数解析在 src/service/routes.rs 的fetch处理器中完成。Range 请求头如何写才精确Range是/fetch唯一的必填请求头必须写成单段形式Range: bytes{first}-{last}解析逻辑在 ReadRange 提取器中规则如下必须是单段范围bytes0-99,200-299这种多段写法会返回416首尾必须都是具体下标first last且last 2^40约 1 TiB由 16 MiB × 65536 页决定省略Range直接400Range header is required结合C0-Object-Size时若范围起点 ≥ 对象大小服务端不访问任何桶直接返回416服务端会把你的范围映射到 16 MiB 的页上比如请求1048576-18874367实际会取第 0、1 页0-16777215、16777216-33554431再裁出你要的切片。响应中的Content-Range反映的是实际服务的范围而缓存的仍是整页。C0-Bucket多桶副本的声明方式C0-Bucket用于告诉 Cachey 对象存放在哪些桶里行为规则可以发多个同名头多个头表示冗余副本桶第一个是首选桶享有本地性偏好省略时kind路径段会被当作唯一的桶名桶名约束1–64 字符、不含控制字符见 BucketName示例GET /fetch/prod-videos/movie-2024.mp4 HTTP/1.1 C0-Bucket: us-west-videos C0-Bucket: us-east-videos-backup首选桶慢或失败时服务端会依据健康度与延迟模型自动回退到其余桶并可在下载时限内发起最多 3 份对冲副本hedged requests以压低尾部延迟——完整的选择、回退与对冲策略见 docs/replica-reads.md。C0-Config按请求微调 S3 超时与重试C0-Config是空格分隔的键值对用于在缓存未命中时覆盖本次 S3 请求的 SDK 配置解析实现见 routes.rs字段定义在 src/object_store/config.rs键单位含义ctms连接超时新建连接时生效rtms读超时首字节时间 time-to-first-byteotms操作超时跨重试累计oatms单次尝试超时ma次每个桶主操作的 SDK 最大尝试次数ibms重试初始退避时长mbms重试最大退避时长fpsbool强制 path-style 寻址例如C0-Config: ct1000 oat1500 ma5 ib10 mb100三个实用要点未写的键保持默认C0-Config: ct1000只覆盖连接超时其余继承服务端配置未知键会被忽略写错键名不会报错宽容解析但缺少、数值非法、fps1这类非法布尔会返回400有上限所有 SDK 超时最终受服务端下载时限约束默认--bucket-timeout-ms 5000、--download-timeout-ms 10000且早期对冲副本只允许 1 次 SDK 尝试C0-Object-Size 与 C0-Exact两个进阶头C0-Object-Size声明对象总大小告诉 Cachey 对象的精确字节数后服务端能小对象的整页按实际剩余大小计入准入与延迟模型虽然仍请求整页范围起点超过对象大小时本地判定 416不浪费一次桶调用若桶返回的实际大小不一致返回409大小冲突范围越过对象真实末尾则返回416⚠️ 注意准入信任你声明的大小。若声明偏小该次读取实际可能持有超过预留的内存额度。C0-Exact精确范围缓存模式默认模式下即使只读 1 KiB缓存的也是它所在的 16 MiB 页。如果对象的某些范围总是被完整读取例如固定切片的热数据可设置C0-Exact: true此时请求范围被整体下载并作为一个独立条目缓存上限 16 MiB超出返回400Exact range exceeds the page size只有请求完全相同范围的后续请求才会命中该条目取值必须是字面量true/false1之类会400选型建议范围读会反复重叠 → 用默认页模式范围固定且总是整段读 → 用C0-Exact省空间。读响应Content-Range 与 C0-Status成功响应为206 Partial Content响应头包含响应头说明Content-Range实际服务的字节范围如bytes 1048576-18874367/52428800Content-Length本次返回字节数Last-Modified首个缓存条目的时间戳Content-Type固定application/octet-streamC0-Status首个缓存条目的状态C0-Status的格式为{first}-{last}; {bucket}; {cached_at}例如C0-Status: 1048576-16777215; us-west-videos; 1704067200前两项告诉你数据来自哪个桶、覆盖哪个字节范围cached_at是 Unix 时间戳0 表示本次是缓存未命中刚下载跨多页的 GET 响应中后续各页的C0-Status放在HTTP/2 trailers里HTTP/1.1 只携带第一个条目HEAD请求走同一解析逻辑只返回头不返回体适合探测对象是否存在及大小。常见状态码速查表状态码含义典型原因400请求无效缺Range、C0-Config键值对格式错误、C0-Exact超限404对象不存在所有桶都报NoSuchKey409对象大小冲突桶报告的大小与C0-Object-Size或已缓存值不一致416范围不可满足请求越过对象末尾、多段范围503过载准入失败或后端 429/503/SlowDown504网关超时桶下载超时含回退后错误到状态码的映射见 on_chunk_error。排查时优先看503是否伴随429——那说明 S3 侧在限流可考虑调大ib/mb退避或降低并发。顺带一提监控接口GET /stats返回 10 秒窗口出入向吞吐的 JSON适合负载均衡与健康检查GET /metricsPrometheus 文本格式全量指标含桶延迟模型、下载延迟、C0-Status相关统计总结一份请求头速记清单✅Range: bytesfirst-last必填且必须是单段具体下标✅C0-Bucket可多值第一桶为首选不写则以kind为桶名✅C0-Config空格分隔键值对只写要覆盖的项超时受服务端总时限约束✅C0-Object-Size让边界判定提前本地化但要保证数值真实✅C0-Exact: true用于固定热范围上限 16 MiB✅ 想看每页缓存状态就启用 HTTP/2读 trailers 里的后续C0-Status更多背景可参考项目文档README.md、docs/replica-reads.md以及副本选择的模拟实验 docs/simulation/README.md。赞分享【免费下载链接】cacheyRead-through cache for object storage项目地址https://gitcode.com/gh_mirrors/cac/cachey点击查看免费下载相关推荐VibeFigma API参考指南Figma转React的 POST /v1/api/vibe-figma 请求参数与响应字段逐项精讲VibeFigma API参考指南Figma转React的 POST /v1/api/vibe figma 请求参数与响应字段逐项精讲 VibeFigmSkiaSharp.HarfBuzz 2.88.1 API 变更深度解读SKShaper.Result 新增 Width 属性与带宽度构造函数SkiaSharp.HarfBuzz 2.88.1 API 变更深度解读SKShaper.Result 新增 Width 属性与带宽度构造函数本篇技术指南围redux-localstorage persistState API完整参考paths与config全解析redux localstorage persistState API完整参考paths与config全解析 redux localstorage 是一个轻量上一篇如何为Skills Manager开源项目贡献代码从环境搭建到提交第一个PR的完整指南下一篇oxwm Nix 部署完整指南NixOS 与 Home Manager 声明式配置 --validate 构建期校验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Cachey API完全参考：/fetch精确Range、C0-Bucket与C0-Config请求头逐项解析

相关推荐

常用虚机模式

如何快速搞定DS4Windows：轮询率、HIDHide隐藏手柄与多控制器输出槽完整指南

CC Switch v4.0.19 升级指南：第 12 个应用 Kimi Code 接入与用量页重排的完整说明

更多资讯

n8n与数据库集成优化实战：连接池与事务管理

C++链表栈实现：动态内存与高效操作解析

嵌入式系统资源开发实战：RTOS+DMA+低功耗工程化落地指南

MTK刷机硬件适配指南：驱动缝合与HAL层替换实战

WinCC实现GMP合规审计追踪的替代方案

深入解析CPU缓存原理与性能优化实战

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？