New API / One API 托管迁移方案：模型映射、密钥权限、余额解释和回滚窗口

旧系统里模型名称、分组权限、余额和计费规则缺少文档，迁移当天容易集中爆发问题。

用户客户端已经配置旧 Base URL，切换通知不清楚会导致新旧入口混用。

客服没有统一话术，不知道应该收集哪些非敏感字段来判断迁移问题。

迁移前建立旧入口到新入口的模型、密钥、权限、余额和日志字段映射表。

按低风险任务、小流量用户和生产路径分阶段切换，保留清晰回滚窗口。

把迁移公告、FAQ、客服模板和检查清单同步发布，减少重复沟通。

模型映射表

把旧模型名映射到新入口真实调用名，区分可替代、需降级和暂不支持。

映射表包含旧名称、新名称、适用任务、风险说明和验证结果。

密钥和权限迁移

梳理旧 key、用户、分组、环境和权限，避免 401、403、402 集中出现。

迁移记录包含 owner、group、environment、quota、balance 和启用状态。

用户通知和客服话术

用公告、邮件、FAQ 和工单模板说明用户需要改哪些字段。

通知包含新旧入口、切换时间、回滚截止时间、排查字段和支持入口。

灰度和回滚

先切低风险路径，观察状态码、失败率、消耗和真实用户反馈，再扩大范围。

保留批次、切换时间、影响用户、回滚条件和实际结果。

冻结旧入口变更窗口，导出旧模型、密钥、分组、余额、调用方和近期错误统计。

建立新入口映射表，并用最小请求验证普通调用、stream、余额不足、限流和模型不可用场景。

先迁移内部测试和低风险脚本，再灰度少量真实用户，观察工单和用量记录。

发布迁移公告、配置邮件和客服模板，明确新入口、旧入口保留时间和回滚方式。

迁移结束后把旧文档、旧截图和旧客服话术下线或标记过期，避免用户继续传播。

什么时候适合托管迁移？

当旧系统维护成本高、渠道复杂、账单不清或故障排查依赖少数人时，托管统一入口更适合长期运营。

是否可以一次性全量切换？

不建议。真实用户、余额和生产流量存在不确定性，应保留灰度、观察和回滚窗口。

迁移后旧入口要保留多久？

保留时间取决于用户规模和客户端缓存，一般应覆盖至少一个观察周期，并明确停止时间。

迁移前后 401、402、429、model not found 和 timeout 的变化。

已切换用户占比、新旧入口残留流量和工单数量。

模型映射命中率、回滚次数和余额争议数量。

旧文档链接、旧配置截图和旧客服话术的下线完成度。

This solution describes managed migration from New API, One API, self-hosted gateways, or temporary proxies to a unified AI API entry point.

The important migration fields are old endpoint, new endpoint, model mapping, key mapping, permissions, balance, billing, notice, support evidence, rollout batch, and rollback window.

ALLTKN is useful when teams need to reduce gateway maintenance while preserving controlled rollout and support clarity.

迁移前最容易漏掉什么？

最容易漏掉模型真实调用名、旧 key 权限、余额解释、客户端缓存、stream 行为和失败任务是否扣费。

迁移公告是不是越短越好？

公告可以简洁，但必须写清用户要改什么、什么时候改、旧入口保留多久、出问题提供哪些非敏感字段。