1. 为什么我要用 docker compose 跑 new-api
new-api 是一个把多家大模型 API 统一成 OpenAI 兼容格式的开源网关，简单说就是：你手里有 OpenAI、Claude、Gemini 或者任意兼容 OpenAI 协议的服务，通过 new-api 可以只暴露一个地址、一套 Key，让下游的客户端、脚本、Agent 都只认这一个入口。适合谁？自建 AI 网关的开发者、想给团队做统一计费和额度管理的同学、以及需要把多个模型渠道聚合到一个 Key 后面的场景。
但真到自己部署的时候，坑往往不在 new-api 本身，而在编排：MySQL 和 Redis 的连接串写错一个字符，容器起来了但页面 500；SESSION_SECRET 没设或者太短，登录态一直掉；端口映射和云服务器安全组对不上，本地 curl 通、外网访问不了。我试过手动 docker run 三个容器，改一次配置要重启三次，后来换成 docker compose 一把梭，配置文件即文档，重建环境只要一条命令。
这篇就聚焦一件事：用 docker compose 把 new-api + MySQL + Redis 一次性编排跑通，并且把上游渠道指向 TaoToken 的统一 API 通道，让 new-api 作为你本地的统一出口。全程给你可复制的docker-compose.yml、环境变量清单、启动后的连通性验证命令，以及最常见的几类报错怎么排。你跟着做，十分钟内应该能看到登录页。
2. TaoToken 前置准备：拿到统一 Key 和 API 地址
new-api 本身是网关，它需要至少一个上游渠道才能真正转发请求。这里我们用 TaoToken 作为上游：它提供 OpenAI 兼容的统一 API 通道，一个 Key 可以调用多种模型，正好和 new-api 的「渠道」概念对上。
你需要提前准备两样东西：
第一是 API Key。登录 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制保存。这个 Key 就是后面填进 new-api 渠道里的密钥。
第二是 API 地址。TaoToken 的 API 端点是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 new-api 渠道的 Base URL 填入即可。new-api 在转发时会自动拼接/v1/chat/completions这类路径，所以你不要自己多加/v1，否则会变成/v1/v1/...导致 404。
相关入口我列一下，方便你按需跳转：
- 模型对话体验：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat
- Coding Plan（长期编码/Agent 场景）：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan
- 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
注意：Key 只在创建时完整显示一次，页面刷新后就看不到了。建议创建后立刻粘贴到你的密码管理器或临时文件里，别等关了页面再找。
3. 可复制的 docker-compose.yml 与配置骨架
下面这份编排是我实际在用的精简版，三个服务：new-api 主程序、MySQL 8.0 存数据、Redis 7.0 做缓存和会话。目录结构建议这样放：
new-api-deploy/ ├── docker-compose.yml ├── data/ # new-api 运行数据 ├── mysql/ # MySQL 持久化 └── redis/ # Redis 持久化docker-compose.yml内容如下，你可以直接复制：
version: '3.8' services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - "3000:3000" volumes: - ./data:/data environment: - SQL_DSN=root:newapi_pass_2024@tcp(mysql:3306)/newapi?charset=utf8mb4&parseTime=True&loc=Local - REDIS_CONN_STRING=redis://redis:6379/0 - SESSION_SECRET=change_this_to_a_long_random_string_at_least_32_chars - NODE_TYPE=master - TZ=Asia/Shanghai depends_on: - mysql - redis mysql: image: mysql:8.0 container_name: new-api-mysql restart: always environment: - MYSQL_ROOT_PASSWORD=newapi_pass_2024 - MYSQL_DATABASE=newapi - TZ=Asia/Shanghai volumes: - ./mysql:/var/lib/mysql command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci redis: image: redis:7.0 container_name: new-api-redis restart: always volumes: - ./redis:/data command: redis-server --appendonly yes几个关键点解释一下，这些是我踩过坑之后固定下来的写法：
SQL_DSN里的密码必须和 MySQL 服务的MYSQL_ROOT_PASSWORD完全一致，tcp(mysql:3306)里的mysql是 compose 的服务名，容器间通过服务名互相解析，不要写成localhost或127.0.0.1，那会指向容器自己。
SESSION_SECRET别用示例里的字符串，换成你自己的随机串，长度至少 32 位。生成方法：
openssl rand -hex 32REDIS_CONN_STRING用redis://redis:6379/0，末尾的/0是数据库编号。如果你给 Redis 设了密码，要写成redis://:你的密码@redis:6379/0，冒号前面留空表示用户名。
MySQL 的command里加了mysql_native_password，是因为部分 new-api 版本对 MySQL 8 默认的caching_sha2_password兼容性一般，显式指定更稳。
4. 启动、验证与渠道接入
配置文件就位后，在new-api-deploy目录下执行：
docker compose up -d第一次会拉取三个镜像，耐心等。如果卡在拉取不动，多半是镜像仓库网络问题，可以给 Docker 配置镜像加速器，在/etc/docker/daemon.json里加：
{ "registry-mirrors": ["https://docker.m.daocloud.io"] }改完执行sudo systemctl restart docker再重新up -d。
启动完成后查看状态：
docker compose ps三个服务都应该是Up状态。如果 new-api 反复重启，先看日志：
docker compose logs -f new-api日志里出现database connection failed就是 DSN 写错了，出现NOAUTH就是 Redis 连接串有问题。
确认容器健康后，验证 HTTP 端口是否通：
curl -I http://127.0.0.1:3000返回HTTP/1.1 200 OK或 302 跳转都算正常。如果部署在云服务器，记得在安全组放行 3000 端口，否则外网访问不了。然后浏览器打开http://你的服务器IP:3000，首次访问会引导你创建管理员账号。
登录后进入「渠道」页面，添加一个渠道：
- 类型选择 OpenAI
- Base URL 填
https://taotoken.net/api - 密钥填你在 TaoToken 创建的 API Key
- 模型可以手动填，比如
gpt-4o-mini、claude-3-5-sonnet等，按你实际要用的填
保存后点渠道的「测试」按钮，如果返回绿色成功，说明 new-api 已经能通过 TaoToken 通道转发请求了。接着在「令牌」页面创建一个 new-api 自己的令牌，这个令牌才是你给下游客户端用的。
最后用 new-api 的令牌做一次端到端验证：
curl http://127.0.0.1:3000/v1/chat/completions \ -H "Authorization: Bearer 你的new-api令牌" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "说一句你好"}] }'返回里带choices字段和正常内容，整条链路就通了：客户端 → new-api → TaoToken → 模型。
5. 本篇常见错排查
报错一：dial tcp 127.0.0.1:3306: connect: connection refused
说明 new-api 在连本机的 3306，而不是 MySQL 容器。检查SQL_DSN里的主机名是不是写成了localhost或127.0.0.1，必须改成服务名mysql。
报错二：NOAUTH Authentication required
Redis 设了密码但连接串没带。要么去掉 Redis 密码，要么把连接串改成redis://:密码@redis:6379/0。
报错三：页面能打开但登录后立刻掉线
SESSION_SECRET没设或太短。换成长随机串后重建容器：docker compose down && docker compose up -d。注意down不会删数据卷，数据还在。
报错四：渠道测试返回 404
Base URL 多写了/v1。TaoToken 的地址就是https://taotoken.net/api，new-api 会自己拼路径，你多加一层就重复了。
报错五：外网访问超时，本地 curl 正常
云服务器安全组没放行 3000 端口，或者系统防火墙拦了。检查安全组入站规则和ufw/firewalld状态。
报错六：MySQL 容器启动后马上退出
多半是./mysql目录权限问题，或者之前用不同密码初始化过数据目录导致密码不匹配。可以备份后清空./mysql重新初始化，但注意这会丢数据。
6. 后续怎么用这套骨架
这套编排跑通之后，你手里就有了一个本地统一出口。下游无论是 ChatBox、NextChat 这类客户端，还是自己写的脚本、Agent 框架，都只需要填http://你的IP:3000/v1和 new-api 令牌，不用再关心上游到底是哪家模型。想加新模型，在 TaoToken 侧确认可用后，在 new-api 渠道里补一个模型名就行，客户端完全无感。
如果你后面要做长期编码或 Agent 场景，可以了解下 Coding Plan，配合 new-api 做额度隔离会更顺手；单纯想先验证模型效果，直接去模型对话页面试就行。接入过程中遇到渠道配置或 Key 的问题，接入文档里有更细的字段说明，API Keys 页面可以随时新建和吊销 Key。整套骨架的价值在于：配置文件即环境，换台机器复制目录、改一下 SESSION_SECRET 和密码，docker compose up -d就能重建一套一模一样的网关。
