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 Notes

GitHub 地址

https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.2

Highlights

缓存一致性加固：用户缓存和 Token 缓存引入 Redis generation fence，DB 回填必须匹配当前版本；删除、禁用、额度变更和 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 参数兼容。

Improvements

tiered 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 Notes

v1.0.5-preview.2 会新增或更新 quota_data 相关结构，包括 aggregate_key、snapshot marker、retry marker 和操作锁表；SQLite、MySQL、PostgreSQL 均应走项目迁移流程。
历史 quota_data.aggregate_key 整理默认不会自动执行。需要整理旧大表时，请在低峰期、单主节点下显式设置 QUOTA_DATA_AGGREGATE_MIGRATION_ENABLED=true，并预留迁移时间。
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)" -count=1，覆盖关键路由/聚合桶、账号登录桶、公共状态桶、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_tokens=50638 后，通用 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