项目 Redis API

根路径为 /projects/:projectId/redis。只接受用户 JWT。所有响应为裸 DTO，错误为 { "error": "稳定错误码" }。项目 read 可查询，write 可操作，修改缓存额度另外需要 admin。服务端构造环境和物理 key，客户端仅传相对 key 或本项目资源 ID。

方法与相对路径	请求或行为
GET /	快照：权限、缓存额度、主题、订阅、预算、运行策略和限制
GET /cache	search、prefix、cursor、limit 查询参数，分页最多 100
PUT /cache	{key,type:"json"或"string",value:string,ttlSeconds?:正整数,createOnly?:boolean}，省略 ttlSeconds 为 24 小时；null（已取消的「永不过期」）返回 400 cache_no_expiry_unsupported；新增传 true 原子拒绝已有 key
DELETE /cache?key=...	删除指定相对 key
PUT /settings	单独传 cacheQuotaBytes 或 deliveryPaused，不能同时传两者
POST /topics	{name,description}
DELETE /topics/:topicId	删除主题全部消息、订阅与回执
GET /topics/:topicId/messages	cursor、limit 分页
POST /topics/:topicId/messages	{producerId,clientEventId,payload:JSON对象}
POST /topics/:topicId/trim	{}，裁剪全部消费者终态消息
POST /subscriptions	{topicId,name}
PATCH /subscriptions/:subscriptionId	{status:"online"或"paused"}
DELETE /subscriptions/:subscriptionId	删除消费者、group 与回执
GET /subscriptions/:subscriptionId/receipts	cursor、limit 分页，不返回可用领取 token
POST /subscriptions/:subscriptionId/claim	{count:1..20}，返回 message、receipt、token、leaseUntil
POST /subscriptions/:subscriptionId/receipts	{messageId,token,status:"processed"或"failed",result:string}

缓存相对 key 为 1..256 UTF-8 字节且无控制字符；TTL 为 1..2592000 秒，省略使用 86400 秒。null 返回 400 cache_no_expiry_unsupported（不再支持永不过期，也不会被静默改成 24 小时）；0、负数、小数、非有限或越界值返回 400 invalid_cache_ttl，均在写入前拒绝。更新只重设当前条目的期限，查询不续期；Redis 可以在到期前淘汰缓存。缓存单项不能超过项目额度，整个 JSON 请求体上限为 16 MiB + 64 KiB，转义字符同样计入请求体。缓存分页 cursor 为服务端返回的写序号；消息与回执分页 cursor 原样传回，不自行构造。

值与物理过期期限在一个 Lua 脚本内写入，期限命令权限不足或 OOM 返回 503。

GET /cache 的条目 expiresAt 恒为毫秒时间戳。升级前以「永不过期」保存的历史条目额外带 legacyNoExpiry:true，其 expiresAt 为升级后首次读到时缓存容器的物理回收时间（容器缺物理 TTL 时为查询时刻起 30 天，随查询推移，并带 legacyDeadlinePending:true，直到下一次 PUT 按写入时刻起 30 天固化）；项目内下一次 PUT 会把该时间固化进元数据，之后不随其他写入顺延，到期后与普通条目一样清理。覆盖该 key 后成为普通条目。

发布 24 小时内同身份同规范化正文幂等，正文冲突返回 409。客户端结果未知时保留同身份同正文重试。领取租约 60 秒，过期 token 立即拒绝；确认同 token 同结果幂等，不同结果冲突。暂停不使有效租约失效。

消息最多 16 KiB，结果最多 256 字节，每回执预留 4096 字节支持最多 10 次尝试。项目可靠预算 2 MiB，平台模块预算 64 MiB。当前可靠 key 的物理 TTL 迁移尚未完成，需先建立 durable 恢复和缓存隔离；本次默认 24 小时仅作用于缓存 PUT，不宣称所有 Redis 写入已满足有限 TTL。消息不使用 MAXLEN 自动裁剪；裁剪或删除释放预算，未到期去重占用直到 24 小时到期清理。

HTTP 400 表示参数错误，401 表示没有有效认证，403 表示非用户会话或项目权限不足，404 表示项目/资源不存在，409 表示状态冲突或业务限额，503 表示 Redis 不可用、OOM、数据状态异常或不安全淘汰策略。请求体超过上限返回 413。不会返回原始 Redis 连接错误。

当前支持 noeviction 与 volatile-lru/lfu/random/ttl，拒绝 allkeys 和未知策略写入。内存使用比例不是禁写门槛，满容量实例仍可通过淘汰带 TTL 缓存接收新数据。可靠恢复仍依赖 Redis 数据保留，不能将它等同全库灾备。