1. 为什么要在阿里云 ECS 上把 OneApi 和 TaoToken 拼在一起如果你手里同时用着 Claude Code、Cursor、Cline、Continue、OpenAI SDK 脚本还有几个自建的小工具那大概率会遇到一个很烦的问题每个工具都要单独配一遍 Key、Base URL、模型名换一个模型就得改一圈配置。OneApi 这类网关的价值就在这里——它把上游渠道统一收口对外只暴露一个地址和一把 Key下游工具全部指向它。而 TaoToken 在这里扮演的是「统一 Key 通道」的角色你从 TaoToken 拿到一把 Key把它作为 OneApi 里的一个渠道接进去之后所有下游工具只需要认 OneApi 的地址和 OneApi 自己签发的令牌。这样做的直接好处是工具链的配置骨架稳定了换模型、加渠道、调额度都在 OneApi 后台完成不用去动每个客户端的 settings.json。这篇聚焦的是阿里云 ECS 上用 Docker 部署 OneApi 之后怎么用config.toml和settings.json这两个骨架文件把 TaoToken 的通道接进现有 AI 工具链并且给出容器起来之后验证 Key 通道是否真的通的命令和排查动作。适合已经在阿里云上有一台 ECS、会基本 Docker 操作、想让 AI 工具链配置收敛的人。需要提前说清楚OneApi 本身是开源的网关项目TaoToken 是上游 API 服务两者是「网关 渠道」的关系。下面所有配置都是围绕这个关系展开的不涉及任何网络层面的特殊操作纯粹是标准的 HTTP 接口对接。2. 前置准备ECS、Docker 与 TaoToken Key在阿里云 ECS 上动手之前先把几件事确认掉不然后面排查会很痛苦。第一ECS 的安全组要放行你打算用的端口。OneApi 默认监听 3000如果你打算用 Nginx 反代到 443那安全组至少要放行 443如果只是内网测试放行 3000 即可。我一般建议先放行 3000 做本地验证验证通了再上反代。第二Docker 和 Docker Compose 要装好。阿里云的 Ubuntu 镜像一般自带 Docker 源直接apt install docker.io docker-compose-plugin就行。装完docker compose version能输出版本号即可。第三去 TaoToken 拿一把 Key。地址是 https://taotoken.net/api 登录后在控制台里创建 API Key。这个 Key 就是后面要填进 OneApi 渠道里的「密钥」。同时记一下 TaoToken 的接口地址OneApi 里填渠道时要区分「接口地址」和「密钥」两个字段。第四规划好数据目录。OneApi 的 SQLite 数据库、日志都放在挂载目录里我习惯用/home/ubuntu/data/one-api你可以在 ECS 上先mkdir -p建好并确认当前用户有写权限。如果用 MySQL那这一步换成准备数据库连接串。把这四件事做完再进入部署环节会顺很多。3. 可复制的 Docker Compose 与 config.toml 骨架3.1 docker-compose.yml 片段相比一长串docker run我更推荐用 Compose 管理改配置、看日志、重启都方便。下面这份是 SQLite 版本适合单机、并发不高的场景services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SESSION_SECRETchange_this_to_a_random_string volumes: - /home/ubuntu/data/one-api:/data如果你的并发量比较大SQLite 会成为瓶颈这时候加 MySQL。把SQL_DSN环境变量补上即可格式是用户:密码tcp(主机:端口)/库名environment: - TZAsia/Shanghai - SQL_DSNroot:yourpasswordtcp(mysql-host:3306)/oneapi - SESSION_SECRETchange_this_to_a_random_stringSESSION_SECRET建议换成随机字符串否则多实例部署时登录态会互相踢掉。数据目录/home/ubuntu/data/one-api要确保存在且可写否则容器起来会因为无法写 SQLite 文件而退出。启动命令cd /home/ubuntu/one-api docker compose up -d docker compose logs -f one-api日志里看到监听 3000 端口、数据库初始化完成就说明容器本身没问题了。3.2 config.toml 配置骨架OneApi 支持通过配置文件做一部分初始化config.toml放在数据目录下会被读取。它的作用是帮你把一些默认行为固定下来避免每次重建容器都要手动点一遍后台。下面是一份骨架字段按需保留# OneApi 基础配置骨架 port 3000 theme default # 日志与调试 debug false log_dir /data/logs # 会话与安全 session_secret change_this_to_a_random_string session_max_age 86400 # 渠道与重试 retry_times 3 channel_disable_threshold 5 # 前端展示 notice 内部统一网关请使用分配的令牌访问几个字段说明一下。retry_times控制上游请求失败后的重试次数接 TaoToken 这种上游时设 2 到 3 比较稳太高会在上游抖动时放大请求量。channel_disable_threshold是渠道连续失败多少次后自动禁用设 5 可以避免一个坏渠道拖垮整体。session_secret和 Compose 里的环境变量保持一致避免两处冲突。注意config.toml不是所有版本都支持全部字段具体以你拉取的镜像版本为准。如果某个字段不生效优先看容器日志有没有解析报错而不是反复改文件。3.3 在后台把 TaoToken 配成渠道容器起来后浏览器打开http://你的ECS公网IP:3000首次登录用默认账号root/123456登录后第一件事就是改密码。然后进「渠道」页面新建一个渠道类型选 OpenAI 兼容类型TaoToken 的接口是 OpenAI 兼容格式名称随便填比如taotoken-main密钥填你在 TaoToken 控制台创建的那把 Key接口地址填 TaoToken 的 API 地址注意不要带多余的路径后缀模型列表填你实际要用的模型名多个用逗号分隔保存后点渠道的「测试」按钮如果返回成功说明 OneApi 到 TaoToken 这一段通了。这一步是整个链路的关键先保证这一段通再去配下游工具。4. settings.json 示例把下游工具指向统一通道4.1 通用 settings.json 骨架下游工具比如 Claude Code、Cline、Continue 这类大多支持通过配置文件指定 Base URL 和 API Key。核心思路是Base URL 指向 OneApi 的地址API Key 填 OneApi 里签发的令牌而不是 TaoToken 的 Key。{ apiProvider: openai-compatible, apiKey: sk-oneapi-你的OneApi令牌, baseUrl: http://你的ECS公网IP:3000/v1, model: 你配置的模型名, timeout: 60000, maxRetries: 2 }这里有几个容易踩的点。第一baseUrl末尾的/v1要不要带取决于工具本身。OpenAI 兼容客户端一般要求带/v1但有些工具会自动补带了反而变成/v1/v1。判断方法很简单看工具文档或者先用 curl 测一下带和不带哪个能通。第二apiKey是 OneApi 的令牌不是 TaoToken 的 Key。OneApi 的令牌在后台「令牌」页面创建可以设置额度、过期时间、可用模型范围。这样即使某个下游工具的配置泄露了你只需要在 OneApi 里吊销对应令牌不影响 TaoToken 那把 Key。第三model字段要填 OneApi 里实际存在的模型名。如果你在渠道里填的模型名和下游工具请求的模型名对不上OneApi 会返回模型不存在的错误。4.2 用环境变量覆盖的场景有些工具不方便改 settings.json而是读环境变量。这时候可以这样设export OPENAI_API_KEYsk-oneapi-你的OneApi令牌 export OPENAI_BASE_URLhttp://你的ECS公网IP:3000/v1环境变量的优先级一般高于配置文件适合临时切换或者 CI 场景。但要注意环境变量在容器里不会自动继承如果你在 Docker 里跑下游工具得通过-e或 compose 的environment传进去。4.3 多工具共存的配置思路如果你同时用多个工具建议在 OneApi 里给每个工具单独签发一个令牌命名上区分开比如token-claude-code、token-cline。这样做的价值在于哪个工具用量异常你在 OneApi 的日志里一眼能看出来某个工具不用了直接吊销对应令牌不影响其他工具。settings.json 里除了 baseUrl 和 apiKey其他字段各工具差异较大按各自文档填即可。骨架部分保持一致工具特有的字段单独加。5. 验证 Key 通道连通性的命令与排查动作配置写完不代表通了必须实际发一次请求验证。下面按从内到外的顺序给命令。第一步在 ECS 上直接测 OneApi 容器本身curl -s http://127.0.0.1:3000/api/status返回 JSON 且success为 true说明 OneApi 进程正常。第二步用 OneApi 令牌测模型列表curl -s http://127.0.0.1:3000/v1/models \ -H Authorization: Bearer sk-oneapi-你的OneApi令牌能返回模型列表说明令牌有效、OneApi 的鉴权链路正常。第三步发一次真实的对话请求这一步才真正验证到 TaoToken 那一段curl -s http://127.0.0.1:3000/v1/chat/completions \ -H Authorization: Bearer sk-oneapi-你的OneApi令牌 \ -H Content-Type: application/json \ -d { model: 你配置的模型名, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices字段和内容说明 OneApi 到 TaoToken 的整条通道打通了。如果返回错误看错误信息里的type和message一般能定位到是鉴权问题、模型名问题还是上游问题。第四步从 ECS 外部测确认安全组和端口映射没问题curl -s http://你的ECS公网IP:3000/v1/models \ -H Authorization: Bearer sk-oneapi-你的OneApi令牌这一步不通但第三步通基本就是安全组没放行或者 OneApi 只监听了 127.0.0.1。排查动作上我习惯按这个顺序先看docker compose logs -f one-api有没有报错再看 OneApi 后台的「日志」页面每次请求都有记录能看到是哪个渠道、什么状态码最后看渠道的「测试」按钮是否还通。这三层信息基本能覆盖 90% 的问题。6. 本篇常见错排查容器起来就退出。最常见的原因是数据目录权限不对SQLite 写不进去。检查/home/ubuntu/data/one-api是否存在、当前用户是否有写权限。另一个原因是端口被占用docker compose logs里会有address already in use。渠道测试失败提示鉴权错误。先确认 TaoToken 的 Key 有没有复制完整前后有没有多余空格。再确认接口地址填对了有些服务要求地址带特定路径填错会 404 而不是 401注意区分。下游工具报 404。大概率是 baseUrl 的/v1重复或缺失。用 curl 分别测带和不带的地址看哪个返回正常。另外确认工具请求的路径是不是/v1/chat/completions有些工具用的是/chat/completions需要 baseUrl 里补上/v1。模型不存在。OneApi 里渠道配置的模型列表和下游请求的模型名要能对上。如果你在渠道里只填了gpt-4o下游请求gpt-4o-mini就会报模型不存在。解决办法是在渠道里把要用的模型都列上或者用 OneApi 的模型重定向功能做映射。请求超时。先看 OneApi 日志里请求卡在哪一段。如果是上游慢调大下游工具的 timeout如果是 OneApi 到 TaoToken 这一段慢检查 ECS 的出网是否正常。retry_times设太高会让超时表现得更久排查阶段可以先设成 1。多实例登录态互相踢。SESSION_SECRET没设或者各实例不一致。所有实例用同一个随机字符串即可。改了 config.toml 不生效。确认文件放在数据目录下且容器有读取权限。改完要重启容器docker compose restart one-api。如果日志里有 TOML 解析错误按提示改字段。7. 接下来怎么把这套骨架用起来到这里阿里云 ECS 上的 OneApi 容器、TaoToken 渠道、下游工具的 settings.json 骨架就串起来了。你可以先按第 5 节的四条 curl 命令把链路验证一遍确认从 ECS 内部到外部、从模型列表到真实对话都通再去改各个工具的配置。如果你主要用 Claude Code 这类编码工具建议在 OneApi 里单独给它签一个令牌配合 Coding Plan 的额度管理避免和其他工具混在一起看不清用量。相关入口在 https://taotoken.net/api 的 coding-plan 页面。如果你更想先验证模型对话本身可以直接用模型对话页面发几条请求确认 TaoToken 侧返回正常再回头排查 OneApi 的配置。入口在 https://taotoken.net/api 的模型对话。令牌和 Key 的管理都在控制台的 API Keys 页面接入文档在 doc 页面。这两个页面建议收藏后面加渠道、换令牌、查用量都会用到。整套骨架搭好之后你换模型、加工具、调额度基本都只在 OneApi 后台和 TaoToken 控制台两个地方操作下游工具的配置文件可以长期不动。
