做 AI 应用这件事做到后面基本都会撞上一个坎模型服务越接越多Key 越管越乱账单越来越说不清。New API 这种自托管的大模型网关与 AI 资产管理系统就是拿来一次性解决这些问题的。它把上游各家大模型服务统一收口到一个入口让你自己定义令牌、额度、分组和计费规则开发者和业务系统只认网关这一个地址不用再直接接触上游平台。这篇文章写给三类人准备自己搭 AI 服务网关的开发者、要给团队统一管理模型成本的技术负责人、正在调研内部 AI 平台方案的运维同学。我不打算复读官方文档而是按照实际部署走过的路径把环境准备、启动、渠道接入、令牌分发、安全加固、问题排查一条线讲完。你不需要先把所有原理吃透跟着章节一步步跑起来再回来看配置项背后的逻辑会顺手很多。1. 部署之前先搞清楚 New API 到底是什么1.1 从三个典型场景看它解决什么问题第一个场景是我见过最多的某团队做内部效率工具接了三四个大模型服务有人用官网控制台的 Key有人用自己注册的账号代码里到处写死密钥。上线一个月后账单出来全是糊涂账根本说不清哪个项目烧了多少额度哪个人在用高价模型。第二个场景和权限有关。公司里不同小组共用一套模型服务谁都能拿到上游 Key意味着谁都能改配置、查余额、消耗整个账户的额度。你要给某个实习生只管一个模型、一个月的额度在云平台控制台里基本做不到这么细。第三个场景是稳定性。上游某个平台偶尔超时或限流如果所有请求都打同一个渠道用户体验直接崩掉。你希望有一套机制做自动重试、负载均衡、故障转移而不是出了问题以后人肉切 Key。New API 这类网关项目本质就是把这些零散问题收纳成四个概念渠道、令牌、分组、额度。渠道保存上游的真实连接信息令牌是分发给使用者的虚拟密钥分组决定令牌能使用哪些渠道额度负责计量和扣费。理解了这四个词整个系统的设计逻辑就通了。1.2 渠道、令牌、分组、额度四个核心概念先说渠道。渠道可以理解成一张“上游连接卡”上面记录着模型平台的类型、API Key、BaseURL、可用模型列表、超时时间、分组归属。一个系统里可以配很多渠道同一个平台也可以配多个 Key 做负载均衡。令牌则是给下游使用者的。它本身不包含任何上游真实 Key只包含网关内部的标识、额度上限、过期时间、可用分组和模型范围。开发者拿到的就是一个形如sk-xxxx的字符串后端看到这个字符串后去数据库里查出对应的权限和额度再决定是否放行。分组更像一个权限集合。渠道属于某个分组令牌也属于某个分组只有两边分组匹配请求才能继续转发。默认情况下所有资源都在default分组你可以根据团队、项目、环境拆成不同分组互不干扰。额度是整个系统的记账单位。你可以把它理解成一种虚拟货币用户请求模型网关根据模型价格和用量扣减令牌的额度同时记录到日志和账单里。请求链路大致是这样的用户携带令牌发起请求网关校验令牌有效性和剩余额度根据令牌分组找到可用渠道用渠道里的真实 Key 去请求上游拿到响应后回传给用户再根据上游返回的 usage 字段计算扣费。这个设计最大的好处是安全边界清晰真实 Key 永远只存在于网关服务端前端、客户端、同事电脑上都看不到。需要收回权限时吊销一个令牌即可不需要去所有代码仓库里改密钥。1.3 和直接用云平台控制台有什么区别有人会问我直接在模型服务商的控制台里管理 Key不也能用吗确实可以但那只适合“一个人、一个平台、不涉及分发”的极简场景。一旦涉及多人协作、多平台切换、内部计费、统一审计控制台的权限粒度远远不够。网关层相当于在你和各家模型平台之间加了一个抽象层。所有开发者只面对一个固定的 BaseURL 和各自独立的令牌模型平台怎么变、Key 怎么换、价格怎么调对使用方完全透明。我见过一个团队从某模型平台迁移到另一个平台整个过程中业务代码零改动只是因为他们在网关里改了渠道配置和模型映射。自托管还有一个现实优势请求日志、Token 消耗明细、用户账单都留在你自己的服务器上。对于一些数据敏感的场景这比把每次调用记录交给第三方要稳妥得多。当然自托管也意味着你要自己承担部署、升级、备份、防攻击这些运维责任后面的章节会逐个讲到。2. 快速部署实操Docker Compose 从零到能登录2.1 环境准备与部署方式选型部署 New API 其实不挑机器。个人体验下来一个 2 核 4G 的 Linux 服务器跑小型团队场景已经绰绰有余磁盘给 20G 以上就行因为日志和数据库会慢慢增长。如果你只是本地开发调试Docker Desktop 也能跑只是注意端口占用。操作系统方面Ubuntu、Debian、CentOS 这类常见发行版都可以。依赖只有一个Docker Engine 和 Docker Compose 插件。Docker 20.10 以上版本基本自带 Compose v2可以直接敲docker compose命令而不是老旧的docker-compose。部署方式我强烈建议优先选 Docker Compose。原因很简单镜像已经打包好了运行时和依赖不用自己在服务器上装各种底层库升级时拉一个新镜像重启容器就行所有配置和数据通过卷映射出来备份迁移都方便。二进制部署适合没有 Docker 的特殊环境但对日常运维来说容器化省心的多。2.2 编排文件与启动先建一个部署目录比如/opt/new-api在里面放一个docker-compose.yml。基础版本这样写就行version: 3.8 services: new-api: image: new-api:latest container_name: new-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai volumes: - ./data:/data这个版本用的是内置 SQLite 数据库数据文件存放在宿主机的./data目录下。不要小看这个卷映射很多人部署完以后忘记挂数据目录容器一删所有渠道和令牌全没了。restart: always保证服务器重启后网关自动拉起不至于因为一次宕机导致整个服务断掉。启动命令只需要两步docker compose up -d docker compose ps第一条命令会拉取镜像并按编排文件启动服务第二条命令用来确认容器状态。正常情况下你会看到容器处于Up状态端口映射到0.0.0.0:3000。如果启动异常用docker compose logs -f跟踪日志绝大多数问题都能在日志里看到原因。这里要提一个容易踩的坑如果你的服务器上已经跑了别的服务占用 3000 端口启动会直接失败。要么改宿主机映射端口比如8080:3000要么先把旧服务停掉。端口映射改掉以后外部访问地址也要跟着变。2.3 首次登录与初始化设置浏览器访问http://你的服务器IP:3000第一次打开会进入初始化注册页面。这里有个很关键的机制首次注册的账号会自动成为系统管理员。如果实例已经暴露在公网上一定要立刻注册并抢占管理员身份否则任何人抢先注册你就被动了。注册完成后进入管理后台我建议先别急着配渠道按顺序做三件事。第一确认系统设置里的站点地址、系统名称对不对这会影响后续生成分享链接和回调地址。第二把时区调整正确否则日志和账单时间会差好几个小时排查问题时会很痛苦。第三想清楚这个实例是只给自己用还是要开放给外部用户如果只给自己和团队内部用关闭“允许用户注册”选项避免陌生人注册账号消耗你的额度。整个初始化过程不到五分钟。到这里New API 已经能登录了但它还只是一副空壳因为没有渠道任何模型请求都发不出去。下一章是真正让系统产生价值的部分。2.4 数据备份的起点趁现在系统还没多少数据我建议建立备份习惯。SQLite 的备份很简单把挂载目录里的数据库文件复制一份就行。最稳妥的做法是先停容器再拷贝数据文件最后重新启动。不停容器直接复制虽然大多数时候也能用但极端情况下可能复制到不一致的数据。我习惯把备份动作写成一个脚本每天凌晨执行一次保留最近七天的备份文件。等到渠道和令牌都配好以后再想到备份往往已经晚了。很多人在这个环节粗心大意直到数据丢失才追悔莫及。3. 核心配置接入渠道、发放令牌、设置计费3.1 渠道配置的完整流程登录后台左侧菜单找到“渠道”点“新增渠道”。第一个要选择的就是渠道类型不同模型平台对应各自的适配器网关会按照对应的协议格式去拼接请求。如果你接的是和标准接口格式兼容的服务也可以选择自定义渠道手动填写 BaseURL 和模型列表。接下来填 API Key。这个 Key 来自你在模型平台创建的真实密钥务必保管好因为它会以明文或加密形式保存在数据库里。填写时注意不要带多余空格也不要填错字符常见的渠道测试失败原因里API Key 错误排在第一位。然后是模型列表。我的建议是只勾选你实际开通、实际要用的模型不要图省事把所有模型都勾上。原因有两个一是模型列表越宽越容易在不知情的情况下被别人调用高价模型二是部分网关逻辑里模型列表也决定了这个渠道能处理哪些请求勾错了会导致请求被路由到不支持该模型的渠道。模型倍率、分组这些字段可以暂时不动保持默认。保存后渠道列表里会出现一条新记录点击操作列的“测试”按钮网关会发送一个最小请求确认密钥和网络是否可用。测试通过说明渠道本身没问题后面更多是权限和路由层面的配置。补充一个细节国内很多模型平台都提供了兼容接口你完全可以把它们也接进来。一个渠道对应一个平台的密钥同一个平台也可以创建多个渠道网关会自动根据分组和模型去匹配。不要把所有平台混在一个渠道里那样既无法精细限流出了问题也不好定位。3.2 令牌创建与开发者接入渠道配好以后使用方还需要一个令牌才能调用。在后台找到“令牌”菜单新增一个令牌设置好名称、额度上限、过期时间、所属分组、允许的模型范围。对内部团队来说我建议一个项目一个令牌额度按需分配用完再追加这样账单能精细到项目维度。令牌的额度设置非常灵活。你可以设置一个总数也可以设置每日限额可以设置永不过期也可以设置一周后自动失效。实际管理经验是宁可初始额度给少一点也不要一口价给一整月的量。额度不够用户会来找你加给多了再想收回就麻烦。开发者接入时只需要把请求的 BaseURL 改成你的网关地址Key 换成这个令牌。下面是一个最基础的调用示例import requests url http://你的网关地址:3000/v1/chat/completions headers { Authorization: Bearer sk-你的令牌, Content-Type: application/json } payload { model: your-model-name, messages: [{role: user, content: 你好}] } resp requests.post(url, jsonpayload, headersheaders, timeout60) print(resp.json())如果你的项目原本就在用各种模型平台的 SDK绝大多数 SDK 都允许自定义base_url。把base_url指向网关把 API Key 换成网关令牌代码几乎不需要其他改动。这正是网关层的价值所在底层的渠道切换、模型平台切换对开发者完全透明。3.3 模型映射与价格倍率模型映射是实际使用中特别重要的功能。场景是这样的你的团队统一约定调用model-a但某天model-a的上游服务不稳定你想临时把流量切到另一个模型model-b。如果让所有开发者改代码效率太低如果只是修改渠道配置网关还认model-a这个请求仍然会路由到原渠道。正确做法是在网关里配置模型重定向把model-a映射到model-b。这样用户侧代码不用动请求进来后网关自动完成模型名的转换对调用方来说它们始终在调model-a。这个能力在做模型迁移、灰度切换、成本控制的时候都极其有用。价格倍率则关系到账单是否准确。额度单位由你自己定义常见做法是让 1 额度对应 0.1 元人民币。这时需要把上游模型的按 Token 计费价格换算成网关里的倍率。举个例子某模型上游每 100 万 Token 收费 2 元也就是每 100 万 Token 应消耗 20 额度那么每 1 万 Token 就是 0.2 额度。网关里的模型倍率通常以每 1K Token 或每 1M Token 为基准按你使用版本的实际字段填进去即可。填完以后最好用小流量请求验证一下扣费是否符合预期避免账单出现系统性偏差。4. 上线之后安全加固、监控与运维4.1 必须做的安全加固清单网关一旦接入真实模型密钥就成了高价值目标。很多人部署完就裸奔在公网端口上这非常危险。我建议上线前做一轮安全加固优先级从高到低列出来第一用反向代理加上 HTTPS。Nginx 或 Caddy 都可以对外只开放 443 端口内部服务的 3000 端口不要直接暴露公网。没有 HTTPS令牌和请求内容在网络上都是明文传输很容易被中间人截获。第二严格控制注册入口。如果实例是公司内部使用关闭用户自助注册由管理员统一创建账号和令牌。公网部署时这个选项尤其关键否则别人注册进来就能消耗你的额度。第三管理后台要做访问限制。最简单的方式是通过反向代理增加 IP 白名单只允许公司出口 IP 或跳板机访问后台。就算服务器被扫描攻击者也进不了管理界面。第四妥善保护好数据库和日志目录。数据库文件里有所有渠道的真实密钥和令牌一旦泄露等于把所有模型额度拱手让人。宿主机上要设置好文件权限备份文件也要加密或妥善隔离。第五渠道配置里的上游 BaseURL 尽可能固定不要随意填写不可信地址。因为这个系统本质上会替用户发起 HTTP 请求配置不当可能成为请求转发的跳板外部人员能用你的服务器去访问内网或其他资源。4.2 日志、监控与告警配置New API 的一大优势是自带完整的请求日志。每一条请求的时间、调用方令牌、模型、Token 消耗、响应状态都记录在案这对成本归因和问题排查非常有价值。我建议运营过程中定期浏览日志不需要每天看但每周至少翻一次重点关注异常高频调用和模型分布是否符合预期。系统还支持配置通知方式。常见做法是设置一个 Webhook 地址当系统发生错误、渠道失效、额度不足等事件时自动推送到团队的消息工具。这个能力在渠道被上游限流时尤其好用你能第一时间知道而不是等用户投诉。不要忽视服务器层面的监控。容器占用内存持续上涨、磁盘空间即将写满这些事网关自身通常不会主动报警。用 Docker 自带的docker stats或外部监控工具盯住 CPU、内存、磁盘和网络即可数据量小的时候一天看一次都行但最好有告警兜底。4.3 性能扩展与高可用对大部分场景来说单机加 SQLite 就够用了。但如果团队人数增多、并发请求量上来SQLite 的写入锁会开始成为瓶颈。这时候建议把数据库切换到 MySQL并在系统设置中启用 Redis 缓存。数据库迁移本质上涉及导数据、改连接配置、重启服务三步每一步都要验证不能直接删掉旧库。多实例部署是更高阶的话题。网关本身可以做成无状态服务多个实例挂在同一个数据库和 Redis 后面由负载均衡器分发请求实现高可用。但前提是数据库不再使用 SQLite否则多实例并发写同一个库文件会直接出问题。要不要走到这一步取决于你对服务可用性的要求不必过早设计。什么时候该升级我的判断标准很简单系统监控里看到请求平均响应时间开始变长或日志里频繁出现 SQLite 锁相关的报错就是该动数据库和缓存的信号。如果只是每天几百次调用老老实实跑单机反而省心。5. 常见问题与排查技巧实录5.1 请求报错类问题症状常见原因处理方式返回 401令牌无效、令牌过期、令牌被禁用检查请求头 Authorization 是否填对确认令牌状态返回 403令牌分组与渠道分组不匹配核对令牌和渠道的分组确保两边一致返回 404模型不存在或渠道不可用确认该令牌可用模型列表里包含目标模型返回 429上游限流、额度不足、并发超限查看日志定位是哪个渠道考虑增加备用渠道返回 502网关服务异常或上游连接失败先看网关日志再检查上游平台可用性401 是最常见的接入问题。几乎每次都是开发者复制错了令牌或者在请求头里少了Bearer前缀。排查时可以先用系统里的测试功能验证令牌本身是否正常再让调用方逐字核对请求头。502 则需要区分是网关自身挂了还是上游失败。如果网关所有请求都 502多半是容器异常或反向代理配置有误如果只是某几个渠道 502那就是上游平台的问题可以在日志里看到具体的上游响应信息。5.2 功能异常类问题额度不扣减是我被问得最多的问题之一。出现这种情况首先要看令牌的计费设置是否正常其次要确认上游响应里是否返回了 usage 字段。网关是根据上游返回的 Token 用量来算钱的如果上游没有返回 Token 消耗系统无法计量自然没有账单。模型列表在接口里找不到通常是令牌可用模型和渠道可用模型没对齐。令牌限制了模型范围渠道也有模型范围两者取交集才是实际可调用的集合。两边都放养式的全勾选反而容易出问题建议明确到具体模型名。还有一类问题是模型重定向失效。排查时先确认请求里带的 model 名和重定向配置里的源模型名严格一致注意大小写和空格。网关的重定向是精确匹配还是模糊匹配不同版本有差异配置完以后一定要实测一次。账单对不上的情况多半出在倍率设置上。我建议先做一个小成本验证用一个非常短的请求调用一个价格已知的模型看系统扣除的额度和手工计算是否一致。如果偏差很大回头看倍率字段的单位和换算逻辑。5.3 运维故障类问题忘记管理员密码是常见的小事故。大部分版本提供了命令行重置入口执行相应的用户管理命令即可。如果不知道具体命令去查看你部署版本的使用说明或帮助输出不要直接去改数据库除非你非常清楚表结构。改坏一个字段可能把整个用户体系搞乱。容器重启后数据丢失十有八九是没挂数据卷或者挂载路径不对。部署的时候先把docker compose config的输出看一遍确认宿主机路径是否真实存在。另外SQLite 数据文件写入需要目录有足够权限否则容器可能以匿名卷形式运行数据也存不住。数据库迁移失败通常发生在切换 MySQL 的过程中。建议迁移前先备份 SQLite 文件迁移完成后立刻对比渠道数量和令牌数量确认一致后再切换连接配置。迁移过程中最好停掉服务避免新旧数据库双写造成数据不一致。5.4 几个值得长期坚持的操作习惯我自己的习惯是每次改完渠道、令牌或倍率都会立刻用最小请求做一次端到端验证确认业务方拿到的响应正常、日志里的扣费正常。这套验证流程看起来琐碎但能避免八成以上的“改完配置以后静默出错”。后台日志我会顺手打开“按令牌聚合”的视角发现某个令牌消耗量突然飙升时会主动联系对应负责人确认是不是业务量增长了。这种主动监控比事后对账有效得多因为很多额度问题在爆发前都有征兆。最后再分享一个经验正式对外开放之前先在开发环境把整套流程跑通包括渠道接入、令牌分发、模型映射、倍率扣费、日志排查。开发环境里怎么折腾都行一旦上了生产每次操作都建议先备份再动手。网关类系统最怕的不是功能不会用而是脏数据积累到一定程度以后账目和日志彻底失去可信度。