Files
moyi-model-intelligence-hub/docs/19-enterprise-gateway-increment.md
T

8.2 KiB
Raw Blame History

企业网关增量建设(2026-10-13)

用户确认:在现有 MOYI 系统补齐 Sub2API 对比中发现的能力,保留 Java/Vue、账户、余额、权限、历史记录及发布体系。当前服务 B/G 端,通过合同对公付款;支付及订阅能力后置。现有管理员入账与审计流程继续使用。

本轮验收范围

  • 可用状态与真实适配器一致;标准 Embeddings 接口及按输入用量结算。
  • Messages、Responses、Gemini 原生协议入口,保留工具调用及流式事件;不支持的上游协议明确拒绝。
  • 渠道账号健康、暂时隔离、安全重试、会话绑定;跨渠道切换不得越过模型授权或改变本次用户售价。
  • 版本化价格快照,缓存写入、上下文阶梯;采购成本独立于用户扣费,未知成本不得当零成本。
  • 调用中断及用量缺失进入成本待核状态,支持人工对账与审计,避免重复扣费。
  • 用户总并发及请求限额,Key 到期/IP/总额和周期预算,所有协议共用准入与扣费限制。
  • 运营健康及错误率告警、持久化状态、冷却与通知配置。
  • TOTP 双因素认证、重放保护、恢复流程;后台及用户设置可操作。
  • 新增 V35–V40 迁移;单元与隔离 PostgreSQL、Redis 验证及前端类型检查通过。

后置范围

自助充值(支付宝/微信/Stripe/易支付)、用户付费套餐与订阅账号接入。本轮不要求用户提供商户或订阅账号凭据。

实施原则

以当前生产提交 512ca522(维护文档提交 1528b718)为起点,新增迁移,不修改已执行的迁移。所有金额采用人民币 Decimal/BigDecimal,保存调用时的价目快照。故障切换只在已确认未产生输出且允许重试的错误上进行;已经输出的流式响应不重新请求。对外接口和管理入口均保持原有鉴权边界。新增凭据加密存储,不返回给列表、日志或导出。外部源码仅供行为比较,独立实现。

实施记录

2026-10-13:完成上述增量实现,保留现有合同对公付款后的管理员额度入账与审计。

入口与操作

入口 可操作内容
管理端 → 企业调用策略 用户全部 Key 共用的 RPM、总并发、人民币月预算;默认 120 RPM / 16 并发,预算不限
用户端 → Key 安全与预算 到期时间、IPv4/IPv6/CIDR 白名单、总/日/月预算;周期按北京时间
管理端 → 价格版本与对账 维护人民币/百万 Token 的普通输入、输出、缓存读、5 分钟/1 小时缓存写入、上下文阶梯;采购成本独立填写;保留历史版本
同一页面 → 本月对账 查看用户消费、已知采购成本/利润,按渠道账单填写实际成本和依据;不更改用户扣费
同一页面 → 原生协议 按路由启用 Messages、Responses、Gemini,启用已授权的同模型备用渠道;上线默认不自动打开
管理端 → 渠道健康与告警 账号指纹、响应延迟、冷却状态、错误率阈值及站内告警;邮件通知默认关闭
账号设置 → 双因素认证 密码确认后配置认证器;6 位 TOTP,10 个一次性恢复码只展示一次
用户端 → 接入文档 原生协议请求示例、鉴权及使用限制;在线调试可提交 Embeddings

定价单位 1M tokens 等于 1,000,000 tokens(一百万 Token)。手工调整绝对金额后显示“自定义价格”,避免继续显示失效的旧折扣。原有渠道原价乘折扣的批量定价功能保留。本轮迁移不重算现有售价,不把未知采购成本填成 0。

