codex-proxy-rs/release/notes.md

v3.21.0

新增

• OpenAI 账号亲和支持宽松和严格两种模式：默认宽松，允许子代理按模型权限、可用性和容量独立分流；严格模式保持同一会话共用账号
• 设置中可调整账号绑定保留时长和单请求最大换号次数，默认分别为 24 小时和 3 次，保存后对新请求生效
• 管理员使用管理页面时自动续期登录会话，并发请求共用会话恢复结果，临时网络或服务故障不再直接清除登录状态
• Codex Desktop 客户端画像支持填写系统版本，并在预览中展示实际出站值

修复与改进

• 错误排查保留本地原因链、上游错误正文和附属清理失败，避免重试与错误包装丢失底层原因；诊断导出保留受控的失败分类
• 日志与请求观测使用有界非阻塞写入，并为失败记录预留容量，减少日志拥堵对请求的影响；文件日志写入缺口通过健康状态报告
• 统一首 token 耗时与请求总耗时的计时基准，减少请求副本驻留并优化 XZ 缓冲分配
• 修复账号订阅名称过长时的布局溢出
• 收敛后端设置、观测及共享业务模型的重复声明和校验，明确管理模型、请求策略与存储转换的职责

升级事项

• 从正式版 v3.20.0 升级时自动应用 0023_error_details_and_account_affinity.sql，保留已有错误文本和运行设置，并补齐新增设置默认值
• 默认账号亲和改为宽松；需要继续让子代理跟随根会话账号的实例，应在设置中选择严格模式
• 管理员原有 admin.session_ttl_minutes 配置继续作为不活动期限；新增 admin.session_absolute_ttl_minutes，省略时为 30 天。配置模板的不活动期限为 7 天，已有配置不会被自动改写；旧会话重新登录后应用续期策略，密钥身份仍使用固定有效期
• 自行调用管理 API 的客户端需将运维错误字段 rawUpstreamError 改为 errorDetails；整体保存运行设置时需包含 openaiAccountAffinity、openaiSessionAffinityTtlHours 和 maxAccountRotations。诊断快照的 schemaVersion 升为 2，管理端导出诊断包升为 3
• 已在源码部署中执行原 0023_error_details.sql、0024_account_affinity.sql 或 0025_session_affinity_ttl.sql 的数据库，与合并后的迁移历史不兼容，不适用上述直接升级路径；不要修改迁移校验和绕过检查