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

83 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 企业网关增量建设(2026-10-13)
用户确认:在现有 MOYI 系统补齐 Sub2API 对比中发现的能力,保留 Java/Vue、账户、余额、权限、历史记录及发布体系。当前服务 B/G 端,通过合同对公付款;支付及订阅能力后置。现有管理员入账与审计流程继续使用。
## 本轮验收范围
- [x] 可用状态与真实适配器一致;标准 Embeddings 接口及按输入用量结算。
- [x] Messages、Responses、Gemini 原生协议入口,保留工具调用及流式事件;不支持的上游协议明确拒绝。
- [x] 渠道账号健康、暂时隔离、安全重试、会话绑定;跨渠道切换不得越过模型授权或改变本次用户售价。
- [x] 版本化价格快照,缓存写入、上下文阶梯;采购成本独立于用户扣费,未知成本不得当零成本。
- [x] 调用中断及用量缺失进入成本待核状态,支持人工对账与审计,避免重复扣费。
- [x] 用户总并发及请求限额,Key 到期/IP/总额和周期预算,所有协议共用准入与扣费限制。
- [x] 运营健康及错误率告警、持久化状态、冷却与通知配置。
- [x] TOTP 双因素认证、重放保护、恢复流程;后台及用户设置可操作。
- [x] 新增 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/原生协议,因此回退后应停止依赖这些新增能力。