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/console
- API 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.yml：
version: '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: - TZ=Asia/Shanghai - SESSION_SECRET=change_this_to_a_random_string - STREAMING_TIMEOUT=120 - SQL_DSN= - LOG_LEVEL=info这份配置里，image用的是官方 ghcr 镜像，latest标签在我写这篇时对应 v0.4.8。ports把宿主机的 3056 映射到容器 3000。volumes把数据和日志挂出来，保证容器重建后数据不丢。
环境变量逐项说明：
| 变量名 | 作用 | 建议值 |
|---|---|---|
| TZ | 容器时区 | Asia/Shanghai |
| SESSION_SECRET | 会话加密密钥 | 随机字符串，务必改 |
| STREAMING_TIMEOUT | 流式回复超时秒数 | 120 |
| SQL_DSN | 外部数据库连接串 | 留空则用内置 SQLite |
| LOG_LEVEL | 日志级别 | info |
SESSION_SECRET这个一定要改，别用默认值，否则会话安全性没保障。生成随机串可以用openssl rand -hex 32。SQL_DSN留空时 Veloera 会用内置的 SQLite，自用完全够；如果你打算跑运营模式、多人共用，建议换成 MySQL 或 PostgreSQL，把连接串填进去，格式类似user:password@tcp(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/api，Key 是你在 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 --tail=50 veloera日志里应该能看到这次请求的记录，包括渠道名称、Token 统计。Veloera 的增强日志会显示总/输入/输出 Token，方便你核对用量。
第五步，接客户端。以 Cherry Studio 为例，添加供应商，类型选 OpenAI，API 密钥填 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 后台就行。这样一套下来，你的模型调用层就算立起来了。
