企业官网建设流程全解析

1. 为什么我要把 Sub2API 和 Codex CLI 串起来

如果你正在用 Codex CLI 写代码，大概率遇到过这种尴尬：每台机器都要单独配一遍 API Token，团队里谁换了 Key 就得挨个通知，本地调试和服务器跑批用的还是两套凭证。Sub2API 这个自托管项目解决的就是这个问题——它把上游的 OpenAI/Codex 账号统一收口，对外只暴露一个网关地址和一组 API Token，Codex CLI 只要把base_url指过来就能用。

Sub2API 本质上是一个 API Token 管理与调度服务，跑在 Docker 里，自带 PostgreSQL 和 Redis，支持分组、账号池、余额和并发控制。它适合需要在本地或服务器统一管理 API Token 的开发者，尤其是手里有多个 Codex 账号、想让 Codex CLI 走统一入口的场景。这篇就按我实际部署的链路走一遍：Docker Compose 起服务、后台建分组和账号、签发 Token、改~/.codex/config.toml、最后用curl和codex双重验证。中间踩过的坑，比如 503 账号调度失败、请求打到根路径返回 HTML，都会单独拎出来讲。

整个链路的核心检索词就三个：Sub2API 负责托管，Docker Compose 负责部署，Codex CLI 负责消费。把这三段打通，你就有了一套可迁移、可备份、可团队共用的 Token 配置链路。

2. 部署前的环境准备与 TaoToken 前置说明

先说环境。Sub2API 官方推荐 Linux 服务器加 Docker Compose 部署，我实测下来 Ubuntu 22.04 和 Debian 12 都没问题。硬性要求是 Docker 20.10+、Docker Compose v2（或者旧版独立的docker-compose命令），并且开放 TCP 端口 8080。如果你打算公网访问，记得在安全组里放行，同时后面会讲怎么加反向代理。

docker --version docker compose version

两条命令能正常输出版本号就行。如果只有旧版 Compose，把后面所有docker compose换成docker-compose即可，逻辑完全一样。

关于上游账号来源，这里有个容易混淆的点。Sub2API 自己不管上游凭证，它需要你提供一个可用的 OpenAI/Codex 账号做 OAuth 授权。如果你希望统一管理多家模型的 Token、又不想在每台机器上散落配置，可以先用 TaoToken 这类平台把 Key 集中管起来，再决定哪些走 Sub2API 调度。TaoToken 的模型对话入口适合先验证模型连通性，控制台用来管理 API Keys，接入文档里有完整的鉴权说明。它的 API 地址是https://taotoken.net/api，官网在https://taotoken.net/。这一步不是必须的，但如果你后面要接多个上游，提前把 Key 管好会省很多事。

注意：Sub2API 的部署目录建议固定，比如/opt/sub2api，因为它的数据持久化、备份和迁移都围绕这个目录展开。换目录会导致 Compose 找不到卷。

3. 用 Docker Compose 起 Sub2API 服务

官方提供了一键部署脚本，它会自动下载 Compose 配置、创建.env、生成 PostgreSQL 密码、JWT 密钥和 TOTP 加密密钥，还会建好数据持久化目录。我建议直接用脚本，省得手写一堆密钥。

mkdir -p /opt/sub2api cd /opt/sub2api curl -sSL \ https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh \ | bash

脚本跑完后，目录里会有docker-compose.yml和.env。启动服务：

docker compose up -d

旧版 Compose 用docker-compose up -d。启动后检查容器：

docker ps

正常情况下你会看到三个容器：sub2api、sub2api-redis、sub2api-postgres。如果只看到一两个，多半是镜像没拉全或者端口冲突，先看日志：

docker logs -f --tail=200 sub2api

健康检查用这个：

curl http://127.0.0.1:8080/health

返回正常状态就说明服务起来了。浏览器访问http://服务器IP:8080进管理后台。如果管理员密码是自动生成的，从日志里捞：

docker logs sub2api 2>&1 | grep -i "admin password"

这里有个细节：.env里存着数据库密码和 JWT 密钥，千万别提交到公开仓库。我习惯部署完立刻把.env备份到密码管理器，然后给目录设权限chmod 600 .env。

4. 后台配置：分组、账号与 API Token 的对应关系

后台配置是整条链路最容易出错的地方，核心就一句话：API Key 所属分组必须和上游账号所属分组一致。三者关系是分组串起来的，账号进分组，Key 也进同一个分组，调度时才能匹配上。

4.1 创建分组

进管理后台 → 分组管理 → 新建分组，比如建一个叫codex的分组。初次测试建议启用分组、暂时不设复杂模型白名单、不设模型映射、用默认倍率。等链路跑通再回来加限制。

4.2 添加上游账号

进管理后台 → 账号管理 → 添加账号，添加 OpenAI/Codex OAuth 账号并完成设备授权。必须确认四件事：账号状态为启用、OAuth 授权成功、并发数至少为 1、账号已经加入前面创建的codex分组。

最后一条是最容易漏的。光建账号和分组不够，必须在账号编辑页里把账号挂到对应分组上。我见过太多人卡在这里，日志里一直报no available accounts，其实就是账号没进组。

4.3 创建 API Token

进管理后台 → API Key 管理 → 新建 API Key，设置分组为codex、状态启用、余额足够。这里的分组必须和账号所属分组一致，否则调度阶段直接返回 503。

