MAX-API v1.0.5-preview.2：安全加固、计费一致性与限流隔离

[!WARNING]v1.0.5-preview.2为预览版本重点是安全、计费一致性、缓存一致性、限流策略和管理端细节修复。升级前建议先在测试环境验证 OAuth 登录/绑定、系统访问令牌生成、用户/Token 缓存、BillingSession、quota_data 看板刷盘、登录/关键接口限流和渠道编辑器。[!NOTE]本稿只描述v1.0.5-preview.1之后需要对外说明的变化。v1.0.5-preview.1已经覆盖的 Playground 参数、DoubaoVideo/Seedance 差额结算、系统实例面板基础能力等内容不在这里重复已有的 tiered pricing 表达式变量和可视化编辑能力也只按本轮安全/结构优化描述。Release NotesGitHub 地址https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.2Highlights缓存一致性加固用户缓存和 Token 缓存引入 Redis generation fenceDB 回填必须匹配当前版本删除、禁用、额度变更和 Token 删除后的缓存失效增加有限重试降低旧缓存继续授权或旧额度继续命中的风险。计费与看板一致性修复BillingSession 对资金差额、Token 调整失败和部分补偿状态做更明确建模quota_data 刷盘改为快照化、幂等聚合和失败重试减少异常退出、重放或并发刷盘导致的重复/丢失。限流策略隔离与可观察性增强全局 API、SPA 回退页、公共状态接口、关键操作和账号登录使用更明确的独立策略Redis 限流改为原子滚动窗口429 响应补齐重试信息Redis 异常时采用有界超时、记录错误并放行请求避免限流依赖故障放大为站点 500。账号与 OAuth 安全收口OAuth 身份写入增加串行化和长度约束身份占用查询错误会被显式处理OAuth 回调只允许站内 redirect绑定回调不再只依赖window.opener判断。系统访问令牌路径防回归access-token-only 更新从通用 OAuth 身份锁路径中剥离普通用户资料更新也不会再从旧快照回写access_token避免生成后的系统访问令牌被并发资料更新覆盖。管理端可用性修正渠道编辑器、模型映射、Pricing 侧边筛选、系统实例清理、移动端表格和状态徽章继续修复长内容、状态同步和错误提示细节。New Features新增QUOTA_DATA_AGGREGATE_MIGRATION_ENABLED环境开关默认不自动整理历史大表需要时可在低峰期单主节点手动开启。新增 Turnstile token header 传递方式前端默认发送X-Turnstile-Token后端保留 query 参数兼容。Improvementstiered pricing 表达式编译缓存从整表清空改为有序淘汰避免达到缓存上限时丢弃所有已编译表达式。tiered pricing 的header()/param()改为正向白名单只暴露定价所需的 provider feature header 和少量 request metadata path避免表达式读取 prompt、工具定义、凭据或任意 payload。tiered pricing 前端编辑器拆分为主编辑器、可视化阶梯编辑器和请求规则编辑器降低单文件复杂度并补充运行时测试。BillingSession 结算失败后会区分已确认资金差额、部分补偿残差和补偿结果不明后续重试不会盲目重复非幂等资金操作。quota_data 启动迁移增加操作锁、心跳和释放重试历史聚合键整理默认跳过并写入明确日志避免多节点启动时抢跑重活。用户状态、角色、分组、设置、签到和 Token 额度等缓存相关路径统一向版本化失效模型收敛Redis 短暂异常时保留可恢复窗口。全局 API、SPA HTML 回退、/api/status//api/setup、关键操作聚合、关键路由和密码登录限流拆分独立策略登录桶按规范化账号哈希减少共享出口 IP 下不同账号相互挤占登录额度。Redis 限流改为 Lua 有序集合实现的原子滚动窗口内存与 Redis 路径统一返回Retry-After、X-RateLimit-*和结构化rate_limit_exceeded错误前端查询不会再自动重试 429。Redis 限流调用增加 500ms 有界超时和明确错误日志Redis 不可用或返回异常时限流故障开放避免缓存故障阻断正常请求。OAuth provider 身份占用判断和绑定/注册错误处理更严格数据库错误不会被当作“未占用”继续放行。登录、注册、邮箱验证和密码重置的 Turnstile 传参方式统一后端 JSON 解析继续走项目common.DecodeJson包装。渠道编辑器拆分状态逻辑渠道测试结果会更稳定地回写列表缓存模型映射预检会拒绝非字符串目标模型。Pricing 侧边栏、AUTO_GROUP/auto route 展示、渠道能力矩阵和长标签展示继续细化减少管理员误读配置状态。系统实例批量清理流程改为统一 mutation/hook 和 query key 失效批量操作期间会禁用刷新和单实例删除减少重复提交。DataTable、移动端卡片列表、StatusBadge 和表格 skeleton 支持更精细的 header/cell/mobile class长模型名或长标签不再轻易撑破布局。Footer 自定义 HTML 改用统一 HtmlContent 渲染OAuth、支付和公共外链打开时补齐noopener,noreferrer。handleServerError在生产环境只展示安全业务信息调试详情限制在开发环境输出。Bug Fixes修复 access-token-only 用户更新可能被新增 OAuth 身份锁阻塞的问题避免系统访问令牌生成受到邮箱/OAuth 身份写锁释放异常影响。修复普通用户资料更新会从旧快照默认复制access_token从而覆盖并发生成的新系统访问令牌的问题。修复用户资料更新可能把旧的 quota、used_quota、request_count 等账务字段写回数据库的问题。修复用户/Token 缓存缺少版本栅栏时删除或失效后的旧 DB 快照仍可能异步回填 Redis 的问题。修复用户删除后缓存清理失败可能中断后续 Token 缓存失效的问题。修复用户状态/角色等管理操作只记录缓存失效失败、没有重试窗口的问题。修复 BillingSession 在资金结算成功但 Token 调整失败后可能留下资金、Token 和日志状态不一致的问题。修复 BillingSession 部分补偿返回残差或结果不明确时后续自动重试可能重复执行资金补偿的问题。修复 quota dashboard 缓存刷盘失败静默丢失、重放同一快照可能重复累计、旧数据缺少聚合键时无法安全创建唯一索引的问题。修复静态资源请求消耗全局 Web 限流额度、公共状态接口与普通 API 共用同一桶、关键操作只使用单一聚合桶以及 Redis 限流多命令并发竞态可能造成额度判断不准确的问题。修复 Redis 限流异常直接返回 500 或长时间阻塞请求、429 响应缺少可操作重试信息的问题。修复 OAuth 回调redirect可携带外部 URL、协议相对 URL 或非法路径导致跳转不受控的问题。修复 OAuth 绑定页在noopener或浏览器限制下可能被误判为登录回调的问题。修复 Turnstile token 混用 body/query 导致前后端保护接口口径不一致的问题。修复渠道模型映射预检忽略非字符串 target 的问题。修复长模型名、长渠道标签、多语言状态徽章和移动端表格内容在窄屏下溢出的问题。修复 OpenAI Responses/audio、Claude cache creation、Gemini thought/candidate/modality token、MiniMax TTS 和部分任务 usage 解析边界降低实际计费与日志展示不一致风险。Compatibility Notesv1.0.5-preview.2会新增或更新quota_data相关结构包括aggregate_key、snapshot marker、retry marker 和操作锁表SQLite、MySQL、PostgreSQL 均应走项目迁移流程。历史quota_data.aggregate_key整理默认不会自动执行。需要整理旧大表时请在低峰期、单主节点下显式设置QUOTA_DATA_AGGREGATE_MIGRATION_ENABLEDtrue并预留迁移时间。Redis 用户/Token 缓存会新增 generation key升级后旧缓存可自然过期新读写路径会逐步按版本化规则刷新。Token 缓存重试队列是进程内有限重试不是跨进程持久队列进程退出后未完成的缓存重试不会自动恢复。tiered pricing 的header()/param()读取范围比 preview.1 更严格若已有表达式依赖非白名单 header/path需要改成受支持的定价 metadata。X-Turnstile-Token是新的前端默认传递方式后端仍保留?turnstile查询参数兼容旧调用方。OAuth 回调redirect现在只能是站内相对路径外部 URL、//host和非法路径会回退到/dashboard。新增CRITICAL_ROUTE_RATE_LIMIT、CRITICAL_ROUTE_RATE_LIMIT_DURATION、LOGIN_RATE_LIMIT_ENABLE、LOGIN_RATE_LIMIT和LOGIN_RATE_LIMIT_DURATION环境变量默认分别为每路由 20 次/1200 秒、每账号 10 次/900 秒。关键路由桶仍受CRITICAL_RATE_LIMIT_ENABLE总开关控制账号桶只用于密码登录并可独立关闭。GLOBAL_WEB_RATE_LIMIT现在只统计 SPA HTML 回退请求不再统计已命中的静态资源GET /api/status和GET /api/setup使用独立的公共状态桶但仍沿用GLOBAL_API_RATE_LIMIT及其 duration 配置。Redis 限流 key 和存储结构已切换为按 policy 区分的有序集合升级时旧计数不会延续到新桶并会按原 TTL 自然过期。Redis 限流故障现在会记录日志并放行请求对安全边界要求更高的部署应同时监控 Redis 可用性和对应错误日志。429 响应现在返回结构化 JSON 及Retry-After、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、X-RateLimit-Policy自定义客户端应优先遵循Retry-After不要立即重试。发布前仍需要先执行cd web/default bun run build生成前端产物再重启 Go 进程直接go run main.go不会自动重建嵌入资源。Verification后端建议执行go test ./...、go vet ./...、go run ./tools/jsonwrapcheck。系统访问令牌生成入口新增锁隔离回归测试验证该路径不会重新等待 OAuth 身份写锁。限流定向测试通过go test ./middleware -run Test(CriticalRateLimit|LoginRateLimit|RateLimitResponse|BootstrapStatus|RedisRateLimit) -count1覆盖关键路由/聚合桶、账号登录桶、公共状态桶、429 元数据、Redis 原子并发和故障开放。定向后端验证应覆盖Redis versioned hash、user cache、token cache、用户字段更新、access token 并发更新、BillingSession、tiered settle、quota_data snapshot/aggregate migration、OAuth lookup、Turnstile header。前端建议执行cd web/default bun run typecheck、bun run i18n:sync并对渠道编辑、Pricing、System Info、safe redirect、handle-server-error、StatusBadge 和 DataTable 相关文件做 ESLint / Prettier 定向检查。前端定向测试应覆盖channel editor state/actions、model mapping guardrail、pricing sidebar、tiered pricing runtime、safe redirect、handle-server-error、status badge 和系统实例批量清理。Seedance Fast 端到端验证通过上游完成响应返回usage.total_tokens50638后通用media.task轮询链路能够进入 token 重算并在测试费率下从预扣 ¥8.325000 调整为 ¥1.686244、退款 ¥6.638756。发布草稿写入后应使用 UTF-8 直接读回检查标题、链接、关键字和乱码.tmp文件为 gitignored不依赖git status/git diff验收。变更空白检查建议执行git diff --check。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.5-preview.1…v1.0.5-preview.2