自托管AI API网关AKDN：统一管理多模型服务，实现智能路由与故障转移

1. 项目概述为什么你需要一个自托管的AI API网关如果你和我一样手里攒了好几个不同AI服务商的API密钥——OpenAI的、Claude的、DeepSeek的还有国内国外各种大大小小的模型平台——那你肯定也头疼过管理问题。每次在OpenClaw、LobeChat这些应用里切换模型都得手动改一遍API地址和密钥麻烦不说还容易出错。更别提某个服务商突然抽风或者你的用量超了配额整个应用就卡在那里用户体验直线下降。AKDNAI API Key Delivery Network就是来解决这个痛点的。简单说它是一个你完全可以自己部署的“智能中转站”。你只需要把所有AI提供商的API密钥都配置到AKDN里然后让你所有的下游应用比如聊天客户端、自动化脚本都指向AKDN这一个地址。之后无论是切换模型、轮换密钥以防限流还是设置用量配额、在多个服务商之间做故障转移你都可以在AKDN的统一面板里搞定下游应用完全无感。我自己部署使用了一段时间最大的感受就是“省心”。以前需要时刻盯着各个平台的余额和响应状态现在AKDN的仪表盘一目了然。哪个提供商慢了、挂了、配额快用完了它都能自动处理把请求智能地路由到健康的节点上。这对于需要高可用性的生产环境或者只是想更优雅地管理个人AI工作流的开发者来说是个非常实用的工具。2. 核心架构与工作原理拆解2.1 整体设计思路化繁为简的代理层AKDN的核心设计哲学是在用户的应用与真实的AI API提供商之间插入一个轻量、智能的代理层。这个设计听起来简单但里面包含了几个关键考量首先兼容性是基石。它选择完全兼容OpenAI的API格式/v1/chat/completions。这意味着市面上绝大多数基于OpenAI SDK开发的应用如OpenClaw、LobeChat、ChatGPT-Next-Web都能无缝接入几乎不需要修改任何代码。这极大地降低了用户的迁移成本也是项目能快速被接受的关键。其次状态集中管理。所有敏感信息各个厂商的API Key和路由逻辑用哪个厂商、什么模型都收归AKDN统一管理。下游应用只需要记住AKDN的地址和一个由AKDN生成的“通行证密钥”key0。这样一来即使你更换了底层的API提供商或者某个密钥失效需要轮换也只需要在AKDN后台操作一次所有连接的应用会自动生效实现了配置的“一次变更处处生效”。最后智能路由与韧性。这是AKDN区别于简单反向代理的核心价值。它不是一个被动的转发器而是一个主动的流量调度器。它持续监控后端各个提供商Provider的健康状态、响应速度和配额使用情况并基于你设定的策略如优先级、轮询来智能分配请求。当某个提供商出现故障时它能自动将请求切换到备用节点保障服务的连续性。2.2 核心概念解析Provider、Strategy与Key0要玩转AKDN必须理解它抽象出来的三个核心对象这构成了其配置的逻辑骨架。1. Provider提供商这是指一个具体的AI API服务端点。例如一个OpenAI账户使用gpt-4模型可以作为一个Provider另一个使用claude-3-opus模型的Anthropic账户是另一个Provider。在AKDN中你需要为每个这样的端点创建独立的Provider配置内容包括基础URL和API密钥目标服务的真实地址和密钥。模型映射指定此Provider实际使用的模型名称。这是实现“模型抽象”的关键下游应用可以统一请求一个虚拟模型如“akdn”AKDN会根据路由结果将请求中的模型字段替换成该Provider配置的真实模型。代理设置可为每个Provider单独配置HTTP或SOCKS5代理这对于访问有地域限制的服务非常有用。配额限制设置该Provider每天/每月可使用的提示词Prompt和补全Completiontoken上限。2. Strategy策略策略定义了请求的路由规则。你可以创建多个策略来应对不同场景。例如一个“主力策略”优先使用GPT-4挂掉后用Claude-3备份另一个“低成本策略”则轮询使用多个便宜的模型。每个策略包含调度模式优先级Priority严格按照你设定的Provider顺序尝试。只有当前一个彻底失败或配额用尽时才会尝试下一个。适合有明确主备关系的场景。轮询Round Robin在策略内所有可用Provider间循环分发请求。适合负载均衡平摊使用量和成本。关联的Provider列表将上面创建的Provider添加到策略中并可以排列优先级。策略级配额除了Provider自身的配额外你还可以为整个策略设置总用量上限实现更灵活的预算控制。3. Key0应用密钥这是AKDN向下游应用暴露的统一接口密钥。当你创建一个策略后AKDN会为其生成一个唯一的Key0格式如akdn-a1b2c3d4...。你的OpenClaw、LobeChat等应用只需要配置AKDN的服务器地址和这个Key0就像配置一个普通的OpenAI服务一样。Key0与策略绑定所有使用该Key0的请求都会按照其绑定策略的规则进行路由。三者关系图解你的AI应用 (使用 Key0) ↓ 访问 AKDN ↓ AKDN 验证 Key0 → 找到关联的【策略】 ↓ 【策略】根据模式优先级/轮询选择一个健康的【提供商】 ↓ 【提供商】使用其自身的API密钥和模型将请求转发至真实AI服务 ↓ 响应流经AKDN返回给你的应用这个设计清晰地将“身份认证”Key0、“路由逻辑”Strategy和“执行端点”Provider解耦提供了极大的灵活性。3. 详细部署与配置指南3.1 环境准备与部署方案选择AKDN提供了多种部署方式你可以根据自身的技术栈和运维习惯来选择。方案一一键脚本安装推荐给新手或快速体验这是最快捷的方式特别适用于干净的Debian/Ubuntu系统。curl -fsSL https://raw.githubusercontent.com/Yorkian/AKDN/main/install.sh | sudo bash这个脚本会自动完成以下工作检查并安装Node.js 20运行环境。安装PM2进程管理工具用于守护AKDN进程。克隆GitHub仓库到/opt/akdn目录。安装前后端所有依赖npm包。运行构建命令编译TypeScript和前端资源。自动生成加密密钥用于加密存储的API Key和JWT签名这是安全运行的关键。启动服务默认监听在服务器的3060端口。脚本执行完毕后直接在浏览器访问http://你的服务器IP:3060即可进入初始化页面创建管理员账户。整个过程基本无需人工干预。注意一键脚本通常以root权限运行且会修改系统服务。如果你对生产环境的权限控制有严格要求或者系统环境比较特殊如非Debian系Linux建议使用下面的Docker方案它能提供更好的环境隔离。方案二Docker部署推荐用于生产环境Docker方案提供了最好的可移植性和一致性避免了环境依赖问题。# 创建项目目录并下载docker-compose.yml mkdir akdn cd akdn curl -fsSL https://raw.githubusercontent.com/Yorkian/AKDN/main/docker-compose.yml -o docker-compose.yml # 启动容器 docker compose up -d这个docker-compose.yml文件定义了一个使用官方镜像yorkian/akdn:latest的服务。它会将容器内的3060端口映射到宿主机的3060端口。创建一个名为akdn-data的Docker卷volume用于持久化存储数据库、加密密钥和配置文件。设置容器自动重启策略。首次运行容器时AKDN会在卷内自动生成加密密钥。所有数据包括你后续添加的API Key都会安全地保存在这个卷里即使删除并重建容器数据也不会丢失。方案三手动安装适合深度定制或开发如果你需要修改源码或者希望更精细地控制安装路径和依赖版本可以选择手动安装。# 1. 克隆代码 git clone https://github.com/Yorkian/AKDN.git /opt/akdn cd /opt/akdn # 2. 安装后端依赖并构建 npm install npx tsc # 编译TypeScript # 3. 安装前端依赖并构建 cd frontend npm install npx vite build cd .. # 4. 生成加密密钥关键步骤 node setup-keys.js # 此命令会生成.env文件内含AKDN_ENCRYPTION_KEY和JWT_SECRET # 5. 使用PM2启动并管理进程 npm install -g pm2 pm2 start ecosystem.config.js pm2 save # 保存进程列表 pm2 startup # 设置开机自启根据提示执行生成的命令手动安装让你对每一个环节都了然于胸方便后续的调试和自定义开发。3.2 初始配置与安全加固无论采用哪种部署方式首次通过http://IP:3060访问时都会进入管理员账户创建页面。这里设置的用户名和密码将用于登录Web控制面板请务必使用强密码。关键安全配置加密密钥备份AKDN使用AKDN_ENCRYPTION_KEY来加密存储在数据库中的真实API密钥。这个密钥在首次运行时自动生成位于/app/data/.akdn-keys.json或项目根目录的.env文件中。务必备份这个密钥或整个.env文件如果丢失或更改此密钥之前存储的所有API密钥将无法解密导致服务不可用。修改默认端口如果3060端口与现有服务冲突可以通过修改.env文件中的PORT环境变量来更改。配置反向代理与HTTPS生产环境必做直接暴露3060端口是不安全的。你应该使用Nginx或Caddy等反向代理并配置SSL证书启用HTTPS。# Nginx 示例配置片段 server { listen 443 ssl http2; server_name akdn.yourdomain.com; # 你的域名 ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { proxy_pass http://127.0.0.1:3060; # 指向AKDN实际运行地址 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下两行对SSE流式传输至关重要 proxy_buffering off; proxy_cache off; } }配置完成后你的下游应用就应该使用https://akdn.yourdomain.com来访问AKDN服务。3.3 添加第一个Provider与Strategy登录Dashboard后我们就可以开始配置核心内容了。第一步添加Provider点击左侧导航栏的“Providers”然后点击“ New Provider”。基本设置Name: 起个易记的名字如 “OpenAI GPT-4 Turbo”。Base URL: 填写API服务的基础地址例如OpenAI的是https://api.openai.com/v1。对于Azure OpenAI或其他兼容服务填写对应的端点。API Key: 粘贴该服务商提供的真实API密钥。请注意此密钥将被AKDN加密后存储。Model: 填写该Provider实际要使用的模型名如gpt-4-turbo-preview。这是“模型覆盖”的目标值。高级设置按需Priority: 在优先级调度模式下的权重数字越小优先级越高。Proxy: 如果需要通过代理访问该服务商在此处配置HTTP或SOCKS5代理地址。Quotas: 设置该Provider的用量限制例如每天最多使用 1,000,000 个Prompt Tokens。点击“Create”。你可以重复此步骤添加Claude、DeepSeek等其他Provider。第二步创建路由策略点击左侧导航栏的“Strategies”然后点击“ New Strategy”。基本设置Name: 策略名称如 “主力策略-优先GPT4”。Scheduling Mode: 选择Priority优先级或Round Robin轮询。关联Provider在 “Providers” 区域从右侧列表中选择你刚刚创建的Provider点击箭头添加到左侧“Selected Providers”列表中。你可以添加多个并通过上下箭头调整它们在优先级模式下的顺序。设置策略配额可选你可以在策略层面设置总Token消耗上限作为第二道管控。点击“Create”。第三步获取Key0并配置下游应用创建Strategy成功后页面会显示生成的Key0格式为akdn-xxx。这个Key0就是你的下游应用需要使用的“万能密钥”。以配置LobeChat为例进入LobeChat设置 - 语言模型 - OpenAI。在API Key字段填入AKDN生成的Key0。在Endpoint字段填入你的AKDN服务地址并加上/v1路径如https://akdn.yourdomain.com/v1。模型名称可以任意填写如akdn因为实际模型由AKDN的Provider配置决定。保存设置。现在LobeChat的所有请求都会通过你的AKDN网关进行路由。4. 高级功能与实战调优4.1 故障转移与健康检查机制深度解析AKDN的故障转移Failover不是简单的“出错就换”而是一个有状态、可恢复的智能过程。理解其细节有助于你更好地配置和排错。故障检测时机流式请求SSE这是最复杂的情况。AKDN将流式响应视为一个持续的数据流。在收到第一个Token之前超时如果在一个可配置的超时窗口FIRST_TOKEN_TIMEOUT默认15秒内没有从Provider收到任何数据流AKDN会判定此次请求失败立即中止并向客户端返回错误同时将该Provider标记为“故障”Fault并尝试策略中的下一个Provider如果配置了的话。这对于处理某些提供商偶发的“假死”非常有效。流式传输中断如果流已经开始传输但中途异常断开如网络波动、提供商服务中断AKDN会尽力将已收到的数据传回客户端。同时它会将该Provider标记为“不稳定”并可能在未来一段时间内降低其优先级或暂时移出健康池但不会立即中断当前客户端的连接。非流式请求相对简单。如果请求在NON_STREAM_TIMEOUT默认30秒内没有完成或返回非2xx状态码特别是5xx则判定为失败标记Provider为“故障”并尝试下一个。故障恢复健康检查被标记为“故障”或“不稳定”的Provider并不会被永久抛弃。AKDN后台运行着一个健康检查守护进程每隔HEALTH_CHECK_INTERVAL默认60秒就会对“故障池”中的Provider进行一次探活。检查方式发送一个极轻量的测试请求例如一个只包含hi的聊天补全请求到该Provider。恢复条件如果探活请求成功完成AKDN会将该Provider的状态从“故障”重置为“正常”并重新将其纳入调度池。实操建议超时参数调整FIRST_TOKEN_TIMEOUT和NON_STREAM_TIMEOUT可以在.env文件中调整。如果你的网络到某个提供商延迟较高但稳定性尚可可以适当调大超时时间避免误判。观察故障池Dashboard的“Providers”页面会清晰显示每个Provider的状态正常、故障、节流。定期查看这里可以了解各个服务商的稳定性。优先级策略配置对于“优先级”模式请将你认为最稳定、最快的Provider放在列表最前面。只有当前面的Provider连续失败进入故障状态流量才会切到下一个。4.2 配额管理与成本控制实战对于个人开发者或小团队控制AI API的使用成本至关重要。AKDN的配额管理系统提供了两层控制。第一层Provider级配额这是最直接的管控。在创建或编辑Provider时你可以设置Prompt Token Limit: 该Provider允许消耗的提示词Token总数上限。Completion Token Limit: 该Provider允许消耗的补全Token总数上限。Reset Interval: 配额重置周期如“每日”、“每月”或“永不”总上限。当某个Provider的用量达到其配额上限时它的状态会变为“Throttled”节流。在调度时处于“节流”状态的Provider会被跳过请求会自动路由到策略中其他可用的Provider。这完美实现了“预算用尽自动切换”的需求。第二层Strategy级配额除了控制单个Provider你还可以为整个Strategy设置一个总配额。例如你有一个“图文创作策略”里面包含了GPT-4和Midjourney的接口如果支持。你可以为这个策略设置一个月的总Token预算无论内部怎么分配总额度不会超。Dashboard数据监控AKDN的仪表盘提供了强大的数据可视化。用量趋势图以折线图展示不同时间段内Prompt和Completion Token的消耗情况帮助你识别使用高峰和模式。提供商排名按请求量或Token消耗量对Provider进行排序一目了然谁是主力。实时请求日志记录每一笔请求的详细信息包括时间、客户端IP匿名化处理、使用的策略和Provider、消耗的Token数同时记录提供商返回的数值和AKDN本地估算的数值可用于交叉验证、响应状态以及通过GeoIP解析出的客户端大致地区国家级别。成本控制实战技巧设置预警阈值虽然AKDN没有内置告警但你可以通过定期查看Dashboard或自行编写脚本读取其数据库需谨慎在用量达到配额的80%或90%时给自己发送通知。利用轮询模式平摊成本如果你有多个相同价位、相同能力的Provider例如两个不同账号的相同模型使用“轮询”策略可以均匀地分配请求避免单个账号过快触达速率限制或用量上限。创建低成本备用策略专门创建一个策略里面只包含如gpt-3.5-turbo或claude-haiku这类低成本模型并将此策略的优先级设置得较低。当主力策略如GPT-4因配额用尽或故障而不可用时流量可以自动降级到这个低成本策略保证服务不中断同时控制意外成本。4.3 代理配置与地理限制绕过许多AI服务对访问来源有地域限制。AKDN支持为每一个Provider单独配置代理这个功能非常实用。配置方法在Provider的编辑页面找到Proxy字段。HTTP代理格式为http://用户名:密码代理服务器IP:端口或http://代理服务器IP:端口。SOCKS5代理格式为socks5://用户名:密码代理服务器IP:端口或socks5://代理服务器IP:端口。工作原理当AKDN需要向该Provider转发请求时它会通过你配置的代理服务器来建立连接。这意味着即使你的AKDN服务器部署在A地区你也可以通过配置一个位于B地区的代理来访问一个仅限B地区使用的AI API服务。注意事项代理性能代理会增加网络延迟。请选择稳定、低延迟的代理服务否则会影响AI响应的整体速度。代理安全性如果代理需要认证密码会以明文形式存储在AKDN的配置中尽管数据库已加密。请确保代理服务器本身是可信的。非全局代理此代理配置仅作用于该Provider对上游API的请求不影响AKDN本身对下游客户端的服务也不影响其他Provider。5. 常见问题排查与维护技巧5.1 部署与连接问题问题1一键安装脚本执行失败提示Node.js或npm错误。原因目标系统可能缺少基本的构建工具或Node.js版本过低AKDN需要Node.js 18。解决手动安装Node.js 20。对于Ubuntu/Debian可以尝试curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs或者放弃一键脚本直接使用Docker部署这是最干净、问题最少的方式。问题2服务启动成功但无法通过浏览器访问IP:3060。原因最常见的是服务器防火墙或安全组未开放3060端口。解决检查AKDN进程运行pm2 logs akdn如果使用PM2或docker logs akdn如果使用Docker查看日志确认服务是否在监听。检查本地防火墙sudo ufw status # 查看UFW状态 sudo ufw allow 3060/tcp # 如果使用UFW开放端口检查云服务商安全组登录到你的云服务器控制台如AWS安全组、阿里云安全组、腾讯云防火墙确保入站规则允许TCP 3060端口。问题3下游应用如LobeChat配置AKDN后测试连接失败或一直“转圈”。原因AKDN服务本身可能正常但无法连接到后端真实的AI API提供商。排查步骤检查AKDN Dashboard登录Dashboard查看“Providers”的状态。刚添加的Provider可能因为网络问题或API Key错误而处于“故障”状态。检查Provider配置确认Base URL和API Key完全正确没有多余的空格。可以尝试在服务器上用curl命令直接测试该Provider的API是否可达注意保护密钥curl https://api.openai.com/v1/chat/completions \ -H Authorization: Bearer YOUR_REAL_OPENAI_KEY \ -H Content-Type: application/json \ -d {model:gpt-3.5-turbo,messages:[{role:user,content:hi}]}查看AKDN日志日志中会记录每个请求转发的详细过程和错误信息。在Dashboard的“Logs”页面或者服务器的PM2/Docker日志中查找对应请求的报错通常是连接超时、认证失败401/403或额度不足429。5.2 路由与故障转移异常问题1配置了优先级策略但请求似乎没有按顺序走有时会用到后面的Provider。原因优先级调度只在当前优先Provider不可用故障、节流时才会尝试下一个。如果第一个Provider健康但响应慢未超时请求仍然会发给它。理解这不是BUG而是设计如此。AKDN的“故障”判定基于超时和HTTP错误码而不是响应速度。如果你希望将慢速响应也视为一种“不健康”目前版本需要你手动调整FIRST_TOKEN_TIMEOUT到一个更短的值但这可能会增加误判率。问题2某个Provider因网络波动进入“故障”状态后很久都没有自动恢复。原因健康检查探活请求本身也可能失败。排查在Dashboard上手动点击该Provider的“测试连接”按钮看是否能成功。检查服务器的网络连通性是否所有对外访问都出现了问题。检查该Provider的配额是否用尽配额用尽是“节流”状态健康检查不会恢复“节流”状态需要管理员手动重置配额或提高限额。临时解决你可以在Dashboard上手动将该Provider的状态从“故障”强制重置为“正常”。问题3流式响应SSE时断时续或者客户端收不到完整回复。原因这通常是网络问题或者反向代理配置不正确。解决确认反向代理配置如果你使用了Nginx务必在location /配置块中加上proxy_buffering off;和proxy_cache off;。缓冲和缓存会干扰SSE数据流的实时传输。检查超时设置确保Nginx的proxy_read_timeout等设置足够长例如设置为3600s以支持长时间对话。直连测试暂时绕过反向代理让客户端直接连接AKDN的3060端口测试流式响应是否正常。如果正常问题就出在反向代理配置上。5.3 数据维护与备份定期备份 AKDN的所有核心数据用户、配置、密钥、日志都存储在SQLite数据库文件默认位于./data/akdn.db和.env文件存储加密密钥中。Docker部署数据在名为akdn-data的卷中。备份该卷即可。# 找到卷的实际存储路径通常/var/lib/docker/volumes/... docker volume inspect akdn-data # 然后复制该路径下的所有文件进行备份手动/脚本部署备份项目目录下的data文件夹和.env文件。tar -czf akdn-backup-$(date %Y%m%d).tar.gz /opt/akdn/data /opt/akdn/.env更新版本 当项目发布新版本时更新流程很平滑。Dockercd /path/to/akdn docker compose pull docker compose down docker compose up -d手动部署cd /opt/akdn pm2 stop akdn git pull npm install cd frontend npm install npx vite build cd .. npx tsc pm2 restart akdn重要更新前请务必确认已备份.env文件。更新脚本或新版本通常不会覆盖它但以防万一。性能与监控 对于请求量较大的场景可以关注以下几点数据库性能SQLite在轻到中度负载下表现良好。如果请求日志表变得非常庞大可能会影响Dashboard查询速度。可以考虑定期归档或清理旧的请求日志需谨慎操作或等待未来版本提供日志管理功能。内存与CPU使用pm2 monit或docker stats监控AKDN进程的资源使用情况。Node.js服务通常内存占用稳定如果出现内存持续增长可能需要检查是否有内存泄漏。网络I/OAKDN作为代理会消耗上传和下载带宽。确保服务器所在网络的带宽足以支撑你的总流量。部署和使用了几个月AKDN已经成了我个人AI工作流中不可或缺的基础设施。它带来的最大价值不是某个炫酷的功能而是那种“无需操心”的稳定感。我再也不用在各个API平台之间来回切换也不用担心某个服务宕机导致我的自动化脚本中断。它的Web仪表盘给了我全局的视角成本控制变得前所未有的清晰。如果你也在管理多个AI服务强烈建议花点时间部署一套这种投入带来的效率提升和心智负担减轻绝对是值得的。