1. 为什么自建 AI 网关要把 Redis 和 one-API 放进同一个 Compose如果你正在自建 AI 网关大概率会遇到一个很具体的组合one-API 负责把上游模型通道统一成 OpenAI 兼容接口Redis 负责缓存会话、限流计数和渠道状态。这两个东西单独跑都不难难的是让它们稳定地互相发现、重启后数据不丢、密钥不裸奔。我见过太多人用docker run起两个容器结果 one-API 重启后连不上 Redis或者 Redis 没设密码被同网段扫到。这篇就聚焦一件事用 Docker Compose 把 Redis 和 one-API 编排成一个可复制的本地/小规模生产环境并且把上游通道统一指向 TaoToken 的 API 入口用一套 Key 管理所有模型调用。适合已经会基本 Docker 命令、想把手动docker run升级成声明式编排的开发者。读完你能拿到一份可直接改路径就用的docker-compose.yml知道 Redis 持久化和密码怎么写one-API 的环境变量骨架长什么样以及怎么用 curl 和日志确认整条链路通了。先说清楚整体数据流客户端请求打到 one-API 的 3000 端口one-API 用 Redis 做缓存和限流同时把模型请求转发到上游。上游这里我们统一走 TaoToken 的 API 地址https://taotoken.net/api这样你不需要在 one-API 里为每个模型厂商单独配 Key一套 TaoToken Key 就能覆盖对话、补全等通道。Redis 在这个架构里不是可选项one-API 的渠道健康检查、令牌额度缓存都依赖它少了它并发一上来就会频繁回源。Compose 相比docker run的核心优势是网络和依赖顺序。默认情况下 Compose 会创建一个 bridge 网络服务之间用服务名当主机名解析。也就是说 one-API 容器里写redis:6379就能连上 Redis 容器不用管宿主机 IP 变来变去。再加上depends_on和健康检查能避免 one-API 比 Redis 先起来导致的连接拒绝。下面从环境准备开始一步步把这份编排落地。2. 前置准备Docker 环境检查与 TaoToken Key 获取在写 Compose 文件之前先把两件事确认掉Docker 引擎能正常工作以及你手里有一个可用的 TaoToken Key。这两步任何一步缺失后面都会卡在报错上。先验证 Docker。打开终端执行docker --version docker compose version第一条返回类似Docker version 26.x.x就说明引擎在。第二条要确认docker compose注意是空格V2 插件形式能输出版本号。如果你只有docker-compose带横杠的 V1建议升级到 V2因为本文的depends_on健康检查语法在 V1 上行为不一致。Windows 用户如果遇到Docker Desktop is unable to start通常是 WSL2 没装好在管理员 PowerShell 里执行wsl --install重启后再确认wsl --set-default-version 2。接着确认端口没被占用。one-API 默认 3000Redis 默认 6379。用下面命令看一眼# Linux / macOS lsof -i :3000 -i :6379 # Windows PowerShell netstat -ano | findstr 3000 6379有输出就说明被占了要么停掉对应进程要么在 Compose 里改映射端口比如13000:3000。然后是 TaoToken Key。访问控制台创建 API Key地址是https://taotoken.net/console。创建后你会拿到一串以sk-开头的密钥先复制到安全的地方。这里有个关键点one-API 里配置上游渠道时Base URL 填https://taotoken.net/apiKey 填你刚创建的这串。注意 API 地址不要带任何查询参数就是干净的/api路径。提示TaoToken 的 Key 建议按用途分开创建比如一个给 one-API 网关用一个给本地调试用。这样某个 Key 泄露时可以直接在控制台吊销不影响其他服务。如果你还想在接入前先验证模型通道是否正常可以打开模型对话页面https://taotoken.net/models手动发一条消息确认账号和通道没问题。这一步不是必须的但能帮你把「Key 本身有问题」和「Compose 配置有问题」两类故障提前分开。环境确认完目录结构也顺手建一下。我习惯这样组织mkdir -p ~/ai-gateway/redis-data cd ~/ai-gatewayredis-data用来挂载 Redis 的持久化文件这样容器删了数据还在。接下来写 Compose 文件。3. 可复制配置docker-compose.yml 与 Redis 密码持久化这一节是全文的核心直接给你一份能跑的docker-compose.yml然后逐段解释为什么这么写。把下面内容保存到~/ai-gateway/docker-compose.ymlservices: redis: image: redis:7-alpine container_name: ai-redis restart: unless-stopped command: redis-server --requirepass ChangeMe_Redis_2024 --appendonly yes --appendfsync everysec ports: - 6379:6379 volumes: - ./redis-data:/data healthcheck: test: [CMD, redis-cli, -a, ChangeMe_Redis_2024, ping] interval: 10s timeout: 3s retries: 5 networks: - ai-net one-api: image: justsong/one-api:latest container_name: ai-one-api restart: unless-stopped depends_on: redis: condition: service_healthy ports: - 3000:3000 environment: - TZAsia/Shanghai - REDIS_CONN_STRINGredis://:ChangeMe_Redis_2024redis:6379/0 - SESSION_SECRETplease_change_this_session_secret - SQL_DSNoneapi:oneapi_passtcp(mysql:3306)/oneapi volumes: - ./one-api-data:/data networks: - ai-net networks: ai-net: driver: bridge先看 Redis 部分。command里做了三件事--requirepass设密码--appendonly yes开启 AOF 持久化--appendfsync everysec每秒刷盘一次。AOF 比 RDB 更适合 one-API 这种需要缓存一致性的场景因为 RDB 是定时快照容器意外退出可能丢最近几分钟的计数。volumes把./redis-data挂到容器/dataAOF 文件就落在这里容器重建数据不丢。healthcheck是整份编排的关键。它用redis-cli -a 密码 ping探测返回PONG才算健康。one-API 那边的depends_on配了condition: service_healthy意思是等 Redis 健康检查通过再启动 one-API。没有这个one-API 可能先起来然后连不上 Redis日志里刷一堆连接错误。再看 one-API 的环境变量。REDIS_CONN_STRING的格式是redis://:密码主机:端口/库号注意密码前面有个冒号主机名直接用服务名redis。SESSION_SECRET是会话加密用的务必改成你自己的随机串。SQL_DSN这里我留了 MySQL 的占位如果你只想单机跑可以把这行删掉one-API 会默认用 SQLite数据落在./one-api-data里。注意密码ChangeMe_Redis_2024和SESSION_SECRET一定要改。Redis 端口映射到宿主机后如果密码太弱同网络下很容易被扫。生产环境建议把ports里的6379:6379去掉只让 one-API 通过内部网络访问 Redis。启动命令docker compose up -d docker compose psps输出里两个容器的 STATUS 都应该是UpRedis 那行还会显示(healthy)。如果 one-API 显示Restarting先别急看下一节的日志排查。4. 验证请求curl 探活与 one-API 日志核对容器起来不等于链路通。这一节用三个动作确认Redis 能读写、one-API 能连上 Redis、one-API 能通过 TaoToken 通道完成一次真实模型调用。第一步验证 Redis 密码和读写docker exec -it ai-redis redis-cli -a ChangeMe_Redis_2024 ping返回PONG说明密码对、服务活。再写一个键读出来docker exec -it ai-redis redis-cli -a ChangeMe_Redis_2024 set testkey hello docker exec -it ai-redis redis-cli -a ChangeMe_Redis_2024 get testkey第二条返回hello就说明 AOF 写入正常。你可以顺手docker compose restart redis再get testkey如果还能读到说明持久化挂载生效了。第二步看 one-API 日志里有没有 Redis 连接错误docker compose logs one-api --tail50正常启动的日志里会有监听 3000 端口的记录不应该出现redis: connection refused或NOAUTH Authentication required。如果出现NOAUTH说明REDIS_CONN_STRING里的密码和 Redis 的requirepass不一致回去核对。如果出现connection refused多半是depends_on没生效或服务名写错。第三步真实调用。先在 one-API 后台添加渠道。浏览器打开http://localhost:3000默认账号root密码123456登录后立刻改密码。进入「渠道」页面新增一个渠道类型选 OpenAIBase URL 填https://taotoken.net/apiKey 填你的 TaoToken Key模型填你要用的比如gpt-4o-mini。保存后点「测试」返回绿色成功即可。然后创建令牌在「令牌」页面新增复制生成的sk-开头的令牌。用 curl 打一次对话接口curl -s http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的one-api令牌 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }返回的 JSON 里choices[0].message.content应该是「通了」。这一步同时验证了三件事one-API 服务正常、Redis 缓存没拖后腿、TaoToken 上游通道可达。如果返回 401看下一节。5. 本篇常见错排查401、local proxy failed 与 reading choices排障的核心思路是分层先确认是哪一层断了再针对性修。下面按真实报错逐个说。报错一401 Unauthorized或invalid api key这个最常见来源有两个。一是 curl 里用的 one-API 令牌不对检查Authorization: Bearer后面是不是你在「令牌」页面生成的那串别把 TaoToken 的 Key 填进来了。二是 one-API 渠道里填的 TaoToken Key 有问题去渠道页面点「测试」如果测试也 401说明 Key 无效或额度用尽去https://taotoken.net/api-keys重新生成一个。注意 Base URL 必须是https://taotoken.net/api多一个斜杠或少一个/api都会 404 或 401。报错二local proxy failed或dial tcp: lookup redis这是 one-API 连不上 Redis 的典型表现。先确认两个容器在同一个网络docker compose exec one-api ping -c 2 redisping 不通说明网络没对上检查docker-compose.yml里两个服务是不是都写了networks: - ai-net。ping 通但报NOAUTH就是密码问题核对REDIS_CONN_STRING和requirepass。还有一种情况是 Redis 健康检查一直不过docker compose ps里 Redis 显示unhealthy这时 one-API 会因为depends_on一直不启动去看docker compose logs redis找原因多半是密码里有特殊字符没转义。报错三reading choices或unexpected end of JSON input这个报错说明 one-API 收到了上游响应但解析失败。常见原因是上游返回了非 JSON 内容比如 HTML 错误页。先直接打 TaoToken 的接口确认通道本身正常curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的TaoToken_Key \ -d {model:gpt-4o-mini,messages:[{role:user,content:hi}]}如果这条直接返回正常 JSON那问题在 one-API 的渠道配置检查模型名是否和 TaoToken 支持的名称一致。如果这条也报错说明 Key 或模型名有问题。另外reading choices有时是超时导致响应被截断可以在 one-API 渠道设置里把超时调大。报错四OAuth相关或SESSION_SECRET警告one-API 启动日志里如果提示SESSION_SECRET未设置或太短说明你用了默认值。这不影响基本调用但会导致登录态不稳定。改成一个 32 位以上的随机字符串然后docker compose up -d重建容器。注意改SESSION_SECRET后已登录的会话会失效重新登录即可。排查完记得看一眼 Redis 里的键有没有正常增长docker exec -it ai-redis redis-cli -a ChangeMe_Redis_2024 dbsize调用几次接口后这个数字应该变大说明 one-API 确实在用 Redis 做缓存。6. 长期运行建议与统一 Key 接入的下一步跑通之后有几件事值得顺手做掉能让这套编排更省心。第一把 Redis 端口从宿主机撤掉。docker-compose.yml里 Redis 的ports那两行删掉one-API 通过内部网络redis:6379照样能连外部扫不到 6379安全性直接上一个台阶。如果本地调试需要连 Redis用docker compose exec redis redis-cli进容器操作就行。第二给 one-API 加个反向代理和 HTTPS。现在 3000 端口是明文 HTTP如果要在公网用前面挂 Nginx 或 Caddy 做 TLS 终止。这一步和本文的 Compose 不冲突代理指向127.0.0.1:3000即可。第三统一 Key 的长期管理。你现在 one-API 里配的是 TaoToken 的 Key好处是上游通道集中在一处换模型、加通道都不用改客户端。如果后面要跑长期编码任务或 Agent 类负载可以了解下 Coding Plan 这类按周期计费的方案地址是https://taotoken.net/coding-plan适合调用量大且稳定的场景。接入文档在https://taotoken.net/doc里面有各语言 SDK 的 Base URL 配置示例和本文的 one-API 配置可以互相印证。第四备份策略。./redis-data和./one-api-data这两个目录就是全部状态定期打包即可。Redis 的 AOF 文件在redis-data/appendonly.aofone-API 如果用 SQLite数据库在one-api-data/one-api.db。写个 cron 每天 tar 一下比任何花哨的备份工具都实在。最后回到编排本身。这套 Compose 的价值在于声明式你改密码、改端口、加服务都只动 YAML然后docker compose up -d让它收敛到目标状态。比起记一堆docker run参数这种方式在换机器、交接、复现问题时优势明显。把这份文件存进你的 dotfiles 仓库下次换电脑十分钟就能把 AI 网关重新拉起来。