v1.0.3

Note

当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复，便于在真实环境中验证兼容性、稳定性和安全性；正式版将在对应 Preview 预览版稳定运行 1 周后正式发布，以保障系统安全性和可靠性。

MAX API v1.0.3 正式版 Release Notes

GitHub 地址

https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3

Highlights

• 新增系统信息与系统任务运维视图，Root 管理员可查看多节点实例心跳、资源状态、任务进度和历史执行结果。
• 日志清理改为持久化系统任务执行，支持进度回写、任务锁、历史记录和前端进度展示，避免大批量删除日志时阻塞请求。
• 加强支付、订阅、兑换码、邀请额度和任务计费链路的一致性，降低重复回调、重复兑换、重复退款和并发扣减造成的错账风险。
• 新增 OpenAI Chat / Responses 空补全重试能力，并将内部空补全错误码与通用 empty_response 区分，避免影响 Gemini 等其它渠道的正常重试策略。
• 优化用量日志加载体验：页面进入后不再自动查询大批量日志，搜索后加载列表，详情正文按需打开。
• 完善后台运维能力：新增管理操作审计、SMTP STARTTLS / NTLM 兼容、通道自动测试模式、批量模型测试进度和用户令牌数量限制设置。
• 首页与 Markdown 渲染能力增强，支持自定义首页按 URL、HTML、Markdown 自动识别，并改进公式、图表和富文本内容展示。
• Markdown 内容净化进一步加固，在测试 / SSR 等非浏览器环境下不再回退输出原始 HTML，并提前拦截危险链接协议。
• 修复公告栏 Markdown 链接渲染崩溃，并恢复用户打开网页后的公告自动弹出体验。
• 继续完善前台交互体验：登录 / 注册协议确认、游乐场一键清空、模型 / 分组选择保护，以及首页、关于页、公告和法务文档的统一富文本渲染。
• 补强流式请求和用量统计边界：异常流式结束且上游未返回 usage 时会按预扣额度兜底结算，并修正重试日志统计、环境默认值和可关闭流式超时等运行时细节。

New Features

• 新增 Root 专属“系统信息”页面：
  • 展示当前部署实例列表、在线 / 离线状态、Master / Worker 角色、运行时版本、启动时间和最后心跳时间。
  • 展示 CPU、内存、磁盘使用情况，便于多节点部署时快速定位异常实例。
  • 支持删除已离线实例记录，在线实例会被后端拒绝删除。
• 新增系统实例心跳上报机制：
  • 节点默认每 30 秒上报一次实例状态。
  • 未配置 NODE_NAME 时使用主机名作为节点名，并在返回信息中标记建议显式配置。
• 新增持久化系统任务模型：
  • 支持 pending、running、succeeded、failed 状态。
  • 支持任务锁、执行节点、进度状态、执行结果和错误信息记录。
  • Root 管理员可查看系统任务列表、当前活跃任务和任务历史。
• 日志清理新增异步系统任务：
  • 后台日志维护页启动清理任务后显示进度条。
  • 后端按批次删除旧日志并持续回写进度。
  • 同一时间只保留一个活跃日志清理任务，重复触发会返回当前任务。
• 新增结构化管理操作审计：
  • 覆盖用户、渠道、兑换码、系统配置、Passkey、OAuth 解绑、手动补单等关键管理操作。
  • 审计日志记录操作标识、参数、管理员信息、认证方式、路由和响应状态。
  • 新增 LogTypeLogin 登录日志类型，为后续登录行为审计预留统一结构。
• SMTP 邮件能力增强：
  • 支持机会式 STARTTLS。
  • 支持强制 STARTTLS。
  • 支持 465 端口隐式 TLS。
  • 支持 NTLM / LOGIN / PLAIN 自动认证选择。
  • 支持服务器未声明 AUTH 时跳过认证发送。
  • 后台 SMTP 设置新增安全模式和 TLS 校验相关配置。
• 通道自动测试新增模式配置：
  • scheduled_all：按计划测试全部可测试通道。
  • passive_recovery：仅测试自动禁用通道，用于被动恢复。
• 通道连接测试弹窗增强：
  • 支持对筛选后的模型批量测试。
  • 展示批量测试进度、成功数和失败数。
  • 支持一键选择测试成功的模型。
  • 支持复制选中的模型列表。
  • 模型价格未配置时提供更明确的失败说明。
• 安全设置新增“Token Limits”配置，可在后台调整每个用户最多可创建的令牌数量。
• 用量日志新增详情接口：
  • 管理员可按需查看完整日志详情。
  • 普通用户只能查看自己的日志详情。
  • 列表默认隐藏请求 / 响应审计正文，详情弹窗按需加载完整内容。
