写入路径与缓存

SynapS3 采用缓存优先的写入模型。一次 S3 写入返回成功，表示对象内容已经持久化到本地磁盘，元数据也已经提交到数据库。

PutObject 流程

SynapS3 会校验请求，保存对象及其元数据，再返回 S3 兼容的 ETag。客户端收到成功响应后，Filecoin 存储会继续推进。

持久化不变量

IMPORTANT

SynapS3 只有在本地缓存持久化和数据库提交都成功后才返回成功。

因此，S3 响应不需要等待 Filecoin 存储提供方。对象被接受后，后台任务再继续上传。

读取路径

GetObject 会先读本地缓存。缓存缺失时，如果记录了可用的远端副本，SynapS3 可以从存储提供方取回并校验对象、返回响应，并在可能时恢复本地缓存。

前台成功打开缓存时，会刷新该条目的 LRU 访问时间。这包括 S3 对象和 Range 读取、命中缓存的 CopyObject 源、Admin 内容下载和版本恢复。HeadObject 等只读元数据操作不会刷新，后台 Uploader 读取也不会让条目看起来刚被使用。远端内容完整回填后，会为恢复的缓存重新开始计算 LRU 时间。

同一版本的重复读取会合并访问时间更新，每分钟最多写一次数据库。访问时间按 best-effort 方式记录，更新失败不会让原本成功的读取失败。

缓存淘汰

策略	行为
lru	达到容量高水位后，按最近访问时间为远端安全的版本排队，直到计划使用量降至低水位。
after_upload	存储桶要求的最低耐久副本提交后，为该版本排队清理。
none	不创建或执行自动缓存淘汰任务。

存储桶创建时最低耐久副本数等于其目标副本数，因此只有该次上传的全部副本都已存储后才释放缓存。在仪表盘中，到该存储桶的 Settings → Replica policy 设置。运维人员可以设置 1 到当前目标之间的显式数量；目标随后提高时该数字保持不变。Replicas 本身只能调高：不支持调低，界面上更小的选项会显示但不可选。降低门槛只会让仍保留的缓存有资格被删除，其余副本会继续补齐。是否真正删除仍取决于 after_upload、lru 或 none。该门槛不会超过单次上传的目标副本数。提高门槛只影响尚未删除的缓存，无法恢复已经删除的缓存。

只有当前满足最低耐久副本数且存在可读已提交远端副本的版本才可淘汰。系统会在授权删除前再次检查当前门槛，并等待同一版本正在进行的读取关闭。清理是异步流程，因此清理追赶不及时或没有安全候选时，写入仍可能返回 507 Insufficient Storage。

分段上传

分段上传会把各分段保存在本地，直到完成上传。完成时会校验请求中的分段、组装最终对象、返回 S3 multipart ETag，并安排后台 Filecoin 存储。

运维影响

条件	含义
缓存磁盘已满	新写入可能在进入 Filecoin 存储前失败。
后台存储未运行	已确认写入仍在本地，但远端存储不会推进。
缓存对象已淘汰	如果远端元数据存在且对象可取回，读取仍可成功。
LRU 没有安全候选	不安全或仍在处理的数据会继续保留，新写入仍可能因空间不足失败。
数据库提交失败	S3 写入不会返回成功。

容量和恢复步骤见运行数据和故障排查。