cache aside基础路径为先更新数据库再删除缓存，适用于读多写少场景；为应对主从延迟引入延迟双删（同步等待100ms或异步kafka消息二次删除）；更新失败时通过告警、重试、降级三级补偿保障一致性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
先更新数据库，再删除缓存（Cache Aside 基础路径）
这是 Codex 服务端最常采用的一致性策略，适用于用户资料、组织配置、模型参数等读多写少场景。
第一步：执行 UPDATE users SET avatar = '/uploads/123.png', updated_at = NOW() WHERE id = 123；【必须确保这一步成功提交，否则后续所有操作都失去意义】
第二步：立即执行 DEL user:123 删除 Redis 中对应用户缓存键；若使用 Codex 自研缓存层，则调用 cache.Invalidate("user", 123)。
第三步：后续首个读请求命中缓存失败，自动触发从数据库加载最新数据并重建缓存——这个“懒加载”过程天然规避了并发写缓存的覆盖风险。
延迟双删：应对主从延迟导致的脏读
当 Codex 后端连接的是 MySQL 主从集群，且从库同步存在毫秒级延迟时，基础 Cache Aside 可能漏掉一次脏数据写入。此时需在首次删除后加一道保险。
方法一：同步双删
首次删除缓存 → 更新数据库 → 等待 100ms → 再次删除缓存。Codex 桌面版 SDK 的 codex sync --force-refresh 命令底层即走此逻辑。
方法二：异步消息兜底
数据库更新成功后，向 Kafka 发送一条 cache_invalidate:user:123 消息；独立消费者服务监听该主题，1 秒后执行二次删除。该方式不阻塞主流程，但需确保消息至少投递一次。
注意：延迟时间不能设为 0，也不能超过从库最大延迟阈值；Codex 默认取 150ms，可通过环境变量 CACHE_INVALIDATE_DELAY_MS=200 覆盖。
更新失败时的补偿机制
数据库更新成功但缓存删除失败，是线上高频故障点。Codex 不依赖事务回滚，而是启用三级补偿：
通过 Codex CLI 生成图片，支持尺寸控制和批量模式。依赖：codex (npm)。代理默认启用。用 generate.sh 生成单张，batch_generate.sh 批量生成游戏 UI 素材，gen_size.sh 指定尺寸。所有输出保存至 ~/.codex/generated_images/。
① 第一时间记录告警日志，包含用户 ID、操作类型、失败键名、Redis 连接状态；
② 启动后台重试任务，对失败键执行最多 3 次删除，间隔为 1s→3s→10s；
③ 若三次均失败，则触发降级开关：codex cache disable --scope=user:123，强制后续读请求跳过缓存直连数据库，避免脏数据扩散。
这一步不需要人工干预，Codex v2.4.7+ 版本已将该逻辑内建于 UpdateUserAvatarHandler 中。
桌面版本地缓存与远端数据库对齐
Codex 桌面版启动时报「无法加载组织设置」，90% 是本地 config.toml 与服务端数据库结构不匹配，而非网络问题。
打开终端，进入 Codex 安装目录，执行：codex doctor --check-config；它会校验 config.toml 字段是否被新版本废弃，比如旧版允许 org_id 字段为空，新版要求非空且格式为 UUID。
若校验失败，运行：codex config migrate ——该命令会自动备份原 config.toml 为 config.toml.bak，并按当前版本规则重写字段。
最后清空本地运行时缓存：rm -rf ~/.codex/cache/org*（macOS/Linux）或 del /q "%LOCALAPPDATA%\Codex\Cache\org*"（Windows）；【务必先执行 migrate 再清缓存，顺序颠倒会导致启动时解析空配置崩溃】