• 用量日志筛选增强：
  • 支持 request_id、upstream_request_id 等精确筛选。
  • 任务日志和普通日志筛选栏补齐相同的请求 ID 查询能力。
  • “所有类型”中新增 Retry 筛选项，可单独查询普通渠道重试和 OpenAI 空补全重试日志。
• 用户管理新增余额状态筛选：
  • 负余额
  • 零余额
  • 正常余额
• 用户余额列新增负余额异常标记和说明提示。
• 顶部导航新增自定义导航项配置，支持名称、链接和启用状态，并支持外部链接在桌面端与移动端统一展示。
• 个人菜单新增系统信息入口，并遵循侧边栏模块可见性配置。
• 自定义首页内容支持 URL、HTML、Markdown 自动识别：
  • 完整 http / https URL 会作为 iframe 嵌入。
  • HTML 片段会直接作为自定义首页内容渲染。
  • 其它内容按 Markdown 渲染。
• 公告中心恢复页面打开后的自动弹出能力：
  • 有系统通知或公告内容时，页面会自动打开公告中心。
  • “今日关闭”会在当天抑制后续自动弹出。
  • 自动打开默认优先展示未读通知或未读公告。
• 公告中心新增“今日关闭”操作，登录后和公开页面的通知入口都会共享当天关闭状态。
• 关于页、公告详情、用户协议和隐私政策等内容页统一支持富文本渲染：
  • Markdown 内容继续走 Markdown 渲染器。
  • HTML 片段会先净化再渲染。
  • 纯 iframe 片段可提取安全 http / https 地址进行嵌入展示。
• Markdown 渲染器增强：
  • 改用 marked + DOMPurify 渲染与净化内容。
  • 支持 GFM、表格、任务列表、外链安全属性。
  • 支持 KaTeX 数学公式。
  • 支持简单 flow / sequence 图表代码块。
  • 支持 [========] 分页分隔符和常用 emoji shortcode。
• 登录 / 注册页协议确认交互增强：
  • 用户协议和隐私政策勾选项会覆盖密码登录、Passkey、OAuth 和微信登录入口。
  • 未勾选时在用户实际提交或点击第三方登录时提示错误，并自动聚焦到勾选项。
  • 登录 / 注册按钮不再因为未勾选协议而直接置灰，降低用户不知道原因的情况。
• 游乐场新增“一键清除聊天历史”操作：
  • 有对话记录时可直接清空当前聊天。
  • 生成中会禁用清空操作，避免与正在进行的请求冲突。
  • 当前模型或分组不可用时会阻止继续发送，避免使用失效选择发起请求。
• 兑换码批量复制改为只复制兑换码本身，方便直接分发。
• README 新增稳定版 / Preview 预览版发布渠道说明，并同步到多语言文档。

Improvements

• 支付、订阅、兑换码等事务路径统一使用 GORM v2 clause.Locking 行锁封装。
• MySQL 下用户额度更新遇到 no-op RowsAffected=0 时，会在事务内确认用户是否存在，避免把有效订单误判为用户不存在。
• Stripe / Creem / Waffo / Waffo Pancake / 手动补单等充值路径统一加强额度写入校验。
• 兑换码创建和更新增加服务端额度正数校验，并补充后端 i18n 文案。
• 订阅订单完成、过期、余额支付、预扣退款、用量回写等路径加强事务状态判断和幂等处理。
• 订阅计费使用数据库事务时间，减少应用时间和数据库时间不一致导致的边界问题。
• 订阅负向用量调整返回实际生效 delta，日志和结算字段按实际可退额度记录。
• 邀请额度转余额增加并发扣减保护，避免并发兑换时重复扣减或超额转换。
• 用户禁用、升降级等管理操作会主动失效用户缓存和令牌缓存，降低旧缓存继续生效的风险。
• 日志删除从同步批量删除升级为系统任务执行，提升大表日志清理的可靠性和可观测性。
• 日志查询改进精确文本筛选，减少空关键字和宽泛匹配造成的大范围扫描。
• 日志模型新增 is_retry 标记字段，用于直接索引重试日志；升级时会对已有日志按顶层 retry_log / empty_retry 标记回填。
• 重试日志回填改为迁移后异步执行；读取 Retry 日志前会兜底确认回填完成，避免升级启动被历史日志阻塞，同时保证旧日志仍可被筛选。
• 重试日志筛选改为依赖 retry_log / empty_retry 标记，避免通过 use_channel 数组形态推断造成误匹配。
• 成功日志与错误日志复用同一套重试元数据组装逻辑，统一写入 admin_info.use_channel 和 retry_log 标记。
• 用量统计的额度、RPM、TPM 查询统一应用时间范围、日志类型、模型、用户、令牌、渠道、分组和 Retry 过滤条件，降低列表筛选与统计摘要不一致的情况。
• 用量日志类型筛选统一归一化空值、All Types、Retry 和数字类型，保持前端本地列筛选与后端 API 查询语义一致。
• 用量日志类型允许值统一由筛选配置导出，路由校验和筛选栏复用同一来源，降低后续新增类型时的配置漂移风险。
• 用量日志列表和统计统一由 searchVersion 触发，避免首屏自动查询和重复刷新。
• 用量日志页默认分页调整为 100 条，降低大表查询压力。
• 用户搜索在关键字为空时不再拼接全字段 LIKE '%%'。
• 用量日志展示新增模型徽标、用量统计摘要和更清晰的详情弹窗布局。
• 用户侧日志会剥离管理员专用字段，仅暴露允许用户可见的 audit_info。
• OpenAI Responses 兼容层增强：
  • 支持 refusal 文本提取。
  • 空输出可触发重试。
  • EOF 且无可见输出时也可触发空补全检测。
  • 流式前置事件增加缓冲上限，避免无界占用内存。
  • 空补全不会触发自动禁用通道。
  • 记录空补全重试链路，便于排查。
