1. one-api 启动报错 tiktoken 下载失败的真实场景如果你正在用 docker-compose 部署 one-api某天docker compose up -d之后容器反复重启日志里刷出这样一行Get https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken: dial tcp 57.150.97.129:443: i/o timeout那基本可以确定你遇到的就是 one-api 启动报错 tiktoken 下载失败。这个报错的核心不是 one-api 本身写错了而是它在启动阶段需要加载 tiktoken 的编码文件cl100k_base.tiktoken默认会去openaipublic.blob.core.windows.net拉取而你的部署机器访问这个地址超时或不通于是进程直接卡死或退出。先说清楚 tiktoken 是什么。它是 OpenAI 开源的一个分词tokenizer库用来把文本切成 token 并计数。one-api 在计费、限流、统计用量时都要算 token 数所以启动时会初始化 tiktoken。cl100k_base是 GPT-3.5/GPT-4 系列用的编码表文件本身不大但默认走的是境外 blob 存储网络一抖就失败。这个场景适合谁三类人最典型一是在内网或受限网络环境里跑 one-api 的运维二是用国内云主机部署、出网策略比较严的开发者三是本地用 docker-compose 做测试、机器本身能上网但访问该域名不稳定的人。共同点是one-api 容器起不来日志指向 tiktoken 资源拉取失败。我试过几种思路最后收敛到两条路一是把 tiktoken 文件提前下载好挂载进容器让 one-api 走本地缓存二是把相关 endpoint 指向一个可达的地址。前者最稳后者适合你已经有稳定可达的 API 网关。下面按可跟做的顺序把 docker-compose 配置、环境变量、验证日志一步步写清楚。需要提醒的是报错里的 IP57.150.97.129只是当时解析出来的一个节点不同时间不同地区解析结果会变所以不要试图去 ping 某个固定 IP 来“修好”要从资源加载路径上解决。2. TaoToken 前置准备拿到 Base URL 与 API Key在动手改配置之前先把要用的接入信息准备好。TaoToken 在这里扮演的是一个稳定可达的 API 入口one-api 可以把上游地址指向它同时 tiktoken 相关的资源加载也可以借助它的可达性来规避直连超时。你需要准备三样东西我把它叫做“三件套”Base URL、API Key、Model ID。这三样在任何一个上游接入场景里都缺一不可后面配置 one-api 的渠道时也会用到。Base URL 用https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。API Key 需要你登录后在控制台生成路径是 API Keys 页面。Model ID 则取决于你要接的模型比如常见的对话模型标识。具体操作顺序第一打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。这一步不用纠结正常走邮箱流程即可。第二进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 找到 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 新建一个 Key。生成后立刻复制保存页面刷新后通常不再完整显示。第三确认你要用的模型标识。如果你只是想让 one-api 能正常启动并跑通一次请求可以先选一个通用对话模型。模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以查看可用模型列表。如果你后续要做长期编码或 Agent 类任务可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它在额度使用上更适合持续调用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到参数细节可以对照。这里强调一点one-api 的渠道配置里Base URL 填https://taotoken.net/apiKey 填你刚生成的模型名填对应 Model ID。这三件套填错任何一个都会在验证阶段报 401 或模型不存在而不是 tiktoken 报错所以先把它们备好后面排查时能快速区分问题层次。3. 可复制的 docker-compose 与配置文件片段这一节是重点直接给可复制的配置。核心思路是双保险一方面把 tiktoken 文件挂载进容器走本地缓存另一方面把 one-api 的上游渠道指向 TaoToken 的 Base URL。先解决 tiktoken 文件。你需要拿到cl100k_base.tiktoken这个文件并把它重命名为它的 SHA1 哈希名9b5ad71b2ce5302211f9c61530b329a4922fc6a4注意没有后缀名。这个命名规则是 tiktoken 的缓存约定文件名必须和哈希一致否则库找不到缓存还是会去联网。把文件放到和docker-compose.yml同级的目录然后修改 compose 文件在 one-api 服务的 volumes 下增加挂载。完整片段如下version: 3.8 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 volumes: - ./data:/data - ./9b5ad71b2ce5302211f9c61530b329a4922fc6a4:/tmp/data-gym-cache/9b5ad71b2ce5302211f9c61530b329a4922fc6a4 environment: - TZAsia/Shanghai - GIN_MODErelease - SQL_DSNroot:123456tcp(mysql:3306)/oneapi depends_on: - mysql mysql: image: mysql:8.0 container_name: one-api-mysql restart: always environment: - MYSQL_ROOT_PASSWORD123456 - MYSQL_DATABASEoneapi volumes: - ./mysql-data:/var/lib/mysql关键就是那一行挂载把本地文件映射到容器内的/tmp/data-gym-cache/目录下文件名保持哈希名。tiktoken 初始化时会先查这个缓存目录命中就不再联网。如果你不想手动下载文件也可以让容器启动时通过环境变量指定一个可达的下载源。one-api 支持通过环境变量覆盖部分行为但 tiktoken 的缓存路径是固定的所以最稳的还是挂载。下面再给一个带环境变量的版本方便你对照environment: - TZAsia/Shanghai - GIN_MODErelease - TIKTOKEN_CACHE_DIR/tmp/data-gym-cacheTIKTOKEN_CACHE_DIR指向缓存目录和上面的挂载路径保持一致。这样即使库版本变化缓存目录也不会跑偏。接下来配置 one-api 的上游渠道。启动容器后访问http://你的服务器IP:3000用默认账号登录进入渠道管理新建渠道。类型选 OpenAI 兼容Base URL 填https://taotoken.net/apiKey 填你在第 2 节生成的 API Key模型填对应 Model ID。保存后测试连通性。如果你更习惯用配置文件方式one-api 也支持通过环境变量预置渠道但渠道数据存在数据库里首次还是建议在 Web 界面配置避免格式出错。配置完成后one-api 的 token 统计就能正常工作因为 tiktoken 已经从本地缓存加载不再依赖外网。4. 验证请求与成功结果看日志确认 tiktoken 加载配置改完重启容器然后盯日志。这一步是确认问题真的解决了而不是碰巧网络恢复。执行docker compose down docker compose up -d docker compose logs -f one-api观察启动日志。正常情况下你会看到 one-api 完成数据库迁移、加载配置、启动 HTTP 服务的输出不再出现dial tcp ... i/o timeout或cl100k_base.tiktoken相关的报错。如果之前是卡在 tiktoken 初始化现在应该能顺利走到监听端口的日志。接着做一次实际请求验证。用 curl 打 one-api 的接口确认它能正常转发并返回结果curl -X POST http://127.0.0.1:3000/v1/chat/completions \ -H Authorization: Bearer 你的one-api令牌 \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: 你好测试一下}] }如果返回里带有choices字段和正常内容说明整条链路通了one-api 启动成功、tiktoken 加载成功、上游渠道转发成功。如果返回 401检查 one-api 令牌和上游 Key如果返回模型不存在检查 Model ID 是否和渠道里填的一致。再补一个更直接的验证进入容器内部确认缓存文件在位。docker exec -it one-api ls -l /tmp/data-gym-cache/你应该能看到9b5ad71b2ce5302211f9c61530b329a4922fc6a4这个文件大小非零。如果文件不存在或大小为 0说明挂载路径写错了回到第 3 节核对 volumes 那一行。实测下来只要缓存文件挂载正确one-api 启动时不会再发起对openaipublic.blob.core.windows.net的请求日志干净重启也稳定。这一步的验证价值在于它把“网络问题”和“配置问题”彻底分开了——文件在、日志无报错、请求有返回三个条件同时满足才算真正解决。5. 本篇常见错排查401、local proxy failed、reading choices即使按上面做了还是可能踩到几个坑。这一节把真实报错和对应原因列出来方便你对照。第一个401 Unauthorized。这个和 tiktoken 无关是鉴权问题。常见原因one-api 渠道里的上游 Key 填错或过期Base URL 多写了斜杠或路径比如写成https://taotoken.net/api/v1而实际应该用https://taotoken.net/api或者请求时用的 one-api 令牌本身无效。排查顺序是先确认三件套Base URL、Key、Model ID都对再确认 one-api 自己的令牌。第二个local proxy failed或类似的代理连接错误。这通常出现在你给容器配了 HTTP_PROXY/HTTPS_PROXY 环境变量但代理地址不可达。如果你没有代理需求直接把这两个环境变量从 compose 里删掉。注意这里说的是容器环境变量层面的配置不是让你去搭什么网络工具纯粹是清理无效配置。第三个返回里reading choices相关报错比如解析响应时找不到choices字段。这多半是上游返回了非预期格式比如错误信息被当成正常响应。检查 Base URL 是否指向了正确的 API 根路径以及模型 ID 是否是上游支持的。如果上游返回的是错误 JSONone-api 解析choices就会失败。第四个容器启动后立刻退出日志只有一行 tiktoken 报错。这说明挂载没生效。检查三点文件是否真的在 compose 同级目录文件名是否严格是那串哈希、没有后缀volumes 里的容器路径是否是/tmp/data-gym-cache/。任何一处不对缓存都不命中。第五个OAuth相关报错。如果你在 one-api 里配了 OAuth 登录而回调地址或客户端配置不对会在登录环节报错。这和 tiktoken 是两码事分开排查。先保证 one-api 能启动、能发请求再去调 OAuth。把这几类错误和 tiktoken 报错区分开很重要tiktoken 报错发生在启动阶段日志里带cl100k_base.tiktoken和dial tcp而 401、choices 解析错误发生在请求阶段。定位清楚阶段排查效率会高很多。6. 长期使用建议与接入入口把 tiktoken 缓存挂载好之后one-api 的启动稳定性基本就解决了。但如果你打算长期跑还有几个实用习惯值得养成。第一把那个哈希文件纳入你的部署仓库或初始化脚本别只放在某台机器上。换机器部署时文件跟着走就不会再遇到同样的启动报错。可以写个简单的下载脚本在 CI 或初始化阶段把文件放到指定目录。第二定期检查 one-api 日志里的 token 统计是否正常。tiktoken 加载成功后用量统计才有意义。如果发现统计为 0 或异常回头确认缓存文件是否被误删。第三上游渠道建议统一走一个稳定入口Base URL 固定为https://taotoken.net/apiKey 和 Model ID 按需切换。这样渠道配置清晰出问题也好定位。如果你后续要做更复杂的接入比如把 one-api 作为网关对接多个上游接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有参数说明。需要新建或轮换 Key 时去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 操作。想先验证模型是否可用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以直接试。长期编码或 Agent 场景Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 更合适。最后回到那个报错本身cl100k_base.tiktoken下载失败本质是资源加载路径问题不是 one-api 的 bug。把文件挂载进容器、把上游指向可达的 Base URL两个动作做完启动日志就干净了。下次再看到类似dial tcp超时先想是不是又有资源在走默认外网地址按同样的思路挂载或改 endpoint 即可。