1. one-api 分词器缓存为什么总在重复下载
如果你用 Docker Compose 部署过 one-api，大概率遇到过这个场景：容器起来了，日志里却在反复请求openaipublic.blob.core.windows.net，网络一抖就卡住，接口调用报tiktoken相关错误，甚至整个网关启动超时。这不是 one-api 本身的 bug，而是它依赖的 tiktoken 分词器在首次使用时需要下载编码文件，而默认缓存目录在容器里是临时的，容器一重建，缓存就没了，于是又得重新下载一遍。
one-api 是一个把多家大模型 API 统一成 OpenAI 兼容格式的自建网关，适合想在自己服务器上聚合多个模型渠道、给团队或应用提供统一入口的开发者。它内部用 tiktoken 做 token 计数，用来做额度统计和请求预估。tiktoken 在初始化某个编码（比如cl100k_base）时，会先查本地缓存目录，没有就去官方地址拉取，拉完存到TIKTOKEN_CACHE_DIR指向的位置。问题就在于：这个环境变量如果不显式设置，缓存路径可能落在容器可写层，docker-compose down再up之后就丢了。
我试过最直接的解法，就是把缓存目录挂到宿主机上，让分词器文件持久化。这样第一次下载完之后，后续无论怎么重建容器，都直接读本地文件，不再依赖外网。下面按「问题定位 → 前置准备 → 可复制配置 → 验证生效 → 排错」的顺序，把整套落地过程写清楚，你可以直接照着改自己的docker-compose.yml。
2. 前置准备：TaoToken 渠道与 API Key
one-api 本身只是网关，要真正跑通一次对话验证分词器是否生效，你还需要一个可用的上游模型渠道。这里我用 TaoToken 作为上游接入，它的接口是 OpenAI 兼容的，填进 one-api 的渠道配置里很顺。
先去控制台拿一个 API Key，地址是 https://taotoken.net/api-keys ，登录后新建一个 Key，复制出来备用。这个 Key 后面会填到 one-api 的「渠道」里，作为调用上游模型的凭证。如果你还没注册，从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 进官网注册即可。
拿到 Key 之后，one-api 的渠道配置大致是这样：渠道类型选 OpenAI，Base URL 填https://taotoken.net/api，模型可以填gpt-4o-mini这类常用名，密钥就是刚才复制的 Key。保存后点「测试」，能返回成功就说明上游通了。这一步通了，后面验证分词器缓存才有意义，否则你分不清是网络问题还是缓存问题。
注意：Base URL 用
https://taotoken.net/api，不要带多余的路径后缀，one-api 会自动拼接/v1/chat/completions。
3. 可复制的 docker-compose 配置与 TIKTOKEN_CACHE_DIR 骨架
核心思路一句话：把 one-api 容器里的/data挂到宿主机目录，再把TIKTOKEN_CACHE_DIR指向/data/cache，让分词器文件落在挂载卷里。下面是一份可以直接改的docker-compose.yml片段，我保留了 one-api 和它常用的 mysql、redis 依赖。
version: "3.8" services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - "3000:3000" environment: - TZ=Asia/Shanghai - TIKTOKEN_CACHE_DIR=/data/cache volumes: - ./oneapi:/data depends_on: - mysql - redis mysql: image: mysql:8.0 container_name: one-api-mysql restart: always environment: - MYSQL_ROOT_PASSWORD=oneapi123 - MYSQL_DATABASE=oneapi volumes: - ./mysql:/var/lib/mysql redis: image: redis:7-alpine container_name: one-api-redis restart: always volumes: - ./redis:/data关键点有三个。第一，TIKTOKEN_CACHE_DIR=/data/cache写在environment里，容器启动时就会带上这个变量。第二，volumes把宿主机的./oneapi挂到容器的/data，所以/data/cache实际就是宿主机的./oneapi/cache。第三，目录要提前建好，否则容器可能因为权限或路径不存在而写入失败。
在宿主机上执行：
mkdir -p ./oneapi/cache chmod 755 ./oneapi/cache然后启动：
docker-compose up -d启动后进容器确认变量生效：
docker exec -it one-api env | grep TIKTOKEN正常应该输出TIKTOKEN_CACHE_DIR=/data/cache。如果没输出，说明环境变量没写进 compose 或者容器没重建，先docker-compose down再up -d。
4. 手动预置分词器文件，彻底摆脱外网依赖
即使配了缓存目录，第一次启动时 one-api 还是要去外网拉一次cl100k_base.tiktoken。如果你的服务器出网不稳定，这一步照样会卡。更稳的做法是手动把文件放进去，让容器启动时直接命中缓存。
tiktoken 的缓存文件名不是原始文件名，而是对下载 URL 做 SHA1 得到的哈希值。cl100k_base对应的两个常见哈希文件名是：
9b5ad71b2ce5302211f9c61530b329a4922fc6a4fb374d419588a4632f3f557e76b4b70aebbca790
你可以先下载原始文件：
cd ./oneapi/cache curl -O https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken然后复制成两个哈希名：
cp cl100k_base.tiktoken 9b5ad71b2ce5302211f9c61530b329a4922fc6a4 cp cl100k_base.tiktoken fb374d419588a4632f3f557e76b4b70aebbca790放好之后目录结构应该是：
./oneapi/ ├── cache/ │ ├── 9b5ad71b2ce5302211f9c61530b329a4922fc6a4 │ ├── fb374d419588a4632f3f557e76b4b70aebbca790 │ └── cl100k_base.tiktoken └── one-api.db重启容器：
docker-compose down docker-compose up -d这样容器启动时，tiktoken 查缓存直接命中，不会再发起外网请求。如果你用的是其他编码，比如o200k_base，哈希名不同，需要按同样方式处理，但cl100k_base覆盖了 GPT-3.5/4 系列，日常够用。
提示：哈希文件名必须完全一致，多一个字符少一个字符都会导致缓存未命中，tiktoken 会重新去下载。
5. 验证分词器缓存是否真正生效
配置完不能只看「没报错」，要确认它确实读了本地缓存。有三种验证方式，从简到繁。
第一种，看容器日志有没有下载请求。启动后执行：
docker logs -f one-api如果日志里没有出现openaipublic.blob.core.windows.net或Downloading字样，基本说明缓存命中了。反之如果还在刷下载日志，说明路径或文件名不对。
第二种，进容器直接跑一段 Python 验证 tiktoken 读取路径。one-api 镜像里带了 Python 环境，可以这样测：
docker exec -it one-api python3 -c " import tiktoken, os print('cache dir:', os.environ.get('TIKTOKEN_CACHE_DIR')) enc = tiktoken.get_encoding('cl100k_base') print('tokens:', enc.encode('hello one-api')) "如果输出cache dir: /data/cache和一段 token 列表，且执行很快（没有卡顿等待下载），说明缓存生效。如果卡了几秒才出结果，多半还是在联网下载。
第三种，最贴近真实业务：在 one-api 后台建好渠道后，发一次对话请求，看额度统计里的 token 数是否正常累加。token 计数正常，说明分词器工作正常。你可以用模型对话页面直接测：https://taotoken.net/api-keys 拿到的 Key 配好渠道后，在 one-api 的「对话」里发一条消息，观察返回和用量。
curl http://localhost:3000/v1/chat/completions \ -H "Authorization: Bearer sk-你的one-api令牌" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "你好"}] }'返回正常且后台用量有变化，整条链路就通了。
6. 本篇常见错误排查
报错一：PermissionError: [Errno 13] Permission denied: '/data/cache/xxx'宿主机./oneapi/cache权限不够，容器内进程写不进去。执行chmod -R 777 ./oneapi/cache临时放开，或者确认容器运行用户对挂载目录有写权限。生产环境建议用chown指定 uid，而不是直接 777。
报错二：日志一直刷下载，缓存目录里没文件先确认TIKTOKEN_CACHE_DIR是否真的进了容器，用第 3 节的env | grep检查。再确认挂载路径对不对，docker exec -it one-api ls /data/cache看目录是否存在。如果目录不存在，说明宿主机./oneapi/cache没建，或者挂载点写错了。
报错三：文件名对了但还是重新下载哈希名必须和 tiktoken 内部计算的完全一致。不同版本的 tiktoken 对同一编码的 URL 可能不同，哈希也会变。最稳的办法是让容器先联网下载一次，然后去/data/cache里看实际生成的文件名，把它备份下来，下次直接复用。这样比死记哈希名可靠。
报错四：docker-compose up卡在拉镜像这跟分词器无关，是镜像源问题。可以分开拉：
docker pull justsong/one-api:latest docker pull mysql:8.0 docker pull redis:7-alpine一个个拉失败概率低，拉完再docker-compose up -d。
报错五：渠道测试通过但对话报 token 相关错误多半是分词器编码和模型不匹配。one-api 会根据模型名选编码，如果你填了非常规模型名，可能选到未缓存的编码。此时要么补对应编码的缓存文件，要么换成cl100k_base覆盖的模型名测试。
7. 长期编码与 Agent 场景的接入建议
如果你不只是拿 one-api 做临时网关，而是要长期跑编码助手、Agent 工作流这类高频调用场景，建议把渠道配置和额度策略一起规划好。TaoToken 的 Coding Plan 适合这种持续调用的需求，地址是 https://taotoken.net/coding-plan ，按套餐走比单次计费更可控。接入文档在 https://taotoken.net/doc ，里面有 one-api 渠道配置的详细字段说明，遇到 Base URL 或模型名不确定的时候可以直接查。
回到分词器这件事，核心就一句：把TIKTOKEN_CACHE_DIR指到挂载卷，再手动预置哈希文件，之后无论怎么重建容器都不再依赖外网。这套配置我放在自己的docker-compose.yml里跑了很久，docker-compose down && up -d循环多次，日志里再没出现过下载请求。你可以先把第 3 节的片段抄进去，跑通第 5 节的验证，再按第 4 节补文件，顺序反了容易在排错时分不清是网络还是缓存的问题。
