优秀的大模型API网关系统Veloera：Docker部署与TaoToken统一Key接入实践

1. 为什么要在 Docker 里跑 Veloera 这类 API 网关如果你手上有不止一个模型供应商的 Key比如一个用来跑日常对话、一个专门跑代码补全、还有一个备用防限流那很快就会遇到一个很现实的问题每换一个客户端就要重新填一遍地址和密钥团队里几个人共用一套额度时更是没法统计谁用了多少。Veloera 就是解决这类问题的 API 网关系统它基于 new-api 二次开发遵循 GPL 3.0 许可证可以自由使用和修改核心能力是把多个上游渠道聚合成一个统一入口对外只暴露一个 Base URL 和一把令牌。它适合谁个人开发者想给自己搭一个稳定的模型调用中转层小团队想集中管理额度和日志或者你正在做 AI 应用需要统一处理请求和响应都可以用。Veloera 支持多渠道、礼品码、正则屏蔽词、增强日志和 Token 统计这些功能在自用和运营两种模式下都能派上用场。我这次的做法是把它跑在 Docker 里然后用 TaoToken 作为统一的上游通道接进去。这样做的原因是Veloera 负责对外发令牌、记日志、做渠道分发TaoToken 负责提供稳定的模型 API 通道两边职责分开配置起来也清晰。下面从环境准备开始一步步给出可复制的 docker-compose 配置、环境变量清单以及启动后怎么验证连通性。先说清楚整体链路客户端比如 Cherry Studio、Cline→ Veloera 网关Docker 容器→ TaoToken API 通道 → 具体模型。你只需要在 Veloera 里配一次上游渠道之后所有客户端都连 Veloera 就行。这个结构的好处是以后换模型或者加渠道只改网关这一层客户端不用动。2. 前置准备TaoToken 统一 Key 与 Docker 环境在动手写 compose 文件之前先把两样东西准备好一个是 TaoToken 的 API Key一个是能跑 Docker 的环境。这两样缺一不可而且顺序上建议先拿 Key因为后面配渠道时要用到。TaoToken 在这里扮演的角色是统一的上游 API 通道。你可以把它理解成一个已经帮你对接好多种模型的入口你拿到一把 Key就能通过它去请求不同的模型不用自己一个个去对接供应商。对于 Veloera 来说TaoToken 就是一个标准的 OpenAI 兼容渠道填 Base URL 和 Key 就能用。拿 Key 的步骤不复杂。打开 TaoToken 的控制台进入 API Keys 页面新建一个密钥。建议给这个 Key 起个能认出来的名字比如veloera-gateway方便以后在日志里对照。创建完之后把 Key 复制出来注意它通常只完整显示一次先存到安全的地方。控制台入口https://taotoken.net/consoleAPI Keys 管理https://taotoken.net/api-keys接入文档https://taotoken.net/doc这里有个细节要提醒TaoToken 的 API 地址是https://taotoken.net/api注意结尾没有多余的斜杠也不带任何查询参数。在 Veloera 里填渠道地址时一般填到这个根路径就行Veloera 会自己拼接/v1/chat/completions这类后缀。如果你填成带/v1的地址可能会出现路径重复导致 404这个坑后面排障部分会再讲。Docker 环境方面你需要一台能跑容器的机器群晖、Linux 服务器、或者本地开发机都行。确认 Docker 和 docker-compose 都装好了可以用下面两条命令检查docker --version docker compose version如果第二条报错说compose不是有效命令试试docker-compose version老版本用的是带横杠的写法。两个命令的输出能正常显示版本号就说明环境没问题。另外建议提前规划好数据目录。Veloera 需要持久化两个位置一个是/data存数据库和配置一个是/app/logs存运行日志。我习惯放在/volume1/docker/veloera下面分成data和logs两个子目录。这样以后备份或者迁移直接打包这个文件夹就行。还有一点Veloera 默认监听容器内的 3000 端口映射到宿主机时你可以自己选比如 3056。选端口的时候注意别和已经占用的冲突可以用netstat -tlnp | grep 3056之类的命令先看一眼。3. 可复制的 docker-compose 配置与环境变量清单这一节是核心直接给你能用的配置。我先把完整的docker-compose.yml贴出来然后逐项解释每个环境变量的作用最后再给一份 JSON 格式的渠道配置片段方便你在 Veloera 后台直接粘贴。先建目录再写文件mkdir -p /volume1/docker/veloera/{data,logs} cd /volume1/docker/veloera然后把下面的内容保存成docker-compose.ymlversion: 3.8 services: veloera: image: ghcr.io/veloera/veloera:latest container_name: veloera restart: unless-stopped ports: - 3056:3000 volumes: - ./data:/data - ./logs:/app/logs environment: - TZAsia/Shanghai - SESSION_SECRETchange_this_to_a_random_string - STREAMING_TIMEOUT120 - SQL_DSN - LOG_LEVELinfo这份配置里image用的是官方 ghcr 镜像latest标签在我写这篇时对应 v0.4.8。ports把宿主机的 3056 映射到容器 3000。volumes把数据和日志挂出来保证容器重建后数据不丢。环境变量逐项说明变量名作用建议值TZ容器时区Asia/ShanghaiSESSION_SECRET会话加密密钥随机字符串务必改STREAMING_TIMEOUT流式回复超时秒数120SQL_DSN外部数据库连接串留空则用内置 SQLiteLOG_LEVEL日志级别infoSESSION_SECRET这个一定要改别用默认值否则会话安全性没保障。生成随机串可以用openssl rand -hex 32。SQL_DSN留空时 Veloera 会用内置的 SQLite自用完全够如果你打算跑运营模式、多人共用建议换成 MySQL 或 PostgreSQL把连接串填进去格式类似user:passwordtcp(host:3306)/dbname。启动容器docker compose up -d启动后看日志确认没有报错docker compose logs -f veloera日志里出现监听 3000 端口、数据库迁移完成之类的信息就说明起来了。第一次启动会自动跑数据库结构迁移稍等几秒。接下来是渠道配置。登录 Veloera 后台后新增渠道类型选 OpenAI 兼容然后填入 TaoToken 的信息。下面这份 JSON 片段可以直接参考字段名和后台表单对应{ name: taotoken-channel, type: 1, base_url: https://taotoken.net/api, key: sk-你的TaoToken密钥, models: gpt-4o,claude-3-5-sonnet,deepseek-chat, group: default, priority: 1 }这里type: 1代表 OpenAI 兼容类型base_url填 TaoToken 的 API 根地址key填你前面拿到的密钥models列出你要开放的模型 ID多个用逗号分隔。填完之后点测试能返回模型列表就说明渠道通了。三件套再强调一遍Base URL 是https://taotoken.net/apiKey 是你在 TaoToken 控制台创建的密钥Model ID 按你实际要用的填。这三个在 Veloera 渠道配置里缺一不可任何一个填错都会导致请求失败。4. 验证请求从容器启动到接口调通配置写完不算完得实际验证一遍。这一节按顺序走先确认容器状态再从 Veloera 发一次请求最后看日志确认链路通了。第一步确认容器在跑docker compose ps输出里STATUS显示Up就对了。如果显示Restarting或者Exited去看日志找原因常见的是端口占用或者挂载目录权限问题。第二步在 Veloera 后台创建令牌。进入「令牌」页面新建一个自用的话可以设成永不过期、无限额度省得以后老要改。创建完把令牌复制出来形如sk-xxxx。第三步用 curl 直接打 Veloera 的接口验证整条链路curl http://127.0.0.1:3056/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Veloera令牌 \ -d { model: gpt-4o, messages: [{role: user, content: 你好测试一下网关}], stream: false }如果返回里带有choices字段和模型回复内容说明 Veloera → TaoToken → 模型这条链路是通的。注意这里的model要填你在渠道里配置过的模型 ID填错了会报模型不存在。第四步看日志确认请求被记录docker compose logs --tail50 veloera日志里应该能看到这次请求的记录包括渠道名称、Token 统计。Veloera 的增强日志会显示总/输入/输出 Token方便你核对用量。第五步接客户端。以 Cherry Studio 为例添加供应商类型选 OpenAIAPI 密钥填 Veloera 生成的令牌API 地址填http://你的机器IP:3056。点管理能看到模型列表就说明客户端也通了。Cline 或者 Cursor 这类工具同理Base URL 填 Veloera 地址Key 填 Veloera 令牌。如果你用的是 Claude Code 这类需要 Anthropic 协议的工具Veloera 也支持对应的渠道类型配置思路一样只是渠道类型选 Anthropic 兼容Base URL 和 Key 还是填 TaoToken 的。具体路径可以参考接入文档里的说明。验证这一步别偷懒尤其是第一次搭的时候。我见过不少人配置看着没问题结果一调就报错最后发现是 Base URL 多写了个/v1或者 Key 复制时带了空格。花两分钟跑一遍 curl能省掉后面很多排查时间。5. 常见报错排查401、local proxy failed 与 reading choices搭网关最烦的就是报错信息不直观这一节把几个高频错误列出来对照着查。401 Unauthorized。这个最常见原因通常是 Key 不对或者没带上。先检查 Veloera 令牌是否正确请求头里Authorization: Bearer sk-xxx格式对不对注意Bearer和 Key 之间有一个空格。如果令牌没问题再去渠道里检查 TaoToken 的 Key 是否填对、有没有多余空格。还有一种情况是渠道被禁用了去渠道列表看状态是不是绿色。local proxy failed。这个报错一般出现在 Veloera 尝试连接上游渠道时。可能的原因有几个一是base_url填错比如填成了https://taotoken.net/api/v1导致路径重复二是容器内 DNS 解析有问题可以进容器docker exec -it veloera sh然后ping taotoken.net试试三是网络出口被限制。先确认base_url是https://taotoken.net/api结尾不带斜杠。reading choices 相关报错比如cannot read property choices of undefined。这通常说明上游返回的结构不是预期的 OpenAI 格式或者请求根本没成功。去日志里看这次请求的实际响应体如果上游返回的是错误信息而不是标准结构就会触发这个。检查模型 ID 是否在渠道的模型列表里以及 TaoToken 那边这个模型是否可用。OAuth 或鉴权类报错。如果你接的是需要 OAuth 的渠道报错可能和 token 过期有关。Veloera 里对应的渠道配置要填对 refresh token 之类的字段。这类问题建议直接看渠道的测试按钮返回什么比翻日志快。容器起不来。先看docker compose logs veloera如果是权限问题检查data和logs目录的属主如果是端口冲突换一个宿主机端口。群晖上还要注意目录路径是不是/volume1/docker/...这种实际存在的路径。模型列表为空。在客户端点管理看不到模型一般是渠道没配好或者令牌权限不对。回 Veloera 后台点渠道的测试按钮能拉到模型列表说明渠道 OK然后检查令牌的模型权限自用模式一般不限运营模式可能要做分组。排查的时候有个通用思路从下往上查。先确认容器在跑再确认 Veloera 自己能发请求再确认渠道测试通过最后才查客户端。这样能快速定位是哪一层出的问题。日志是你最好的朋友docker compose logs -f veloera挂着边操作边看报错基本都能对上。6. 把网关用起来令牌分发与长期维护网关搭好只是开始怎么用起来才是关键。这一节说几个实际使用中的做法。令牌分发方面Veloera 支持给不同用户或不同用途发不同的令牌。比如你可以给团队每个人发一个这样日志里能看出谁用了多少也可以按项目分一个项目一把令牌方便统计成本。自用的话一把就够设成永不过期省事。运营模式建议开启额度限制配合礼品码功能控制总使用次数。渠道管理上TaoToken 作为主渠道你还可以再加一两个备用渠道Veloera 支持多渠道随机或按优先级选择。这样某个渠道临时不可用时请求能自动切到另一个稳定性会好很多。渠道的优先级和权重在后台可以调。日志和 Token 统计是 Veloera 比较实用的部分。增强日志支持刷新、显示渠道名称还有总/输入/输出 Token 统计。定期看一眼能发现异常调用或者某个模型用量暴涨的情况。如果你做的是对外服务这些数据还能用来做计费参考。长期维护方面镜像更新用docker compose pull然后docker compose up -d就行数据在挂载目录里不会丢。升级前建议先备份data目录尤其是用 SQLite 的时候。环境变量有变动改完 compose 文件重新 up 一下即可。如果你后面要接更多客户端比如从 Cherry Studio 扩展到 Cline、Continue 或者自己写的脚本思路都一样Base URL 填 Veloera 地址Key 填 Veloera 令牌模型 ID 填渠道里配过的。一套网关多处复用这就是把它跑起来最大的价值。最后留个实用技巧把 Veloera 的访问地址和令牌记在一个地方团队共享时直接发这个不用每个人都去配上游 Key。上游 Key 只在 Veloera 渠道里存一份泄露风险也小很多。需要看用量或者调渠道登录 Veloera 后台就行。这样一套下来你的模型调用层就算立起来了。