企业官网建设流程全解析

TokenHub是一个企业级私有 AI 模型网关，把原本散落在各处的模型访问统一成可控、可追踪、可归因的入口。如果你正在使用LiteLLM作为 AI 网关，TokenHub 内置的tokenhub-migrate迁移工具可以把你的proxy_config.yaml一键转化为迁移包（bundle），通过extract → plan → apply → verify → rollback五个步骤，平滑、幂等地搬进 TokenHub，全程无需手写任何配置。本文就是这套迁移流程的完整教程。

为什么需要把 LiteLLM 迁移到 TokenHub？

很多团队用 LiteLLM 起步，但随着规模扩大会遇到这些问题：

• 配置即代码，缺少统一的审计与治理面板；
• 预算、用量、成本分散在各处，难以按团队/项目归因；
• 路由、限流、密钥轮换依赖人工维护，风险高。

TokenHub 的迁移框架正是为解决"迁移成本高"而设计：它把源网关（目前是 LiteLLM）的配置抽取为一个无密钥的标准化 JSON 包（Canonical Bundle），再幂等地写入 TokenHub。整个过程可预演（plan）、可校验（verify）、可回滚（rollback），对新手非常友好。

📖 延伸阅读：docs/migration/README.md、docs/migration/architecture.md

迁移前先看懂：三阶段架构

迁移框架采用清晰的三阶段设计（详见 docs/migration/architecture.md）：

迁移最终通过 TokenHub 的Admin API完成，因此你的 TokenHub 实例必须是持久化部署（如配合 PostgreSQL），内存临时实例会被 CLI 直接拒绝。

版本与功能兼容性速查

LiteLLM 适配版本要求：>=1.52.0, <1.70.0。核心功能映射如下（完整表格见 docs/migration/litellm.md）：

⚠️ 注意：预算限制、fallback 链、guardrails、回调等非 OpenAI 兼容特性目前只会在报告中产生warning，迁移前请人工确认这些配置是否需要另行处理。

准备工作：获取 tokenhub-migrate 工具

从源码构建 CLI（源码入口在 backend/cmd/tokenhub-migrate/main.go）：

git clone https://gitcode.com/gh_mirrors/to/TokenHub cd TokenHub/backend go build -o tokenhub-migrate ./cmd/tokenhub-migrate/

然后确认目标 TokenHub 实例的管理员凭证：

export TOKENHUB_API=http://localhost:8080 export TOKENHUB_ADMIN_TOKEN=<admin-token>

第 0 步：inspect —— 体检一下源配置

正式迁移前，先用inspect让 CLI 快速"体检"你的 LiteLLM 配置，确认版本和可迁移内容：

tokenhub-migrate inspect litellm --from proxy_config.yaml

一个典型的小规模配置长这样（仓库自带示例：sdk/migration-e2e/fixtures/proxy_config.yaml）：

model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY key_management_settings: teams: - team_id: team-red virtual_keys: - key_alias: red-team-key team_id: team-red

如果输出中出现了无法识别的字段，先处理掉再继续。

第 1 步：extract —— 抽取迁移包

extract会把 LiteLLM 配置转化为标准化的bundle.json，这是整个迁移的"中间形态"：

tokenhub-migrate extract litellm --from proxy_config.yaml --out bundle.json

两个值得了解的细节：

• 密钥零落地：os.environ/OPENAI_API_KEY这类引用会被保留为{"$secretRef": "OPENAI_API_KEY"}，内联明文 API key 也会被转成 SecretRef，bundle 里永远不会出现明文密钥（schema 详见 docs/migration/bundle-schema.md）。
• ID 策略：默认使用prefixed（源前缀 + 哈希）生成 TokenHub 资源 ID；如果想保留 LiteLLM 原始 ID，可以加--id-strategy source。

抽取完成后，bundle 里会包含 providers、models、routes、teams、users、api_keys 等资源数组，以及一组按info / warn / blocker分级的 warnings——先通读一遍 warnings，再进入下一步。

第 2 步：plan —— 先预演，再动手

plan是一个只读干跑（dry-run）：它连接目标 TokenHub 实例，报告"如果现在 apply 会发生什么变化"，但不做任何写入：

tokenhub-migrate plan --bundle bundle.json

这一步是你确认迁移范围的最佳时机：检查即将创建的 Provider、Route、API Key 数量是否符合预期，有没有意外覆盖已有资源。确认无误后进入正式执行。

第 3 步：apply —— 正式执行迁移

建议先跑一次带--dry-run的 apply 验证参数，再正式执行：