计费与可靠性边界

  • 每次调用冻结售价版本和采购价格;价格编辑使用乐观冲突检查。撤下价格后新请求停止计费准入,已受理请求按原快照结算。
  • 所有 Key 共用用户预算与并发;异步任务也占用户并发,长任务 Redis 租约不会被短请求缩短。预算按已消费和在途预留检查;上游异常超出预留仍按真实用量记账,可能形成欠款并阻止后续调用。
  • 原生协议当前覆盖文本与本地函数工具。Responses 为完整上下文、store=false;不支持 previous_response_id、云端会话和后台任务。媒体、托管工具、外部缓存引用需要独立计费适配器,当前明确拒绝。
  • 原生接口不会自动假定所有渠道支持。管理员核实渠道能力后按路由启用;本轮使用本地 HTTP 模拟上游验证,没有批量发起收费模型调用。
  • 账号明确返回 401/403/429 时可尝试账号池中其他 Key;跨路由切换需显式开启,仅限 Key 已授权、同逻辑模型/类型/上游模型名的最多 2 个备用路由。仅明确拒绝受理或账号全部冷却可切换;超时、已开始输出的流不重试。
  • X-Moyi-Session 提供账号亲和性,纳入调用凭据隔离;不绕过健康、授权或限额。
  • 客户端断开时尽量继续读取最终用量;用量缺失或流不完整不估算用户扣费,释放预留并记录待对账成本。管理员可记录实际渠道损失。
  • IP 白名单使用可信代理解析后的地址;生产 Nginx 覆盖客户端伪造的转发头。直接运行后端时默认不信任转发头。
  • 站内告警每分钟评估;邮件仅管理员启用且 SMTP 已配置时发送,最多尝试 3 次。发送可能因进程中断重复,使用告警编号识别。
  • TOTP 密钥加密,恢复码只存哈希;动态码防重放,错误尝试 5 次后限制 5 分钟。已有用户不会被自动开启 MFA。

验证记录

  • 2026-10-13 18:56:scripts/test_enterprise_increment.py,118 个 Java 测试全部通过,0 跳过;使用全新本机 PostgreSQL 17,完成后停止。日志:.tools/enterprise-test-67yhxfz7/tests.log。
  • Redis Lua 实测通过:共享用户并发、拒绝超额、释放、RPM、长短租约共存;仅使用唯一前缀临时键并清理,不触碰业务键。
  • 部署工具:37 项中 33 项通过;4 项旧凭据维护测试要求单独固定端口 PostgreSQL,未启动该专用环境,明确跳过。真实 Docker Compose 插值和 HTTPS 覆盖测试通过。
  • Vue 类型检查通过;本地隔离浏览器完成登录、企业预算保存、空价格首次配置/重复保存、告警页面、Key 空状态、MFA 设置展示验证。
  • 19:07:追加的异步领取回滚测试通过,GatewayDeploymentTest 共 19 项通过。该修复避免数据库领取失败遗留 Redis 长租约。
  • 最终发布包完成 Maven clean verify、18 项前端测试、Vue 类型检查与 Vite 构建。打包时未启动数据库,因此数据库测试由上面的独立全量运行提供证据。

上线结果

  • 发布:20261013-191204-af43947b;应用提交:af43947b。
  • 发布包 SHA-256:826a633e402c26dac413f512a147d3a321f805d0db03c4ea515c04bc84c6093b。
  • 备份:/opt/moyi/backups/pre-upgrade-q5e8c_ez,已验证归档可读取。
  • 生产目录:/opt/moyi/releases/20261013-191204-af43947b/infra/moyi。
  • 前后端容器健康,HTTPS、管理员登录、会话及原有管理接口通过;数据库迁移到 V40。
  • 366 条模型目录的价格与状态校验一致;用户、Key 保留,钱包快照完全一致。
  • 原生四类接口未登录返回 401;新管理接口未登录拒绝访问,登录后价格历史、企业策略、成本对账、运营告警返回正常。
  • MFA 与邮件通知默认关闭,没有自动启用任何用户认证器、付费订阅或商户渠道。
  • 验收结果文件:outputs/sub2api-comparison-20261013/enterprise-verification.json;本地界面截图:同目录 enterprise-policy-preview.jpg。

部署与回退

使用 scripts/package-deployment.ps1 从干净提交生成 JAR、静态资源和校验清单。infra/moyi/upgrade_release.py 先备份现有数据库,再构建并启动同一个 Compose 项目,不执行 docker compose down。保留旧镜像和备份。

V35–V40 为新增表、列、索引和价格历史触发器。紧急回退优先切回旧应用镜像,保留新增数据库结构;除非明确接受备份后数据丢失,不覆盖恢复生产数据库。旧应用不理解新预算/MFA/原生协议,因此回退后应停止依赖这些新增能力。