先交代一下背景。我之前在团队里负责 AI 应用的统一接入最早大家各调各的模型OpenAI 一个 key、DeepSeek 一个 key、智谱又一个 key散落在代码仓库、环境变量和聊天记录里。后来被上游风控警告过一次才开始认真做开源 AI API 密钥管理与代理平台。这篇文章就是我基于开源方案搭建这类平台的完整记录它做什么、为什么这么做、怎么落地以及我压测和上线时踩过的一些坑。如果你手里有多个模型厂商的 key或者团队有十来个人都要调 AI 接口下面这套思路你应该用得上。这个领域现在很热但很多人只是粗暴地把所有 key 塞进一个配置文件里然后写一个转发接口。真正的密钥管理和代理平台核心不是“转发”这两个字而是权限、审计、限流、模型路由、成本归集这一整套治理能力。我们先从为什么需要它开始讲。1. 为什么需要密钥管理与代理平台1.1 密钥散落是把安全主动权交给运气先说最直接的问题密钥管理。很多人以为 key 是私有的只要不提交到 GitHub 就没事。实际上团队协作时很容易暴露有人把 key 放在前端代码里有人贴到群里有人为了方便直接写在脚本里我见过最夸张的情况是一个测试 key 被打包进客户端一天被刷走几百美元。一旦 key 泄露损失不只是账单金额。供应商的风控会把整个账号封掉影响线上所有使用同一账号的服务如果你把渠道、配额都绑在一个 key 上恢复流程会非常痛苦。集中管理不是为了多一层麻烦而是为了把风险收敛到可控边界内。密钥管理的关键原则很简单上游 key 只出现在服务器端永远不下发到业务应用或终端用户手里。1.2 代理平台到底解决了什么问题代理平台的本质是一个 API 网关它做三件事收口上游密钥、统一对外接口、记录每一笔请求。部署之后业务方不用再关心上游是 OpenAI 还是国产大模型也不需要自己维护 key。网关把上游渠道统一封装成 OpenAI 兼容格式业务方只需要一个平台 token 就能调用所有模型。模型切换、厂商故障切换、灰度发布都在网关层面完成。对多人协作的场景平台还能按用户或令牌维度做隔离。A 团队拿自己的 tokenB 团队拿自己的 token谁调用多、花了多少钱后台一眼就能看到。这个能力直接决定月底对账的工作量。没有平台的时候我们团队月底对账要导 Excel 手工处理现在点几个按钮就出报表还能设定额度上限防止某个业务方把预算烧穿。1.3 为什么选开源而不是自研我见过不少团队一开始想自研网关理由也很简单就这么个转发功能花不了几天。真做起来就发现鉴权、限流、重试、并发控制、模型映射、计费、日志、高可用每个模块都不小。只写一个能用的转发代理很容易但要扛住线上流量且不出安全事故需要不少沉淀。开源的 one-api、new-api、LiteLLM Gateway 这些项目已经把通用能力做得很成熟。自部署到自己的基础设施里数据不出内网还可以按需求改代码。对比商业中转平台开源方案没有按量抽成也不存在第三方替你保管上游 key 的风险。当然前提是你要读懂部署文档、做好运维这点时间成本是必须的。2. 核心原理与模块拆解2.1 密钥安全不是把 key 存进数据库就完事很多人以为把 key 存进数据库就安全了其实还差得远。开源网关平台一般会提供数据库字段加密部署时要求你设置一个加密密钥。这个密钥一旦丢失已经加密的渠道 key 就无法解密只能重新配置所以务必要备份好。我通常把它放在独立的环境变量文件里和代码仓库完全隔离。容器部署时还要注意环境变量权限。.env文件权限至少设为 600不要提交到 Git。更规范的做法是用 Docker Secrets 或 Kubernetes Secret 挂载这样即使容器被攻破也不容易从镜像层翻出明文密钥。理想状态下上游 key 是一次性写入配置的之后任何人从数据库中导出的都应该是密文。平台内部有两条凭证链路。上游 key 是网关和模型厂商之间的凭证下游 token 是业务方和网关之间的凭证。业务方只应该拿到平台 token永远接触不到上游 key。平台 token 在创建时通常只展示一次数据库里存的是哈希值即使数据库泄露攻击者也无法反推出可用 token。权限控制方面最少要用角色区分管理员、普通用户、只读审计角色。管理员能配置渠道和上游 key普通用户只能创建自己的令牌和查看调用记录。给团队成员分配 token 时尽量做到一人一 token不要多人共用一个否则出了问题没办法定位到人。2.2 请求转发与模型映射机制整个调用链大概是这样的业务应用携带平台 token 调用网关的/v1/chat/completions网关先做鉴权再根据请求里的模型名找到匹配的渠道最后用该渠道的上游 key 和 base_url 转发到真实模型厂商。响应返回时网关会把请求日志、token 用量记录到数据库。模型映射是网关里很实用的功能。你可以把请求中的模型名gpt-4o-mini映射到渠道 A把gpt-4o映射到渠道 B甚至可以配置多个相同模型名的渠道做负载均衡。当某个上游不稳定时可以在管理后台把流量切到另一个渠道业务方完全无感知。转发层还要处理超时、重试和流式响应。流式输出对网关的挑战比较大不能等上游全部返回后再转发必须以 SSE 方式实时转发给客户端。如果网关实现得不好用户侧会明显感觉到首字延迟。开源方案一般会提供参数控制超时时间和重试次数重试时要特别注意请求体是否可重复发送。2.3 限流、配额与成本审计限流算法一般是令牌桶或固定窗口。平台按 token 维度设置每分钟请求数、每日请求上限。超过限制的请求会返回 429并附带 Retry-After 头。我上线时踩过的坑是只设置了每分钟限制没有设置每天总额度结果某个测试脚本在一小时内把月预算刷掉了一半。现在我会同时配置短期限流和长期额度。成本审计依赖上游返回的 usage 数据。完成一次请求后网关会记录 prompt_tokens、completion_tokens、total_tokens再根据后台配置的模型单价换算成金额。按令牌归集后你就能清楚看到某个团队、某个应用、甚至某个用户消耗了多少钱。开源平台一般还支持设置告警阈值超过阈值自动通知管理员。配额功能还需要考虑透支缓冲。用户额度用完时网关可以选择直接拒绝也可以允许一定范围内的透支。我建议内部系统直接拒绝外部客户系统则允许小额透支避免影响真实用户体验但需要在后台把阈值调低并接上告警。2.4 日志、监控与可观测性没有日志的网关等于没有刹车。每个请求至少应该记录请求时间、令牌标识、模型名、渠道、是否成功、HTTP 状态码、耗时、token 用量。日志里绝对不能出现上游 key 的明文也不能出现请求消息体的完整内容否则隐私风险太大。开源平台通常会有日志脱敏选项建议上线前就打开。监控维度上我最关注四个指标请求成功率、平均延迟、按模型维度的 token 消耗、429 和 5xx 数量。前端可以接入 Prometheus 和 Grafana把网关的指标可视化。数据库里的大日志表建议定期归档否则表会越滚越大查询会越来越慢。3. 主流开源方案对比与选型3.1 one-api / new-api适合需要后台管理的场景one-api 是老牌开源项目功能覆盖渠道管理、令牌管理、用户管理、日志查看、模型定价界面是中文的上手成本很低。new-api 是它的增强 fork继承了一整套管理能力还加入更多模型厂商渠道、充值兑换码、按量计费等商业化功能适合需要对外提供 AI API 服务的团队。选型时不要只看 star 数量要看维护活跃度。one-api 和 new-api 的社区都很活跃但要注意版本差异。如果你 fork 了一个老版本可能无法直接升级到最新版最好在初始选型时就确定跟随哪个主线版本。这两个方案的部署方式也简单官方都有 Docker 镜像和 docker-compose 示例。后台管理型方案的最大优势是省心。页面里能完成渠道连通性测试、模型映射、令牌额度调整不需要写一行配置。对没有专职运维的团队来说这是最快的落地路径。3.2 LiteLLM Gateway适合偏开发者的配置驱动方案LiteLLM Gateway 是另一条路线。它定位是轻量级、配置驱动的 AI 网关支持 100 多个模型提供商统一输出 OpenAI 兼容接口。它特别适合已经有代码仓库、希望通过 YAML 管理一切配置的团队。model_list、litellm_settings、general_settings 都在 config.yaml 中声明改完配置后重启服务即可生效。LiteLLM 也支持虚拟 key、预算和用量追踪。但它的管理后台相对简单更多能力靠 API 和配置文件驱动。如果你的团队都是开发者偏好 GitOps 流程LiteLLM 会比后台管理系统更舒服。它也是 Python 写的想做一些自定义转发逻辑时可以直接写 Python 代码嵌入扩展性强。3.3 选型对照表速查项目语言部署难度管理界面计费能力适合场景one-apiGo React低完整基础计费小团队统一模型入口new-apiGo React低完整较强含充值兑换码内部使用或对外提供 API 服务LiteLLM GatewayPython中简单支持预算和用量开发者团队、GitOps 管理如果只是个人项目或者三五个人的小团队one-api 足够用。如果业务要对外开放 API 或者需要做用户充值选 new-api 更合适。如果团队崇尚配置即代码、不希望依赖重型后台LiteLLM 是最佳选择。4. 实操过程从零搭建一套可用平台4.1 准备环境用 Docker 把服务拉起来我以 new-api 为例因为它的后台管理能力最全面。准备一台 Linux 服务器或本机 Docker 环境安装 Docker 和 Docker Compose。下面是可用的 docker-compose.yml 示例version: 3.4 services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SESSION_SECRETchange_me_to_a_long_random_string # - SQL_DSNroot:passwordtcp(host.docker.internal:3306)/new_api volumes: - ./data:/data启动前把 SESSION_SECRET 改成一长串随机字符这是会话加密的基础不要用默认值。生产环境建议把 SQLite 换成 MySQL 或 PostgreSQL把SQL_DSN那行注释打开否则数据量上来之后写入性能会明显下降。启动命令很简单docker compose up -d docker compose logs -f首次启动后访问http://服务器IP:3000用初始化管理员账号登录按提示修改默认密码。这里有个个人建议如果不是在公司内网使用不要在云服务器上裸奔 3000 端口用 Nginx 或 Caddy 做 TLS 终止和域名转发让用户走 HTTPS 访问。4.2 后台配置渠道、模型与令牌登录后台后第一件事是添加渠道。找到“渠道管理”点击新增渠道选择模型厂商类型填入上游 API key 和 base_url再勾选或手动输入该渠道支持的模型名称。不同类型厂商的鉴权方式可能不同比如 OpenAI 用 Bearer Token部分国产模型厂商只要求填入 key。保存后点击“测试”如果返回成功说明渠道配置正确。模型映射方面后台一般支持“模型重定向”或“自定义模型名”。例如你可以把请求中的gpt-4o映射到渠道 A把gpt-4o-2024-11-20映射到渠道 B。多模型名之间用逗号分隔。我这里踩过一个坑渠道列表只勾选了gpt-4o但应用请求的是gpt-4o-2024-11-20导致 404。现在我会统一在后台维护一份“可用模型清单”业务方按清单申请模型名。接着创建令牌。令牌是业务方调用网关时使用的凭证可以绑定用户也可以绑定分组并设置额度、过期时间和 IP 限制。我一般按项目维度建令牌比如project-order-service、project-search-service这样日志和计费报表能直接对到项目。令牌创建后只展示一次记得复制保存。4.3 应用接入OpenAI SDK 和 curl接入时业务方只需要改 base_url 和 api_key不需要关心上游厂商。下面是 Python 示例使用 OpenAI SDKfrom openai import OpenAI client OpenAI( api_keysk-你的平台令牌, base_urlhttps://your-gateway.example.com/v1, ) resp client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 你好介绍一下你自己} ], ) print(resp.choices[0].message.content)curl 方式也类似把/v1/chat/completions指到网关地址即可curl https://your-gateway.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的平台令牌 \ -d { model: gpt-4o, messages: [{role: user, content: 你好}] }如果你问 DeepSeek API 如何调用通过网关后其实很简单后台新增 DeepSeek 渠道填好 key模型名填deepseek-chat然后应用侧照旧把请求发给网关模型名传deepseek-chat即可。业务方无需直接访问 DeepSeek 官网的接口也不用在自己的代码里保存 DeepSeek 的 key。4.4 上线前的检查清单修改默认管理员密码关闭不必要的注册入口或开启邀请码注册。所有上游 key 只配置在平台业务方代码中不得出现任何一路上游 key。给每个业务方分配独立令牌设置额度上限和过期时间。开启 HTTPS 访问不要直接用明文 HTTP 暴露公网。配置数据库自动备份加密密钥和.env文件单独备份。压测一遍流式输出、超时重试、超限返回 429 的场景。日志中确认不包含请求消息体内容和 key 明文。我建议上线前把这份清单打印出来或者贴在 wiki 上每一条都过一遍再放流量。漏掉任何一条后续都可能变成线上事故。5. 常见问题与排查技巧实录5.1 高频 API 报错速查表报错信息可能原因处理方案400 invalid schema for function artifactfunction calling 的 JSON Schema 不合法或包含目标模型不支持的字段简化 function schema去掉复杂正则断言升级网关版本400 content exists risk上游内容安全引擎拦截了请求调整 prompt降低输入内容风险或切换内容策略更宽松的模型maximum context length is 1048576 tokens请求 token 加上 max_tokens 超过模型上下文上限裁剪历史消息启用摘要压缩调低 max_tokens429 rate limit exceeded令牌限流或上游限流检查配额设置提高上限客户端加退避重试401 authentication error平台 token 无效、过期或格式错误检查 Authorization 头格式重新生成令牌404 model not found模型名未在渠道配置或映射未生效在后台渠道中补充模型名确认映射规则重点说下 400 invalid schema。这个问题我在接入 function calling 时经常遇到尤其在定义一个包含复杂正则校验的 function 时比如名称叫artifactschema 里写了带负向断言或 Unicode 属性的 patternOpenAI 兼容接口很容易直接返回 400。排查思路是先把 schema 简化成最基础的type、properties、required确认能通过后再逐步加校验逻辑。5.2 部署与集成中的典型坑Windows 用户用 Docker Desktop 时有时会看到failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。这个报错通常不是配置问题而是 Docker Desktop 的 Linux 引擎没启动或者 WSL2 后端异常。解决办法是先重启 Docker Desktop确认右下角图标变成 Running再执行docker version验证连接。个人建议生产环境尽量别在 Windows 上长时间跑容器用 Linux 服务器更省心。自托管 GitLab 和开源项目结合时常见报错是login failed. check api token or gitlab version. log in via git if the versi...。这个一般是 Personal Access Token 失效、scope 不够或者 GitLab 版本太老导致鉴权方式不匹配。处理方式重新生成一个带apiscope 的 token确认 GitLab 版本不低于接口要求的版本。如果是 CI 场景可以考虑用 CI Job Token而不是个人 token。另一个常见场景是渠道测试通过但应用实际调用失败。这种情况优先看模型名是否一致。测试渠道时后台可能用的是gpt-4o应用请求的是gpt-4o-2024-11-20大概率会 404。其次是令牌绑定关系有些平台令牌绑定用户分组业务方没有加入对应分组时会被拒绝。建议每次配置变更后用真实请求在终端里跑一遍 curl 做验证。5.3 开源项目的使用与贡献经验使用开源项目时版本管理要留个心眼。不要长期跟随 master 分支因为上游可能随时有破坏性变更。正式环境锁版本号升级前先看 CHANGELOG 和 release notes。像 one-api、new-api 这类更新快的项目升级前最好先备份数据库再在预发环境跑一遍。如果你希望回馈社区可以从文档贡献开始。开源项目最缺的不一定是代码而是清晰的文档。遇到不理解的配置可以提交 issue 并附上复现步骤如果确认是文档缺失直接提 PR 补充。给开源项目提 issue 时一定要写清楚版本号、完整报错、请求和响应脱敏后的日志这样维护者才能快速定位。最后说下开源许可证。在 Gitee 或 GitHub 上开源自己的项目时许可证不要随便选。如果你是个人项目用 MIT 或 Apache-2.0 都行如果是 fork 别人的项目必须保留原项目的 LICENSE 和版权声明不能私自改成自己的名字。选许可证之前先确认代码里用到的依赖都是兼容的协议否则可能会出现法律合规风险。我在实际落地这套方案后最深的体会是密钥管理与代理平台不是一次性工具而是一套需要不断维护的基础设施。密钥只进平台代码里永远用环境变量上线前把常见报错都压测一遍日志里不出现上游 key每周对一次账超过阈值自动告警。如果你也正准备搭一套建议先小范围跑两周把限流、模型映射和计费打磨好再逐步放量到全团队。最后再分享一个小技巧网关的流量曲线和 token 消耗数据一定要留底。当业务方说“模型变慢了”或者“费用对不上”时这些数据就是你排查问题的第一手证据。有了它们很多扯皮都能变成一次清晰的数据核对。