# Eddy 摄取容量、限速和正文去重 ## 范围与默认值 单次请求的512 KiB/64事件(对话)、128 KiB/100事件(使用行为)限制继续保留。 新增服务端配额,不接受客户端传入配额或身份。SSO完整邮箱派生SHA256预算标识,同一用户所有设备共用额度;该标识只用于预算,不进入产品指标响应。 使用行为 schema 2 允许不带凭据上传(只收正式环境、一批只能来自一台设备)。**所有未登录上传共用一份额度**(预算标识固定为 `anonymous` 的 SHA256),不按客户端声明的设备标识分:设备标识可以随便填,按它分额度会让每个请求都换一份新额度、新增一行预算记录,进而把全局额度耗尽。这份共用额度单独可配(`EDDY_USAGE_ANONYMOUS_BYTES/_ROWS/_DAILY_BYTES/_DAILY_ROWS/_RPM/_BURST`,默认 1 GiB / 400 万行 / 每天 64 MiB、40 万行 / 每分钟 300 批、突发 16 批),累计和速率都不超过全局的一半,登录用户的上传始终有余量。设备标识只用于统计;未登录的数据是客户端自报的,看板把它单独标为「未登录」。 | 项目 | 对话默认 | 使用行为默认 | | --- | --- | --- | | 账号每日新增逻辑字节 | 256 MiB | 16 MiB | | 账号每日新增行数 | 250,000 | 100,000 | | 账号累计逻辑字节 | 2 GiB | 256 MiB | | 账号累计行数 | 2,000,000 | 1,000,000 | | 全局累计行数 | 10,000,000 | 10,000,000 | | 账号速率 / 突发 | 60批/分钟 / 8批 | 同左 | | 全局速率 / 突发 | 600批/分钟 / 32批 | 同左 | | 原始记录保留 | 接收后90天 | 接收后90天 | `EDDY_CONVERSATION_GLOBAL_BYTES` 和 `EDDY_USAGE_GLOBAL_BYTES` **必须显式配置正整数**。未配置、为0或非法时,摄取503拒绝,绝不默认为无限。`.env.example` 中的全局数字只是语法示例,须先由部署人员核对DB可用容量、索引/WAL/副本余量并填写预算。代码未查询生产磁盘余量,未实现物理磁盘水位自动熔断,不能把逻辑字节预算当数据库物理磁盘上限。 配置前缀为 `EDDY_CONVERSATION_` / `EDDY_USAGE_`;其余后缀见 `.env.example`。额度按UTC天计算。修改配置、重启生效,不需改schema;降低至已有用量之下只会暂停新增,不删除旧数据。保留期可由 `EDDY_CONVERSATION_RETENTION_DAYS` 调整。 ## 去重和兼容 `eddy_conversation_records` 只保存一次正文,键为SHA256(完整SSO用户、设备、来源、事件id)。不跨用户合并,不按文本值去重;同样文字出现在两个不同事件里仍完整保留。 原 `eddy_conversation_events` 保留每个任务的轻量索引、sequence、标题和来源,正文改为record_id引用。维持现有逐任务分页、不同设备隔离及任务/来源列表;**任务索引仍按事件存在,去重降低正文空间,不承诺降低总行数**。配额同时计入规范化UTF-8正文和任务元数据、两张表的新增行数。PG行头、索引、WAL、副本、物理膨胀不计入逻辑字节。 新客户端可在schema1请求里附带至多32个`tasks`,只发一份事件。服务端事务生成所有任务索引,返回`taskIds`;客户端核对全部关联后才推进游标。旧客户端单任务请求仍可用并在服务端去重;旧服务器无多任务回执时,新客户端回退逐任务请求,不推进未确认的任务游标;每小时重新探测能力。来源/文件/游标不同的任务保持分别上传。 ## 并发、拒绝和清理 PG共享令牌桶在独立短事务中扣请求额度,失败的写请求也消耗请求次数。每个通道使用跨进程try advisory lock,最多一个写事务,繁忙返回429;有500ms锁等待和SQL超时,避免大量摄取请求长时间占满连接池。 存储事务先查询已有事件/任务索引,在同一事务中检查并占用全局/账号累计与每日额度,再批量写入正文及索引。拒绝在大正文写入前发生,整批无部分成功;重试仅确认已有记录,不重复扣存储额度。成功响应的`accepted`包含幂等重复记录。 拒绝提供安全错误码和`Retry-After`:`eddy_rate_limited`、`eddy_daily_quota`、`eddy_storage_quota`、`eddy_ingestion_unconfigured`。客户端不推进游标,遵循提示并指数退避/随机延迟;设置显示额度暂停,原始日志不删除。产品使用本地队列仍最多7天/1000条,长时间暂停后超期数据可能被淘汰。 每小时按最多5000条清理过期任务索引/无引用的旧正文,使用同一通道锁,删除与累计额度回收同事务;不退还每日新增额度。清理繁忙或失败延后,不阻塞正常本地使用。计时按接收时间,客户端从头重传的旧日志可能重新进入保留窗口,仍受所有配额约束。预算账本每个用户仅一行,没有无限增长的每日明细表。 ## 部署、观察和回滚 本改动包含`0067_eddy_ingestion_budgets.sql`,**迁移、服务更新必须安排一次摄取维护窗口**:停止旧控制面写入,使用正常部署迁移流程原子执行迁移,再启动新控制面。不要让旧版写入器跨迁移继续写,以免旧写入不计预算。迁移将既有正文去重、保留原任务索引和分页sequence,并初始化累计用量;每日用量从新版本接收时开始累计。既有使用事件没有SSO预算归属,迁移只计入全局预算,不猜用户归属。 全局字节预算未配置时,新版仍能读历史,所有摄取等待配置;建议先配置小范围灰度预算核对监控,再恢复客户端开关。只通过迁移和部署流程发布,开发机不得执行生产DDL。 管理员可用`GET /api/eddy/admin/ingestion`查看两个通道的全局用量、行数、配置和是否就绪;普通用户/API key/客户端会话不授予管理员访问权。接口不返回账号标识或聊天正文。 回滚:先停止摄取和新服务,通过部署迁移工具恢复旧列正文: ```sql UPDATE eddy_conversation_events e SET event = r.event FROM eddy_conversation_records r WHERE r.id = e.record_id AND e.event IS NULL; ``` 恢复后才启动旧二进制,暂不删新表/索引;旧版本没有预算保护,保持客户端上传关闭。再次升级需要重新核算预算,不直接复用回滚期间的账本。