# 干跑：只验证，不写入 tokenhub-migrate apply --bundle bundle.json --dry-run # 正式执行 tokenhub-migrate apply --bundle bundle.json

成功 apply 后会生成两个权限 0600的敏感文件，请妥善保管并及时分发/销毁：

如果密钥来自文件而非环境变量，可指定密钥源：

tokenhub-migrate apply --bundle bundle.json --secret-source file --secret-file migration.secrets

📖 更多标志与退出码说明见 docs/migration/cli.md。

⚠️两个重要注意事项：

1. 用户导入依赖邮件通道：bundle 中新建的用户会通过 Admin CSV 导入，要求目标实例启用了邮件通知渠道，否则 apply 会失败（每个导入用户会收到密码重置邮件）。
2. 远程 apply 不是事务：若后面的资源失败，前面的资源可能已变更。CLI 仍会写出部分回滚检查点，并以退出码5结束——此时直接用rollback恢复。

第 4 步：verify —— 校验迁移一致性

apply 完成后，用verify对照 bundle 与目标实例的实际状态，确认迁移结果"对得上"：

tokenhub-migrate verify --bundle bundle.json

• 全部一致 → 退出码0；
• 发现不一致 → 退出码3，报告会列出具体差异资源。

迁移后的资源可以在控制台中直观确认：模型目录、路由规则、用量总览一目了然。

第 5 步：rollback —— 出问题时一键回滚

万一验证失败或业务发现异常，用 apply 时保存的检查点即可回滚到迁移前状态：

tokenhub-migrate rollback --checkpoint bundle.json.checkpoint.json

rollback 会删除本次 apply 创建的资源（包括导入的用户），之后再跑一次verify可确认已回到迁移前的状态。得益于 Sink 的幂等 upsert设计，重复执行 apply 也不会产生重复资源，因此"apply → verify 不过 → rollback → 修 bundle → 重新 apply" 可以安全地反复进行。

附赠：本地一键跑通 E2E 迁移演练

仓库内置了完整的端到端演练环境：真实 LiteLLM + TokenHub + 模拟上游 + 本地 SMTP（Mailpit），可以安全地练习整套 extract → plan → apply → verify → rollback 流程：

cd backend && go build -o tokenhub-migrate ./cmd/tokenhub-migrate/ docker compose -f deploy/docker-compose.migration-e2e.yml up -d --wait cd sdk/migration-e2e && npm ci TOKENHUB_MIGRATE_BIN=../../backend/tokenhub-migrate npm run test:litellm

该演练会验证：TokenHub 通过真实 Admin API 接受 bundle、重复 apply 零新建零更新、检查点与一次性密钥文件正确落盘、rollback 后 verify 能检测到回滚状态。详见 docs/migration/e2e.md。

常见退出码速查

常见问题 FAQ

Q：迁移后 LiteLLM 的旧 API Key 还能用吗？迁移后 TokenHub 会签发全新的 API Key（见bundle.json.new-keys.json和 apply 报告中的report.new_keys[]）。请更新客户端后按流程轮换并吊销旧 LiteLLM 密钥。

Q：bundle 里会不会泄露我的 API Key？不会。所有密钥都以$secretRef引用形式存储，apply 时才从环境变量、文件或交互式输入中解析，bundle 本身可安全分享用于审查。

Q：LiteLLM 1.70+ 或 1.52 以下的版本能迁移吗？当前适配器支持的版本区间为>=1.52.0, <1.70.0，超出区间会明确报错，请先对齐 LiteLLM 版本再迁移。

Q：迁移过程中 TokenHub 会中断服务吗？不会。迁移全部通过 Admin API 增量 upsert 完成，不影响已有网关流量的转发。

总结

把 LiteLLM 迁移到 TokenHub 并不复杂，核心就是记住五步口诀：

1. extract：抽出无密钥的标准化 bundle；
2. plan：干跑预演，确认变更范围；
3. apply：正式执行，保存检查点与新密钥；
4. verify：核对一致性，退出码 0 才算通过；
5. rollback：不放心？一个检查点文件随时回到原点。

配合幂等设计与完整的 E2E 演练环境，你可以在不影响线上流量的前提下，把模型、路由、团队和密钥完整搬进 TokenHub，从此在统一的 AI 网关中享受审计、用量与成本治理能力。

📚 相关文档：docs/migration/README.md · docs/migration/cli.md · docs/migration/litellm.md · docs/migration/bundle-schema.md

📂 相关源码：backend/cmd/tokenhub-migrate/ · backend/internal/migration/source/litellm/adapter.go