1. 为什么要在本地折腾 One-Api 这层网关如果你手里同时握着 OpenAI、Claude、通义千问、DeepSeek 好几个平台的 Key每次写代码都要为不同 SDK 改一遍请求格式那种感觉就像家里有五个遥控器却只能开一台电视。One-Api 解决的就是这件事它把各家大模型的接口统一翻译成 OpenAI API 格式你只需要记住一套/v1/chat/completions的写法后面换模型只改一个model字段。这篇要做的是在本地用 Docker 把 One-Api 跑起来数据用 SQLite 存不额外装 MySQL然后通过 TaoToken 的统一 Key 通道把上游模型接进来最后用 curl 打一发请求确认整条链路通了。适合谁适合正在学 Semantic Kernel、LangChain 这类框架但被各家 API 申请和格式差异卡住的开发者也适合想把多个模型 Key 收拢到一处、方便切换和记账的人。我试过直接在每个项目里硬编码不同厂商的请求逻辑维护起来非常痛苦后来把 One-Api 当成一层本地代理代码里只认 OpenAI 格式清爽很多。下面按“装网关 → 配渠道 → 发令牌 → 验证 → 排错”的顺序走一遍命令都可以直接复制。2. 前置准备TaoToken 统一 Key 与本地环境2.1 TaoToken 在这里扮演什么角色One-Api 本身是个“翻译转发”的网关它需要下游有真实可用的模型通道。TaoToken 提供的是统一的 Key 和 API 通道你可以把它理解成一个已经帮你对接好多种模型的入口One-Api 只要把渠道地址指向它就能用一套凭证调用多个模型。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。这样做的好处是你不需要在 One-Api 里为每个厂商单独填一堆参数渠道配置更干净同时多模型调用的额度、切换都集中在 TaoToken 侧管理。对于本地学习和中小项目来说少维护一层账号体系。2.2 本地需要装什么Docker Desktop 是必须的Windows 和 macOS 都行。装好后确认docker命令可用docker --version docker compose version如果docker compose version报错说明你的 Docker 版本较老需要升级到带 Compose V2 的版本。另外准备一个存放数据的目录比如 Windows 下用C:/LLM/OneApi-DatamacOS/Linux 下用~/oneapi-data后面挂载给容器保证重启不丢配置。3. 用 docker-compose 部署 One-ApiSQLite 存储3.1 为什么选 SQLite 而不是 MySQLOne-Api 默认支持 SQLite 和 MySQL。本地学习、单机使用SQLite 足够零额外依赖数据就是一个文件备份直接拷走。只有多人协作、高并发场景才需要上 MySQL。所以这里用 SQLite把复杂度降到最低。3.2 可复制的 docker-compose 骨架新建一个目录比如oneapi在里面创建docker-compose.ymlservices: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SQL_DSN volumes: - ./data:/data healthcheck: test: [CMD-SHELL, wget -q -O - http://localhost:3000/api/status || exit 1] interval: 30s timeout: 5s retries: 3这里几个关键点SQL_DSN留空表示使用默认的 SQLite数据库文件会落在容器/data目录下volumes把宿主机的./data映射进去这样数据持久化在本地healthcheck用来确认服务真的起来了不是容器在跑但进程挂了。启动docker compose up -d docker compose logs -f one-api看到日志里出现监听 3000 端口、数据库初始化完成之类的信息就说明起来了。如果拉镜像慢可以先单独docker pull justsong/one-api:latest。3.3 首次登录与改密码浏览器打开http://localhost:3000默认账号root密码123456。登录后第一件事就是改密码在“个人设置”里改掉别留着默认密码。改完重新登录一次确认生效。4. 配置渠道与令牌把 TaoToken 接进来4.1 新增渠道进入“渠道”页面点“添加新的渠道”。类型选择OpenAI因为 TaoToken 提供的是 OpenAI 兼容接口名称随便起比如taotoken-main。关键字段字段填写内容类型OpenAI名称taotoken-main分组default模型按需填如 gpt-4o,claude-3-5-sonnet,deepseek-chat代理留空密钥你的 TaoToken Key代理地址https://taotoken.net/api模型这一栏要和你实际要调用的模型名对应多个用英文逗号分隔。代理地址填 TaoToken 的 API 基址注意不要带末尾斜杠。填完点“提交”渠道列表里状态应该变成绿色“已启用”。4.2 生成访问令牌渠道通了还需要一个给本地项目用的令牌。进入“令牌”页面点“添加新的令牌”名称随意额度按需设置学习用可以设个较小值过期时间留空表示不过期。生成后会得到一串sk-开头的 Key这就是你项目里要用的凭证。注意这个令牌是 One-Api 自己签发的和你填在渠道里的 TaoToken Key 是两回事。前者给本地项目用后者是 One-Api 访问上游用的别搞混。5. 验证请求curl 打通 /v1/chat/completions5.1 用 curl 发一发拿到 One-Api 令牌后直接打本地网关curl http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的OneApi令牌 \ -d { model: gpt-4o, messages: [ {role: user, content: 用一句话解释什么是 API 网关} ], temperature: 0.7 }如果返回结构里有choices[0].message.content说明整条链路通了本地 One-Api 收到请求 → 按渠道配置转发到 TaoToken → 拿到模型回复 → 按 OpenAI 格式返回给你。5.2 成功结果长什么样正常返回大致是这样{ id: chatcmpl-xxxx, object: chat.completion, created: 1715000959, choices: [ { index: 0, message: { role: assistant, content: API 网关是位于客户端和后端服务之间的中间层负责统一入口、转发请求并处理鉴权等公共逻辑。 }, finish_reason: stop } ], usage: { prompt_tokens: 18, completion_tokens: 40, total_tokens: 58 } }看到usage里有 token 统计说明计费链路也正常。这时候你在 Semantic Kernel 或 LangChain 里把base_url指向http://localhost:3000/v1api_key填 One-Api 令牌就能直接跑框架代码了。6. 本篇常见错排查6.1 渠道测试报 401 或 403多半是渠道里的密钥填错或者代理地址写成了带路径的形式。检查两点密钥是不是 TaoToken 的 Key代理地址是不是https://taotoken.net/api且没有多余斜杠。另外确认渠道类型选的是 OpenAI不是 Azure 或其他。6.2 请求返回 model not found说明你请求里的model字段不在渠道配置的模型列表里。回到渠道编辑页把要用的模型名加进去保存后重新测试。模型名要和上游实际支持的名称一致大小写敏感。6.3 容器起来但浏览器打不开 3000先看docker compose logs -f one-api有没有报错。常见原因是端口被占用改一下映射端口比如3001:3000然后访问http://localhost:3001。Windows 下还要确认 Docker Desktop 的端口转发没被防火墙拦。6.4 重启后配置丢了检查docker-compose.yml里的volumes映射路径是否正确数据文件应该出现在宿主机的./data目录下。如果用的是相对路径注意 compose 文件所在目录就是基准目录。SQLite 模式下one-api.db文件在就说明持久化生效了。6.5 令牌额度用完或过期在“令牌”页面能看到每个令牌的剩余额度和状态。学习阶段如果额度设太小请求会返回额度不足的错误直接编辑令牌调大或新建一个即可。7. 后续怎么用把本地网关接进你的项目整条链路跑通后你的项目代码只需要认 OpenAI 格式。以 Python 为例from openai import OpenAI client OpenAI( base_urlhttp://localhost:3000/v1, api_keysk-你的OneApi令牌 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)想换模型只改model字段不用动请求逻辑。如果你要长期跑编码类任务或 Agent建议把调用凭证和额度规划放到 Coding Plan 里统一管理入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要查看和生成 Key 的话在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 想先在网页里直接试模型效果可以用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入过程中遇到报错对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 排查会更快。一个实用小技巧把docker-compose.yml和data目录一起放进你的 dotfiles 仓库换机器时 clone 下来docker compose up -d几分钟就能恢复整套本地网关比重新配一遍渠道省事得多。