• 自动通道测试支持“只测试自动禁用通道”模式，减少定时任务对正常通道的额外请求压力。
• 批量新增通道逻辑拆分出可测试构造函数，并补充后端测试覆盖。
• 通道密钥查看、通道增删改、标签批量操作和上游模型应用等管理动作写入结构化审计日志。
• 渠道模型展示优化：添加 / 编辑渠道时的模型多选框，以及渠道列表的 Models 列会直接展示全部模型标签，不再折叠为 +N。
• SMTP 发送流程统一走显式 client 流程，便于支持 STARTTLS、隐式 TLS、认证协商和错误处理。
• 前端设置页补齐 SMTP 安全模式、通道测试模式、空补全重试、令牌数量限制等新配置项。
• 公告中心的已读和自动弹出去重改为内容签名：
  • 同一后端公告 ID 的内容被编辑后会被识别为新版本。
  • 相同公告集合即使服务端返回顺序变化，也不会被误判为新内容。
  • 已读公告、已读系统通知和“今日关闭”状态按用户隔离存储，避免切换账号后互相影响。
  • 自动弹出记录提升到当前页面加载内的共享状态，公共页面切换导致 Header 重新挂载时不会重复弹出同一内容。
  • 手动打开和定时器取消等边界场景下仍会正确记录已展示内容。
• 移动端抽屉支持自定义外部导航链接。
• 侧边栏模块可见性逻辑复用于个人菜单，避免被禁用的模块仍在菜单中出现。
• 数据表批量操作栏、移动端卡片列表和部分后台表格交互细节优化。
• 游乐场模型和分组加载逻辑改进：接口短暂失败时保留已有选项，选中项不可用时自动回落到可用模型或默认分组。
• 前端依赖更新：升级 TanStack Router 相关包，引入 marked、katex、dompurify 支撑新的内容渲染能力。
• JSON wrapper 检查工具清理失效 allowlist 条目，继续限制业务代码直接调用 encoding/json。
• 环境变量驱动的运行时配置补齐包级默认值，保证 InitEnv 执行前后默认行为一致，并统一复用默认常量。
• 流式扫描器支持将 STREAMING_TIMEOUT=0 作为关闭流式超时处理，不再创建非法 ticker。
• 文本、音频和实时流式计费在异常结束且 quota 为 0 时，会优先使用实际预扣额度兜底结算；没有实际预扣记录时回落到模型预扣配置。

Bug Fixes

