NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules
Go modules, #2969 by repository stars
Latest stable
v1.0.5
Last release 3 months ago
23 Aug 2026
Ships on a steady schedule
a new release about every 1 weeks
Nearly every release is documented
notes for 6 of 6 stable releases
Nothing withdrawn
no release was ever pulled
5 months old
24 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
> v1.0.5 是一次围绕路由能力、计费可靠性、安全边界和渠道兼容性的正式更新。版本整合了 v1.0.5-preview.1 至 v1.0.5-preview.4 的主要成果,并将预览阶段的零散改动归并为面向用户的功能与稳定性说明。
[!IMPORTANT] v1.0.5 是一次围绕路由能力、计费可靠性、安全边界和渠道兼容性的正式更新。版本整合了 v1.0.5-preview.1 至 v1.0.5-preview.4 的主要成果,并将预览阶段的零散改动归并为面向用户的功能与稳定性说明。
本版本包含数据库结构变更。生产升级前请备份主库与日志库,确认数据库账号具备 AutoMigrate 所需权限,并在同版本数据副本或测试环境完成迁移与核心计费流程验证。前端资源也必须重新构建后再重启服务。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5
POST /v1/alpha/search,支持 Codex 与 Advanced Custom 直通渠道,并纳入模型映射、Param Override、渠道选择和 Web Search 计费。thinking_budget,完善 OpenAI Realtime、Alpha Search、状态码映射及多家渠道显式 0 / false 参数转发。group 配置。/v1/alpha/search 中继能力,以及 /health、/health/live、/health/ready 编排探针。enable_thinking 与 thinking_budget,并保留显式零值。0、空字符串或 false 的问题。group 和 cross_group_retry 生成兼容策略;新客户端建议优先使用 routing 字段。POST /api/oauth/state,并要求携带 provider 与 intent;删号接口现在要求 account_delete 二次验证,旧 Midjourney 裸图片地址不再可用。tiered_expr 的 header() / param() 读取范围进一步收紧;Midjourney、Suno 和换脸任务不再使用未配置价格的隐式兜底,升级前应复核表达式、任务费率和 Alpha Search 工具价格。TRUSTED_PROXIES、SSRF、防护抓取、PassThrough 字段权限、视频 data URL 和上游响应头转发采用更严格的失败关闭规则;非标准代理或自定义渠道需要复核配置。web/default 执行 bun install 与 bun run build,再重启 Go 服务;直接复用旧 dist 不会包含新的路由编辑、Alpha Search 样例和前端修复。go vet、JSON wrapper 检查及计费、认证、路由、支付、任务和数据库兼容性定向回归。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4...v1.0.5
Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
Nothing published for this version
> v1.0.5-preview.4 为预览版本,新增 Token 路由策略存储、API Key 路由编辑、OpenAI Alpha Search 中继和健康检查端点,并继续收紧支付回调、Midjourney 异步账务、渠道更新、日志持久化、认证会话和上游 HTTP 边界。升级前请确认生产环境会执行
[!WARNING]
v1.0.5-preview.4为预览版本,新增 Token 路由策略存储、API Key 路由编辑、OpenAI Alpha Search 中继和健康检查端点,并继续收紧支付回调、Midjourney 异步账务、渠道更新、日志持久化、认证会话和上游 HTTP 边界。升级前请确认生产环境会执行项目 AutoMigrate、重新构建管理端资源,并在测试环境验证自动路线、手工分组顺序、跨分组重试、旧 Token 兼容、Alpha Search 渠道与价格配置、支付金额与币种、Midjourney 提交/失败/回调、渠道多密钥更新以及代理和响应头策略。新版本会在tokens表增加routing_policy文本字段,创建midjourney_billing_claims账务归属表和auth_flows一次性认证流程表;既有 Token 不要求立即回填。
TRUSTED_PROXIES、定价 JSON、视频 data URL、OAuth discovery 抓取和上游响应头转发均增加更严格的失败关闭规则。依赖全网可信代理、环境代理访问私网 discovery、超大定价配置、非视频 data URL,或直接透传上游Set-Cookie/ hop-by-hop header 的部署需要在升级前调整配置与集成。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.4
Token 路由从单一分组投影升级为可持久化策略:每个 Token 可以选择系统定义的自动路线,或配置最多 8 个有序手工分组,并独立控制失败后的跨分组重试。
认证、渠道选择和模型目录使用同一份路由计划:请求进入运行时后,路由策略会被规范化为有序分组计划,普通中继、Affinity 选择、重试和 /v1/models 返回不再各自推导分组。
管理端 API Key 支持可视化路由编辑:可以查看自动路线包含的分组、切换到手工模式,通过拖拽、方向键或按钮调整分组顺序,并配置跨分组重试;已有但当前不可供新选择的路由会被标记并保留。 <div align="center"> 功能示例(由参与内测平台提供)<br> <img width="539" height="563" alt="image" src="https://github.com/user-attachments/assets/8ab41b0a-43ec-40ec-bb2c-6b7497b76b95" /> <img width="540" height="767" alt="image" src="https://github.com/user-attachments/assets/3151a6aa-255a-4a00-91ee-93e49358f9a2" /> </div>
渠道更新改为显式字段补丁:更新接口只接受允许修改的配置字段,省略字段会保留原值,余额、累计用量、测试时间和内部多密钥状态等运行时数据不能再通过普通渠道编辑请求覆盖。
旧 Token 不需要迁移即可继续工作:旧的 group 和 cross_group_retry 字段仍作为兼容投影,未携带新路由字段的旧客户端仍可创建和更新 Token。
多分组模型目录与实际选组保持一致:手工路由下来自所有有序分组的可用模型都会返回,并按模型名去重,同时保留优先 owner 信息。
随机选择与安全令牌统一使用系统安全随机源:OAuth state、通用随机 key、渠道权重选择、多密钥随机选择、签到随机奖励和模型同步退避抖动不再依赖 math/rand。
支付回调以订单真值为准:Stripe、Creem、易支付、Waffo 和 Waffo Pancake 的充值/订阅完成路径会在入账前核对支付渠道和金额,并在供应商提供币种时校验币种;不匹配回调不会把订单标记成功或增加额度。
Midjourney 接入持久化异步账务归属:上游任务 ID 按渠道绑定到唯一的本地账务任务,提交重放、重复 provider ID、明确失败退款、未知提交结果和回调/轮询竞争统一进入 CAS 与持久结算流程。
日志和上游 HTTP 边界统一收口:持久日志会清理控制字符、无效 UTF-8 并限制总长度;任务错误不再暴露任意原始上游响应,响应头转发会过滤 cookie、hop-by-hop、畸形值及 Connection 动态声明的字段。
认证与敏感设置使用服务端当前状态:被禁用、删除或降权的用户不能继续依赖旧会话或 Token owner 状态访问;Webhook、Gotify 等通知凭据不会再通过当前用户接口回显,更新时省略凭据会安全保留原值。
OpenAI Alpha Search 成为独立中继能力:新增 POST /v1/alpha/search,支持 Codex 原生路径和 Advanced Custom 直通路线,统一纳入渠道选择、模型映射、Param Override、请求体保留和 Web Search 计费。
健康检查面向编排系统补齐:新增 /health、/health/live 和 /health/ready,readiness 会执行数据库探测,失败时返回 503 和通用错误消息,便于 Kubernetes/负载均衡探针接入。
1 的 Token 路由策略对象,支持 smart 和 manual 两种模式、自动路线 key、手工分组数组及 retry_on_failure 配置。routing 与 routing_legacy 信息;分组接口同时返回可供当前用户选择的 auto_routes,前端可以显示系统定义的路线名称和分组链。openai-alpha-search endpoint 类型、RelayModeAlphaSearch 和 AlphaSearchRequest DTO;请求解析会保留原始 JSON,模型映射后仍把未知字段转发给上游,避免新参数在网关层丢失。/v1/alpha/search 已接入 Relay 路由和渠道测试流程:Codex 渠道走 /backend-api/codex/alpha/search,Advanced Custom 只在配置了同名 incoming route 且 converter 为 none 时参与选择。curl、Python、TypeScript、JavaScript 调用样例;JS/TS 样例会先检查 response.ok,避免错误响应被当作成功 JSON 展示。/health、/health/live、/health/ready,readiness 检查复用数据库连接探测并保持错误消息脱敏。/pg/chat/completions 中显式指定的分组仍优先于 Token 的存储策略。group/cross_group_retry 投影;更新时省略路由字段会保留原有策略,单独提交 cross_group_retry: false 也会作为明确变更生效。UpdateFields 只持久化本次实际变更的配置和多密钥字段。crypto/rand;底层随机源失败时,安全敏感路径返回错误或采取明确降级,不再继续使用可预测伪随机结果。PaymentValidation,金额按最小货币单位精确比较,币种大小写归一化;订单状态迁移、额度增加、订阅激活和缓存失效保持在对应数据库事务或持久失效任务中。NaN / Infinity,结算表达式失败时使用冻结的预扣值与分组后估算值中较高者并记录可观测错误。innerHTML 前再次净化;图表 ID、CSS 变量名和颜色值会过滤样式逃逸、URL、@import 和可执行表达式,降低服务端配置或动态内容触发 XSS/CSS 注入的风险。/v1/alpha/search,Codex 和匹配 incoming route 的 Advanced Custom 才会进入直连与缓存选择路径。QuotaPerUnit 与 CNY USDExchangeRate,查价失败对外统一返回 billing information unavailable,原始错误仅写入服务端日志。common.Marshal / common.Unmarshal / common.DecodeJson,覆盖 DTO value、OpenAI message、Ali、Baidu、Coze、SiliconFlow、Vertex 和 Zhipu;JSON policy allowlist 从 158 条收敛到 121 条。0、空字符串或 false 会保留到上游 payload。/v1/models 只读取第一个 owner group,导致后续分组独有模型不出现在模型目录的问题。cross_group_retry 时请求被当作“未修改路由”的问题,特别是显式关闭重试的 false 值现在不会被零值语义吞掉。group 为空时 API Key 表单保留空手工分组并阻止保存的问题;表单会使用当前可用默认分组,同时限制默认列表不超过 8 项。Channel 模型造成的批量赋值风险;伪造的余额、用量、创建/测试时间、内部状态和 channel_info 不再写入数据库。/api/user/self 回显 Webhook secret、Gotify token 等通知凭据,以及编辑设置时因前端收到脱敏值而清空已有凭据的问题;通知邮箱现在使用标准地址解析校验。Set-Cookie、Transfer-Encoding、CR/LF 注入值和 Connection 声明的临时 header 被转发,以及被动态声明的 request ID 仍被错误捕获的问题。mj_*、suno_* 和 swap_face 任务模型继续使用隐式兜底价格的问题;只有明确模型价格、默认价格或 rate card 可用时才允许继续计费。[DONE] 的问题;Gemini 图片响应超过 OpenAI 兼容上限时也会明确拒绝。GetBody 复用同一个可变 seeker、并发 retry 可能共享 cursor 或发送错误内容的问题;内存和磁盘 body 现在都会为每次重放创建独立 reader。top_p 时仍注入最小值的问题;缺省值保持不发送,仅对显式越界值按 Ali 范围钳制。service_tier、speed 等可能增加成本字段的问题;只有渠道显式允许的受控字段才会保留。GetRandomInt、GetRandomString 和 CPU profile 监控在随机源、CPU 采样、目录或文件错误时终止进程的问题;GenerateRandomKey 改用可返回读取错误的 reader 路径,避免 Go 新版本 crypto/rand.Read 的不可恢复 fatal 行为。stream/历史保存、Baidu 搜索/引用开关及 Ali provider 参数的显式零值被 omitempty 丢弃;相关请求现在区分“未提交”和“明确提交零/false”。custom_id 对空分片、缺失索引、非正索引和未知 *_variation 后缀处理不完整的问题,避免 malformed custom ID 导致 panic 或被错误转换为合法动作。updated_at 字段而导致清理失败的问题。QuotaPerUnit 为 0、负数、NaN、Infinity 或 CNY 汇率无效时可能除零/产生非有限金额的问题;token 展示和 unlimited token 路径保持兼容。tokens 表新增 routing_policy 文本字段,由 GORM AutoMigrate 创建,SQLite、MySQL 和 PostgreSQL 均使用通用文本类型。升级前请确认数据库账号具备迁移权限,并在副本上先演练启动迁移。routing_policy 会根据原 group、用户分组和 cross_group_retry 在运行时合成兼容策略;不会自动把历史 Token 批量改写为新 JSON。旧字段仍保存首个投影分组和重试开关,供旧客户端继续使用。routing。只发送旧 group 时仍按兼容路径处理;更新请求省略 routing 和 group 时会保留当前存储策略。显式提交新策略时,自动路线必须是当前用户可选择的路线,手工模式只能使用真实可用分组,最多 8 个且不能重复。cross_group_retry 现在按可选布尔值处理:省略表示保持现状,显式 false 表示关闭重试。自定义客户端不应再依赖布尔零值等同于“未提交”的旧行为。/api/group 响应新增 auto_routes 字段;自定义客户端应忽略未知响应字段,并继续兼容原有分组字典。Token 详情响应新增路由字段,routing_legacy 可用于区分兼容合成结果和实际存储策略。PUT /api/channel/ 现在是显式允许字段的局部更新:未提交字段保持原值,空白密钥不会清除已有密钥,未知渠道状态会被拒绝,余额、用量、时间戳、内部状态和客户端提交的原始 channel_info 会被忽略。依赖该接口直接改写运行时字段的非标准客户端需要迁移到专用管理流程。@testing-library/react@16.3.2。从源码升级时应在 web/default 使用 Bun 按最新 web/bun.lock 安装依赖,不要复用旧 node_modules。RandomSleep 的抖动会降级为零延迟,而不会切回可预测的伪随机实现。0、空字符串和 false 现在属于有意上游参数。midjourney_billing_claims,以 (channel_id, mj_id) 唯一索引绑定上游任务与本地账务任务。数据库账号需要具备建表和索引权限;历史同名 Midjourney 任务不会自动合并,无法唯一判定时会失败关闭并要求人工复核。TRUSTED_PROXIES 只接受具体 IP 或受限 CIDR;0.0.0.0/0、::/0、可组合覆盖整个地址空间或无效条目会使进程启动失败。未配置时仍只信任默认 loopback,反向代理部署应显式填写真实代理网段。HTTP_PROXY / HTTPS_PROXY,以确保连接目标与已验证 DNS/IP 一致。必须经代理访问的内部 discovery 地址需要通过明确的 SSRF allowlist 和受控网络方案处理,不能依赖环境代理绕过校验。Set-Cookie、hop-by-hop header、畸形名称/值,以及 Connection 中动态列出的字段。依赖这些非端到端 header 的自定义渠道应改用专用响应处理;安全的多值端到端 header 仍会保留。content 与任务失败原因现在最多保留 4096 个 Unicode 字符,换行和制表会规范化为空格,并在截断时追加标记。依赖完整原始上游正文排障的部署应改用受控 debug 日志或外部追踪,不能再从业务日志读取无限正文。ModelRatio 和 CompletionRatio 会按模型匹配规则规范化键并拒绝别名冲突。升级前应检查自动生成的大型配置和只在大小写/后缀上不同的重复键。video/mp4、video/webm、video/quicktime、video/x-matroska,解码后上限为 100 MiB。返回其他媒体类型或超大内联视频的自定义适配器需要改为受控视频 URL 或调整上游输出。auth_flows 表和唯一 token HMAC 索引。OAuth state 接口由 GET /api/oauth/state 改为 POST,请求必须携带 provider 和 intent;自定义前端或客户端需要同步升级,绑定流程还必须携带有效用户会话。service_tier、speed、inference_geo 等能力的渠道必须显式启用对应允许项,并同步确认本地倍率或计费表达式覆盖真实上游价格。cd web/default && bun run build 生成最新资源,再重启 Go 进程;直接使用旧 dist 不会包含本版路由配置入口。/v1/alpha/search 使用新的 openai-alpha-search endpoint 类型。自定义渠道若要承接该路径,需要使用 Codex 渠道类型,或在 Advanced Custom 中配置 incoming_path: /v1/alpha/search、无转换器的直通路线。web/default 构建,直接复用旧静态资源不会显示新的 endpoint 样例。/health/ready 在数据库探测失败时返回 HTTP 503 与通用 "database connection failed" 消息;部署探针应优先使用该 readiness 端点,不应继续依赖管理后台状态接口解析。USDExchangeRate 为正且有限;配置为 0、负数、NaN 或 Infinity 会返回通用账单不可用错误,而不会继续输出不可信金额。1e8e5cf6..06b82459 范围执行的集中门禁结果;本次补充基于当前 09654cc5 干净源码树重新核查 06b82459..09654cc5 的实际差异。go test ./... -count=1 通过,覆盖 Controller、Model、Service、Relay、计费表达式、认证、支付、Midjourney、任务轮询、渠道更新和数据库兼容回归;资源独占时 relay/helper 时间敏感用例连续 3 次通过。go vet ./...、go run ./tools/jsonwrapcheck 和 bun run typecheck 通过;JSON wrapper 检查报告为 121 条 allowlisted direct calls。bun run build:check,包含 tsc -b、Rsbuild 生产构建和 Tailwind 产物校验;构建生成 2 个 CSS 文件并通过 Tailwind 检查。go test ./relay ./service ./model ./controller ./router -run "TestAlphaSearch|TestAlphaSearchSelectionUsesOnlySupportedChannelTypes|TestBuildTestRequestAlphaSearch|TestRelayRouterRegistersAlphaSearch|TestBilling(QuotaDisplayAmount|SubscriptionDisplayAmount)|TestCoverPlusActionToNormalActionRejectsMalformedCustomID|TestHealth|TestGetHealth|TestUserSoftDelete|TestUserHardDelete" -count=1 -p=1,覆盖 Alpha Search、账单展示、Midjourney custom ID、健康检查、路由注册和用户删除清理。bun.cmd test src/features/pricing/components/model-details-api.test.ts:8 项通过、0 项失败,覆盖 Responses Compact 与 Alpha Search 的四种 API 样例。.test 已同步并复核 222 个测试源和 2 个 workflow 文件,当前无镜像漂移。git diff --check 通过,当前可见源码差异没有空白错误。replacement_chars=0、trailing_whitespace=0,并用关键词检查确认 09654cc5、06b82459..09654cc5、Alpha Search、/health/ready、billing information unavailable 和 222 个测试源 均已落入文稿。Connection header 过滤、视频 data URL 限制、受保护抓取禁用环境代理、Turnstile/SMTP 超时及后台 runner 停止。top_p 缺省和边界、OAuth state 生成/绑定/过期/并发消费/重放、OIDC/Generic 私网 endpoint 拒绝和敏感日志、用户级跨 IP 限流,以及 PassThrough 默认过滤和显式允许。full profile 在进入 frontend lint 前的测试、vet、JSON policy 和 typecheck 均通过,随后因全仓既有 81 项 lint 基线问题(75 errors / 6 warnings)停止;production build 已通过单独执行的 bun run build:check。当前 OAuth 前端差异只触及 state API 参数,变更文件中的唯一 lint 命中是 use-oauth-login.ts:50 既有的 set-state-in-effect,该行不在本轮差异内。.tmp/。v1.0.5-preview.3 本地标签仍未检出,下面的 compare URL 按计划发布标签名称生成,正式发布前请确认远端标签与目标提交。CGO_ENABLED=0 且没有 GCC/Clang,Go race detector 也未执行。这些环境级验证仍应在正式发布前完成。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.5-preview.3...v1.0.5-preview.4
Nothing published for this version
> v1.0.5-preview.3 为预览版本,包含计费结算、订阅预扣、异步任务退款、缓存失效、日志幂等以及模型/供应商名称唯一键相关数据库结构变更。升级前请备份主库与日志库,并在测试环境验证钱包/订阅计费、Realtime 长会话、异步任务成功/失败/超时、Redis 故障恢复、渠道状态码映射、
[!WARNING]
v1.0.5-preview.3为预览版本,包含计费结算、订阅预扣、异步任务退款、缓存失效、日志幂等以及模型/供应商名称唯一键相关数据库结构变更。升级前请备份主库与日志库,并在测试环境验证钱包/订阅计费、Realtime 长会话、异步任务成功/失败/超时、Redis 故障恢复、渠道状态码映射、模型元数据迁移和 Midjourney 图片转发。日志幂等使用独立小型 receipt 表,不会在大体量logs表上创建新的唯一索引。
[!NOTE] 本稿只描述
v1.0.5-preview.2之后需要对外说明的变化。preview.2 已覆盖的 generation fence、进程内缓存重试、BillingSession 补偿状态、quota_data 刷盘、OAuth/Turnstile 收口和管理端基础优化不在这里重复;本版仅描述这些机制在持久化恢复、原子结算、Redis 限流降级、渠道协议兼容和具体缺陷修复上的新增增量。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.3
created_at_path 与 updated_at_path 可视化配置,可从不同供应商响应中提取任务创建和更新时间;相关字段已同步到中、英、法、日、俄、越六种前端语言。BillingSettlement 持久化结算记录,operation key 会绑定资金来源、用户、订阅、Token、任务、额度参数和日志副作用;重复调用返回既有结果,参数变化或身份不一致不会再次扣费/退款。BillingPreConsumeSelection,同一 request ID 首次选定钱包或订阅后不可在重试中切换资金来源,避免余额变化或并发回放把一次请求结算到两个来源。last_reset_time,跨重置周期的延迟结算或退款会失败关闭。BillingLogReceipt 表完成幂等声明和日志同事务写入,避免给高容量 logs 表增加唯一索引;receipt 通过随机 claim token 判断本次归属,不依赖 MySQL RowsAffected 的连接参数语义。CacheInvalidationTask;用户资料、OAuth 绑定、用户删除、Token 更新/删除及钱包/订阅结算会在同一数据库事务中登记任务,提交后由持久 runner 执行,成功处理时按 revision 删除,较旧 worker 不会误删更新后的任务。max_tokens / max_completion_tokens 的解析收敛为共享规则,显式 0 在没有旧字段时仍会保留;AWS Nova、Baidu、Ollama、智谱、讯飞和阿里任务适配器也会保留客户端显式传入的 0 / false。null,避免运行时配置被空值意外置空。100..599 源/目标状态码,拒绝 0429 等别名、重复规范化 key、null、非对象和越界值;运行时遇到无效配置会保持原状态码。vendor_extension 等自定义内容。getSelf(),默认 30 秒内复用同一身份的验证结果;身份变化时会等待并重新验证,不应用旧用户的在途响应。openai-beta: realtime=v1 / openai-beta.realtime-v1,*-realtime-preview 模型继续保留旧协议兼容。NaN、Infinity、null 和非对象配置,避免产生负计费或静默写入无效 JSON。name_key 建立活跃名称唯一性;软删除时原子切换为记录专属保留键,使三种数据库都能阻止并发创建同名活跃记录,同时允许删除后重新使用原名称。status: 0 也会按禁用状态保留。DataExportInterval 规范为 1..1440 分钟,避免任意配置落库和零/负间隔触发导出忙循环。ServerAddress 在未显式设置 SESSION_COOKIE_SECURE 时会自动启用 Secure cookie;显式环境变量仍保持最高优先级,纯 HTTP 部署继续兼容并输出风险日志。PreConsumeQuota / ReturnPreConsumedQuota 入口及重复 operation-key 命名空间,避免新代码绕开持久化幂等结算;同时移除需手工同步迁移列表的死代码 migrateDBFast()。status_code_mapping 在编辑抽屉中填入后,保存时被表单转换遗漏,导致更新后内容消失且数据库字段未写入的问题。JsonEditor 首次渲染已有 JSON 时可视行为空、切换“可视化/JSON”模式会回写空值,以及外部 value 更新后表格未同步的问题。created_at_path、updated_at_path 和未知扩展字段的问题。context.Background() 导致客户端断开后仍继续调用上游的问题;无全局 Relay timeout 时也保留显式取消能力。SumUsedToken 使用 MySQL 专用 ifnull(),导致 PostgreSQL 日志统计查询报错的问题;现在使用三种数据库均支持的 COALESCE()。0、false 的问题;同时修复讯飞将 n 错写为 top_k,以及 max_completion_tokens 与 max_tokens 的优先级在渠道间不一致的问题。ChannelInfo 快照可能覆盖较新修改的问题。subscription_plans.price_amount 类型迁移失败只记录日志后继续启动的问题;迁移现在在核心表创建后执行,并向上返回失败。content 时访问 Content[0] 引发 panic 的问题。Header.Code 导致上游业务错误被当作 200 成功的问题;读取、发送和客户端取消现在共享同一事件生命周期。global。Infinity 序列化为 null 后破坏配置。mj_id 查询且无需身份凭据造成的跨用户读取问题;签名校验失败、过期或用户不匹配统一返回 403。account_delete 作用域的短期二次验证。localStorage,以及登出/删号路径仍操作该持久缓存的问题。User.Edit、邮箱/OAuth 绑定清理、GitHub 身份迁移和用户设置更新在数据库提交后才清理缓存,进程中断或 Redis 故障可能长期保留旧身份/分组/设置的问题;outbox 不可写时相关业务事务现在会整体回滚。io.ReadAll 失败路径未关闭上游响应体的问题;Baidu、Zhipu、Cohere 写客户端响应失败现在会记录错误而不再静默丢弃。MultiKeyPollingIndex 的数据竞争,以及故障转移可能反复选中本次请求中已经失败渠道的问题。Content-Disposition,可能破坏 part 头的问题;文件名现在通过标准媒体类型编码安全生成。/v1/models 在可见模型列表为空时读取首尾元素导致 panic 的问题;空列表现在返回 data: [] 和 has_more: false。NULL deleted_at 语义下阻止并发同名创建的问题;同时阻止删除仍被模型引用的供应商,并让模型软删除中的保留键更新与删除动作同事务回滚。status: 0 被当作未提供而回退启用的问题。billing_settlements、billing_pre_consume_selections、billing_log_receipts、cache_invalidation_tasks 四张表;subscription_pre_consume_records 新增 Token 和订阅重置周期绑定字段。SQLite、MySQL、PostgreSQL 部署均需先完成项目 AutoMigrate,生产升级前应在同版本数据副本上演练。models 与 vendors 新增非空 name_key 列和单列唯一索引,并移除原 (name, deleted_at) / (model_name, deleted_at) 联合唯一索引。迁移会保留 ID 最小的同名活跃记录作为名称占用者,其他历史重复记录改写为记录专属保留键;软删除后的名称可重新创建。生产升级前应先检查重复元数据并在三种数据库的同版本副本上演练。subscription_plans.price_amount 会在核心 schema 就绪后迁移为 decimal(10,6);元数据查询或 ALTER TABLE 失败会阻止启动,升级前应先在数据副本演练,不应依赖原先的仅日志告警行为。billing_log_receipts 表,不再修改 logs 表索引;独立日志库同样需要允许 AutoMigrate 创建该 receipt 表。receipt 会随幂等记录长期保留,未建立安全保留期前不要手工删除。request_id;缺少 request ID 时会失败关闭,不再退回非幂等直接扣减。自定义 relay/插件若调用旧 PostConsumeQuota 路径,应确保整个请求生命周期复用同一 ID。100..599 状态码。此前可保存但不规范的 0429、小数、越界值、null 或非对象配置需要先修正。NaN、Infinity、null 或非对象设置在再次保存前需要修正。/mj/image/:id 地址现在返回 403。客户端应重新查询任务并使用带 uid、expires、signature 的 15 分钟签名 URL;不要长期缓存或持久化该临时地址。DELETE /api/user/self 现在要求先完成 account_delete 安全验证。启用 2FA/Passkey 的账号必须使用已配置的强验证方式;未配置时可回退当前密码。自定义客户端需按更新后的 OpenAPI 流程调用。SESSION_COOKIE_SECURE 且 ServerAddress 为有效 HTTPS URL 时,session cookie 现在自动标记 Secure;显式配置仍优先。HTTP 部署不会被强制开启,但会记录明文传输风险提示。*-realtime-preview 模型继续发送 beta header;正式 Realtime 模型改用当前协议。使用自定义模型别名时,应确认别名是否仍包含 -realtime-preview 并与实际上游协议一致。null;自动化配置脚本应发送有效 JSON 值,或省略未修改的字段。DataExportInterval 仅接受 1..1440 的整数分钟值;依赖写入自定义 options 行或零/负导出间隔的自动化脚本需要调整。0、0.0 和 false 转发给相关供应商;此前依赖网关静默省略这些零值以使用供应商默认值的调用方,需要改为省略字段。localStorage.user 恢复登录状态,升级后以 HttpOnly cookie session 为准,并默认每 30 秒重新确认一次;依赖读取该非公开 localStorage 项的自定义脚本需要调整。cd web/default && bun run build 生成最新嵌入资源,再重启 Go 进程;直接运行旧 dist 会缺少状态码映射、视频时间路径和会话校验修复。go test -p 1 ./... -count=1 -timeout=120s;静态检查通过:go vet ./...。串行包执行用于隔离各包共享 SQLite 测试资源,避免测试进程并发争用。go run ./tools/jsonwrapcheck;本轮触及的 AWS/讯飞 JSON 调用已迁移到 common wrapper,其余历史调用仍由既有 allowlist 管理。cd web/default && bun run typecheck、bun run build:check;Rsbuild 与 Tailwind 构建校验通过。bun run lint 仍有本次范围外的 75 个 error 和 6 个 warning,主要是既有 React 19 Hooks 规则债务,因此不列为全量通过项。controller、middleware、model、dto、setting/config、计费/任务费率设置,以及 OpenAI、AWS、Baidu、Cohere、Ollama、PaLM、Ali、Hailuo、Jimeng、讯飞和智谱渠道包均以 -count=1 通过。controller、model、service、relay/helper、OpenAI、Replicate 和 Sora 包测试,覆盖 Stripe webhook 重试/幂等、订阅分组回落、渠道排除与轮询并发、multipart 文件名编码、图片内容识别、Anthropic 空列表、元数据唯一键迁移、供应商引用保护、上游同步错误和 Option 边界。go vet ./... 与 go run ./tools/jsonwrapcheck 通过。.test 已同步 173 个测试源和 2 个 workflow 文件,sync-tests.ps1 -Mode Check 通过。git diff --check 通过,未发现新增尾随空白或补丁格式错误。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.5-preview.2...v1.0.5-preview.3
> v1.0.5-preview.2 为预览版本,重点是安全、计费一致性、缓存一致性、限流策略和管理端细节修复。升级前建议先在测试环境验证 OAuth 登录/绑定、系统访问令牌生成、用户/Token 缓存、BillingSession、quota_data 看板刷盘、登录/关键接口限流和渠道编辑器。
[!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 表达式变量和可视化编辑能力也只按本轮安全/结构优化描述。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.2
window.opener 判断。access_token,避免生成后的系统访问令牌被并发资料更新覆盖。QUOTA_DATA_AGGREGATE_MIGRATION_ENABLED 环境开关,默认不自动整理历史大表,需要时可在低峰期单主节点手动开启。X-Turnstile-Token,后端保留 query 参数兼容。header() / param() 改为正向白名单,只暴露定价所需的 provider feature header 和少量 request metadata path,避免表达式读取 prompt、工具定义、凭据或任意 payload。/api/status / /api/setup、关键操作聚合、关键路由和密码登录限流拆分独立策略;登录桶按规范化账号哈希,减少共享出口 IP 下不同账号相互挤占登录额度。Retry-After、X-RateLimit-* 和结构化 rate_limit_exceeded 错误,前端查询不会再自动重试 429。common.DecodeJson 包装。noopener,noreferrer。handleServerError 在生产环境只展示安全业务信息,调试详情限制在开发环境输出。access_token,从而覆盖并发生成的新系统访问令牌的问题。redirect 可携带外部 URL、协议相对 URL 或非法路径导致跳转不受控的问题。noopener 或浏览器限制下可能被误判为登录回调的问题。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,并预留迁移时间。header() / param() 读取范围比 preview.1 更严格;若已有表达式依赖非白名单 header/path,需要改成受支持的定价 metadata。X-Turnstile-Token 是新的前端默认传递方式;后端仍保留 ?turnstile= 查询参数兼容旧调用方。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 配置。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 不会自动重建嵌入资源。go test ./...、go vet ./...、go run ./tools/jsonwrapcheck。go test ./middleware -run "Test(CriticalRateLimit|LoginRateLimit|RateLimitResponse|BootstrapStatus|RedisRateLimit)" -count=1,覆盖关键路由/聚合桶、账号登录桶、公共状态桶、429 元数据、Redis 原子并发和故障开放。cd web/default && bun run typecheck、bun run i18n:sync,并对渠道编辑、Pricing、System Info、safe redirect、handle-server-error、StatusBadge 和 DataTable 相关文件做 ESLint / Prettier 定向检查。usage.total_tokens=50638 后,通用 media.task 轮询链路能够进入 token 重算,并在测试费率下从预扣 ¥8.325000 调整为 ¥1.686244、退款 ¥6.638756。.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
> v1.0.5-preview.1 为预览版本,建议先在测试环境验证前端构建、渠道配置保存、异步任务轮询和计费日志后再用于生产。
[!WARNING]
v1.0.5-preview.1为预览版本,建议先在测试环境验证前端构建、渠道配置保存、异步任务轮询和计费日志后再用于生产。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.5-preview.1
.gitignore 的裸 home 规则误排除 web/default/src/features/home,导致 Tailwind 未生成首页桌面栅格 CSS、go run main.go 嵌入后宽屏首页仍显示单列的问题。bun run build 与 bun run build:check 直接失败,避免本地构建与 Docker 构建产物出现静默差异。usage.total_tokens 返回实际 token 的任务结果,同时允许运营侧在费率调整或上游结算策略不匹配时关闭差额补退。系统信息 -> 实例 增加删除所有离线实例操作,后端批量接口只清理超过离线判定阈值的实例记录,并返回实际删除数量。Video Task Billing 模块,可在高级设置中开启或关闭 Completion delta settlement。disable_task_delta_settlement 设置项。默认保持完成态差额结算开启;仅当管理员显式关闭时,保存为渠道级关闭配置。系统信息 -> 实例 新增 删除所有离线 按钮和确认弹窗;按钮仅在存在离线实例时展示,执行后自动刷新实例列表。DELETE /api/system-info/stale-instances Root 管理接口,用于一次性删除所有超过心跳离线判定阈值的实例记录。/home,不再影响前端源码扫描。features/home,即使上层工作区后续增加宽泛忽略规则,首页 utility 仍会进入构建产物。0 等有效值会保留,随机种子为空时不会发送 seed,避免把“未设置”误解为固定种子。media.task 结果解析补充读取 usage.completion_tokens 和 usage.total_tokens,Seedance 兼容接口返回实际 token 后可进入统一任务计费链路。disable_task_delta_settlement: true,重新开启会移除该字段。refetch()。+{{count}} more mapping(s) 的映射计数文案不自然问题。渠道 -> 编辑 -> 高级设置 -> Video Task Billing 中直接调整。completion_tokens 与 total_tokens 使用相同值的问题,避免错误的共享字段映射被测试漏过。Completion delta settlement、新建渠道 API Key 提示、订单完成、兼容 API 支持、embeddings 和 Seed 等文案。go run main.go 仍只嵌入已有的 web/default/dist。从源码启动前应先执行 cd web/default && bun run build,再重启 Go 进程;Docker 构建已自动执行此前端步骤。bun run build / bun run build:check,不会自动执行 CSS 产物守卫;发布流水线应继续使用项目脚本。total_tokens 自动补扣或退款。disable_task_delta_settlement 存储在渠道 settings JSON 中,不需要数据库迁移;该字段只对 DoubaoVideo 渠道生效。ModelRatio / 任务计费配置中按实际上游成本单独校准;本版本提供结算开关和 usage 解析,不自动改写生产费率。last_seen_at 早于当前时间 SystemInstanceStaleAfterSeconds 的记录;在线实例和正好处于阈值边界的实例不会被删除。DELETE /api/system-info/stale-instances 复用现有 system_instances 表,不新增数据库迁移;响应中的 deleted_count 仅用于管理端提示。Tailwind build verification passed,确认新增产物守卫已执行。node scripts/verify-tailwind-build.mjs,确认生成的 CSS 包含首页 Hero 桌面双列规则。seed 空值处理、显式零值发送和禁用参数过滤。bun run typecheck、bun run lint、定向 Prettier 检查及 bun run i18n:sync 通过。go test ./service ./controller ./relay/channel/task/taskcommon ./relay/channel/task/doubao。go test ./model -run "TestDeleteStaleSystemInstance|TestDeleteStaleSystemInstances" -count=1。bun run typecheck、bunx eslint src/features/system-info/components/system-instances-panel.tsx src/features/system-info/hooks/use-stale-instance-cleanup.ts、对应文件 Prettier 检查。go test ./relay/channel/task/taskcommon -run TestParseConfiguredTaskResultReadsUsageTokens -count=1。bun test src/features/channels/components/drawers/channel-editor-state.test.ts。go test ./...、go vet ./...、go run ./tools/jsonwrapcheck。bun run typecheck、相关渠道编辑文件的 ESLint / Prettier 定向检查、bun run i18n:sync。git diff --check。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4...v1.0.5-preview.1
> Claude/Anthropic 流式输出 token 计费回归已修复。 v1.0.4 曾在 Claude/Anthropic 流结束时正确解析顶层 CompletionTokens,但生成最终 BillingUsage 快照时遗漏 OutputTokens,导致用量日志中的 completio
[!IMPORTANT] Claude/Anthropic 流式输出 token 计费回归已修复。 v1.0.4 曾在 Claude/Anthropic 流结束时正确解析顶层
CompletionTokens,但生成最终BillingUsage快照时遗漏OutputTokens,导致用量日志中的completion_tokens可能为0,输出 token 也可能未进入实际结算。当前版本已补齐最终快照回填,并加入完整流式事件链回归测试。该问题按响应处理器而不是模型名称划分:Anthropic 原生、AWS Bedrock Claude、Vertex Claude 模式、Advanced Custom Anthropic Messages,以及通过
/v1/messages复用 Claude 流式处理器的兼容渠道都可能受影响。Claude 非流式请求以及原生 OpenAI Chat、OpenAI Responses、Gemini 路径未发现同类问题。历史受影响请求无法仅凭本地
completion_tokens=0恢复精确输出量,应优先结合上游 usage 或账单记录进行对账;根据响应文本重新分词只能作为估算。额度并发与结算一致性已完成正式版加固。 发布前复核确认并修复了用户/token 额度在 Redis 与数据库之间异步更新、并发扣减缺少余额条件、邀请奖励全字段覆盖,以及资金结算成功但 token 调整失败后被错误标记为已完成等问题。额度扣减现在以数据库条件写为最终判定;旧版预扣路径会在同一数据库事务中同时扣减用户与 token;Redis 通过共享单调代次、条件回填、实体删除清理和持续失效重试阻断旧快照或已撤销 token;结算会分别处理已确认的部分补偿与结果不明的补偿错误,后者不会自动重复非幂等资金操作。
v1.0.4 涉及计费结算、分阶段计费、GPT-5.6 缓存写入、异步任务、Responses 兼容、安全验证、数据库迁移和项目授权说明等关键变化。升级前建议在测试环境核对常用模型、缓存创建价格、任务类渠道、用户额度、反向代理和 access token 相关流程,并阅读最新版 README 中的授权要求。
生产数据库提醒:正式环境不建议使用 SQLite。 SQLite 仅适合本地体验、开发和小规模测试;并发请求、多实例部署、大量日志与用量数据、数据库迁移、备份恢复和长事务可能引发锁等待、写入阻塞、迁移耗时或失败,以及可用性和数据维护问题。正式环境请使用 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6,并配置可靠的备份与恢复方案。
[!NOTE] 本正式版草稿汇总 v1.0.4-preview.1 至 v1.0.4-preview.4 的主要更新,并补充正式发布前确认的授权政策、前端体验更新和 Claude/Anthropic 流式计费关键修复。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4
BillingUsage、tiered_expr 分阶段计费和统一 quota 转换策略,扩展 OpenAI、Claude、Gemini 的缓存、图片、音频、reasoning 等细分用量,并补齐 GPT-5.6 cache_write_tokens 的跨协议结算以及 Claude/Anthropic 流式输出 token 的最终快照映射。GroupRatio 入口共享同一运行时 RWMap;指针型配置会在原对象上安全更新,坏 JSON 不会污染现值;用户缓存失效/删除、token 缓存删除、quota_data 聚合键和 OAuth 身份唯一性都有更明确的迁移与重试边界。auto、auto:fast、auto:cheap 等多条具名自动链路,并优化渠道抽屉、模型/分组倍率编辑、模型广场链路展示和 OAuth 回调配置提示。service/openaicompat 兼容层和 Gemini Responses adaptor,支持 Responses 请求接入 Chat Completions 或 Gemini 上游。dto.BillingUsage 协议用量快照,并在 InputTokenDetails 中支持 cache_write_tokens,为格式转换后的原始协议语义、缓存写入量及 Claude/Anthropic 流式输出量结算提供统一载体。tiered_expr 分阶段计费及可视化/表达式编辑能力,可按上下文长度、输入输出、缓存、图片、音频、请求参数、header 和时间条件组合价格规则。Pass Through Body、模型映射与 Param Override 可组合使用。content[] 请求及 safety_identifier、priority、generate_audio、ratio、resolution 等参数,并按分辨率和视频输入动态计费。Param Override 修改后的时长、尺寸、媒体输入和 header 会同时作用于实际请求与费用计算。auto / auto:* 自动链路会从用户完整模型集合加载选项,避免使用虚拟分组过滤后得到空列表。group_ratio_setting.group_ratio 与旧 GroupRatio 指向同一运行时倍率表,UpdateConfigFromMap 会原地更新指针型子配置,坏 JSON 会在校验失败后返回错误且不污染现有 RWMap。bigint,管理端操作保持在 JavaScript 安全整数范围内。cache_write_tokens 可在 Responses 非流式、流式、compact 和 Responses/Chat 转换中完整保留;结算时归一为缓存创建 token,并写入用量日志便于对账。tool_calls 和 Wan2.7 图生视频 input.media 等请求响应格式。/api/* 及旧版 Dashboard 账单接口,模型中继 /v1/*、Gemini /v1beta/* 继续使用独立的模型请求限流。response_time / test_time 同步回渠道列表,便于管理员即时判断上游连通性和延迟。remain_quota >= amount 条件保护并发下界,无限额度 token 继续保留原有不受余额限制的使用语义。remain_quota / used_quota 与用户额度统一为 64 位整数,并为 MySQL、PostgreSQL 老库补充 bigint NOT NULL DEFAULT 0 迁移;SQLite 继续使用兼容的类型亲和性与 AutoMigrate 路径。quota_data_snapshots 中与累计更新同事务去重。数据库失败会保留原快照 ID 重新入队,提交结果不明确时重复执行也不会再次累加;看板刷盘和聚合键迁移现在共用跨数据库 operation lock,并使用短租约 heartbeat 持续续租,避免启动迁移扫描后被并发写入覆盖。quota_data.aggregate_key 迁移改为在保留唯一索引约束的前提下清理 stale key、合并旧 NULL/空聚合键记录、删除重复行并回填 survivor;迁移使用有界批量扫描、bigint scratch 表和跨库 set-based apply,后续 upsert 会命中迁移后的累计行,避免同一统计维度拆出并行记录。context 与截止时间:关机保存不再仅停止等待一个仍在后台运行的 goroutine,本地 flush 串行锁、数据库 operation lock 获取和单条持久化事务都会响应取消;截止时间到达时,已摘取 snapshot 会在函数返回前按原 SnapshotID 重入队。单条持久化失败也会在保留失败项重试的同时向调用方返回非空错误,不再把“仅存在于内存中的待重试数据”报告为保存成功。quota_data_operation_locks 的创建、过期抢占和 heartbeat 续租统一使用数据库服务器时钟,并在同一 SQL 语句中计算当前时间与新过期时间;SQLite 使用 strftime、MySQL 使用 UNIX_TIMESTAMP()、PostgreSQL 使用 CURRENT_TIMESTAMP,避免多节点主机时钟偏差导致仍有效的租约被提前抢占。tiered_expr 编译缓存达到上限时只淘汰最早条目,不再全量清空;订阅资金源也改为严格使用调用方传入的预扣额度。WATCH 条件写;用户 group、status、role、name、setting 等窄字段也会在 DB 查询前捕获 generation。实体删除会同时清理 hash 与专属版本键;token 撤销删除失败后会按 HMAC 缓存键去重并在缓存 TTL 窗口内指数退避重试,执行中的旧任务也不能吞掉同一 token 的新删除请求。int64 上下文值,避免 64 位额度升级后被误读为 0 并触发错误预扣。window.opener,并通过短时 OAuth state 标记维持绑定流程。X-Turnstile-Token 请求头传递,避免进入 URL、浏览器历史和常规 query 日志;后端暂时保留 query 回退以兼容旧客户端。new Function,改用受限表达式解释器;服务端 header() / param() 改用正向白名单,只开放明确的计价元数据,并拒绝整个请求、GJSON 查询/修饰符/通配符、未知 body 根和伪装认证 header。[DONE] 时即使 SSE 已关闭也会进入错误收尾,生产错误处理不再输出包含请求头的完整 Axios 对象。BillingUsage 时,会在上游快照缺少输出量的情况下,从已解析的 CompletionTokens 回填 ClaudeUsage.OutputTokens;若上游已提供非零 OutputTokens,则继续保留上游原值。completion_tokens=0 恢复精确输出量,应优先使用上游 usage/账单记录;根据响应文本重新分词只能作为估算。quota_data 累计更新在同一事务中完成;数据库已提交但客户端收到错误时,携带同一快照 ID 的重试不会再次增加 count、quota 或 token_used。group_ratio_setting.group_ratio 不再在旧入口更新后提前返回,注册配置导出和运行时倍率读取会保持一致;指针型配置优先复用已有 UnmarshalJSON 对象,避免替换掉被其他包持有的运行时实例。quota_data 聚合键迁移后重复建行与迁移竞态:迁移会在保持正式唯一索引在线时清理 stale key、合并同维度历史行、回填 aggregate_key 并删除重复记录;跨实例迁移和看板刷盘通过数据库 operation lock 串行化,短租约由 heartbeat 全程续租,失去 owner 会中止后续写入,避免全局 scratch 表互相覆盖,或用旧扫描汇总覆盖迁移期间的新 quota 写入。QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS 现在会形成真实的取消 deadline,而不是只让 main goroutine 停止等待;锁获取被取消或截止时间到达时,已脱离全局缓存的 snapshot 会先重入队再返回。单条数据库写入失败会继续处理同批其他数据、只重入队失败项,并把首个持久化错误返回给关机调用方。FillUserBy* 返回真实数据库错误,并通过 ErrUserDeleted 明确区分 OAuth 软删除账户;内置和通用 OAuth 流程都返回“用户已注销”域错误。OAuth 身份唯一性查询失败会记录 provider 与内部错误,但客户端只收到本地化通用信息。配置反序列化失败改为向上返回,group_ratio_setting.group_ratio 会与旧 GroupRatio 入口更新同一运行时倍率映射,兑换码前缀搜索正确转义 _ / %,数据看板刷盘失败会保留待重试数据。GET /api/user/token 改为 POST /api/user/token,依赖旧接口的脚本、SDK 和自动化客户端需要同步调整。TrustedProxies 不再信任私网网段;使用 Nginx、Cloudflare Tunnel、内网负载均衡或容器代理时,请显式配置 TRUSTED_PROXIES。如果后端未信任代理的实际来源地址,多名公网用户可能被识别为同一个代理 IP,进而共享登录、OAuth、支付、令牌明文读取等关键接口的限流桶并统一返回 429。请仅信任精确代理地址或最小 CIDR,并确认代理转发 X-Real-IP / X-Forwarded-For,不要直接信任整个私网地址段。GLOBAL_API_RATE_LIMIT 的未配置默认值调整为 720 次、窗口仍为 180 秒;显式环境变量继续优先。该配置不改变 CRITICAL_RATE_LIMIT 的默认 20 分钟 20 次,也不改变默认关闭、按用户/分组独立配置的模型请求限流。Param Override 现在会在计费前生效,header override 会在 adaptor 默认 header 之后应用;请复核已有任务渠道的改写规则和价格配置。bigint;升级前请备份数据库,并先在测试环境验证启动迁移。remain_quota / used_quota 迁移为 bigint。大规模 tokens 表执行 DDL 可能持有元数据锁或触发表重写,建议安排低峰窗口,必要时提前使用在线 DDL。BATCH_UPDATE_ENABLED=true 不再延迟聚合用户/token 可用额度变更;这些账务写入会直接落库以保证条件扣减和错误传播,批量模式仍可用于非余额类统计。高吞吐部署应观察数据库写入负载。GET、SET、WATCH、MULTI/EXEC、EVAL/EVALSHA、INCR、DEL、HSET 和过期时间相关命令;额度缓存 generation 由共享 Redis 的 cache-version:sequence 单调序列协调,不能用仅存在于单个进程的本地计数替代。专属版本键只在对应用户/token 删除时清理,不应手工设置普通 TTL。token 撤销和用户缓存失效/删除重试队列位于应用进程内,进程存活时会在各自缓存 TTL 窗口内持续重试;若故障期间同时重启全部实例,未完成任务不会跨进程持久化,旧 hash 仍以缓存 TTL 为最终上界。quota_data_snapshots 去重表,用于保证看板聚合快照重试幂等;SQLite、MySQL 5.7.8+ 和 PostgreSQL 9.6+ 均通过 GORM 自动迁移创建,数据库账号需要具备建表和索引权限。quota_data.aggregate_key:老库中的 NULL/空键会按统计维度合并、清理重复行并回填 survivor。迁移会额外创建 quota_data_operation_locks 和短生命周期 scratch 表/索引,需数据库账号具备建表、建索引、更新和删除权限;多实例启动时其他实例或看板刷盘会等待该 operation lock。锁使用短租约和 heartbeat,持有实例异常退出后不会长期阻塞,长迁移也会持续续租;大表建议低峰升级并保留升级前备份。QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS 现在同时限制本进程 flush 串行等待和数据库 operation lock 获取;超时会返回 context deadline exceeded 并重新入队未确认完成的 snapshot。运维日志中出现 quota cache save failure 或待重试数量大于 0 时,应视为本次关机保存未完全落库,不能仅依据进程已退出判断保存成功。users 表会为 GitHub、Discord、OIDC、WeChat、Telegram 和 LinuxDO 身份字段建立非空唯一约束;升级时空字符串会归一为 NULL,重复值会保留排序最靠前的一个账户(优先未软删除用户)并清空其他重复绑定。MySQL 通过生成列实现可空唯一语义,需 MySQL 5.7.8+ 与 DDL 权限。input_tokens_details.cache_write_tokens 会按缓存创建 token 计费:ratio 模式使用 CacheCreationRatio,表达式模式使用 cc;请根据实际上游价格检查对应配置。cached_creation_tokens 和 cache_write_tokens,系统取两者中的较大值作为缓存创建总量,不会相加,外部对账工具应采用相同口径。tiered_expr 系数表示每 100 万 token 的实际美元价格,不包含旧倍率表的隐式换算;未启用该模式的模型继续使用原有 ModelRatio / ModelPrice。tiered_expr 的 header() 仅开放 anthropic-beta / openai-beta,param() 仅开放文档列出的计价元数据、数组计数和 role/type 路径;其他路径、@this、查询、修饰符、通配符与未知 header 均返回空字符串或 nil。旧规则需要按新白名单调整。prompt_tokens_details、input_tokens_details、cache_write_tokens 和 billing_usage。/v1/messages 或其他 Anthropic Messages 兼容入口可能把非 claude-* 模型也交给 Claude 流式响应处理器;升级验证和对账应按实际响应适配器检查,不能只按模型名称筛选。X-Turnstile-Token 发送验证 token;后端仍接受旧 query 参数作为过渡兼容,但自定义前端、SDK 和网关应尽快迁移到请求头。Param Override、TrustedProxies 和 access token 自动化脚本。TRUSTED_PROXIES、GLOBAL_API_RATE_LIMIT* 和 CRITICAL_RATE_LIMIT* 环境变量。反向代理部署应从不同公网网络分别执行状态页与登录探针,确认后端识别到各自真实客户端 IP,普通控制台请求与关键操作不会因共享代理 IP 限流桶而同时返回 429。users / tokens 表预估 bigint 迁移时间,并在升级窗口观察数据库锁等待、启动日志和额度字段默认值。quota_data 同维度多行;在测试环境启动一次迁移,确认清理日志、回填结果和唯一索引创建完成。auto:* 自动链路,确认路由、流式响应、usage 明细和结算日志符合预期。completion_tokens=0 但响应有实际输出的记录,应结合上游 usage 或账单记录进行人工对账。CacheCreationRatio / cc 配置;外部报表请采用“缓存创建 token 取最大值而非相加”的同一口径。tiered_expr 是否读取敏感 header 或请求内容;将这类条件迁移到明确、非敏感的计价元数据,并在图形预估器和真实请求上分别验证结果。quota_data_snapshots;升级后连续触发两次看板刷盘并抽查 count、quota、token_used 未因重试重复累计。quota_data_operation_locks,quota_data.aggregate_key 唯一索引在旧数据合并期间保持存在;大表或多实例部署应观察启动日志、heartbeat 和锁等待时间,避免在迁移窗口内误判看板刷盘延迟为数据丢失。quota_data_operation_locks 后触发关机 flush,确认 QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS 到期时调用会返回、snapshot 仍保留相同 ID 等待重试,释放锁后再次刷盘只累计一次;同时模拟单条持久化失败,确认关机日志收到非空错误而失败项仍在缓存中。quota_data、日志和任务表规模、迁移耗时、写锁等待及恢复流程。group_ratio_setting.group_ratio 的导出值和运行时倍率是否一致;模拟用户设置更新和用户删除期间 Redis 短故障,确认恢复后缓存会被失效或删除,接口不把已提交的数据库删除误报为失败。billing settlement failed after 3 attempts、error adjusting token quota after funding settled 和资金补偿失败日志配置告警;出现后按 request/user/token 维度对照上游 usage,不要仅依赖本地预扣值判断最终费用。X-Turnstile-Token,并确认反向代理允许该请求头通过。GET /api/user/token 的脚本或 SDK,改用 POST /api/user/token,并准备 Passkey、2FA 或限定作用域密码验证流程。CompletionTokens = 53,最终 BillingUsage.ClaudeUsage.OutputTokens = 53。OutputTokens 时,不会被本地回填值覆盖。go test ./relay/channel/claude ./relay/channel/aws ./relay/channel/vertex ./relay/channel/advancedcustom ./service -count=1。go test ./... -count=1;本轮涉及的 model、service、billingexpr、config、middleware、controller 定向测试与 go vet ./... 通过,go run ./tools/jsonwrapcheck 和 git diff --check 通过。bun run typecheck、bun test src/features/channels/lib/channel-actions.test.ts、针对渠道测试与模型定价编辑器变更文件的 bunx eslint、bunx prettier --check、bun run i18n:sync 与 git diff --check。bun run typecheck、bunx eslint --no-warn-ignored src/features/system-settings/models/model-ratio-visual-editor.tsx、bunx prettier --check src/features/system-settings/models/model-ratio-visual-editor.tsx src/i18n/locales/ru.json 与 bun run i18n:sync。int64 信任判断、计费表达式全请求/查询绕过、OAuth 软删除域错误和 SSE 未完成关闭均有定向回归覆盖。WATCH/事务交错,主动阻塞旧用户/token DB 快照及用户 group 窄字段回填;同时验证实体删除后 hash/版本键释放、删除前快照被拒绝且重建 generation 大于旧值。go test ./common -run "TestVersionedHashDeletionRejectsStaleRefillsAndReleasesEntityKeys" -count=1、go test ./service -run "TestBillingSession|TestPreConsume" -count=1、go test ./model -run "TestSaveQuotaData|TestUserQuotaInvalidation|TestUserGroupInvalidation|TestTokenQuotaInvalidation|TestTokenDeleteRetries|TestTokenCacheRetry|TestIsOidcIdAlreadyTaken|TestAtomicTokenAndUserPreConsume|TestUpdateOption" -count=1、go test ./controller -run "TestOAuthBindMasksUniquenessLookupDatabaseError|TestFindOrCreateOAuthUser" -count=1。go test ./... -count=1、go vet ./...、jsonwrapcheck 和 git diff --check 均通过。race 模式因验证环境 CGO_ENABLED=0 未执行。TestUpdateOptionFiltersAutoRouteGroupRatioNamesBeforePersistence 和 TestUpdateOptionMapFiltersAutoRouteGroupRatioNames 已修复;分层键 group_ratio_setting.group_ratio 现在会更新实际运行时 RWMap。完整 go test ./model -count=1 与 go test ./... -count=1 均通过。TestUpdateConfigFromMap_PointerUnmarshalerUpdatesInPlace、TestLoadFromDBReturnsInvalidSubConfigError、TestTokenCacheDeleteRetryGetsBoundedDeadline、TestQuotaDataMigrationBackfillsAndMergesLegacyRows、TestUpdateUserSettingRetriesCacheInvalidation、TestUserDeletesRetryCacheDeletionAfterDatabaseCommit 和 TestMigrateUserOAuthIdentityConstraintsBackfillsAndEnforcesUniqueness。go test ./model -count=1、go test ./setting/config ./types -count=1、go test ./... -count=1、go vet ./... 与 git diff --check。bun run typecheck、bun run build:check 与变更文件 Prettier 检查通过。go test ./common ./middleware ./router;控制台 /api/*、关键操作和模型中继分别使用全局 API、Critical 与 Model Request 三套独立限流配置。quota_data 迁移补强通过:保留正式唯一索引、stale key 修复、row B 计数保真、bigint scratch schema、迁移 operation lock 等待、quota 写入等待锁、锁竞争测试先观察到真实抢锁尝试再断言阻塞、短租约 heartbeat 续租、失去 owner 中止和 release 失败重试均有回归覆盖;同时确认旧 token/user 逐字段缓存 setter 已无残留符号。go test ./model -count=1、go test ./... -count=1、go vet ./...、go run ./tools/jsonwrapcheck 与 git diff --check。TestSaveQuotaDataCacheRequeuesSnapshotWhenCallerStopsWaiting、TestSaveQuotaDataCacheReturnsIndividualPersistenceFailure 和 TestQuotaDataOperationLockUsesDatabaseClockForLeaseSQL;单条失败错误传播、超时重入队、后续幂等落库,以及 SQLite/MySQL/PostgreSQL 数据库时钟 SQL 均已验证。聚焦回归连续 10 次、go test ./model -count=1、go test ./... -count=1、go vet ./...、go run ./tools/jsonwrapcheck 与 git diff --check 通过。Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.3...v1.0.4
Nothing published for this version
> 正式发布前进一步核查发现,Claude Messages、OpenAI Responses、Gemini、Realtime、OpenAI 音频和 MiniMax TTS 的 usage 归一化与最终结算存在多类同源缺陷,可能导致输出 token、缓存、图片、音频或精确字符用量未进入日志、普通倍率
[!WARNING]
v1.0.4 正式版发布继续阻断
正式发布前进一步核查发现,Claude Messages、OpenAI Responses、Gemini、Realtime、OpenAI 音频和 MiniMax TTS 的 usage 归一化与最终结算存在多类同源缺陷,可能导致输出 token、缓存、图片、音频或精确字符用量未进入日志、普通倍率计费或
tiered_expr结算。由于这些问题直接影响账务准确性,v1.0.4 暂不进入正式版,先发布 v1.0.4-preview.5 完成验证。本预览版同时合并原计划进入 v1.0.5-preview.1 的 Dashboard、统一表格、移动导航、系统设置、渠道编辑、Tiered Billing、Ollama 模型管理、Playground、多语言和 README 更新,避免已确认修复继续滞留在下一版本分支。
升级前请在测试环境重点核对 Claude/Anthropic 流式输出、Responses 多模态 usage、Gemini 图片/音频生成、Realtime 音频表达式、TTS/STT、MiniMax 字符计费,以及移动端表格、Dashboard、系统设置、渠道编辑和 Playground 自动分组。
[!IMPORTANT] 修复前已经产生的异常日志无法始终仅凭本地记录恢复精确用量。Claude
completion_tokens=0、丢失的 Responses modality 明细或异常 Gemini fallback 应优先结合上游 usage、供应商账单和原始响应进行对账;根据响应文本或媒体数量重新估算只能作为辅助依据。
[!NOTE] v1.0.4-preview.5 是正式版前的计费阻断修复与前端体验集中验证版本。该版本没有新增数据库迁移,但会改变部分模型在异常 usage、音频路由和分阶段计费下的最终结算结果;发布前请以最终 tag、构建产物、上游官方价格和实际部署验证结果为准。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.5
message_delta 缺少 output_tokens 时会从累计 CompletionTokens 回填,并同步写回客户端 JSON;上游已有非零值继续优先保留。output_tokens_details。audio/* inline data 错算成图片。tiered_expr 可读取 cr、ai、ao,OpenAI TTS/STT 会归一化音频明细,Responses 音频路由覆盖 gpt-4o-audio*、gpt-4o-mini-audio*、gpt-audio* 和带音频 usage 的模型别名。usage_characters 会直接进入输入 token、日志和倍率结算,缺失时才回退本地估算。/500。auto 或 auto:* 模型分组后无法选择模型的问题,自动分组现在会正确加载用户模型集合。message_delta 输出 token 清零:最终事件或上游快照缺少 OutputTokens 时,从已累计的 CompletionTokens 恢复;修复值同时进入 BillingUsage、日志、结算和客户端 usage.output_tokens。cached_creation_tokens、text/image/audio 和输出侧 reasoning/text/image/audio 明细均可进入内部结算。ImageTokens。imageCount * 1400 可同时进入候选总量与 CandidatesTokensDetails;已有非零 IMAGE/AUDIO/TEXT 明细不会被本地估算覆盖。image/* 时计入图片数量,audio/* 不再产生错误的 1400 图片 token。tiered_expr 缺少音频和缓存变量:结算参数现包含缓存读取、音频输入与音频输出,并继续按表达式实际使用的变量从基础 p/c 中自动排除,避免重复或遗漏计费。input_tokens_details / output_tokens_details 会映射到统一 usage;Responses 可按模型家族或实际音频明细进入音频结算。usage_characters 现在作为 PromptTokens、TotalTokens 和文本明细参与日志及倍率结算;生产代码统一使用项目 JSON wrapper。TotalTokens 重算或原预扣额度。BuildTieredTokenParams 进入分阶段结算,缓存与音频变量遵循和文本请求相同的自动排除规则。id、Label 关联、aria-describedby、错误提示和禁用原因,点击标签和键盘操作更加可靠。sync_fields 在键为空时仍保留已选类型。text-xsst 样式类和零散的响应式样式问题,避免构建后样式静默失效。bun:test 类型声明导致 GitHub Frontend checks 失败。message_delta JSON 未携带累计输出 token,导致日志、结算或客户端 usage 中 output_tokens=0 的问题。output_tokens_details,导致部分输出明细在反序列化阶段消失的问题。ImageTokens、混合文本图片漏算图片、已有细分值被估算覆盖和音频 inline data 被误识别为图片的问题。cr、ai、ao 永远为零,音频 token 也无法按表达式变量从 p/c 自动排除的问题。TotalTokens、实际倍率结算仍使用本地估算的问题。/500,导致表单、筛选、分页和任务上下文丢失的问题。body 滚动锁可能残留的问题。whitespace-nowrap 使长模型名、标签或描述撑宽容器的问题。auto / auto:* 作为真实 group 参数请求模型,导致自动分组下模型列表为空、无法选择模型的问题。sync_fields 在 key 暂时为空时丢失所选类型的问题。Save tiered billing、Tiered Billing、保存成功提示及 JSON 标签仍显示英文的问题。bun:test,导致 GitHub Actions 执行 tsc -b 时找不到模块类型声明的问题。message_delta.usage.output_tokens 中收到本地累计回填值;已有非零上游值不会被覆盖。input_tokens_details、output_tokens_details 和 completion_tokens_details;依赖旧零值行为的对账脚本应同步更新。tiered_expr 现在可使用 cr、ai、ao,引用这些变量时会改变 p/c 的归一化结果;升级前应复核实时音频模型表达式。gpt-4o-audio*、gpt-4o-mini-audio*、gpt-audio* 或返回音频 token 明细的 Responses 请求会进入音频结算路径。usage_characters;上游精确字符数与历史本地 token 估算存在差异时,升级后费用可能变化。/500;页面会保留当前上下文并显示局部错误与重试。依赖旧跳转行为的自动化测试需要更新。auto 或 auto:* 分组时会省略模型列表请求中的 group 参数,这是自动分组的预期行为;显式分组仍按原有参数请求。本预览版已完成以下针对性验证;正式发布前仍建议在最终 tag 和发布构建上重新执行:
go test ./relay/channel/gemini -count=1go test ./dto ./service -count=1go test ./relay/channel/claude ./relay/channel/openai ./relay/channel/minimax ./relay -count=1go vet ./relay/channel/claude ./relay/channel/openai ./relay/channel/gemini ./relay/channel/minimax ./dto ./service ./relayOutputTokens 缺失回填、上游非零值保留和 message_delta.usage.output_tokens JSON 写回回归测试output_tokens_details 回归测试cr/ai/ao 参数与 p/c 自动排除回归测试cd web/default && bun run typecheckcd web/default && bun run build:checkcd web/default && bun run i18n:syncgit diff --checkscrollWidth === innerWidth,确认无横向溢出说明:当前仓库的全量
bun run lint与全量格式检查仍存在与本版本无关的历史基线问题,因此本稿不将其列为已通过项。正式版发布前仍建议在最终分支执行完整后端、前端和部署回归。
Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4-preview.4...v1.0.4-preview.5
>[!WARNING] 发布阻断:Claude/Anthropic 流式输出 token 计费回归。 截至 2026-07-16,v1.0.4-preview.4 当前代码在 Claude/Anthropic 流结束时会正确解析顶层 CompletionTokens,但生成最终 BillingUsa
[!WARNING] 发布阻断:Claude/Anthropic 流式输出 token 计费回归。 截至 2026-07-16,v1.0.4-preview.4 当前代码在 Claude/Anthropic 流结束时会正确解析顶层 CompletionTokens,但生成最终 BillingUsage 快照时遗漏 OutputTokens,导致用量日志中的 completion_tokens 可能为 0,输出 token 也可能未进入实际结算。
该问题按响应处理器而不是模型名称划分:Anthropic 原生、AWS Bedrock Claude、Vertex Claude 模式、Advanced Custom Anthropic Messages,以及通过 /v1/messages 复用 Claude 流式处理器的兼容渠道都可能受影响。Claude 非流式请求以及原生 OpenAI Chat、OpenAI Responses、Gemini 路径未发现同类问题。
在修复和完整回归通过前,不应将当前 v1.0.4-preview.4 用于需要准确计费的 Claude/Anthropic 流式生产请求;临时可强制 stream: false,历史受影响请求应结合上游 usage 记录进行对账。
重要升级说明
v1.0.4-preview.4 覆盖计费结算、GPT-5.6
cache_write_tokens缓存写入计费、Responses/Chat 跨协议转换、异步任务计费、渠道请求改写、日志审计、access token 生成与二次验证、前端富文本渲染、登录注册合规和多数据库兼容等关键路径。升级前建议先在测试环境验证主要模型调用、缓存创建价格、分阶段计费表达式、任务类渠道、用户额度变更、用量日志筛选、Playground、OAuth/注册登录、access token 重新生成、订阅重置和管理端渠道配置。如果部署使用 GPT-5.6、Responses API、缓存创建倍率或自定义计费表达式,请重点检查
cache_write_tokens是否按预期进入缓存创建费用;同时复核 Param Override、自动分组/自动路由、Redis 配额缓存、旧 MySQL/PostgreSQL 数据库和反向代理真实 IP 配置。
[!NOTE] v1.0.4-preview.4 是预览版草稿,整理自当前分支中已合入的 v1.0.4 系列变更,并补充最近确认的 GPT-5.6 缓存写入计费、分阶段计费、日志审计、额度安全、密码重置和 access token 安全验证更新。发布前请以最终 tag、上游官方价格和实际验证结果为准。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.4
BillingUsage,结算时优先使用原始协议 usage,并保留 cache、cache write、image、audio、reasoning 等细分 token。input_tokens_details.cache_write_tokens 的计费链路,非流式、流式、compact 和 Responses/Chat 转换均会保留缓存写入 token,不再在跨协议后退化为普通输入 token 或被遗漏。cache_write_tokens 会归一为缓存创建 token:ratio 模式使用 CacheCreationRatio,tiered_expr 模式进入 cc 变量,并从基础输入 token 中扣除后单独计价,避免漏计或重复计费。MaxInt32 / MinInt32 边界。admin_info 容器中追加,不再覆盖异常字段或在 nil 目标上记录误导性 warning。access_token 专用作用域内使用账户密码完成重验证,同时继续优先使用已启用的 Passkey 或 2FA。service/openaicompat 兼容层,用于 Responses request/response 与 Chat Completions request/response 互转。dto.BillingUsage 协议快照结构,支持 OpenAI、Claude、Gemini usage 在跨协议转换后仍按原始语义结算。InputTokenDetails 新增 cache_write_tokens 字段和共享复制逻辑,支持在 input_tokens_details、prompt_tokens_details 与 BillingUsage 之间完整传递 GPT-5.6 缓存写入用量。tiered_expr 分阶段计费模式,单条表达式即可描述模型的基础价格、长上下文阶梯、缓存价格、媒体 token 价格和请求条件倍率。p、c、len、cr、cc、cc1h、img、img_o、ai、ao 等变量,以及 param()、header() 和时间函数,可覆盖文本、缓存、多模态和请求级价格规则。input_tokens_details 映射回 prompt_tokens_details,并在 BillingUsage 恢复时保留细分 input token,避免 cache write、cached、image、audio input 在结算中丢失;六类 input token 字段改由 DTO 共享映射统一维护,降低后续新增字段时跨路径漏同步的风险。BillingUsage 恢复会从 input_tokens_details 补齐 prompt_tokens_details.cache_write_tokens,保证 GPT-5.6 Responses 转 Chat 后仍使用原始缓存写入数据结算。cached_creation_tokens 与 cache_write_tokens 作为同类缓存创建统计进行兼容归一化;两者同时存在时取较大值,不直接相加,避免同一批缓存写入被重复收费。len 判断上下文档位;len 始终表示包含缓存 token 在内的完整输入长度,避免大量缓存命中后误进入较低的长上下文价格档位。p / c 中排除已单独计价的缓存、图片和音频 token,减少基础 token 与细分类 token 重复计费。cache_write_tokens,分阶段计费结果还会记录 billing mode、表达式和命中档位,便于管理员核对缓存创建费用。admin_info.quota_saturation,便于管理员追踪被截断的原始值和 clamp 类型。/api/verify 同时按客户端 IP 和已认证用户 ID 限制关键验证请求,降低通过代理轮换扩大密码或验证码尝试次数的风险。POST /api/user/token、POST /api/verify 请求体以及 GET /api/verify/methods?scope=access_token 的参数与验证方式枚举。cache_write_tokens 时,部分非流式、流式、compact 或 Responses → Chat 路径没有把该字段带入最终 PromptTokensDetails,导致缓存写入 token 可能按普通输入价格结算或未按缓存创建倍率计费的问题。BillingUsage 恢复只保留 input token 总数和部分明细、遗漏 cache_write_tokens,导致转换后的实际结算与上游原始 usage 不一致的问题。BillingUsage 恢复只保留 token 总数,导致 input token 细分项从结算视角消失的问题。2147483647 和 -2147483648 误判为 clamp 错误的问题。attachQuotaSaturationToOther 在 admin_info 已存在但不是 map 时覆盖原值的问题。attachQuotaSaturation 在 other == nil 时仍输出“已写入审计信息”语义 warning 的问题。0 / false 可能在转发时被 omitempty 丢弃的问题。int64 上限,导致超过 Number.MAX_SAFE_INTEGER 后前端展示和回传值发生精度丢失的问题。/api/verify 仅按 IP 限流,攻击者可通过切换代理地址扩大同一账户验证尝试次数的问题。admin_info 结构下可能丢失已有审计元数据的问题。jsonwrapcheck allowlist 与当前代码不一致,减少业务代码直接调用标准 JSON marshal/unmarshal 的回归空间。prompt_tokens_details、input_tokens_details 和 billing_usage。input_tokens_details.cache_write_tokens 返回缓存写入量;该值会按缓存创建 token 处理。ratio 模式需要正确配置 CacheCreationRatio,表达式模式应使用 cc 为缓存写入单独定价。cached_creation_tokens 和 cache_write_tokens,系统会取两者中的较大值作为归一化缓存创建总量,不会相加;外部账单对账工具应采用相同口径。/2、completion multiplier 或其他换算;从 ratio 模式迁移时不能直接复制旧倍率数值。tiered_expr 时,现有模型继续使用 ModelRatio / ModelPrice 计费;启用后该模型的预扣费与实际结算以表达式和请求条件为准。prompt_tokens 通常包含缓存和媒体 token;表达式只有在引用 cr、img、ai 等变量时才会自动拆分对应 token。长上下文条件应使用 len,不要使用拆分后的 p。9007199254740991 的正整数变更量,加减结果必须保持在 JavaScript 安全整数区间,覆盖值必须位于 0..9007199254740991。历史超范围额度可通过覆盖操作恢复到安全范围,依赖更大 int64 额度的外部管理脚本需要同步调整。model_price_error、HTTP 400 和 skip-retry;本次只是统一校验来源,不改变外部错误契约。admin_info;如果调用方传入了异常类型,已有值会被保留但不会追加 saturation 详情。GET /api/user/token 改为 POST /api/user/token;依赖旧接口的脚本、SDK 或自动化客户端必须同步调整请求方法,旧 GET 路由不再可用。access_token 作用域的回退方案,并且只在账户没有启用 2FA 和 Passkey 时提供;密码验证结果不能用于其他敏感操作。PasswordLoginEnabled=false 只禁止新的密码登录,不会使已登录账户现有的密码凭证失效;符合回退条件的用户仍可用当前密码完成 access token 重验证。发布前建议按最终 tag 和发布分支重新执行并更新结果:
go test ./common ./service ./service/openaicompat -count=1go test ./dto ./service ./service/openaicompat ./relay/channel/openai -run "Test(CopyInputTokenDetails|CalculateTextQuotaSummaryPreservesResponsesInputDetailsThroughBillingUsage|CacheWriteTokensTotal|ResponsesResponseToChatCompletionsResponse)" -count=1go test ./pkg/billingexpr -run "Test(Len|Cache|ComputeTieredQuota|RunExpr)" -count=1go test ./relay/helper -run "Test(ModelPriceHelperTiered|ResolveIncomingBillingExprRequestInput)" -count=1go test ./service -run "Test(TryTieredSettle|BuildTieredTokenParams)" -count=1go test ./... -count=1go test ./common ./controller ./model -count=1go test ./relay/helper -count=1go test ./service -run TestAttachQuotaSaturation -count=1go test ./service -run TestPreConsumeValidationSharedByBillingAndQuota -count=1go test ./common -run TestQuotaFromFloatStrictAcceptsExactInt32Boundaries -count=1go test ./service -run TestCalculateTextQuotaSummaryPreservesResponsesInputDetailsThroughBillingUsage -count=1go test ./controller ./model ./middleware ./relay/helpergo test ./controller ./middleware ./router -count=1go test ./router -run 'Test(UniversalVerifyRateLimitFollowsUserAcrossIPs|SecureVerificationOpenAPIIncludesScopeAndRequestBody)' -count=1go test ./router -run TestUniversalVerifyRateLimitFollowsUserAcrossIPs -count=3go test ./relay/channel/openai ./relay/channel/gemini ./relay/channel/claude ./relay/channel/advancedcustomgo test ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel/task/aligo run ./tools/jsonwrapcheckcd web/default && bun run typecheckcd web/default && bun test src/features/users/lib/quota-safety.test.tscd web/default && bun test tests/secure-verification-method-selection.test.tscd web/default && bun run i18n:synccd web/default && bun testgit diff --check -- service/billing.go service/pre_consume_quota.go web/default/src/features/system-settings/models/model-ratio-visual-editor.tsxgit diff --checkFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.3...v1.0.4
> v1.0.4-preview.3 聚焦管理端 fetch、登录态绑定、Redis 配额缓存、验证码消费、代理信任边界、用户余额字段兼容、MySQL 老库注册兼容和用户通知设置的安全边界。受影响部署可能在特定管理操作、OAuth 绑定、密码重置/注册、高并发缓存更新、反向代理配置、用户余额调整或旧
[!WARNING]
重要安全与稳定性修复
v1.0.4-preview.3 聚焦管理端 fetch、登录态绑定、Redis 配额缓存、验证码消费、代理信任边界、用户余额字段兼容、MySQL 老库注册兼容和用户通知设置的安全边界。受影响部署可能在特定管理操作、OAuth 绑定、密码重置/注册、高并发缓存更新、反向代理配置、用户余额调整或旧库用户注册场景中暴露 SSRF、进程 panic、缓存扣减丢失、验证码复用、IP 限流绕过、余额上限异常、弱邮箱校验或注册失败等风险。
建议升级后重点验证渠道模型拉取、OAuth/第三方账号绑定、密码重置、用户注册、老 MySQL 数据库上的新用户注册、用户通知邮箱保存、管理端用户余额添加/减少/覆盖、充值码兑换并发处理、模型请求限流、站点与品牌顶部导航设置、模型广场自动链路分组展示,以及 Redis 启用时的用户/token 配额缓存更新。
[!NOTE] 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放修复和能力,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行后发布。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.3
/api/channel/fetch_models 会按系统 fetch setting 执行 SSRF URL 校验,并通过受保护 HTTP client 发送请求。id.(int) 的 panic 风险,兼容 JSON session 后端反序列化出的数值类型。a@、@b、@.、无点域名和带展示名的非纯邮箱输入。controller/channel.go 中已迁移到 common.* JSON wrapper 的历史 allowlist 条目,保持 jsonwrapcheck 基线与当前代码一致。TRUSTED_PROXIES 显式配置,降低伪造 X-Forwarded-For 绕过 IP 限流的风险。bigint,并放宽管理端 quota 覆盖和增加操作的 32-bit 上限,解除约 4295 显示余额的人工操作天花板。null_int64 表,导致注册失败的问题。RELEASE_LOCK() 返回 0 或 NULL 时会明确报错,不再被误判为释放成功。int、int64、float64 和字符串形式的 session user id。base_url 被拒绝的场景。sql.NullInt64 底层 SQL 行扫描回归测试,覆盖 MySQL 注册写锁结果使用的 1 和 NULL 返回值。1、0 和 NULL 三类返回值。HeaderNavModules 与 RankingsModule。auto_routes 的真实计费分组链路。FetchModels 拼接 /v1/models 前会裁剪 base_url 末尾斜杠,避免生成重复斜杠路径。FetchModels 在读取响应前提前注册 defer response.Body.Close(),错误状态码也会释放响应体。/system-settings/site/rankings 设置路径会自动跳转到 /system-settings/site/header-navigation,避免历史书签进入无效设置页。auto_routes 配置时继续使用 legacy auto_groups fallback。database/sql 的 Row().Scan 接收 GET_LOCK / RELEASE_LOCK 结果,避免 GORM 将 sql.NullInt64 误当作模型表解析。1 才视为锁操作成功。bigint 时执行列类型调整;SQLite 保持原有兼容路径。model.User.Delete / HardDelete,调用方只传 user id 时会先读取现有角色再判断。FetchModels 接收请求体 base_url 后使用裸 http.Client{} 直接请求,绕过项目 SSRF 防护的问题。FetchModels 使用直接 json.NewDecoder,以及渠道密钥处理和 Ollama 拉取流中直接 json.Marshal / json.Unmarshal 的项目规范偏离问题。float64 会触发 panic 的问题。RedisIncr 在 TTL 读取后 key 状态变化时可能静默跳过计数更新的问题。RedisHIncrBy 存在同类 TTL TOCTOU 竞态的问题。@,导致明显非法邮箱也能保存的问题。topUpLocks 按 user id 缓存锁对象且不清理,长期运行后可能持续增长的问题。auto_routes 当成空数组后,旧版 auto_groups 自动分组 fallback 可能不再展示的问题。sql.NullInt64 可能生成 null_int64 表查询并返回 Error 1146 (42S02): Table '...null_int64' doesn't exist 的问题。RELEASE_LOCK() 返回 0 或 NULL 时仍被当作释放成功的问题,避免锁状态异常被静默吞掉。INT 时,最终 quota 可能受 2147483647 quota units(约 4295 显示余额)限制的问题。INT 类型,导致高额度用户可能被截断、溢出或写入失败的问题。X-Forwarded-For 绕过 IP 限流的问题。io.ReadAll,异常 upstream 返回超大错误体时可能放大内存占用的问题。model.Delete / HardDelete 只依赖 controller 层保护,未来直接调用 model 方法时可能误删 root 用户的问题。float64 数值,但仍拒绝空值、零值和无法解析的类型。Name <user@example.com> 不再接受,用户应保存 user@example.com。null_int64 表;该错误来自注册写锁结果扫描方式,升级代码并重启后即可消除对应假表查询。TrustedProxies 不再包含私网网段。部署在 Nginx、Cloudflare Tunnel、内网 LB 或容器网络后方时,应通过 TRUSTED_PROXIES 配置真实代理 IP/CIDR,否则 ClientIP() 会回退到直接连接来源。/system-settings/site/header-navigation。底层 RankingsModule option 仍独立保存。auto_routes 的部署继续使用旧 auto_groups fallback。users.quota、users.used_quota、users.aff_quota 和 users.aff_history 转为 bigint,不再以 2147483647 quota units 作为业务上限。升级前建议备份数据库,并确认这些列没有自定义类型约束。go test ./controller -run "Test(FetchModelsRejectsPrivateBaseURL|SessionUserID|NormalizeNotificationEmail|TopUpLock|UpdateUserSettingPreservesUnrelatedSettings|AdminReset.*RequiresPaymentCompliance)$"go test ./controller -run TestQuotaBoundsValidation -count=1go test ./model -run "TestScanNullableInt64UsesSQLRow|TestMySQLNamedLockResultSuccessRequiresOne|TestInsertRejectsConcurrentDuplicateEmailMySQL" -vgo test ./model -run "Test(UserUpdateDoesNotOverwriteAccountingFields|UserUpdatePersistsZeroValueProfileFields|UserUpdateDoesNotClearEmailFromLoadedPartialUpdate|UpdateUserSettingOnlyUpdatesSetting)$" -count=1go test ./model -run "Test(WaitPendingLogQuotaDataDrainsEnqueuedWork|EnqueueLogQuotaDataAfterShutdownPersistsSynchronously|Record.*QuotaDataAsync)$"go test ./relay/helper -run "TestStreamScanner|TestNewStreamScanner|Test.*Ping"cd web/default && bun run typecheckgo test ./commongo test ./middlewarego test ./servicego test ./modelgo test ./controllergo test ./common ./controller ./model ./relay/helpergo run ./tools/jsonwrapcheckgit diff --checkFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4-preview.2...v1.0.4-preview.3
> 本次 v1.0.4-preview.2 优先处理 new-api 近期暴露和修复的一组高危问题,并补齐 MAX API 二次开发路径中的本地扩展风险。受影响部署可能出现账号归属异常、邮箱重复或密码重置歧义、极端参数下 quota 溢出或错误扣费、SSRF 防护绕过、客户端断流后继续消耗上游流量,
[!WARNING]
⚠️ 严重安全与计费风险警示
本次 v1.0.4-preview.2 优先处理 new-api 近期暴露和修复的一组高危问题,并补齐 MAX API 二次开发路径中的本地扩展风险。受影响部署可能出现账号归属异常、邮箱重复或密码重置歧义、极端参数下 quota 溢出或错误扣费、SSRF 防护绕过、客户端断流后继续消耗上游流量,以及异步任务结算记录不一致等问题。生产环境建议优先升级,并在升级后重点验证账号注册/邮箱绑定/找回密码、充值回调、文本/工具/视频计费、受保护下载/代理、流式响应和异步任务退款/结算。
/\ /!!\ /____\ SECURITY / BILLING本预览版重点覆盖:账号、邮箱和密码安全硬化;计费数量溢出和 quota 饱和转换;SSRF protected fetch、重定向和拨号链路校验;流式断连后的 stale write 与 goroutine 清理;异步任务差额结算 quota 持久化;以及 Go 安全依赖升级。若基于当前开发分支自行构建,请先确认前端 typecheck、后端目标测试和
jsonwrapcheck均通过后再发布。
[!NOTE] 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.2
metadata.url 返回结构,避免已完成任务被误回退为本机 /content 代理地址。SIGINT / SIGTERM 后会等待正在处理的请求结束;如果等待超时会强制关闭活跃连接,再继续看板 quota cache 落库和退出清理,降低重启时 SSE 中断、看板数据丢失和清理阶段并发残留风险。quota、used_quota、request_count 等计费字段。tool_calls 响应、Wan2.7 i2v input.media 请求格式,以及认证守卫 401-only 会话失效处理。duration: 0、修正 seconds / duration、size / aspect_ratio、model / model_name 的优先级,并避免视频输入漏判。base_url / other 默认字段,编辑已有渠道时保留已保存配置。auto、auto:fast、auto:cheap 等多条具名自动链路,并为每条链路独立设置展示名称、启用状态、用户可选状态和真实分组顺序。{api_key} 占位符在直接调用路径也能初始化渠道密钥,重试用量统计不会再混入充值或系统日志 quota。n 校验、流式 helper 空上下文保护、quota filter 路由枚举和分组倍率查询统一走共享/归一化路径,减少前后端校验漂移。metadata.url、metadata.video_url、metadata.output_url 以及 data.metadata.* 兼容路径。wan2.7-i2v、wan2.7-t2v 模型入口;wan2.7-i2v 会自动将 image、images、input_reference 或显式 input.media 映射为新协议 input.media。tool_calls 转换为 OpenAI 兼容的 message.tool_calls,并返回 finish_reason: "tool_calls"。SHUTDOWN_TIMEOUT_SECONDS 配置,默认 120 秒。QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS 配置,默认 30 秒,避免缓存落库无限阻塞进程退出。AutoGroupRoutes 自动链路配置,支持 default_route、routes[].enabled、routes[].user_selectable 和每条链路的真实分组顺序。min-width: 0、最大宽度约束和长词换行策略,提升复杂文本输入时的响应式表现。/v1/videos/{task_id}/content 兜底地址。UpdateUserSetting 路径,只更新 setting 字段和对应缓存;资料更新后的 Redis 用户缓存只刷新非 quota 字段,并同步刷新 Role,避免权限缓存滞后。setting 为基底,只覆盖通知相关字段,保留语言、侧边栏模块和扣费偏好等其它用户设置。getSelf 返回 401 时清理本地登录态;网络错误、超时或 5xx 不再直接踢出登录,也不会继续用本地旧登录态静默放行。common.* wrapper,并清理对应 jsonwrapcheck allowlist。duration 改为指针字段,客户端显式传入 duration: 0 时不会被 omitempty 静默丢弃。model 优先于 model_name、size 优先于 aspect_ratio、seconds 优先于 duration,嵌套 parameters.duration 会同步补齐秒数字段以保持行为一致。input.media 归一化会按媒体类型补齐缺失的首帧、尾帧和驱动音频;即使请求已显式携带部分 media,也不会丢弃同时提供的 last_frame_url 或 audio_url。base_url / other 的类型专属默认值,避免 Vertex、Coze、讯飞、火山等类型之间切换时残留旧字段。Channel Extra Settings 子导航的已配置状态和滚动锚点现在覆盖代理地址、系统提示词和系统提示词拼接模式等真实额外设置字段,避免只配置这些字段时导航提示和定位不一致。AutoGroups 继续作为默认自动链路的兼容字段保留;保存 AutoGroupRoutes 时会自动派生默认链路分组,旧数组格式也会自动归一化为 auto 默认链路。auto:<name> 形式的自动链路键,不再只特殊处理硬编码 auto。auto。AutoGroups、AutoGroupRoutes、ModelRatio、PayMethods、状态码规则和任务计费 rate cards,避免提交后才发现运行时刷新失败。seconds/duration、Kling 任务结果、通用 rate card 和 tiered billing 取整路径,避免极端输入下出现 int 溢出、负 quota 或错误扣费。quota 回写任务记录,避免退款、列表展示或重复结算继续读取旧预扣 quota。x/crypto 安全更新:golang.org/x/crypto v0.52.0、golang.org/x/image v0.41.0、golang.org/x/net v0.55.0,并同步更新相关 x/sys、x/text 依赖。normalized_email 索引列,避免 MySQL 上 LOWER(email) 谓词导致全表扫描和过大锁范围;写入路径会自动维护标准化邮箱。GET_LOCK,直到事务提交或回滚后才释放,覆盖普通注册、OAuth 注册、邮箱绑定和 Creem 充值邮箱回填。"0.0"、"0.00" 等零值格式不会再显示误导性的倍率标签。TaskSubmitReq.ResolvedSeconds / ResolvedSecondsOrDefault,验证、Sora 默认值和阿里请求转换共享同一套解析、错误处理和默认时长逻辑。n 数量上限校验收敛到共享 dto.ValidateImageN,OpenAI 图片请求和阿里 parameters.n 使用同一上限与错误文案模板。isQuotaFilterValue 和 z.enum(QUOTA_FILTER_SEARCH_VALUES) 后续手动维护时漂移。metadata.url 返回视频地址时,MAX API 未能保存该结果 URL,导致查询结果只返回本机 /content 代理地址的问题。metadata.url 结构时,任务结果 URL 解析不到的问题。User@Example.com 和 user@example.com 可被不同账号重复占用,进而影响注册、OAuth 创建、邮箱绑定和密码重置归属的问题。setting 覆盖整份设置,导致语言、侧边栏模块、扣费偏好等无关设置被清空的问题。Role,可能让旧角色权限继续生效到缓存失效的问题。tool_calls 的问题,并保留工具参数中的显式零值。img_url 发送图片的问题;Wan2.7 i2v 现在使用 input.media,Wan2.5 等旧模型仍保留原有 img_url 行为。input.media 时,同时提供的 last_frame_url、audio_url 会被清空而没有合并进 media 的问题。image 而未传 images 时,通用 task action 和后续适配器可能无法识别为图生视频的问题。getSelf 网络错误或服务端 5xx 时误判 session 失效、清空本地登录态的问题;非 401 校验错误现在会交给路由错误边界处理,避免旧登录态静默通过。TaskSubmitReq.Duration 使用非指针 omitempty 导致显式 duration: 0 无法继续透传给上游的问题。model_name 覆盖 model、aspect_ratio 覆盖 size、duration 覆盖 seconds 的优先级不一致问题。parameters.generateAudio 被错误写入 WithAudio,导致下游生成音频开关含义错位的问题。video_url 条目为空时,后续有效视频输入不会继续扫描,可能影响 has_video_input 计费判定的问题。input_reference 和 images 时,第二帧/尾帧图片可能被跳过或错位的问题。image 回填 images 时未裁剪空白,导致不同入口对空白 URL 处理不一致的问题。input_reference 只有空白字符时仍会生成 images: [""] 并被误判为图生视频输入的问题;空白 input_reference 现在会被视为未提供,并可回退到 image。null 时,Claude / Gemini 转换路径可能把参数序列化为 null 而不是空对象 {} 的问题。n、max_tokens、视频时长、rate card quantity 或表达式结果可能导致 quota 计算溢出、转负数或错误扣费的问题。quota 持久化到数据库的问题。seconds <= 0 时未稳定回退默认时长,可能影响请求体和计费倍率一致性的问题。seconds 为非数字字符串时会被静默当作 0 通过校验的问题;非法 seconds 现在返回 invalid_seconds,边界提示也与实际允许的 0..3600 范围一致。gin.Context 或缺失 writer 时仍继续 Render,可能触发 panic 的问题。base_url / other 字段,可能把旧类型配置误提交到新类型的问题。base_url / other 的问题;自动重置仅用于新建渠道。DefaultUseAutoGroup 后新注册用户默认令牌指向不可用链路的问题。user_selectable=false 的隐藏自动链路仍可被普通用户通过令牌创建/更新接口手动指定的问题。runWithTimeout 内部任务 panic 时可能直接终止进程,绕过后续清理流程的问题;panic 现在会记录日志并结束等待流程。SELECT ... FOR UPDATE 无法锁住不存在行,可能落到底层唯一索引错误而不是返回友好邮箱占用错误的问题。PingData,当底层 writer 不支持 deadline 且写入阻塞时,pinger 退出等待可能被永久挂住的问题。ChannelMeta 为空时,runtime header override 中的 {api_key} 可能被替换为空字符串的问题。logType=Unknown 时丢失 LogTypeConsume 限制,可能把充值或系统日志 quota 计入用量统计的问题。bun run typecheck 报 TS2352、阻塞前端构建的问题。GetGroupRatio / ContainsGroupRatio 按正常分组名或带空白入参查询不到并静默回退默认倍率的问题。"0.0"、"0.00" 等字符串零倍率时,模型分组选择器仍显示 Ratio: 0.00 的问题。generic_video_task 的视频渠道,如果上游或中间代理在完成态返回 metadata.url,现在无需额外配置结果路径即可被默认解析。task_protocol_config.result_url_paths,自定义列表会覆盖默认路径;需要兼容 metadata.url 的自定义渠道应将该路径显式加入配置。/v1/videos/{task_id}/content 兜底行为仍然保留,用于没有直接结果 URL 或需要本机内容代理的任务。SHUTDOWN_TIMEOUT_SECONDS,主 HTTP 服务会强制关闭活跃连接;长连接、SSE 或慢请求应按连接关闭语义处理重连或重试。QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS 限制,异常强杀仍可能绕过该流程。wan2.7-i2v 使用 input.media 新协议;显式 metadata.input.media 会被保留,缺失的 last_frame / driving_audio 会从旧字段补齐,旧 Wan i2v 模型继续使用原有 img_url。input_reference 现在按未提供处理;如果同一请求还提供了 image,会继续走单图 fallback。finish_reason: "tool_calls" 和 message.tool_calls,这是对 OpenAI 响应格式的兼容修复。model、size、seconds 的显式值现在会优先保留;如果历史配置依赖 model_name、aspect_ratio 或 duration 覆盖同级字段,需要按新优先级检查配置。duration 作为可选字段会保留显式 0;自定义适配器读取时应使用 DurationValue() 或判空指针,避免重新引入零值丢失问题。seconds 如果是非数字字符串,现在会被拒绝而不是按 0 处理;duration: 0 和 seconds <= 0 的默认时长 fallback 语义仍保留在需要默认值的适配器路径中。quota;后续任务列表、退款和重复结算判断会看到实际扣费值,而不是历史预扣值。base_url / other 类型专属字段;编辑已有渠道时不会自动覆盖已保存的字段。AutoGroupRoutes,旧 AutoGroups 数组仍作为默认链路兼容字段保留。AutoGroups 数组会被解释为 auto 默认链路;管理员保存新配置后,AutoGroups 会同步为当前 default_route 对应的真实分组列表。auto 或 auto:<name>,其中自定义部分允许字母、数字、点、下划线和短横线;链路中的 groups 必须是真实计费分组,不能再嵌套其它自动链路 key。default_route 必须指向存在且启用的自动链路;否则系统设置保存会被拒绝,避免默认令牌生成不可用。user_selectable=false 的链路不会出现在普通用户可选分组中,令牌新建/更新也不能主动选择;已存在的隐藏链路令牌仍会按运行时可用性解析,用于兼容历史配置或管理员预置令牌。DefaultUseAutoGroup 时,新注册用户默认令牌会使用当前 default_route,不再假设默认 key 一定是 auto。" vip " 这类带首尾空白的 key,重新保存后会归一化为 "vip";依赖空白 key 的异常配置需要改为正常分组名。" vip " 和 "vip" 走同一倍率配置。quota_filter 时生效;默认 all 不会发送该参数,保持旧查询结果不变。bunx eslint src\components\ai-elements\prompt-input.tsx src\components\model-group-selector.tsx src\components\ui\input-group.tsx src\features\playground\components\playground-input.tsx --no-warn-ignoredbunx eslint src/features/channels/components/drawers/channel-mutate-drawer.tsxbunx eslint src/routes/_authenticated/route.tsxbun test tests/channel-form.test.tsgo test ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel -count=1go test . ./controller ./model ./relay/channel/ollama ./relay/channel/task/ali ./relay/commongo test . -run "TestRunWithTimeout|TestShutdownHTTPServerClosesActiveHandlersAfterTimeout" -count=5go test ./controller -run TestUpdateUserSettingPreservesUnrelatedSettings -count=1go test ./model -run "TestUserUpdateIgnoresCacheWriteFailure|TestUpdateUserSettingOnlyUpdatesSetting|TestUpdateUserSettingIgnoresCacheWriteFailure|TestUpdateUserSettingMissingUserReturnsError" -count=1go test ./relay/channel/task/ali -run TestConvertToAliRequestWan27I2VMergesLegacyMediaFieldsIntoPartialMedia -count=1go test ./relay/common -run TestValidateMultipartDirectIgnoresBlankInputReference -count=1go test ./relay/channel/task/taskcommon ./relay/channel/task/ali ./relay/common ./service ./model ./controllergo test ./relay/channel/task/taskcommon ./relay/channel/task/doubaogo test . ./setting ./service ./controller -run "TestRunWithTimeoutRecoversPanic|TestParseAutoGroupRoutes|TestHiddenAutoRouteRuntimeUsableButNotUserSelectable|TestAddTokenRejectsNonSelectableAutoRoute|TestUpdateTokenRejectsNonSelectableAutoRoute" -count=1go test ./model ./settinggo test ./setting/...go test ./common ./pkg/billingexpr ./relay/common ./relay/helper ./service ./setting/task_billing_setting ./model ./controller ./relay/channel/openai ./relay/channel/gemini ./relay/channel/ali ./relay/channel/task/ali ./relay/channel/task/gemini ./relay/channel/task/klinggo test ./model ./servicego test ./model ./service ./setting/ratio_setting ./relay/channel ./controllergo test ./model -run "Test(UpdateUserSettingOnlyUpdatesSettingMySQL|InsertRejectsConcurrentDuplicateEmailMySQL)$" -count=1 -v(未设置 TEST_MYSQL_DSN 时会跳过 MySQL 外部库覆盖)go test ./dto ./relay/helper ./relay/channel/aligo test ./relay/common ./relay/channel/task/aligo test ./relay/helpergo test ./setting/ratio_settinggo test ./...go vet ./...bun test src/features/usage-logs/lib/utils.test.tsbun test src/lib/auto-routes.test.tsgo run ./tools/jsonwrapcheckbun run typecheckgit diff --checkFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4-preview.1...v1.0.4-preview.2
> 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
[!NOTE] 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.1
safety_identifier、priority 参数透传,并保留对 Seedance 响应形态的结果解析兼容。content[] 和 ratio、generate_audio、duration、seed 等顶层参数可继续透传到 DoubaoVideo 上游封装。ratio、callback_url、service_tier、safety_identifier 可区分未传和显式空字符串,带空白的 ratio 会在转发前规范化。Pass Through Body,字段改写和默认值复用现有 Param Override。Param Override 请求体,避免视频时长、分辨率、尺寸或输入媒体被改写后仍按旧请求预扣费。Param Override 改写后会按最终上游 JSON 计费,顶层 image / images 也不会被同步后的请求上下文重复计数。Param Override 的 header 联动现在会真正发送到上游;return_error 和无效改写会按本地配置错误处理,不再误触发渠道处罚。in_progress + 100% 的问题,非终态任务不会再因为进度为 100% 而退出后台轮询。/v1/responses 请求接入 Chat 形态上游。/v1/responses 兼容路径,支持将 Responses 请求转换为 Gemini generateContent,并将 Gemini 非流式 / 流式结果回转为 Responses 响应。openai_responses_to_openai_chat_completions 转换器,可为自定义通道配置 Responses 入站、Chat Completions 上游的转发链路。{} 兼容,无效 JSON 参数会明确报错,避免向上游发送被静默改写的空输入。content[] 请求,不再要求同时提供顶层 prompt。callback_url、return_last_frame、service_tier、execution_expires_after、generate_audio、draft、tools 可透传到上游封装。ratio、resolution、duration、frames、seed、camera_fixed、watermark 等生成控制参数会合并进最终上游 payload。generate_audio: false、return_last_frame: false、priority: 0、seed: 0 等显式零值会被保留。ratio、callback_url、service_tier、safety_identifier 等可选字符串会保留“未传”和“显式空字符串”的差异。safety_identifier 可透传到上游。priority 可透传到上游。priority: 0 会被保留并发送,不会因为零值被 omitempty 丢弃。480p / 720p 作为基础档。1080p 使用独立倍率。4k 使用独立倍率。task_billing_setting.rate_cards。duration、resolution、ratio、quality / mode、has_audio、has_video_input、image_count、video_count 等通用字段匹配价格行。OtherRatios 计费逻辑。Pass Through Body 后,JSON 请求会保留客户端字段,并继续应用模型映射。Param Override,可复用现有参数覆盖能力完成字段改写、默认值注入和上游适配。set_header、delete_header、copy_header、move_header 和 pass_headers 可用于异步任务上游请求。NODE_NAME,轮询结算时复用该节点名写入消费数据。quota_data 用量聚合新增分组、令牌、渠道和节点维度,便于后续按更细粒度做数据导出、审计和多节点归因。instructions、字符串 / 数组 input、多模态 content parts、function call、function call output、tools、tool_choice 和 text.format。temperature: 0、parallel_tool_calls: false 和 max_output_tokens。text.format.json_schema 会转换为 Chat Completions response_format.json_schema,并移除 Responses 外层 type 字段。length / content_filter 不完整结束状态。response.created、文本增量、reasoning summary、function call arguments 和最终完成事件。/v1/responses 返回 OpenAI Responses 结构。/v1/responses 返回 Responses SSE 事件。response.completed 事件。openai_responses_to_openai_chat_completions 转换器:
/v1/responses。custom_tool_call 和非 function tool,避免把不符合 Chat Completions 协议的 type: "custom" 请求发给标准 Chat 上游。retry_log 与 empty_retry 两类标记。(模型, 分辨率, 是否视频输入) 计算相对倍率。ModelRatio 配置为基础档无视频输入单价,系统会按实际请求自动追加 OtherRatio。metadata 和官方 protocol 原始请求,避免请求转换链路与计费链路使用不同字段来源。video_url / video,避免官方媒体请求的视频输入被漏算。metadata,保留历史 metadata 覆盖优先级。model 必填;promptless image-driven 请求不会再被基础任务校验提前拒绝。ratio、generate_audio、priority、seed 等官方字段,让透传、字段映射和计费读取同一份最终上下文。generate_audio 在任务上下文中使用独立字段保存,with_audio 只作为兼容回退,减少同一个官方字段被重复映射造成的歧义。callback_url、service_tier、safety_identifier 和 ratio 不会被误当作未传字段丢弃。metadata.video_url、metadata.video 和 metadata.content[].video_url 等结构。null、false 和空 video_url.url 不再触发视频输入倍率。base_url 重复的 path 前缀,减少 /v1/v1/... 这类配置错误。duration_seconds、with_audio、generate_audio、input、parameters、images 和 reference_images 等常见字段,保证字段映射后仍能被计费估算读取。metadata;渠道字段映射、模型映射和参数覆盖后的计费输入与实际上游请求保持一致。parameters.durationSeconds 与 parameters.resolution,降低通用协议字段映射后的计费偏差。Param Override 错误会保留本地错误语义,跳过自动重试和渠道健康处罚;header override 配置错误同样不会被误当作上游失败。in_progress 但结果已生成的任务。100% 就跳过后续处理。response.output 时会跳过 reasoning、computer_call、web_search_call、file_search_call、item_reference 等非 Chat message 形态条目,避免注入空用户消息。incomplete_details.reason 字段,避免继续输出非官方字段名。function_call / function_call_output 的调用 ID,缺少 call_id / id 时提前返回错误,避免转发空 tool_call_id 到上游。tool_calls,文本和工具调用都会保留。arguments 为空时发送 {},arguments 不是合法 JSON object 时返回明确错误。arguments 会包装到 input.arguments,确保 tool_use.input 始终是 object。metadata 转发字段不一致时出现计费 / 请求分歧。resolution / ratio 改为指针字段,显式空字符串会被保留,未传字段仍会省略,符合上游请求 DTO 的零值语义。Other JSON 的开销。doubao-seedance-2-0-260128 顶层 resolution: "1080p" 请求被按基础档计费的问题。51/46 倍率被错误计为 1.0 的问题。priority: 0 这类显式零值可选参数在请求转换时可能无法可靠表达的问题。quota_data 导出维度,导致任务结算数据与普通消费日志在用量看板链路中不一致的问题。quota_data 缓存聚合 key 过粗,可能把不同分组、令牌、渠道或节点的同小时同用户同模型数据合并到同一条记录的问题。video_url、null / false video 或空 video_url.url 仅因字段存在就触发 Seedance 2.0 视频输入折扣的问题。video_url 时,Seedance 2.0 计费没有应用视频输入价格的问题。ratio / generate_audio: false 未生效、视频可能按默认比例生成并带音频的问题。ratio 带前后空白时可能原样转发的问题,现在会按非空校验后的规范值发送。callback_url、service_tier、safety_identifier 显式传入空字符串时无法和未传字段区分,导致空值覆盖无法表达的问题。generate_audio 同时写入 WithAudio 和 GenerateAudio,造成官方字段和兼容回退字段语义混在一起的问题。content[] 且无顶层 prompt 的 Seedance JSON 请求在 DoubaoVideo 校验阶段可能被拒绝的问题。Param Override 改写 duration、resolution、size、视频输入等计费字段后,预扣费仍按改写前请求计算的问题。Param Override 改写最终上游 JSON 后,计费上下文可能没有同步最终请求体,导致分辨率、时长、音频或模型按改写前请求计费的问题。Param Override return_error 或无效规则被包装成 build_request_failed 500 上游错误,可能触发自动重试或渠道处罚的问题。Param Override 中的 set_header / pass_headers 等 header 联动只写入运行时状态、没有真正发送到上游的问题。Param Override 将计费字段写入上游专用 parameters、input 或媒体数组后,计费上下文没有同步这些最终字段的问题。image / images 时,又从同步后的 TaskSubmitReq 镜像字段重复累加 image_count,可能放大按图片数量匹配或计量的价格行的问题。request_body_mode、request_body_mapping、request_body_defaults 配置在前端保存后仍可能残留,导致后端拒绝或重复提交旧协议值的问题。base_url 同时包含 /v1 时可能拼出重复路径的问题。in_progress + 100% 的问题;解析到结果 URL 时会转为完成。progress: 100% 后从后台轮询和超时扫描中消失,导致任务长期卡住的问题。/v1/responses 难以接入只兼容 Chat Completions 的自定义上游的问题。response.completed 事件可能没有 usage 的问题。response.output 时,reasoning、搜索、电脑操作、文件搜索和 item reference 等非消息条目可能变成空 user 消息的问题。custom_tool_call 转成标准 Chat Completions 不支持的 type: "custom" 工具调用并继续转发的问题。tool_call_id,导致 assistant tool call 和 tool result 无法正确关联的问题。tool_calls 时,仅保留工具调用、丢失文本说明的问题。tool_use 在 OpenAI tool call arguments 为空时被跳过的问题;无效 JSON 参数现在会返回错误,避免静默发送空 input。arguments fallback 可能把 tool_use.input 输出为裸字符串、不符合 Anthropic object 要求的问题。arguments 缺少对齐测试覆盖的问题,Claude / Gemini fallback 行为现在都有回归测试保护。metadata.resolution,但计费仍可能读取顶层 resolution,导致请求按 720p 转发却按 1080p 计费的问题。resolution / ratio 时无法和未传字段区分的问题。doubao-seedance-2-0-fast-260128 在 1080p / 4k 搭配视频输入时缺少价格组合,可能没有应用视频输入倍率的问题。retry_log 和 empty_retry 标记时只被归类为空输出重试,导致错误重试筛选和统计少算的问题。BeforeCreate 与 BeforeSave 同时同步 retry 标记,导致 Other JSON 每次创建被重复解析的问题。jsonwrapcheck 过期 allowlist 条目,避免移除直接 encoding/json 调用后 CI 仍因 stale baseline 失败。tasks.private_data 新增 node_name JSON 字段;历史任务没有该字段时会回退使用当前处理节点,保持兼容。quota_data 表新增 use_group、token_id、channel_id、node_name 字段,升级后会随迁移自动补齐。NODE_NAME,这样异步任务日志和用量数据可以稳定归属到提交任务的实例。request_body_mode / mapping / defaults 字段;只保留路径覆盖的渠道会继续作为路径覆盖配置保存。task_protocol_config 不再包含请求体生成 DSL;需要原样透传请求体时使用渠道 Pass Through Body,需要字段映射或默认值时使用 Param Override。Param Override 现在会影响最终计费输入;如果旧配置曾通过默认值或字段改写改变时长、分辨率、尺寸或输入媒体,升级后预扣费会与实际上游请求保持一致。Param Override 把字段改写到上游专用的 parameters / input / 媒体数组结构,升级后这些字段也会进入计费推断;建议检查旧规则是否依赖改写前的低价默认值。image_count 作为匹配条件或数量字段时,顶层 image / images 只会按最终请求体计一次,reference_images 仍作为独立参考图输入计入。set_header / pass_headers 规则不会意外覆盖认证或内容类型。conversation、previous_response_id、prompt 或 context_management 时会返回明确错误。custom_tool_call、custom tool 或 freeform tool;Gemini 通道会在自身兼容路径中过滤这类不兼容工具。openai_responses_to_openai_chat_completions 转换器只匹配 /v1/responses 入站路径;其它路径仍按各自注册的转换器校验。0 或 false 在转发时丢失。function_call 带有 call_id 或 id,function_call_output 带有 call_id;缺失时会返回错误,调用方需要补齐有效 tool call 关联 ID。{}。arguments 时,会把原始字符串保存在 tool_use.input.arguments,不再把裸字符串直接作为 input。resolution / ratio 作为可选字段处理;显式空字符串会继续发送给上游,未提供字段才会省略。callback_url、service_tier、safety_identifier 和 ratio 也按可选字段处理;显式空字符串会保留,未传字段才会省略。metadata 覆盖优先级;已有通过 metadata 改写上游参数的渠道配置会继续优先生效。content[] 和顶层参数支持主要影响 JSON 请求体。.tmp/RELEASE_NOTES_v1.0.4.md 为内部发布草稿,不会进入 Git 提交;发布前如需公开版本,应复制到正式发布流程中重新审阅。go test ./relay/channel/task/doubaogo test ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channelgo test ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel/openai ./model ./servicego test ./model ./servicego test ./model -run "TestGetAllUnFinishSyncTasksIncludesNonTerminalHundredProgress|TestGetTimedOutUnfinishedTasksIncludesNonTerminalHundredProgress" -count=1go test ./service -run "TestShouldApplyTaskResultProgressSkipsNonTerminalCompleteProgress" -count=1go test ./service ./service/openaicompatgo test ./service/openaicompat ./relay/channel/claude ./relay/channel/gemini ./relay/channel/advancedcustom ./relay/channel/openaigo test ./service/openaicompat ./relay/channel/gemini ./relay/channel/advancedcustomgo test ./service/openaicompat -run "TestResponsesResponseToChatCompletionsResponse|TestResponsesRequestToChatCompletionsRequest"go test ./service -run "TestResponseOpenAI2(Gemini|Claude)"go test ./model -run "Test(SumUsedQuotaRetryFilter|GetAllLogsRetrySubtypeFilters|SumUsedQuotaRetrySubtypeFilters|RetryFilterIgnoresNestedRetryMarker|RetryFilterBackfillsLegacyMarkersBeforeCompletion|RetryFilterUsesIsRetryAfterBackfillCompletion)$"go test ./model -run "TestSumUsedQuotaKeepsRpmTpmLiveForHistoricalWindow"go run ./tools/jsonwrapcheckbun test src/components/html-content.test.ts src/components/ui/markdown.test.ts src/lib/renderable-content.test.ts src/hooks/notification-utils.test.ts src/stores/notification-store.test.ts src/features/usage-logs/lib/utils.test.ts src/features/playground/lib/query-state.test.ts src/features/playground/lib/selection-state.test.tsbun test tests/channel-form.test.tsbun run typecheckbun run build/playground/ with a 4000-character continuous prompt at 390px and 1280px viewport widthsgo test ./service -run "TestRecalculate_PositiveDeltaAttributesQuotaDataToSubmitNode"go test ./relay ./relay/channel ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel/task/gemini ./relay/channel/task/vertex ./relay/channel/task/ali ./relay/channel/task/kling ./controller -run "Test(PrepareTaskSubmitRequestBody|DoTaskApiRequestAppliesRuntimeHeaderOverride|ApplyTaskParamOverride|BuildConfiguredTask|EstimateBilling|EstimateTaskBilling|ShouldRetry)" -count=1go test ./controller ./relay ./relay/channel ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel/task/ali ./relay/channel/task/gemini ./relay/channel/task/kling ./relay/channel/task/vertex ./relay/common ./servicego test ./relay/channel/task/doubao ./relay/channel/task/taskcommon ./relay/channel ./relay -count=1go test ./relay/channel/task/taskcommon -run "TestEstimateGenericTaskBilling" -count=1go test ./relay -run "TestPrepareTaskSubmitRequestBody|TestEstimateTaskBilling" -count=1go test ./relay/channel/task/taskcommon ./relay/channel/task/doubao ./relay/channel/task/kling ./relay/channel/task/ali -count=1go test ./relay/channel ./relay -count=1bunx eslint src\features\channels\types.ts src\features\channels\lib\advanced-custom.tsgit diff --check -- relay/common/relay_info.go relay/channel/task/doubao/adaptor.go relay/channel/task/doubao/adaptor_billing_test.go relay/channel/task/taskcommon/request_body.go relay/channel/task/taskcommon/path_config_test.gogit diff --checkFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.3-preview.2...v1.0.4-preview.1
> 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
[!NOTE] 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3
empty_response 区分,避免影响 Gemini 等其它渠道的正常重试策略。NODE_NAME 时使用主机名作为节点名,并在返回信息中标记建议显式配置。pending、running、succeeded、failed 状态。LogTypeLogin 登录日志类型,为后续登录行为审计预留统一结构。scheduled_all:按计划测试全部可测试通道。passive_recovery:仅测试自动禁用通道,用于被动恢复。request_id、upstream_request_id 等精确筛选。Retry 筛选项,可单独查询普通渠道重试和 OpenAI 空补全重试日志。http / https URL 会作为 iframe 嵌入。http / https 地址进行嵌入展示。marked + DOMPurify 渲染与净化内容。[========] 分页分隔符和常用 emoji shortcode。clause.Locking 行锁封装。RowsAffected=0 时,会在事务内确认用户是否存在,避免把有效订单误判为用户不存在。is_retry 标记字段,用于直接索引重试日志;升级时会对已有日志按顶层 retry_log / empty_retry 标记回填。Retry 日志前会兜底确认回填完成,避免升级启动被历史日志阻塞,同时保证旧日志仍可被筛选。retry_log / empty_retry 标记,避免通过 use_channel 数组形态推断造成误匹配。admin_info.use_channel 和 retry_log 标记。Retry 过滤条件,降低列表筛选与统计摘要不一致的情况。All Types、Retry 和数字类型,保持前端本地列筛选与后端 API 查询语义一致。searchVersion 触发,避免首屏自动查询和重复刷新。LIKE '%%'。audit_info。+N。marked、katex、dompurify 支撑新的内容渲染能力。encoding/json。InitEnv 执行前后默认行为一致,并统一复用默认常量。STREAMING_TIMEOUT=0 作为关闭流式超时处理,不再创建非法 ticker。empty_response 在 EmptyCompletionRetryEnabled=false 时被误阻止重试的问题。empty_response 错误码导致跨渠道语义混淆的问题。response.completed、仅 EOF 结束时无法重试的问题。RowsAffected=0 误判失败的问题。pending 状态的问题。Retry 与数字日志类型混合残留、空类型值残留或本地列筛选短路时,可能导致实际查询退回未筛选或页面行未正确过滤的问题。other 字段推断,导致筛选和统计成本高、且嵌套审计字段可能误匹配的问题。STREAMING_TIMEOUT=0 时流式扫描器仍创建 ticker 并可能触发运行时 panic 的问题。parseInline 报错的问题。javascript: / data: 等危险协议未在渲染阶段提前降级的问题。system_instances 和 system_tasks 数据表,升级后会随迁移自动创建。NODE_NAME 节点标识支持;多节点、容器和 Kubernetes 部署建议显式配置,未配置时会使用主机名。stale。monitor_setting.channel_test_mode 配置项,默认 scheduled_all;设置为 passive_recovery 后定时任务只测试自动禁用通道。CHANNEL_TEST_FREQUENCY 环境变量仍会启用定时通道测试,并按兼容逻辑使用 scheduled_all 模式。EmptyCompletionRetryEnabled 配置项,默认关闭;启用时仍需配置 RetryTimes > 0。empty_response 独立为 empty_completion。empty_response 继续按普通状态码重试策略处理。SMTPStartTLSEnabled 和 SMTPInsecureSkipVerify 配置项。SMTP_STARTTLS_ENABLE / SMTP_STARTTLS_ENABLED、SMTP_INSECURE_SKIP_VERIFY / SMTP_TLS_INSECURE_SKIP_VERIFY 环境变量兼容读取。SMTPInsecureSkipVerify 默认关闭;只有在需要兼容自签名或特殊 SMTP 证书时才建议开启。token_setting.max_user_tokens 配置项,默认值为 1000。Retry 是独立筛选条件,通过 log_filter=retry 传递。logs 表新增 is_retry 字段并建立索引;迁移会按 LOG_SQL_DSN 维度记录回填完成标记,避免多日志库部署互相跳过回填。回填会异步调度,首次读取 Retry 日志时若尚未完成会同步兜底一次。All Types 会按未筛选处理;Retry 与具体日志类型混合时按 Retry 处理。STREAMING_TIMEOUT=0 现在表示关闭流式超时;保持默认配置时仍使用 300 秒。STREAMING_TIMEOUT、STREAM_SCANNER_MAX_BUFFER_MB、MAX_REQUEST_BODY_MB、ANONYMOUS_REQUEST_BODY_LIMIT_KB、AZURE_DEFAULT_API_VERSION、通知限制和任务限制等默认值被提升为常量并在包初始化阶段生效。custom 字段,旧配置按默认值兼容。anonymous 作用域。href 链接。marked、DOMPurify、KaTeX,旧的 react-markdown / remark-gfm / rehype-raw 依赖已移除。FOR UPDATE;MySQL / PostgreSQL 使用数据库行锁能力。go test ./...go test ./commongo test ./modelgo test ./model -run "Test(GetAllLogsRetryFilter|GetUserLogsRetryFilter|SumUsedQuotaRetryFilter)$"go test ./model -run "Test(BackfillLogRetryMarker|LogRetryMarker|RetryFilter)"go test ./model -run "Test(GetAllLogsRetryFilter|GetUserLogsRetryFilter|SumUsedQuota|RetryFilter|BackfillLogRetryMarker|MigrateLOGDBSchedulesRetryMarkerBackfill|ScheduleLogRetryMarkerBackfill|LogRetryMarker)"go test ./controllergo test ./controller -run "TestShouldRetry|Test.*Relay|Test.*Retry"go test ./relay/channel/openaigo test ./relay/helper -run "Test(NewStreamingTimeoutTicker|StreamScannerHandler_AllowsDisabledStreamingTimeout|StreamScannerHandler_StreamStatus_Timeout)$"go test ./service ./service/openaicompatgo test ./service -run "TestGenerateTextOtherInfo"go test ./service -run "Test(StreamFallbackQuota|PostTextConsumeQuotaUpdatesUsageStatsForStreamFallback|CalculateTextQuotaSummary)"go test ./constantbun test src/components/html-content.test.tsbun test src/components/ui/markdown.test.tsbun test src/lib/renderable-content.test.tsbun test src/features/playground/lib/query-state.test.tsbun test src/features/playground/lib/selection-state.test.tsbun test src/hooks/notification-utils.test.tsbun test src/stores/notification-store.test.tsbun test src/features/usage-logs/lib/utils.test.tsbunx eslint 针对变更的前端文件bun run typecheckbun run i18n:syncgit diff --checkFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.2...v1.0.3
Nothing published for this version
> 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
[!NOTE] 当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复,便于在真实环境中验证兼容性、稳定性和安全性;正式版将在对应 Preview 预览版稳定运行 1 周后正式发布,以保障系统安全性和可靠性。
https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3-preview.2
empty_response 区分,避免影响 Gemini 等其它渠道的正常重试策略。EmptyCompletionRetryEnabled。empty_completion,专用于 OpenAI Responses 空补全重试链路。clause.Locking 行锁封装。RowsAffected=0 时,会在事务内确认用户是否存在,避免把有效订单误判为用户不存在。searchVersion 触发,避免首屏自动查询和重复刷新。LIKE '%%'。empty_response 在 EmptyCompletionRetryEnabled=false 时被误阻止重试的问题。empty_response 错误码导致跨渠道语义混淆的问题。response.completed、仅 EOF 结束时无法重试的问题。RowsAffected=0 误判失败的问题。pending 状态的问题。EmptyCompletionRetryEnabled 配置项,默认关闭;启用时仍需配置 RetryTimes > 0。empty_response 独立为 empty_completion。empty_response 继续按普通状态码重试策略处理。custom 字段,旧配置按默认值兼容。FOR UPDATE;MySQL / PostgreSQL 使用数据库行锁能力。go test ./...go test ./modelgo test ./controllergo test ./relay/channel/openaigo test ./service ./service/openaicompatbunx eslint 针对变更的前端文件bun run typecheckbun run i18n:syncgit diff --checkGitHub地址:https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3-preview
GitHub地址:https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3-preview
v1.0.3 Preview 聚焦企业部署兼容性、AGI 治理审计、渠道可靠性、日志维护能力与后台管理体验优化。
本版本补齐了 SMTP STARTTLS / NTLM、完整登录与管理操作审计、系统任务式日志清理、被动渠道恢复、用户 Token 数量限制 UI、节点身份信息等能力,并修复了用户 ID 搜索、日志清理权限、批量渠道审计名称等问题。
QUIT 返回异常导致“已投递但被判定失败”的问题。LogTypeLogin = 7 登录日志类型。op.action / op.params 结构化字段。SystemTask 持久化任务模型。DELETE /api/log/ 同步删除兼容接口。LIMIT 限制的问题。passive_recovery 被动恢复模式,只针对真实失败后被自动禁用的渠道进行恢复探测。token_setting.max_user_tokens 后端限制能力。NodeName 未配置时自动回退到主机名。react-markdown + rehypeRaw 切换为 marked + DOMPurify。dompurify 升级到 3.4.11。DeleteOldLogBatch 在 SELECT 与 DELETE 之间 context 取消时仍可能继续删除的问题。data: count。login_method 字段,仅保留结构化 op.params.method。本版本已通过后端测试、Go vet、JSON wrapper 检查、前端 typecheck、针对性 ESLint 与 diff 检查。
Nothing published for this version
本次更新以界面重构、后台设置优化、鉴权安全加固和文档补全为主。
本次更新以界面重构、后台设置优化、鉴权安全加固和文档补全为主。
<img width="2560" height="1271" alt="image" src="https://github.com/user-attachments/assets/e032abea-fb70-4dd2-9fba-b0fe74032794" />
RankingsModule 从旧的 HeaderNavModules 中拆分为独立配置项,同时保留旧配置回退逻辑。audit_info。SESSION_COOKIE_SECURE 环境变量,用于控制 session cookie 是否启用 Secure。TRUSTED_PROXIES 覆盖。TokenAuthReadOnly 现在拒绝禁用和过期 token,仅允许额度耗尽 token 查询自身只读用量或日志。go vet、JSON wrapper policy、前端 typecheck 和 build。max-api-*。web workspace 安装依赖,再构建 web/default。1.3.14,提高 CI / Release 构建稳定性。tools/jsonwrapcheck,用于阻止新增业务代码直接调用 encoding/json。RankingsModule 已成为排行榜显示控制的新配置源;旧的 HeaderNavModules.rankings 仍作为兼容回退。TRUSTED_PROXIES 未配置时,默认信任本机与私网地址段;公网直连部署可按需收紧。SESSION_COOKIE_SECURE 默认仍为 false,HTTPS 部署建议显式设置为 true。go test ./common ./serviceFull Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.1...v1.0.2
Nothing published for this version
新增动态球形与轨道视觉,围绕 MAX API 的治理、路由、审计、计费等核心能力进行表达。
v1.0.0-4-g2a504c9v1.0.02a504c9 新版主页UI设计2026-06-20<img width="1902" height="1031" alt="image" src="https://github.com/user-attachments/assets/278a4182-9cb9-43a7-bd2f-e8f817c0202a" />
en、zh、fr、ja、ru、vi 语言文件。新增 GitHub 图标按钮,链接至:
https://github.com/MAX-API-Next/MAX-API
优化导航栏位置与移动端紧凑布局。
已通过以下检查:
git diff --checkbun run typecheckbun run build主要变更集中在:
web/default/src/features/home/web/default/src/components/layout/components/public-header.tsxweb/default/src/styles/index.cssweb/default/src/i18n/locales/本说明面向正在评估或准备从 New API 迁移的用户。基于当前 MAX API 代码与本地 new-api-1.0.0-rc.13 代码、README 和配置文档对比,MAX API v1.0.0 延续 New API/One API 的多模型网关、用户与令牌、计费、日志、Docker 部署和三数
本说明面向正在评估或准备从 New API 迁移的用户。基于当前 MAX API 代码与本地 new-api-1.0.0-rc.13 代码、README 和配置文档对比,MAX API v1.0.0 延续 New API/One API 的多模型网关、用户与令牌、计费、日志、Docker 部署和三数据库兼容基础,并进一步聚焦 AI 模型治理、AgentOps、渠道配置治理、异步任务治理和成本核算。
一句话概括:MAX API 不只是把多个模型接口统一到一个入口,而是把模型、渠道、令牌、计费、日志、异步任务和运维配置纳入一个可配置、可观测、可核算的治理层。
| 领域 | New API 已有基础 | MAX API v1.0.0 的改进 |
|---|---|---|
| 项目定位 | 多模型 API 网关与 AI 资产管理 | 明确扩展为 AI 模型治理、AgentOps 与应用服务基础设施,强调模型、渠道、Agent 调用链路、成本和审计的持续运营 |
| 渠道治理 | 支持多供应商渠道、模型映射、权重、分组和失败重试 | 增加渠道能力矩阵与配置校验,帮助管理员在保存前识别 Base URL、JSON 配置、模型发现、Codex 凭证、Vertex AI 区域、视频任务占位符等风险 |
| 自定义上游 | 支持 Advanced Custom 渠道与协议转换 | 强化按请求路径选择渠道的逻辑,使高级自定义渠道与普通渠道在缓存和数据库选择路径下保持一致;无效高级自定义配置会被跳过并记录错误,避免影响同模型下的健康渠道 |
| 多模态任务 | 已具备视频任务入口和部分供应商任务适配 | 新增通用视频任务协议,可配置提交路径、查询路径、任务 ID、状态、进度、结果 URL、错误字段和状态映射,减少为兼容型视频上游重复写适配器的成本 |
| 任务结果代理 | 支持任务状态查询 | 强化 /v1/videos/{task_id}/content 内容代理场景,便于在需要隐藏上游资源地址时通过网关返回任务结果 |
| 成本与计费 | 支持倍率、固定价格、表达式计费等基础 | 增加分阶段计费 JSON 统一维护入口,并新增 task_billing_setting.rate_cards 任务 rate-card 计费配置,适合按供应商、模型、时长、质量、音频、视频输入等参数核算异步任务成本 |
| 运维与文档 | 提供部署、环境变量、FAQ 等通用说明 | README 和安装文档改为围绕治理配置、能力矩阵、视频任务协议、计费 JSON、Docker 镜像和多机部署注意事项展开,更适合生产部署前核对 |
| 发布与镜像 | 使用 New API 镜像和仓库命名 | MAX API 使用独立镜像 cscitechtop/max-api:v1.0.0 与 cscitechtop/max-api:latest,服务名、部署示例、文档入口和支持入口已切换到 MAX API 体系 |
MAX API v1.0.0 将网关能力从“统一转发”进一步扩展为治理平面:
渠道新建和编辑流程新增更清晰的治理辅助能力:
chat/completions、responses、Claude Messages、Gemini native、embeddings、images、audio、rerank、video tasks、model discovery 等能力状态。v1.0.0 强化了 Advanced Custom 渠道在多路径、多优先级、多权重场景下的选择行为:
MAX API 将视频任务接入从固定供应商适配扩展为可配置任务协议。渠道可通过 task_protocol = "generic_video_task" 与 task_protocol_config 描述上游任务接口:
{
"task_protocol": "generic_video_task",
"task_protocol_config": {
"submit_path": "/v1/videos/create",
"query_path": "/v1/videos/{task_id}",
"task_id_path": "task_id",
"status_path": "status",
"progress_path": "progress",
"result_url_paths": [
"result.primary_url",
"result.urls.0",
"data.result.primary_url",
"url",
"video_url",
"download_url"
],
"error_message_path": "error_message",
"status_map": {
"queued": "QUEUED",
"running": "IN_PROGRESS",
"succeeded": "SUCCESS",
"failed": "FAILURE"
}
}
}
该能力适合路径、任务 ID、状态字段、进度字段、错误字段和结果 URL 字段可通过 JSON 路径描述的视频上游。查询路径支持 {task_id}、{operation_name} 和 {upstream_task_id},其中 {operation_name} 可保留多段路径,适配 Gemini / Vertex 风格的 operation 查询。
如果上游需要特殊签名、非标准认证、复杂请求体重写、回调机制或完全不同的任务生命周期,仍建议新增或扩展专用适配器,不应仅依赖配置项。
MAX API v1.0.0 对计费配置做了更适合生产维护的整理:
Tiered billing JSON 用于统一维护多个模型的分阶段计费规则,保存时同步更新 billing_mode 与 billing_expr。task_billing_setting.rate_cards 用于维护异步任务计费规则,可按 vendor 区分 Sora、Veo、Seedance、Kling 等供应商分区。示例:
{
"vendor/model-name": {
"vendor": "kling",
"unit": "second",
"quantity_field": "duration",
"default_quantity": 5,
"strict": true,
"defaults": {
"quality": "std",
"has_audio": "false"
},
"rows": [
{
"id": "std_no_audio",
"match": {
"quality": "std",
"has_audio": "false"
},
"unit_price": 0.6
}
]
}
}
v1.0.0 推荐直接使用 MAX API 镜像。固定生产版本可使用 v1.0.0 tag,跟随最新构建可使用 latest tag:
docker pull cscitechtop/max-api:v1.0.0
docker pull cscitechtop/max-api:latest
docker run --name max-api -d --restart always \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v ./data:/data \
cscitechtop/max-api:v1.0.0
生产环境建议使用 Docker Compose,并显式配置数据库、Redis、SESSION_SECRET、CRYPTO_SECRET、日志目录、HTTPS 反向代理和备份策略。
SESSION_SECRET;启用 Redis 或多机共享加密数据时,应配置相同的 CRYPTO_SECRET。cscitechtop/max-api:v1.0.0 或 cscitechtop/max-api:latest,并核对容器名、服务名、Pyroscope 应用名、仓库地址和文档入口。advanced_custom 配置是否能通过当前校验规则,以及每条路由的 incoming_path 是否覆盖真实请求路径。MAX API v1.0.0 延续并兼容 New API 与 One API 的开源基础,在此基础上面向模型治理、AgentOps、异步任务和成本核算场景做进一步工程化增强。感谢相关开源项目和社区生态的长期贡献。