2026/9/2 1:40:05
FEATURED · 精选文章 
这次我们来看一个很有意思的轻量级项目用一周时间搓出来的 AI 聚合网关核心卖点是“一键部署到 Cloudflare免费上云”。它解决的痛点很直接当你手上的 AI 服务商越来越多OpenAI、Anthropic、Google、Groq、国产大模型各有各的 Base URL、密钥体系和模型命名规则业务端要接哪家就得改哪家测试脚本、批量任务、内部工具全被上游 API 格式绑死。这个网关把上游全部收口成一个统一入口对外暴露一套兼容 OpenAI 格式的 API剩下的路由、鉴权、缓存、失败切换都由网关处理。先给结论这类项目适合 AI 应用开发者、自动化脚本作者、团队内部工具负责人。部署平台是 Cloudflare Workers天然免费额度不需要自己买服务器因为有 workers.dev 域名部署完成就能拿到一个公网 HTTPS 地址网关本身不参与模型训练也不保存对话内容只做请求转发和策略控制。下面我会从核心能力、部署方式、路由配置、接口测试、批量任务、性能观察和排错清单几个维度完整过一遍你可以边看边对着自己的项目试。1. 核心能力速览能力项说明项目类型云端部署的 AI API 聚合网关统一接入多家大模型服务商目标平台Cloudflare Workers / Pages常见方式为 Workers KV 组合部署方式一键部署脚本 / Wrangler CLI / Cloudflare 控制台在线编辑核心功能OpenAI 兼容接口、上游服务商配置、自动路由、流式响应、结果缓存、失败切换、密钥托管API 风格对外提供/v1/chat/completions等兼容接口业务端改动最小免费额度依赖 Cloudflare Workers 免费计划个人测试和小流量够用具体配额以 Cloudflare 官方为准显存/硬件要求无。网关是纯云端逻辑不跑本地模型不需要 GPU是否支持批量任务支持。网关本身是 HTTP 转发层可被外部脚本批量调用配合重试和队列即可适合场景个人工具、团队内部 AI 中台、自动化脚本统一入口、多服务商比价与容灾不适合场景大规模生产级高并发、低延迟本地推理、需要长连接私有协议的场景从材料看这个项目最大特点是“免费 一键 白嫖 Cloudflare”对个人开发者和中小团队非常友好。要注意的是网关不提供模型算力你仍然需要各家服务商的 API Key只是由网关统一管理。2. 适用场景与使用边界2.1 适合谁同时使用多家 AI 服务商想统一切换和降级策略的开发者。不想在每个脚本和服务里重复写 API Key、Base URL 和请求头的团队。想给内部项目做一个轻量 AI 接入层但不想单独维护一台服务器的团队。喜欢用 Cloudflare 免费额度解决基础设施问题的技术玩家。2.2 能解决的问题统一接口业务端只认网关的地址上游换成哪家都不影响业务端。密钥集中管理各家 Key 放在 Cloudflare 环境变量或 KV 里不散落在代码仓库。失败切换某家服务商限流或故障时网关自动换到备用服务商。缓存降本命中缓存的重复请求不向上游计费能明显降低高频调用成本。可观测性网关层可以记录请求来源、模型、耗时、状态码给后续用量分析打底。2.3 不适合什么需要极低延迟、本地数据不出内网的企业场景网关只做转发不适合私有化推理。有严格合规要求、不允许请求经过第三方平台的业务。需要自定义传输协议或双向流式长连接的场景。2.4 使用边界与合规提醒聚合网关只改变 API 接入方式不改变数据归属和内容责任。调用任何模型前需要确认上游服务商是否允许代理转发是否覆盖存储与训练条款请求内容是否包含个人信息、商业秘密或敏感数据如果有先做脱敏如果使用人脸、声音、版权素材相关的生成模型必须保证素材来源合法授权部署到公共互联网后网关接口默认就是公开的必须加上访问鉴权避免被刷量。3. 部署前准备与前置条件我不建议一上来就改代码先把环境确认清楚至少能少踩一半的坑。3.1 需要准备的东西项目要求Cloudflare 账号免费注册即可最好开启二次验证域名或开发子域workers.dev 默认域名即可也可以绑定自定义域名上游服务商 API Key至少准备一家可用的 Key例如 OpenAI、Anthropic、智谱、DeepSeek 等Node.js 环境如果使用 Wrangler CLI建议 Node 18 或更高版本代码工具建议准备 Git方便拉取和提交项目代码3.2 免费计划额度预期Cloudflare Workers 免费计划有每日请求数、CPU 时间、KV 读写次数等限制具体数字会随官方政策调整。实际部署时以 Cloudflare 控制台显示的剩余配额为准。个人开发、内部脚本、低频 API 调用基本够用如果做高并发生产接口需要评估付费计划。3.3 安装 Wrangler CLI# 全局安装 wrangler具体版本以官方 npm 包为准 npm install -g wrangler # 验证安装 wrangler --version安装完成后先登录wrangler login浏览器会弹出 Cloudflare 授权页面登录并确认授权即可。如果你的网络环境无法直接访问 Cloudflare请优先检查本地网络和服务连通性不要在网关项目中配置任何代理相关功能。4. 一键部署到 Cloudflare这里给出两种部署方式按你的习惯选择。4.1 方式一通过 Wrangler 命令行部署假定你已经把项目代码克隆到本地进入项目根目录典型的部署流程是# 安装项目依赖 npm install # 部署 worker wrangler deploy部署完成后终端会输出一个形如https://your-worker.你的子域.workers.dev的地址这就是网关对外入口。如果项目里有自定义的wrangler.toml或wrangler.jsonc配置部署前需要注意name、main、compatibility_date和kv_namespaces是否正确。一个简化配置示例name ai-gateway main src/index.js compatibility_date 2025-01-01 # 如果网关用到缓存需要绑定 KV namespace # kv_namespaces [ # { binding CACHE_KV, id your-kv-namespace-id } # ] [vars] DEFAULT_MODEL gpt-4o-mini注意compatibility_date需要实际可用的日期KV 绑定需要先创建 namespace上面的代码只作为通用模板。4.2 方式二通过 Cloudflare 控制台在线部署如果你不想装命令行工具可以直接在 Cloudflare 控制台创建 Worker打开 Cloudflare Dashboard进入 Workers 与 Pages。点击“创建应用程序”然后选择“创建 Worker”。把网关项目的index.js或主要入口代码粘贴到在线编辑器中。在“设置”中添加环境变量逐个放上游 API Key。点击“部署并启用”系统会自动生成访问地址。这种方式适合快速验证但后续要处理多个文件、复杂依赖时还是建议用 Wrangler。4.3 创建 KV 缓存空间如果网关实现里使用缓存需要先创建一个 KV namespace。wrangler kv namespace create CACHE_KV创建完成后控制台会返回一个id把它填到wrangler.toml的绑定里再重新部署。KV 的作用是缓存部分重复请求的响应减少上游调用。4.4 校验部署是否成功部署完成后直接访问根路径预期返回一个简单的 JSON 信息例如{status:ok}或网关名称。如果页面报 404说明服务入口路径不是根路径去控制台查看路由配置。5. 配置上游服务商与路由策略网关的核心价值不在转发本身而在策略。5.1 环境变量里放 Key不建议把 Key 写在代码里而是通过环境和 secrets 注入。使用 Wrangler 设置wrangler secret put OPENAI_API_KEY wrangler secret put ANTHROPIC_API_KEY wrangler secret put DEEPSEEK_API_KEY命令运行后会要求输入 Key 内容保存到 Cloudflare 的加密存储中。这样代码仓库不会出现明文密钥。5.2 服务商路由规则一个常见的路由思路是客户端请求时指定一个provider参数网关根据该参数把请求转发到对应的 Base URL并替换模型名。另一种思路是网关维护一套“模型名到服务商”的映射表客户端只传model网关查表决定转发到哪家。例如const providers { openai: { baseUrl: https://api.openai.com/v1, apiKeyName: OPENAI_API_KEY, modelMapping: { gpt-4o-mini: gpt-4o-mini } }, deepseek: { baseUrl: https://api.deepseek.com/v1, apiKeyName: DEEPSEEK_API_KEY, modelMapping: { gpt-4o-mini: deepseek-chat } } };上面的代码是通用配置示例实际字段名需要以网关项目源码为准。路由逻辑一般位于 Worker 的fetch处理器中收到请求后读取 URL 参数或请求体里的字段决定 target provider。5.3 失败切换策略可靠性比较好的网关会做“主服务商 备用服务商”。主服务商返回 429、5xx 或网络错误时自动重新请求备用服务商。实现时要注意必须设置上游请求超时时间不能无限等待切换后要记录日志方便排查流式响应过程中如果主链路中断切换比较麻烦建议非流式或短流场景先启用。5.4 统一鉴权网关暴露到公网后必须加一层访问控制。最简单的方式是网关自身也校验一个AuthorizationBearer Tokenwrangler secret put GATEWAY_API_KEY客户端调用时携带网关自己的 Key而不是上游 Key。网关验证通过后再替换成上游 Key 去请求目标服务商。6. 功能测试与效果验证部署完成后建议按下面顺序做一轮完整验证不要直接上业务。6.1 验证统一入口是否可用用 curl 发送一个最小编译请求curl -s https://your-worker.子域.workers.dev/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的网关Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好请回复网关连通}], stream: false }如果返回内容包含choices字段和模型输出说明统一入口正常密钥替换也正常。如果返回 401检查网关 Key 是否正确如果返回 502检查上游服务商 Key 或 Base URL 配置。6.2 验证流式输出curl -N https://your-worker.子域.workers.dev/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的网关Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 写一个30字的自我介绍}], stream: true }输出应该是data:开头的 SSE 流最后有[DONE]。如果使用 Node 或 Python 的官方 OpenAI SDK只需把base_url指向网关地址业务代码几乎不用改。Python 调用示例from openai import OpenAI client OpenAI( api_key你的网关Key, base_urlhttps://your-worker.子域.workers.dev/v1 ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}], streamTrue ) for chunk in resp: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end) print()注意模型名要传网关能识别的模型名具体取决于配置。如果网关本身做模型映射你需要按你自己的映射表传参。6.3 验证缓存是否生效开启缓存后连续向网关发两次完全相同的请求。第二次请求的响应时间应明显下降并且 Cloudflare 侧不会产生新的上游计费。判断方式可以看网关日志中是否出现cache hit标识或者查看响应耗时。6.4 验证失败切换临时把主服务商的 Key 改成错误值再发起请求。预期网关自动切换到备用服务商并返回结果。如果网关直接返回 502说明切换逻辑没有配通需要查看日志。6.5 验证批量并发用 Python 脚本模拟 10 个并发请求统一打到网关import requests from concurrent.futures import ThreadPoolExecutor url https://your-worker.子域.workers.dev/v1/chat/completions headers { Authorization: Bearer 你的网关Key, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [{role: user, content: 回复OK}], stream: False } def call_one(i): resp requests.post(url, headersheaders, jsonpayload, timeout30) return resp.status_code with ThreadPoolExecutor(max_workers10) as pool: codes list(pool.map(call_one, range(10))) print(codes)这一步重点验证网关鉴权、路由和限流是否正常。出现 429 或 5xx 时排查 Cloudflare 限流策略和上游服务商配额。7. 接口 API 与批量任务7.1 API 语义设计网关对外接口建议做一层统一规范至少包括以下请求字段字段含义是否必填model模型名例如gpt-4o-mini、deepseek-chat是messages对话消息列表是temperature采样温度否max_tokens最大输出长度否stream是否流式否provider强制指定服务商否不传则自动路由返回格式建议与 OpenAI 保持一致这样现有 SDK 直接可用。7.2 批量任务设计网关本质是 HTTP 服务不内置任务队列但完全可以作为批量任务的目标端。批量任务通常是这样做的准备一批 prompt 文件例如 JSON 数组每条包含id和content。用脚本逐条或分批调用网关接口。收集结果并写入本地文件或数据库。对失败的请求做重试。Python 批量脚本示例import json import time import requests url https://your-worker.子域.workers.dev/v1/chat/completions headers { Authorization: Bearer 你的网关Key, Content-Type: application/json } with open(tasks.json, r, encodingutf-8) as f: tasks json.load(f) results [] for task in tasks: payload { model: gpt-4o-mini, messages: [{role: user, content: task[content]}], stream: False } try: resp requests.post(url, headersheaders, jsonpayload, timeout60) if resp.status_code 200: data resp.json() answer data[choices][0][message][content] results.append({ id: task[id], content: task[content], answer: answer, status: ok }) else: results.append({ id: task[id], status: failed, error: resp.text }) except Exception as e: results.append({ id: task[id], status: exception, error: str(e) }) # 温和限速避免触发上游限制 time.sleep(0.5) with open(results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2)批量任务最容易遇到两个问题一个是上游限流导致大量 429另一个是单条请求超时导致整个脚本卡住。建议批量任务里加入重试、限速和断点续跑能力。7.3 读取流式响应做批处理如果模型本身只支持流式批量脚本需要解析 SSE 流。可以逐行读取找到data: [DONE]作为结束标志。这种方式内存占用更低但代码会复杂一些。8. 资源占用与性能观察这部分是很多人关心的重点但注意Cloudflare Workers 是 Serverless 平台不存在传统意义上的显存、内存常驻占用。你能观察到的指标主要是请求数量、CPU 时间、KV 读写次数和网络耗时。8.1 观察出口登录 Cloudflare 控制台进入对应 Worker 的分析页面可以看到请求总数成功率和错误码分布请求耗时分布上游调用次数如果网关代码中有上报逻辑每日额度消耗8.2 影响性能的关键点上游响应时间网关本身转发很快瓶颈基本在上游模型响应。缓存命中率命中率高网关 CPU 时间和 KV 读取量都更低请求耗时也更短。流式 vs 非流式流式响应能更快返回首字但对网关的代码逻辑要求更严格。请求体大小大 prompt 会增加请求转发耗时Cloudflare 对请求体大小也有限制超大文本要做拆分。并发策略Workers 可以并发处理请求但上游服务商有速率限制网关层需要内置令牌桶或失败回退。8.3 降低资源消耗的建议开启缓存对同 prompt 重复请求直接返回。为不同业务拆多个入口路径避免一个 Worker 被占满配额。错误响应不要做大量字符串拼接减少 CPU 时间消耗。日志输出控制在业务关键节点避免每条请求都写很多结构化日志。8.4 比较不同上游服务商如果你把多家服务商接入同一个网关可以做一个简单的“耗时对照表”providermodel是否流式返回耗时状态码备注providerAmodel-a否2.3s200稳定providerBmodel-b否4.1s200偏慢providerCmodel-c否失败429配额不足这个过程只是网关接入能力的验证不作为模型效果排序依据。9. 常见问题与排查方法问题现象可能原因排查方式解决方案部署后访问返回 404Worker 路由路径不对或入口代码未导出 fetch 处理器打开控制台测试 / 观察日志确认主文件正确绑定fetch事件请求返回 401网关 Key 错误或未配置检查Authorization请求头重新设置GATEWAY_API_KEY请求返回 502上游 Base URL、Key 或模型名错误查看 Worker 日志中上游错误信息核对服务商文档替换正确配置上游返回 429触发服务商限流查看响应头X-RateLimit-*做请求限速、缓存、降级到备用服务商流式输出中断上游流被切断或网关未处理 SSE检查网络稳定性确认代码支持streamtrue分批重试或改用非流式缓存不生效KV 未绑定、请求体含随机参数或缓存键设计错误查看绑定配置和缓存日志修正缓存键只对稳定字段做哈希批量脚本中途失败单条请求超时或上游配额耗尽查看脚本日志记录失败位置加入断点续跑、重试、记录已完成 ID配额消耗过快缓存未生效、并发过高或日志过于频繁控制台查看请求分布开启缓存、控制并发、精简日志自定义域名访问失败DNS、路由规则或证书问题检查域名解析和 Worker Routes在控制台绑定自定义域名并等证书生效代码更新后未生效部署流程未完成或缓存了旧版本重新wrangler deploy清理版本缓存使用新版本部署并观察版本 ID其他服务商请求格式兼容问题各家 API 的字段差异导致参数冲突对比服务商文档与网关源码在网关层做参数归一化排查时最有效的办法是打开 Cloudflare Worker 的实时日志看每次请求转发到哪家、返回的状态码以及报错内容。日志里定位不到的问题再考虑是否混淆传参、模型映射错误或公网连通性问题。10. 最佳实践与使用建议10.1 从最小配置开始第一次部署只接一家服务商先用最简配置把链路跑通。确认统一入口、鉴权、基础对话都没问题后再加第二家、加缓存、加失败切换。不要一开始就把所有模型堆上去否则出问题时很难定位是哪一步。10.2 密钥分离网关 Key、管理人员 Key、各上游 Key 要分开管理。上游 Key 放在 Cloudflare secrets 中不要出现在代码仓库、日志、前端页面或抓包工具中。10.3 缓存键要稳定缓存命中率取决于缓存键的设计。推荐对以下内容做哈希模型名温度等核心采样参数归一化后的 messages 内容不要把时间戳、随机数、请求 ID 放入缓存键否则缓存形同虚设。10.4 批量任务要三件套日志、重试、断点日志每条任务记录 id、请求时间、响应时间、状态码、错误消息。重试遇到 429、5xx、超时才重试不重试 4xx 校验错误。断点记录已完成 id再次运行脚本时跳过已完成任务。10.5 网关鉴权要尽早做你的网关部署到公网很容易被扫描器打。即使只是内部工具也要加上全局鉴权。更稳妥的做法是网关只响应携带正确Authorization的请求其它请求直接返回 401。生产环境还可以加 IP 白名单、地区限制或自定义访问规则但纯免费计划下人力和规则配置能力有限先保住密钥安全。10.6 合规与内容审核聚合网关简化的是技术接入不是责任转移。如果业务要面向外部用户开放建议在网关层增加关键词过滤、输入长度限制、输出内容复核等逻辑。涉及人脸、声音、版权素材等场景必须在上游服务商允许的范围内使用并取得所有必要授权。11. 总结与下一步这个项目最值得尝试的点是用 Cloudflare Workers 的免费额度搭出一个标准的 AI 接入层。不用买服务器不用管运维不用为每家 AI 服务商写一套独立请求代码一个统一入口就能把路由、缓存、失败切换、密钥管理都收进来。如果你准备自己动手我建议按这个顺序跑注册 Cloudflare 账号创建 Worker。只接一家服务商用 curl 验证非流式和流式请求。接第二家服务商配置模型映射和失败切换。加 KV 缓存对比两次相同请求的耗时。写一个 Python 批量脚本验证多请求场景。最后把网关 Key 换掉去掉测试配置再上业务。最容易踩的坑基本集中在三类上游服务商配置错误导致 502、缓存键设计不合理导致配额浪费、网关公网部署后没有加鉴权被刷。前两个坑多看看 Worker 日志就能解决最后一个坑必须在部署早期规避。网关这类项目后续还可以扩展的方向很多比如接入更多国产大模型服务商、增加按量计费统计、加 Web 管理面板、做用量报表、给不同团队分配不同网关 Key、对接私有知识库等。对个人开发者来说先用免费额度把链路跑熟比一开始追求复杂生产架构更有价值。建议收藏备用等你有多个 AI 服务商要接的时候回来把这套逻辑搭起来。
用Cloudflare Workers免费搭建AI聚合网关：统一管理多模型API
这次我们来看一个很有意思的轻量级项目用一周时间搓出来的 AI 聚合网关核心卖点是“一键部署到 Cloudflare免费上云”。它解决的痛点很直接当你手上的 AI 服务商越来越多OpenAI、Anthropic、Google、Groq、国产大模型各有各的 Base URL、密钥体系和模型命名规则业务端要接哪家就得改哪家测试脚本、批量任务、内部工具全被上游 API 格式绑死。这个网关把上游全部收口成一个统一入口对外暴露一套兼容 OpenAI 格式的 API剩下的路由、鉴权、缓存、失败切换都由网关处理。先给结论这类项目适合 AI 应用开发者、自动化脚本作者、团队内部工具负责人。部署平台是 Cloudflare Workers天然免费额度不需要自己买服务器因为有 workers.dev 域名部署完成就能拿到一个公网 HTTPS 地址网关本身不参与模型训练也不保存对话内容只做请求转发和策略控制。下面我会从核心能力、部署方式、路由配置、接口测试、批量任务、性能观察和排错清单几个维度完整过一遍你可以边看边对着自己的项目试。1. 核心能力速览能力项说明项目类型云端部署的 AI API 聚合网关统一接入多家大模型服务商目标平台Cloudflare Workers / Pages常见方式为 Workers KV 组合部署方式一键部署脚本 / Wrangler CLI / Cloudflare 控制台在线编辑核心功能OpenAI 兼容接口、上游服务商配置、自动路由、流式响应、结果缓存、失败切换、密钥托管API 风格对外提供/v1/chat/completions等兼容接口业务端改动最小免费额度依赖 Cloudflare Workers 免费计划个人测试和小流量够用具体配额以 Cloudflare 官方为准显存/硬件要求无。网关是纯云端逻辑不跑本地模型不需要 GPU是否支持批量任务支持。网关本身是 HTTP 转发层可被外部脚本批量调用配合重试和队列即可适合场景个人工具、团队内部 AI 中台、自动化脚本统一入口、多服务商比价与容灾不适合场景大规模生产级高并发、低延迟本地推理、需要长连接私有协议的场景从材料看这个项目最大特点是“免费 一键 白嫖 Cloudflare”对个人开发者和中小团队非常友好。要注意的是网关不提供模型算力你仍然需要各家服务商的 API Key只是由网关统一管理。2. 适用场景与使用边界2.1 适合谁同时使用多家 AI 服务商想统一切换和降级策略的开发者。不想在每个脚本和服务里重复写 API Key、Base URL 和请求头的团队。想给内部项目做一个轻量 AI 接入层但不想单独维护一台服务器的团队。喜欢用 Cloudflare 免费额度解决基础设施问题的技术玩家。2.2 能解决的问题统一接口业务端只认网关的地址上游换成哪家都不影响业务端。密钥集中管理各家 Key 放在 Cloudflare 环境变量或 KV 里不散落在代码仓库。失败切换某家服务商限流或故障时网关自动换到备用服务商。缓存降本命中缓存的重复请求不向上游计费能明显降低高频调用成本。可观测性网关层可以记录请求来源、模型、耗时、状态码给后续用量分析打底。2.3 不适合什么需要极低延迟、本地数据不出内网的企业场景网关只做转发不适合私有化推理。有严格合规要求、不允许请求经过第三方平台的业务。需要自定义传输协议或双向流式长连接的场景。2.4 使用边界与合规提醒聚合网关只改变 API 接入方式不改变数据归属和内容责任。调用任何模型前需要确认上游服务商是否允许代理转发是否覆盖存储与训练条款请求内容是否包含个人信息、商业秘密或敏感数据如果有先做脱敏如果使用人脸、声音、版权素材相关的生成模型必须保证素材来源合法授权部署到公共互联网后网关接口默认就是公开的必须加上访问鉴权避免被刷量。3. 部署前准备与前置条件我不建议一上来就改代码先把环境确认清楚至少能少踩一半的坑。3.1 需要准备的东西项目要求Cloudflare 账号免费注册即可最好开启二次验证域名或开发子域workers.dev 默认域名即可也可以绑定自定义域名上游服务商 API Key至少准备一家可用的 Key例如 OpenAI、Anthropic、智谱、DeepSeek 等Node.js 环境如果使用 Wrangler CLI建议 Node 18 或更高版本代码工具建议准备 Git方便拉取和提交项目代码3.2 免费计划额度预期Cloudflare Workers 免费计划有每日请求数、CPU 时间、KV 读写次数等限制具体数字会随官方政策调整。实际部署时以 Cloudflare 控制台显示的剩余配额为准。个人开发、内部脚本、低频 API 调用基本够用如果做高并发生产接口需要评估付费计划。3.3 安装 Wrangler CLI# 全局安装 wrangler具体版本以官方 npm 包为准 npm install -g wrangler # 验证安装 wrangler --version安装完成后先登录wrangler login浏览器会弹出 Cloudflare 授权页面登录并确认授权即可。如果你的网络环境无法直接访问 Cloudflare请优先检查本地网络和服务连通性不要在网关项目中配置任何代理相关功能。4. 一键部署到 Cloudflare这里给出两种部署方式按你的习惯选择。4.1 方式一通过 Wrangler 命令行部署假定你已经把项目代码克隆到本地进入项目根目录典型的部署流程是# 安装项目依赖 npm install # 部署 worker wrangler deploy部署完成后终端会输出一个形如https://your-worker.你的子域.workers.dev的地址这就是网关对外入口。如果项目里有自定义的wrangler.toml或wrangler.jsonc配置部署前需要注意name、main、compatibility_date和kv_namespaces是否正确。一个简化配置示例name ai-gateway main src/index.js compatibility_date 2025-01-01 # 如果网关用到缓存需要绑定 KV namespace # kv_namespaces [ # { binding CACHE_KV, id your-kv-namespace-id } # ] [vars] DEFAULT_MODEL gpt-4o-mini注意compatibility_date需要实际可用的日期KV 绑定需要先创建 namespace上面的代码只作为通用模板。4.2 方式二通过 Cloudflare 控制台在线部署如果你不想装命令行工具可以直接在 Cloudflare 控制台创建 Worker打开 Cloudflare Dashboard进入 Workers 与 Pages。点击“创建应用程序”然后选择“创建 Worker”。把网关项目的index.js或主要入口代码粘贴到在线编辑器中。在“设置”中添加环境变量逐个放上游 API Key。点击“部署并启用”系统会自动生成访问地址。这种方式适合快速验证但后续要处理多个文件、复杂依赖时还是建议用 Wrangler。4.3 创建 KV 缓存空间如果网关实现里使用缓存需要先创建一个 KV namespace。wrangler kv namespace create CACHE_KV创建完成后控制台会返回一个id把它填到wrangler.toml的绑定里再重新部署。KV 的作用是缓存部分重复请求的响应减少上游调用。4.4 校验部署是否成功部署完成后直接访问根路径预期返回一个简单的 JSON 信息例如{status:ok}或网关名称。如果页面报 404说明服务入口路径不是根路径去控制台查看路由配置。5. 配置上游服务商与路由策略网关的核心价值不在转发本身而在策略。5.1 环境变量里放 Key不建议把 Key 写在代码里而是通过环境和 secrets 注入。使用 Wrangler 设置wrangler secret put OPENAI_API_KEY wrangler secret put ANTHROPIC_API_KEY wrangler secret put DEEPSEEK_API_KEY命令运行后会要求输入 Key 内容保存到 Cloudflare 的加密存储中。这样代码仓库不会出现明文密钥。5.2 服务商路由规则一个常见的路由思路是客户端请求时指定一个provider参数网关根据该参数把请求转发到对应的 Base URL并替换模型名。另一种思路是网关维护一套“模型名到服务商”的映射表客户端只传model网关查表决定转发到哪家。例如const providers { openai: { baseUrl: https://api.openai.com/v1, apiKeyName: OPENAI_API_KEY, modelMapping: { gpt-4o-mini: gpt-4o-mini } }, deepseek: { baseUrl: https://api.deepseek.com/v1, apiKeyName: DEEPSEEK_API_KEY, modelMapping: { gpt-4o-mini: deepseek-chat } } };上面的代码是通用配置示例实际字段名需要以网关项目源码为准。路由逻辑一般位于 Worker 的fetch处理器中收到请求后读取 URL 参数或请求体里的字段决定 target provider。5.3 失败切换策略可靠性比较好的网关会做“主服务商 备用服务商”。主服务商返回 429、5xx 或网络错误时自动重新请求备用服务商。实现时要注意必须设置上游请求超时时间不能无限等待切换后要记录日志方便排查流式响应过程中如果主链路中断切换比较麻烦建议非流式或短流场景先启用。5.4 统一鉴权网关暴露到公网后必须加一层访问控制。最简单的方式是网关自身也校验一个AuthorizationBearer Tokenwrangler secret put GATEWAY_API_KEY客户端调用时携带网关自己的 Key而不是上游 Key。网关验证通过后再替换成上游 Key 去请求目标服务商。6. 功能测试与效果验证部署完成后建议按下面顺序做一轮完整验证不要直接上业务。6.1 验证统一入口是否可用用 curl 发送一个最小编译请求curl -s https://your-worker.子域.workers.dev/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的网关Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好请回复网关连通}], stream: false }如果返回内容包含choices字段和模型输出说明统一入口正常密钥替换也正常。如果返回 401检查网关 Key 是否正确如果返回 502检查上游服务商 Key 或 Base URL 配置。6.2 验证流式输出curl -N https://your-worker.子域.workers.dev/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的网关Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 写一个30字的自我介绍}], stream: true }输出应该是data:开头的 SSE 流最后有[DONE]。如果使用 Node 或 Python 的官方 OpenAI SDK只需把base_url指向网关地址业务代码几乎不用改。Python 调用示例from openai import OpenAI client OpenAI( api_key你的网关Key, base_urlhttps://your-worker.子域.workers.dev/v1 ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}], streamTrue ) for chunk in resp: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end) print()注意模型名要传网关能识别的模型名具体取决于配置。如果网关本身做模型映射你需要按你自己的映射表传参。6.3 验证缓存是否生效开启缓存后连续向网关发两次完全相同的请求。第二次请求的响应时间应明显下降并且 Cloudflare 侧不会产生新的上游计费。判断方式可以看网关日志中是否出现cache hit标识或者查看响应耗时。6.4 验证失败切换临时把主服务商的 Key 改成错误值再发起请求。预期网关自动切换到备用服务商并返回结果。如果网关直接返回 502说明切换逻辑没有配通需要查看日志。6.5 验证批量并发用 Python 脚本模拟 10 个并发请求统一打到网关import requests from concurrent.futures import ThreadPoolExecutor url https://your-worker.子域.workers.dev/v1/chat/completions headers { Authorization: Bearer 你的网关Key, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [{role: user, content: 回复OK}], stream: False } def call_one(i): resp requests.post(url, headersheaders, jsonpayload, timeout30) return resp.status_code with ThreadPoolExecutor(max_workers10) as pool: codes list(pool.map(call_one, range(10))) print(codes)这一步重点验证网关鉴权、路由和限流是否正常。出现 429 或 5xx 时排查 Cloudflare 限流策略和上游服务商配额。7. 接口 API 与批量任务7.1 API 语义设计网关对外接口建议做一层统一规范至少包括以下请求字段字段含义是否必填model模型名例如gpt-4o-mini、deepseek-chat是messages对话消息列表是temperature采样温度否max_tokens最大输出长度否stream是否流式否provider强制指定服务商否不传则自动路由返回格式建议与 OpenAI 保持一致这样现有 SDK 直接可用。7.2 批量任务设计网关本质是 HTTP 服务不内置任务队列但完全可以作为批量任务的目标端。批量任务通常是这样做的准备一批 prompt 文件例如 JSON 数组每条包含id和content。用脚本逐条或分批调用网关接口。收集结果并写入本地文件或数据库。对失败的请求做重试。Python 批量脚本示例import json import time import requests url https://your-worker.子域.workers.dev/v1/chat/completions headers { Authorization: Bearer 你的网关Key, Content-Type: application/json } with open(tasks.json, r, encodingutf-8) as f: tasks json.load(f) results [] for task in tasks: payload { model: gpt-4o-mini, messages: [{role: user, content: task[content]}], stream: False } try: resp requests.post(url, headersheaders, jsonpayload, timeout60) if resp.status_code 200: data resp.json() answer data[choices][0][message][content] results.append({ id: task[id], content: task[content], answer: answer, status: ok }) else: results.append({ id: task[id], status: failed, error: resp.text }) except Exception as e: results.append({ id: task[id], status: exception, error: str(e) }) # 温和限速避免触发上游限制 time.sleep(0.5) with open(results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2)批量任务最容易遇到两个问题一个是上游限流导致大量 429另一个是单条请求超时导致整个脚本卡住。建议批量任务里加入重试、限速和断点续跑能力。7.3 读取流式响应做批处理如果模型本身只支持流式批量脚本需要解析 SSE 流。可以逐行读取找到data: [DONE]作为结束标志。这种方式内存占用更低但代码会复杂一些。8. 资源占用与性能观察这部分是很多人关心的重点但注意Cloudflare Workers 是 Serverless 平台不存在传统意义上的显存、内存常驻占用。你能观察到的指标主要是请求数量、CPU 时间、KV 读写次数和网络耗时。8.1 观察出口登录 Cloudflare 控制台进入对应 Worker 的分析页面可以看到请求总数成功率和错误码分布请求耗时分布上游调用次数如果网关代码中有上报逻辑每日额度消耗8.2 影响性能的关键点上游响应时间网关本身转发很快瓶颈基本在上游模型响应。缓存命中率命中率高网关 CPU 时间和 KV 读取量都更低请求耗时也更短。流式 vs 非流式流式响应能更快返回首字但对网关的代码逻辑要求更严格。请求体大小大 prompt 会增加请求转发耗时Cloudflare 对请求体大小也有限制超大文本要做拆分。并发策略Workers 可以并发处理请求但上游服务商有速率限制网关层需要内置令牌桶或失败回退。8.3 降低资源消耗的建议开启缓存对同 prompt 重复请求直接返回。为不同业务拆多个入口路径避免一个 Worker 被占满配额。错误响应不要做大量字符串拼接减少 CPU 时间消耗。日志输出控制在业务关键节点避免每条请求都写很多结构化日志。8.4 比较不同上游服务商如果你把多家服务商接入同一个网关可以做一个简单的“耗时对照表”providermodel是否流式返回耗时状态码备注providerAmodel-a否2.3s200稳定providerBmodel-b否4.1s200偏慢providerCmodel-c否失败429配额不足这个过程只是网关接入能力的验证不作为模型效果排序依据。9. 常见问题与排查方法问题现象可能原因排查方式解决方案部署后访问返回 404Worker 路由路径不对或入口代码未导出 fetch 处理器打开控制台测试 / 观察日志确认主文件正确绑定fetch事件请求返回 401网关 Key 错误或未配置检查Authorization请求头重新设置GATEWAY_API_KEY请求返回 502上游 Base URL、Key 或模型名错误查看 Worker 日志中上游错误信息核对服务商文档替换正确配置上游返回 429触发服务商限流查看响应头X-RateLimit-*做请求限速、缓存、降级到备用服务商流式输出中断上游流被切断或网关未处理 SSE检查网络稳定性确认代码支持streamtrue分批重试或改用非流式缓存不生效KV 未绑定、请求体含随机参数或缓存键设计错误查看绑定配置和缓存日志修正缓存键只对稳定字段做哈希批量脚本中途失败单条请求超时或上游配额耗尽查看脚本日志记录失败位置加入断点续跑、重试、记录已完成 ID配额消耗过快缓存未生效、并发过高或日志过于频繁控制台查看请求分布开启缓存、控制并发、精简日志自定义域名访问失败DNS、路由规则或证书问题检查域名解析和 Worker Routes在控制台绑定自定义域名并等证书生效代码更新后未生效部署流程未完成或缓存了旧版本重新wrangler deploy清理版本缓存使用新版本部署并观察版本 ID其他服务商请求格式兼容问题各家 API 的字段差异导致参数冲突对比服务商文档与网关源码在网关层做参数归一化排查时最有效的办法是打开 Cloudflare Worker 的实时日志看每次请求转发到哪家、返回的状态码以及报错内容。日志里定位不到的问题再考虑是否混淆传参、模型映射错误或公网连通性问题。10. 最佳实践与使用建议10.1 从最小配置开始第一次部署只接一家服务商先用最简配置把链路跑通。确认统一入口、鉴权、基础对话都没问题后再加第二家、加缓存、加失败切换。不要一开始就把所有模型堆上去否则出问题时很难定位是哪一步。10.2 密钥分离网关 Key、管理人员 Key、各上游 Key 要分开管理。上游 Key 放在 Cloudflare secrets 中不要出现在代码仓库、日志、前端页面或抓包工具中。10.3 缓存键要稳定缓存命中率取决于缓存键的设计。推荐对以下内容做哈希模型名温度等核心采样参数归一化后的 messages 内容不要把时间戳、随机数、请求 ID 放入缓存键否则缓存形同虚设。10.4 批量任务要三件套日志、重试、断点日志每条任务记录 id、请求时间、响应时间、状态码、错误消息。重试遇到 429、5xx、超时才重试不重试 4xx 校验错误。断点记录已完成 id再次运行脚本时跳过已完成任务。10.5 网关鉴权要尽早做你的网关部署到公网很容易被扫描器打。即使只是内部工具也要加上全局鉴权。更稳妥的做法是网关只响应携带正确Authorization的请求其它请求直接返回 401。生产环境还可以加 IP 白名单、地区限制或自定义访问规则但纯免费计划下人力和规则配置能力有限先保住密钥安全。10.6 合规与内容审核聚合网关简化的是技术接入不是责任转移。如果业务要面向外部用户开放建议在网关层增加关键词过滤、输入长度限制、输出内容复核等逻辑。涉及人脸、声音、版权素材等场景必须在上游服务商允许的范围内使用并取得所有必要授权。11. 总结与下一步这个项目最值得尝试的点是用 Cloudflare Workers 的免费额度搭出一个标准的 AI 接入层。不用买服务器不用管运维不用为每家 AI 服务商写一套独立请求代码一个统一入口就能把路由、缓存、失败切换、密钥管理都收进来。如果你准备自己动手我建议按这个顺序跑注册 Cloudflare 账号创建 Worker。只接一家服务商用 curl 验证非流式和流式请求。接第二家服务商配置模型映射和失败切换。加 KV 缓存对比两次相同请求的耗时。写一个 Python 批量脚本验证多请求场景。最后把网关 Key 换掉去掉测试配置再上业务。最容易踩的坑基本集中在三类上游服务商配置错误导致 502、缓存键设计不合理导致配额浪费、网关公网部署后没有加鉴权被刷。前两个坑多看看 Worker 日志就能解决最后一个坑必须在部署早期规避。网关这类项目后续还可以扩展的方向很多比如接入更多国产大模型服务商、增加按量计费统计、加 Web 管理面板、做用量报表、给不同团队分配不同网关 Key、对接私有知识库等。对个人开发者来说先用免费额度把链路跑熟比一开始追求复杂生产架构更有价值。建议收藏备用等你有多个 AI 服务商要接的时候回来把这套逻辑搭起来。 
