1. 为什么要在本地跑一个 NewAPI 网关如果你同时用 OpenAI、Claude、Gemini 三家模型大概率经历过这种场景写好的代码里 OpenAI SDK 跑通了想换成 Claude 得改 base_url 和请求头换 Gemini 又要动一遍协议适配。更麻烦的是每个平台的 Key 分散在不同后台额度、用量、计费各看各的项目一多就乱成一锅粥。NewAPI 解决的就是这个问题。它本质是一个「协议翻译层 渠道管理后台」对外暴露一套 OpenAI 兼容的/v1/chat/completions接口对内把请求转发到不同厂商的渠道上。你只需要在客户端填一个地址、一个 Key就能在gpt-4o、claude-3-5-sonnet、gemini-1.5-pro之间自由切换代码一行不用改。这篇文章聚焦的是「快速落地」用 Docker 在本地或云主机上把 NewAPI 跑起来把 OpenAI、Claude、Gemini 的 Key 统一收敛到 TaoToken 通道最后用 curl 和前端对话两种方式验证多模型切换是否真的生效。整个过程 10 分钟能走完适合想自己搭一个统一入口的开发者、做小工具变现的独立开发者以及需要给团队内部提供统一模型调用入口的技术负责人。需要提前说明的是NewAPI 本身只是一个网关程序它不提供模型能力模型能力来自你配置的渠道。所以「渠道从哪来」是这套方案能不能跑通的关键。我这边用的是 TaoToken 作为统一的上游通道好处是一个 Key 就能覆盖 OpenAI、Claude、Gemini 多条线路省去分别注册、分别充值的麻烦。下面会给出完整的 docker-compose 配置、环境变量清单和渠道添加步骤。在开始之前先确认你手上有这几样东西一台能跑 Docker 的机器本地 Mac/Windows 或 1 核 1G 的云主机都行、Docker 与 Docker Compose 环境、一个 TaoToken 的 API Key。如果 Docker 还没装Ubuntu 下一条命令就能搞定Windows/Mac 直接装 Docker Desktop 即可。2. TaoToken 前置准备拿到统一上游 KeyNewAPI 的渠道配置需要一个上游地址和一个 Key。这里用 TaoToken 作为上游原因是它把 OpenAI、Claude、Gemini 的调用统一成了 OpenAI 兼容格式NewAPI 里只需要建一种类型的渠道就能覆盖多家模型配置量直接减半。第一步是拿到 Key。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。在左侧菜单找到「API Keys」或「令牌管理」点「新建令牌」给它起个名字比如newapi-gateway额度可以先设 10 美元试水生成后会得到一串sk-开头的 Key。这串 Key 只显示一次复制下来存好。第二步是确认上游地址。TaoToken 的 API 端点是https://taotoken.net/api注意这里不带任何查询参数。在 NewAPI 里填渠道时Base URL 要填到这个/api层级NewAPI 会自动拼接/v1/chat/completions。如果你填成https://taotoken.net请求会打到错误路径上测试时就会报 404。第三步是确认模型 ID。TaoToken 支持的模型名和官方保持一致常用的有gpt-4o、gpt-4o-mini、claude-3-5-sonnet-20241022、claude-3-haiku-20240307、gemini-1.5-pro、gemini-1.5-flash。这些名字在 NewAPI 的渠道「模型」字段里要一字不差地填进去大小写和连字符都不能错否则测试会返回「模型不存在」。这里有个容易踩的坑很多人以为 NewAPI 里要建三条渠道OpenAI 一条、Claude 一条、Gemini 一条其实用 TaoToken 作为上游时建一条「OpenAI 类型」的渠道就够了模型字段里把三家模型名都列上NewAPI 会根据请求里的 model 参数自动路由。这样管理起来清爽很多加新模型只需要在模型列表里补一个名字。如果你还想用 TaoToken 的 Coding Plan 做长期编码场景可以在控制台单独开通它和按量计费的 API Key 是两套额度体系互不影响。日常测试用按量 Key 就行成本可控。3. 可复制配置docker-compose 与环境变量这一节给出可以直接复制粘贴的配置。NewAPI 官方推荐用 docker-compose 部署因为它依赖 MySQL 或 SQLite 存数据用 compose 能把应用和数据库一起拉起来省去手动建库的步骤。先建一个目录比如/opt/newapi进去创建docker-compose.ymlversion: 3.8 services: newapi: image: calciumion/new-api:latest container_name: newapi restart: always ports: - 3000:3000 environment: - SQL_DSNroot:newapi_pass_2024tcp(mysql:3306)/new-api - REDIS_CONN_STRINGredis://redis:6379 - TZAsia/Shanghai - SESSION_SECRETnewapi_session_secret_change_me - CRYPTO_SECRETnewapi_crypto_secret_change_me depends_on: - mysql - redis networks: - newapi-net mysql: image: mysql:8.0 container_name: newapi-mysql restart: always environment: - MYSQL_ROOT_PASSWORDnewapi_pass_2024 - MYSQL_DATABASEnew-api volumes: - ./mysql-data:/var/lib/mysql networks: - newapi-net redis: image: redis:7-alpine container_name: newapi-redis restart: always volumes: - ./redis-data:/data networks: - newapi-net networks: newapi-net: driver: bridge几个关键点说明一下。SQL_DSN里的密码要和 mysql 服务的MYSQL_ROOT_PASSWORD一致数据库名new-api要和MYSQL_DATABASE一致这三处对不上容器会起不来。SESSION_SECRET和CRYPTO_SECRET是加密用的生产环境一定要改成随机字符串别用我这里的示例值。TZ设成Asia/Shanghai是为了后台日志时间和你本地一致排查问题时方便。如果你机器内存比较小1G 以下可以把 redis 去掉NewAPI 不强制依赖 redis只是没有缓存会慢一点。去掉的话记得把REDIS_CONN_STRING那行也删掉否则启动时会报连接失败。环境变量清单整理成表格方便对照变量名作用示例值SQL_DSN数据库连接串root:密码tcp(mysql:3306)/new-apiREDIS_CONN_STRINGRedis 连接串可选redis://redis:6379TZ时区Asia/ShanghaiSESSION_SECRET会话加密密钥随机字符串CRYPTO_SECRET数据加密密钥随机字符串配置写好后在/opt/newapi目录下执行docker compose up -d第一次会拉镜像大概一两分钟。看到三个容器都是Up状态就说明起来了。用docker compose ps确认一下再用docker compose logs -f newapi看日志出现server started on :3000就代表服务就绪。浏览器打开http://你的IP:3000会进入初始化页面。选择「自用模式」跳过企业微信、LDAP 这些复杂配置创建管理员账号用户名密码自己定登录后台。登录后第一件事是改默认配置。左侧「系统设置」里把「服务器地址」填成你的实际访问地址比如http://你的IP:3000这个地址会用在生成的回调链接里。然后进「渠道管理」点「新建渠道」。渠道类型选「OpenAI」名称填taotokenBase URL 填https://taotoken.net/apiKey 填你在 TaoToken 控制台生成的那串sk-。模型字段里把要用的模型名都填上用英文逗号分隔gpt-4o,gpt-4o-mini,claude-3-5-sonnet-20241022,claude-3-haiku-20240307,gemini-1.5-pro,gemini-1.5-flash保存后点渠道右边的「测试」按钮如果配置正确会弹出绿色提示显示测试成功。如果报错先看错误信息里的状态码401 是 Key 不对404 是 Base URL 填错模型不存在则是模型名拼写问题。渠道通了之后去「令牌」页面新建一个令牌额度设 10 美元生成后会得到一串sk-newapi-开头的 Key。这个就是给客户端用的「万能 Key」它和上游的 TaoToken Key 是两回事客户端只认这个。4. 验证请求curl 与前端对话双通道测试配置完不代表真的通了得实际发请求验证。这里用两种方式先用 curl 打接口确认协议层没问题再用前端对话页面确认多模型切换生效。先测 curl。把下面的命令里的地址和 Key 换成你自己的curl -X POST http://你的IP:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-newapi-你的令牌 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话说明什么是API网关}], stream: false }正常返回是一个 JSONchoices[0].message.content里就是模型回复。如果返回 401说明令牌不对或没带Bearer前缀返回 404检查 URL 是不是/v1/chat/completions返回model not found说明渠道里没配这个模型名。接着把model换成claude-3-5-sonnet-20241022再打一次如果也能返回内容说明多模型路由生效了。再换gemini-1.5-flash试一次。三次都通就证明 NewAPI 确实在按 model 参数分发到不同上游。curl 通了之后用前端对话页面再验一遍。NewAPI 自带一个聊天页面在后台左侧菜单能找到「对话」或「Playground」。进去后右上角可以选模型选gpt-4o-mini发一句再切到claude-3-5-sonnet-20241022发一句观察回复风格是否变化。Claude 的回答通常更结构化Gemini 相对简洁如果你能明显感觉到差异说明切换是真的生效了不是缓存或固定路由。这里有个细节前端页面用的是后台登录态不需要额外填 Key。如果你想模拟外部客户端可以在「令牌」页面复制令牌然后在对话页面的设置里填入自定义 API 地址和 Key这样走的就是和 curl 完全一样的链路。实测下来从容器启动到 curl 返回第一条内容整个过程在 3 分钟内能完成。冷启动第一次请求会慢一点因为要建数据库连接和加载渠道配置大概 1 秒左右后续请求稳定在几百毫秒取决于上游线路的响应速度。如果你要验证流式输出把 curl 里的stream: false改成true返回会变成 SSE 格式一行行data:开头的内容。前端对话页面默认就是流式的能看到逐字输出的效果。5. 本篇常见错误排查配置过程中最容易卡在几个地方这里按报错信息对照排查。401 Unauthorized两种可能。一是客户端用的令牌不对检查是不是复制了上游 TaoToken 的 Key 而不是 NewAPI 生成的sk-newapi-令牌二是渠道里的上游 Key 填错去渠道管理点测试如果测试也报 401就是 TaoToken 的 Key 有问题回控制台重新生成一个。404 Not FoundBase URL 填错。NewAPI 渠道里的 Base URL 要填到https://taotoken.net/api不要带/v1也不要带末尾斜杠。客户端请求的 URL 是http://你的IP:3000/v1/chat/completions这个/v1是 NewAPI 自己暴露的和上游地址无关。local proxy failed / connection refused容器网络问题。如果你在 docker-compose 里用了自定义网络确认 newapi 和 mysql 在同一个 network 下。另外检查 mysql 容器是否真的起来了docker compose ps看状态如果是Exit就看docker compose logs mysql多半是密码或数据库名不匹配。reading choices: unexpected end of JSON input上游返回了非 JSON 内容通常是上游地址打到了错误路径返回了一个 HTML 错误页。检查渠道 Base URL确认没有多余路径。也有可能是上游 Key 额度用尽去 TaoToken 控制台看下余额。OAuth / 登录回调失败如果你开了第三方登录回调地址要填成 NewAPI 的实际访问地址和「系统设置」里的服务器地址一致。自用模式一般用不到 OAuth直接用户名密码登录即可。模型测试通过但实际调用报 model not found渠道里的模型列表和请求里的 model 名不一致。NewAPI 的模型匹配是精确匹配gpt-4o和gpt-4o-mini是两个不同的模型不能只配一个。建议把常用模型名都列进渠道的模型字段。容器反复重启看docker compose logs newapi如果是数据库连接失败检查SQL_DSN格式密码里如果有特殊字符要 URL 编码。如果是端口占用改ports映射比如3001:3000。排查时有个通用思路先确认容器状态再看应用日志最后用 curl 打上游地址确认上游本身是通的。分层排查能快速定位是 NewAPI 的问题还是上游的问题。6. 把统一入口用起来NewAPI 跑起来之后你的客户端配置就固定成一套了API 地址填http://你的IP:3000/v1Key 填sk-newapi-令牌模型名按需切换。不管是 Python 的 openai 库、Node 的 SDK还是各种支持自定义 API 地址的客户端工具都只需要改这三个值。如果你想让这个入口长期稳定运行建议做两件事。一是把 docker-compose 里的密钥换成随机值别用示例里的二是给容器配个自动重启策略restart: always已经能覆盖大部分场景机器重启后容器会自动拉起。数据存在./mysql-data目录里定期备份这个目录就行。对于需要长期编码或跑 Agent 的场景可以了解下 TaoToken 的 Coding Plan它和按量 API Key 是独立的额度体系适合高频调用。日常测试和小工具用按量 Key 就够了成本透明。最后留一个实用技巧NewAPI 后台的「日志」页面能看到每一次请求的模型、耗时、消耗额度排查问题时比翻容器日志直观得多。如果发现某个模型响应特别慢可以在渠道里给它单独设超时或者临时禁用它让请求走其他线路。这套网关的价值就在于你随时能调整路由策略而客户端代码一行都不用动。
Y �)
