Windows 11 → WSL2 → Ubuntu → Docker → Codex → Sub2API

一、安装 WSL2 + Ubuntu

在 Windows 11 里用管理员 PowerShell 执行：

```powershell

wsl --install

```

重启后进入 Ubuntu，按提示创建 Linux 用户名和密码。

检查 WSL 版本：

```powershell

wsl -l -v

```

如果 Ubuntu 不是 VERSION 2：

```powershell

wsl --set-default-version 2

wsl --set-version Ubuntu 2

```

进入 Ubuntu：

```powershell

wsl

```

建议先更新系统：

```bash

sudo apt update && sudo apt upgrade -y

sudo apt install -y curl git ca-certificates nano openssl

```

二、安装 Docker

推荐新手用 Docker Desktop，因为它和 WSL2 集成最省心。

1. 安装 Docker Desktop for Windows
2. Settings → General → 勾选 Use the WSL 2 based engine
3. Settings → Resources → WSL Integration → 开启你的 Ubuntu
4. 回到 Ubuntu 验证：

```bash

docker version

docker compose version

docker run hello-world

```

如果你不想装 Docker Desktop，也可以在 Ubuntu 内安装 Docker Engine，但要确认 WSL 支持 systemd，并按 Docker 官方 Ubuntu 教程安装。对 Sub2API 来说，重点是最终能跑：

```bash

docker compose version

```

三、安装 Codex CLI

在 Ubuntu 里安装 Node.js。OpenAI 文档推荐 WSL 内用 nvm 装 Node：

```bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

```

关闭并重新打开 Ubuntu 终端，然后：

```bash

nvm install 22

node -v

npm -v

npm i -g @openai/codex

codex --version

```

如果走 OpenAI 官方账号：

```bash

codex --login

```

如果后面要接 Sub2API，则主要用 Sub2API 生成的 API Key 和自定义 provider 配置。

四、部署 Sub2API

Sub2API 官方推荐 Docker Compose，一键脚本会下载 docker-compose.local.yml 和 .env.example，并生成安全密钥。

在 Ubuntu 中执行：

```bash

mkdir -p ~/apps/sub2api-deploy

cd ~/apps/sub2api-deploy

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

docker compose up -d

docker compose ps

docker compose logs -f sub2api

```

浏览器打开：

```text

http://localhost:8080

```

如果 Windows 浏览器打不开，先查 WSL IP：

```bash

hostname -I

```

然后用：

```text

http://WSL_IP:8080

```

进入安装向导后，完成数据库、Redis、管理员账号初始化。Docker Compose 版本已经自带 PostgreSQL 和 Redis 容器，所以通常按向导默认即可。

五、Sub2API 后台基础配置

进入后台后大致做这几件事：

1. 添加上游账号

例如 OpenAI / Claude / Gemini / Antigravity 等，按你实际订阅或 API 来源添加。

2. 创建用户或直接使用管理员用户。
3. 创建 API Key

复制类似 sk-xxxx 的 Key，后面给 Codex 使用。

4. 确认模型名称

在 Sub2API 后台确认可用模型名，例如你的环境里可能是 gpt-5-codex、gpt-5.1-codex 或后台映射出的其他名称。下面配置里的 model 要和后台可用模型一致。

六、让 Codex 走 Sub2API

在 Ubuntu 中创建或编辑 Codex 配置：

```bash

mkdir -p ~/.codex

nano ~/.codex/config.toml

```

写入：

```toml

model = "把这里改成Sub2API后台可用模型名"

model_provider = "sub2api"

model_providers.sub2api

name = "Sub2API"

base_url = "http://localhost:8080/v1"

env_key = "SUB2API_API_KEY"

wire_api = "responses"

supports_websockets = false

```

保存后设置 API Key：

```bash

export SUB2API_API_KEY="sk-你的Sub2API-Key"

```

为了永久生效：

```bash

echo 'export SUB2API_API_KEY="sk-你的Sub2API-Key"' >> ~/.bashrc

source ~/.bashrc

```

测试：

```bash

codex "用一句话介绍当前目录"

```

如果模型不存在，改 ~/.codex/config.toml 里的 model；如果鉴权失败，检查 SUB2API_API_KEY 是否是 Sub2API 后台生成的 Key。

七、常用运维命令

Sub2API：

```bash

cd ~/apps/sub2api-deploy

docker compose ps

docker compose logs -f sub2api

docker compose restart

docker compose down

docker compose pull

docker compose up -d

```

WSL：

```powershell

wsl --update

wsl --shutdown

```

Codex：

```bash

npm i -g @openai/codex

codex --version

which codex

```

八、Nginx 反代注意点

如果你后面把 Sub2API 放到服务器并用 Nginx 反代，Sub2API README 特别提醒：搭配 Codex CLI 时，Nginx 的 http 块要加：

```nginx

underscores_in_headers on;

```

否则带下划线的请求头可能被 Nginx 丢弃，影响 Sub2API 的粘性会话/多账号调度。

九、安全提醒

Sub2API README 明确提示：该项目用于技术学习和研究，使用中转、订阅配额分发等能力可能违反部分上游服务条款，账号封禁或服务中断风险需要自行承担。生产环境还要固定 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD，不要把 API Key 写进公开仓库。

参考来源：
Microsoft WSL 安装文档
Docker Desktop WSL2 文档
Docker Engine Ubuntu 安装文档
OpenAI Codex Windows/WSL 文档
OpenAI Codex 配置参考
Wei-Shaw/sub2api GitHub

会出现一些问题

你这个报错就是：本地版 docker-compose.local.yml 需要读取 deploy\.env，但你当前目录里没有 .env，或者 .env 里没有 POSTGRES_PASSWORD。

在你这个目录执行：

cd E:\project\sub2api\deploy
copy .env.example .env
notepad .env

打开后至少确认这几项有值：

POSTGRES_USER=sub2api
POSTGRES_PASSWORD=随便改一个强密码
POSTGRES_DB=sub2api

ADMIN_EMAIL=admin@sub2api.local
ADMIN_PASSWORD=你的后台管理员密码

JWT_SECRET=随便一串长随机字符
TOTP_ENCRYPTION_KEY=随便一串长随机字符
TZ=Asia/Shanghai

如果懒得手写随机值，可以在 PowerShell 里生成：

[guid]::NewGuid().ToString("N") + [guid]::NewGuid().ToString("N")

复制两次，分别填到 JWT_SECRET 和 TOTP_ENCRYPTION_KEY。POSTGRES_PASSWORD 也可以用这种字符串。

然后创建本地数据目录：

mkdir data
mkdir postgres_data
mkdir redis_data

再启动：

docker compose -f docker-compose.local.yml up -d

查看是否启动成功：

docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs -f sub2api

浏览器打开：

http://localhost:8080

如果你之前已经启动失败过，通常不用清理，补好 .env 后直接 up -d 就行。

如果后面还是报数据库密码相关错误，把 .env 里的 POSTGRES_PASSWORD 确认一下：等号后面不能空，最好不要带中文、空格、引号。