70 lines
7.0 KiB
Markdown
70 lines
7.0 KiB
Markdown
# 企业网关增量建设(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 设置展示验证。
|
||
- 最终发布包另执行 Maven clean verify、18 项前端测试与 Vite 构建;线上验收结果在发布后补充。
|
||
|
||
## 部署与回退
|
||
|
||
使用 `scripts/package-deployment.ps1` 从干净提交生成 JAR、静态资源和校验清单。`infra/moyi/upgrade_release.py` 先备份现有数据库,再构建并启动同一个 Compose 项目,不执行 `docker compose down`。保留旧镜像和备份。
|
||
|
||
V35–V40 为新增表、列、索引和价格历史触发器。紧急回退优先切回旧应用镜像,保留新增数据库结构;除非明确接受备份后数据丢失,不覆盖恢复生产数据库。旧应用不理解新预算/MFA/原生协议,因此回退后应停止依赖这些新增能力。
|