配置完成后，你手里应该有一个形如sk-xxxx的 Token。这个 Token 就是 Codex CLI 要用的凭证。

5. 验证请求：别拿根地址当接口测

很多人部署完直接curl http://服务器IP:8080，结果返回一堆 HTML，就以为服务坏了。其实根地址返回的是管理后台页面，它根本不调用模型。正确的测试方式是打/responses接口。

export SUB2API_KEY='你的新Token' curl -sS -i 'http://127.0.0.1:8080/responses' \ -H "Authorization: Bearer $SUB2API_KEY" \ -H 'Content-Type: application/json' \ --data-raw '{ "model": "gpt-5.3-codex", "input": "只回复 pong" }'

公网测试把127.0.0.1换成服务器 IP 即可。成功时返回的是模型响应 JSON，而不是 HTML 或 503。当前 Sub2API 版本同时处理裸/responses和/v1/responses，所以 Codex CLI 那边两种路径都能接。

如果这一步返回 503，先别急着改配置，直接看服务端日志定位：

docker logs --since=10m sub2api 2>&1 | grep -Ei -C 10 \ 'account_select_failed|no available|oauth|401|403|429|cooldown'

日志里出现openai.account_select_failed且excluded_account_count: 0，基本就是候选账号列表为空，回到账号管理检查分组归属。

6. Codex CLI 接入 config.toml 配置

服务端通了，接下来让 Codex CLI 走 Sub2API。先建配置目录：

mkdir -p ~/.codex nano ~/.codex/config.toml

写入以下内容：

model = "gpt-5.3-codex" model_provider = "sub2api" preferred_auth_method = "apikey" [model_providers.sub2api] name = "Sub2API" base_url = "http://服务器IP:8080" env_key = "OPENAI_API_KEY" wire_api = "responses"

几个参数说明一下。model_provider指向下面定义的sub2api段；base_url填你的 Sub2API 地址，注意不要带/v1，Codex 会自己拼/responses；env_key指定从哪个环境变量读 Token；wire_api = "responses"表示走 Responses API 协议。

设置 Token 环境变量：

export OPENAI_API_KEY='你的Sub2API Token'

macOS 永久保存：

echo 'export OPENAI_API_KEY="你的Sub2API Token"' >> ~/.zshrc source ~/.zshrc

Linux Bash 永久保存：

echo 'export OPENAI_API_KEY="你的Sub2API Token"' >> ~/.bashrc source ~/.bashrc

然后直接启动：

codex

Codex 会向http://服务器IP:8080/responses发请求。如果配置正确，你会看到模型正常响应。如果 Codex 报连接错误，先用第 5 节的curl确认服务端本身没问题，再回头查config.toml的缩进和引号——TOML 对格式比较敏感，base_url少了引号或者多了斜杠都会出问题。

7. 本篇常见报错排查

7.1 401 Unauthorized

原因通常是 Token 错误、Token 已禁用，或者 Authorization 请求头格式不对。检查一下你导出的变量：

echo "${OPENAI_API_KEY:0:8}..."

确认前缀和后台签发的一致。如果 Token 曾经在聊天或截图里暴露过，立刻在后台禁用并重新生成。

7.2 403 Insufficient account balance

Sub2API 用户余额不足、API Key 额度不足，或者分组计费配置导致余额不够。处理方式是进后台 → 用户管理 / 余额管理增加余额。

7.3 503 No available accounts

这是最高频的错误，原因基本都在账号侧：API Key 所属分组没有上游账号、账号没加入分组、账号被禁用、并发数为 0，或者 OAuth 账号已失效。优先检查账号管理 → 编辑账号 → 分组，确认账号挂在 Key 所在的那个分组里。

7.4 503 Service temporarily unavailable

看服务端日志：

docker logs --since=10m sub2api 2>&1 | grep -Ei -C 10 \ 'account_select_failed|no available|oauth|401|403|429|cooldown'

如果出现openai.account_select_failed且excluded_account_count: 0，说明候选账号列表为空，还是分组归属问题。

7.5 返回 HTML 页面

说明请求打到了/而不是/responses。检查 Codex 的base_url有没有多写路径，或者curl测试时是不是漏了/responses后缀。

8. 运维、备份与安全收尾

日常运维命令记几条就够：

docker ps docker logs -f --tail=200 sub2api docker restart sub2api docker compose restart sub2api

更新镜像：

cd /opt/sub2api docker compose pull docker compose up -d

备份用本地目录持久化版本最省事，直接打包整个部署目录：

cd /opt docker compose -f /opt/sub2api/docker-compose.yml down tar czf sub2api-backup-$(date +%F).tar.gz sub2api/ docker compose -f /opt/sub2api/docker-compose.yml up -d

恢复就是解包后docker compose up -d。安全方面几条硬规矩：不要在聊天、截图或日志里公开完整 Token；已公开的立即禁用重签；.env不要上传公开仓库；生产环境建议加 HTTPS 反向代理并限制管理后台访问来源；定期备份 PostgreSQL 和部署目录；镜像版本尽量固定，别长期用latest。

如果你后面要把这套链路接到更多模型或团队协作场景，可以顺手看看 TaoToken 的 Coding Plan，它适合长期编码和 Agent 类任务，配合 Sub2API 做上游调度会更顺。接入文档里有完整的鉴权和路径说明，API Keys 页面用来签发和管理凭证。把 Sub2API 当本地网关、TaoToken 当上游 Key 池，这套组合在团队里迁移起来会轻松很多。