• 修复 Gemini empty_response 在 EmptyCompletionRetryEnabled=false 时被误阻止重试的问题。
• 修复 OpenAI 空补全内部重试复用通用 empty_response 错误码导致跨渠道语义混淆的问题。
• 修复 Responses / Chat 流式空补全在缺少 response.completed、仅 EOF 结束时无法重试的问题。
• 修复 Responses 流式处理在首个可见内容前无界缓存 SSE 事件导致 TTFB 和内存风险的问题。
• 修复纯空白 delta 可能被误判为可见输出的问题。
• 修复兑换码重复兑换可能导致重复加余额的问题。
• 修复零额度或负额度兑换码可能进入后续兑换链路的问题。
• 修复 MySQL no-op 更新可能导致有效充值或兑换被 RowsAffected=0 误判失败的问题。
• 修复订阅订单重复完成时可能重复创建订阅或充值记录的问题。
• 修复订阅预扣退款重复执行时可能重复返还额度的问题。
• 修复订阅余额支付在余额不足时可能越界扣减的问题。
• 修复订阅用量负向调整可能低于 0 或日志记录超额退款的问题。
• 修复部分支付网关回调状态更新未严格限制 pending 状态的问题。
• 修复邀请额度转余额的并发扣减一致性问题。
• 修复用户管理余额筛选在空关键字下仍触发全字段模糊搜索的问题。
• 修复日志列表展示序号与日志详情真实 ID 混用的问题。
• 修复用量日志 Retry 与数字日志类型混合残留、空类型值残留或本地列筛选短路时，可能导致实际查询退回未筛选或页面行未正确过滤的问题。
• 修复历史重试日志只能通过解析 other 字段推断，导致筛选和统计成本高、且嵌套审计字段可能误匹配的问题。
• 修复重试日志回填在迁移阶段同步执行时，历史日志量较大可能拖慢或阻塞服务启动的问题。
• 修复重试日志统计在显式日志类型、时间范围或 RPM / TPM 查询中可能没有完整套用筛选条件的问题。
• 修复流式请求超时、客户端断开、扫描错误、ping 失败或 panic 后，上游未返回 usage 时可能记录 0 额度消费的问题。
• 修复 STREAMING_TIMEOUT=0 时流式扫描器仍创建 ticker 并可能触发运行时 panic 的问题。
• 修复部分环境变量配置在应用初始化前仍为 Go 零值，导致默认流式超时、文件大小限制、通知频率、任务超时等配置不一致的问题。
• 修复日志清理请求取消、长时间运行和前端无进度反馈的问题。
• 修复通道自动测试在被动恢复场景下仍可能触发自动禁用的问题。
• 修复通道测试模型表格在筛选、分页和批量选择时选择状态不稳定的问题。
• 修复 SMTP 服务器支持 STARTTLS 时未自动升级连接的问题。
• 修复强制 STARTTLS 时服务端不支持 STARTTLS 仍继续发送的问题。
• 修复 465 端口隐式 TLS、无 AUTH 服务端、QUIT 阶段连接关闭等邮件发送兼容问题。
• 修复点击或打开包含 Markdown 链接的公告时可能出现 parseInline 报错的问题。
• 修复公告栏自动弹出逻辑缺失，导致用户打开网页后不再自动看到公告的问题。
• 修复同一公告 ID 内容更新后仍被视为已读、不会再次提示的问题。
• 修复公告返回顺序变化时自动弹出去重签名抖动的问题。
• 修复公告中心手动打开后关闭时，同一内容可能立即再次自动弹出的问题。
• 修复公告自动弹出定时器被取消时提前记录签名，导致后续真正需要弹出时被跳过的问题。
• 修复公告已读和“今日关闭”状态未按用户隔离，切换账号后可能继承上一个用户通知状态的问题。
• 修复自定义首页 HTML / iframe 内容可能被当作普通 Markdown 展示的问题。
• 修复关于页、公告详情和法务文档中 HTML 片段可能未走统一净化渲染的问题。
• 修复 Markdown sanitizer 在无可用 DOMPurify 实例时可能返回未净化 HTML 的安全问题。
• 修复 Markdown 链接中 javascript: / data: 等危险协议未在渲染阶段提前降级的问题。
• 修复 Markdown 外链、公式、图表和部分 HTML 内容渲染不完整的问题。
• 修复登录 / 注册页在未勾选协议时直接禁用提交或第三方登录入口，导致用户缺少明确错误提示的问题。
• 修复游乐场模型或分组加载失败后仍可能保留不可用选择并继续发送请求的问题。
• 修复系统信息入口未遵循侧边栏模块配置的问题。

Compatibility Notes

