企业官网建设流程全解析

先交代一下背景。我之前在团队里负责 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 团队拿自己的 token，B 团队拿自己的 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-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: - TZ=Asia/Shanghai - SESSION_SECRET=change_me_to_a_long_random_string # - SQL_DSN=root:password@tcp(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 SDK：

from openai import OpenAI client = OpenAI( api_key="sk-你的平台令牌", base_url="https://your-gateway.example.com/v1", ) resp = client.chat.completions.create( model="gpt-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。这个问题我在接入 function calling 时经常遇到，尤其在定义一个包含复杂正则校验的 function 时，比如名称叫artifact，schema 里写了带负向断言或 Unicode 属性的 pattern，OpenAI 兼容接口很容易直接返回 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 消耗数据一定要留底。当业务方说“模型变慢了”或者“费用对不上”时，这些数据就是你排查问题的第一手证据。有了它们，很多扯皮都能变成一次清晰的数据核对。