• 新增 system_instances 和 system_tasks 数据表，升级后会随迁移自动创建。
• 新增 NODE_NAME 节点标识支持；多节点、容器和 Kubernetes 部署建议显式配置，未配置时会使用主机名。
• 系统实例超过 90 秒未上报会被标记为 stale。
• 日志清理行为变化：前端会启动异步系统任务并显示进度，不再依赖一次请求内同步删除全部旧日志。
• 新增 monitor_setting.channel_test_mode 配置项，默认 scheduled_all；设置为 passive_recovery 后定时任务只测试自动禁用通道。
• CHANNEL_TEST_FREQUENCY 环境变量仍会启用定时通道测试，并按兼容逻辑使用 scheduled_all 模式。
• 新增 EmptyCompletionRetryEnabled 配置项，默认关闭；启用时仍需配置 RetryTimes > 0。
• OpenAI 空补全内部错误码从通用 empty_response 独立为 empty_completion。
• Gemini 等其它渠道返回的 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。
• 用量日志页行为变化：进入页面不会立即加载日志，需要点击“搜索”。
• 用量日志默认分页大小调整为 100。
• 用量日志详情按需加载；列表中不再直接携带完整请求 / 响应审计正文。
• 用量日志 Retry 是独立筛选条件，通过 log_filter=retry 传递。
• logs 表新增 is_retry 字段并建立索引；迁移会按 LOG_SQL_DSN 维度记录回填完成标记，避免多日志库部署互相跳过回填。回填会异步调度，首次读取 Retry 日志时若尚未完成会同步兜底一次。
• 若 URL 或列筛选状态残留空值 / All Types 会按未筛选处理；Retry 与具体日志类型混合时按 Retry 处理。
• STREAMING_TIMEOUT=0 现在表示关闭流式超时；保持默认配置时仍使用 300 秒。
• 异常结束的流式请求在无上游 usage 且存在预扣额度时，可能会从此前 0 额度记录变为按预扣额度结算，以避免超时或断连场景漏计费。
• STREAMING_TIMEOUT、STREAM_SCANNER_MAX_BUFFER_MB、MAX_REQUEST_BODY_MB、ANONYMOUS_REQUEST_BODY_LIMIT_KB、AZURE_DEFAULT_API_VERSION、通知限制和任务限制等默认值被提升为常量并在包初始化阶段生效。
• 顶部导航配置结构新增 custom 字段，旧配置按默认值兼容。
• 自定义首页、关于页和法务文档内容现在会自动识别 URL、HTML、Markdown；HTML 内容会经过前端净化，脚本等不安全内容不会按原样执行。
• 公告中心自动弹出会记录当前页面加载内的用户级内容签名；同一内容在 Header 重新挂载或页面内路由切换时不会重复自动弹出，刷新页面后会重新计算。
• 公告中心已读状态和“今日关闭”状态会迁移为按用户作用域存储；旧匿名状态会迁移到 anonymous 作用域。
• 点击“今日关闭”后当天不再自动弹出。
• Markdown 净化失败时会失败关闭并渲染空内容，而不是输出未净化 HTML；不安全链接协议会被降级为普通文本或无 href 链接。
• Markdown 渲染依赖变更为 marked、DOMPurify、KaTeX，旧的 react-markdown / remark-gfm / rehype-raw 依赖已移除。
• 行锁封装在 SQLite 下不会启用 FOR UPDATE；MySQL / PostgreSQL 使用数据库行锁能力。
• 订阅用量调整函数返回值发生变化，内部调用已同步为实际应用 delta。
• 管理操作会新增结构化管理日志，开启审计和日志留存的部署需要注意日志量增长。

Verification

• go test ./...
• go test ./common
• go test ./model
• go 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 ./controller
• go test ./controller -run "TestShouldRetry|Test.*Relay|Test.*Retry"
• go test ./relay/channel/openai
• go test ./relay/helper -run "Test(NewStreamingTimeoutTicker|StreamScannerHandler_AllowsDisabledStreamingTimeout|StreamScannerHandler_StreamStatus_Timeout)$"
• go test ./service ./service/openaicompat
• go test ./service -run "TestGenerateTextOtherInfo"
• go test ./service -run "Test(StreamFallbackQuota|PostTextConsumeQuotaUpdatesUsageStatsForStreamFallback|CalculateTextQuotaSummary)"
• go test ./constant
• bun test src/components/html-content.test.ts
• bun test src/components/ui/markdown.test.ts
• bun test src/lib/renderable-content.test.ts
• bun test src/features/playground/lib/query-state.test.ts
• bun test src/features/playground/lib/selection-state.test.ts
• bun test src/hooks/notification-utils.test.ts
• bun test src/stores/notification-store.test.ts
• bun test src/features/usage-logs/lib/utils.test.ts
• bunx eslint 针对变更的前端文件
• bun run typecheck
• bun run i18n:sync
• git diff --check

Full Changelog: v1.0.2...v1.0.3