【保姆级教程】手把手教你本地搭建sub2api中转站

本人（纯小白）最近一周才开始了解学习（L吧也是才开始逛），然后在L吧东拼西凑找教程，故此整理了从0到1的完整教程，整体非常简单，教程很详细，希望能帮助和我一样刚接触并且想了解的的朋友。（如果有不正确的地方，佬们随意点评）

## 一、Sub2API 是什么？

Sub2API 是一个开源的 AI API 网关平台，能够将 Claude、OpenAI、Gemini 等 AI 产品的订阅账号统一接入，生成标准 API Key 供下游工具调用

- 项目地址：GitHub - Wei-Shaw/sub2api: Sub2API is an open-source relay platform that unifies Claude, OpenAI, Gemini, and Antigravity subscriptions into a single endpoint. It supports account sharing and cost-sharing, with seamless native tool compatibility. · GitHub

-–

## 二、前置条件

| 条件 | 要求 |

|------|------|

| 操作系统 | Windows 10 2004+ 或 Windows 11 |

| WSL | 已安装 WSL 2 |

| Docker Desktop | 已安装并正常运行 |

| Docker Compose | v2+（Docker Desktop 自带） |

-–

## 三、部署步骤

### 3.1 确认 Docker Desktop 正常运行

打开 PowerShell，执行：

```powershell

docker --version

docker compose version

```

确认两个命令都有输出即可。

### 3.2 开启 Docker Desktop 的 WSL 集成

> **重要！** 如果不开启此设置，WSL 终端中会报 `docker: command not found` 错误。

1. 打开 **Docker Desktop**

2. 点击右上角 **齿轮图标**（Settings）

3. 左侧选择 **Resources** → **WSL integration**

4. 打开 **Enable integration with my default WSL distro** 开关

5. 在下方列表中，找到 **Ubuntu**，把它的开关也打开

6. 点击 **Apply & Restart**

等待 Docker Desktop 重启完成后，进入 WSL 终端验证：

```bash

docker --version

```

有输出即说明集成成功。

> **踩坑提醒：** 如果点击 Apply & Restart 后卡在 “Applying settings” 超过 2 分钟，可以：

> - 按 `Ctrl+Shift+Esc` 打开任务管理器，结束 **Docker Desktop** 进程，再重新打开

> - 或者在 PowerShell 中执行 `Stop-Process -Name “Docker Desktop” -Force`，再重启 Docker Desktop

> - 如果反复卡住，可以先只打开总开关 Apply，成功后再回来单独打开 Ubuntu 的开关

>

> 设置是否生效，可以检查 `C:\Users\你的用户名\AppData\Roaming\Docker\settings-store.json` 文件中是否包含 `WslIntegrations` 相关配置。

### 3.3 配置 Docker 镜像加速（国内网络必做）

> **踩坑提醒：** 国内网络直接拉取 Docker Hub 镜像会超时报错：`dial tcp xxx:443: connectex: A connection attempt failed`。必须配置镜像加速。

1. 打开 **Docker Desktop** → **Settings** → **Docker Engine**

2. 在 JSON 配置中追加 `registry-mirrors` 字段（保留原有配置）：

```json

{

“builder”: {

"gc": {



  "defaultKeepStorage": "20GB",



  "enabled": true



}

},

“experimental”: false,

“registry-mirrors”: [

"https://docker.m.daocloud.io",



"https://dockerproxy.com",



"https://docker.1panel.live"

]

}

```

3. 点击 **Apply & Restart**

> 如果你有代理（科学上网），也可以在 Docker Desktop → Settings → Resources → Proxies 中配置代理地址，效果更好。

### 3.4 进入 WSL 终端

```powershell

wsl

```

### 3.5 创建部署目录

```bash

mkdir -p sub2api-deploy && cd sub2api-deploy

```

### 3.6 一键部署（推荐）

运行官方自动化部署脚本：

```bash

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

```

脚本会自动完成：

- 下载 `docker-compose.yml` 和 `.env.example`

- 自动生成安全凭证（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD）

- 创建 `.env` 文件并填充密钥

- 创建数据目录（data、postgres_data、redis_data）

- 显示生成的凭证（**务必记录保存**）

### 3.7 修复 PostgreSQL 在 Windows 上的权限问题（必做）

> **踩坑提醒：** 在 Windows 上，`docker-compose.yml` 中 PostgreSQL 的数据目录默认绑定挂载到本地 `./postgres_data`，但 NTFS 文件系统不支持 Linux 的 chmod 操作，会导致 PostgreSQL 启动失败，报错：

> ```

> initdb: error: could not change permissions of directory “/var/lib/postgresql/data”: Operation not permitted

> ```

> 以及 `dependency failed to start: container sub2api-postgres is unhealthy`。

>

> **解决方法：** 将 PostgreSQL 的数据目录改为 Docker 命名卷。

打开 `sub2api-deploy/docker-compose.yml`，找到 postgres 服务的 volumes 部分：

**修改前：**

```yaml

postgres:

...



volumes:



  \# Local directory mapping for easy migration



  - ./postgres_data:/var/lib/postgresql/data

```

**修改后：**

```yaml

postgres:

...



volumes:



  \# Use named volume to avoid NTFS permission issues on Windows



  - postgres_data:/var/lib/postgresql/data

```

然后在文件末尾的 `networks` 之后添加 `volumes` 定义：

```yaml

networks:

sub2api-network:

driver: bridge

volumes:

postgres_data:

```

> **说明：** Docker 命名卷存储在 WSL 的虚拟磁盘中，不受 NTFS 权限限制。Redis 的 `./redis_data` 不受影响，无需修改。

### 3.8 启动服务

> **踩坑提醒：** PowerShell 和 WSL 的路径格式不同！

> - **PowerShell** 用 Windows 路径：`C:\Users\22078\Desktop\node\sub2api-deploy`

> - **WSL** 用 Linux 路径：`/mnt/c/Users/22078/Desktop/node/sub2api-deploy`

>

> 必须先 `cd` 到 sub2api-deploy 目录再执行 `docker compose up -d`，否则会报 `no configuration file provided: not found`。

**在 PowerShell 中：**

```powershell

cd C:\Users\22078\Desktop\node\sub2api-deploy

docker compose up -d

```

**或在 WSL 中：**

```bash

cd /mnt/c/Users/22078/Desktop/node/sub2api-deploy

docker compose up -d

```

### 3.9 查看运行状态

```bash

docker compose ps

```

确认三个容器都是 `Up (healthy)`：

- sub2api

- sub2api-postgres

- sub2api-redis

### 3.10 查看日志

```bash

docker compose logs -f sub2api

```

看到服务正常启动的日志即可，按 `Ctrl+C` 退出日志。

-–

## 四、访问后台

浏览器打开：

```

http://localhost:8080

```

### 4.1 获取管理员密码

默认管理员账号：`[email protected]`

初始密码在首次启动时自动生成，在 WSL 终端执行：

```bash

docker compose logs sub2api | grep “admin password”

```

日志中出现的密码即为初始密码。

### 4.2 登录后建议

- 立即修改管理员邮箱和密码

- 记录好所有凭证信息

-–

## 五、基本使用

### 5.1 创建账号分组

进入后台 → 账号管理 → 创建分组，例如：

- `claude` — Claude 订阅账号池

- `openai` — OpenAI 订阅账号池

- `gemini` — Gemini 订阅账号池

### 5.2 导入上游账号

进入后台 → 账号管理 → 导入账号，根据上游类型填写对应信息：

- Claude：填入 Session Key 或 Cookie

- OpenAI：填入 Access Token 或 API Key

- Gemini：填入 API Key

### 5.3 创建 API Key

进入后台 → API Key 管理 → 创建 Key，绑定到指定分组。

### 5.4 使用 API

生成的 API Key 可供 OpenCode、Cursor 等客户端使用，API 地址格式：

```

http://localhost:8080/v1/chat/completions

```

-–

## 六、手动部署（备选方案）

如果一键脚本无法下载，可手动配置：

### 6.1 克隆仓库

```bash

git clone GitHub - Wei-Shaw/sub2api: Sub2API is an open-source relay platform that unifies Claude, OpenAI, Gemini, and Antigravity subscriptions into a single endpoint. It supports account sharing and cost-sharing, with seamless native tool compatibility. · GitHub

cd sub2api/deploy

```

### 6.2 配置环境变量

```bash

cp .env.example .env

```

编辑 `.env`，必须配置以下项：

```env

# PostgreSQL 密码（必需）

POSTGRES_PASSWORD=your_secure_password_here

# JWT 密钥（推荐）

JWT_SECRET=your_jwt_secret_here

# TOTP 加密密钥（推荐）

TOTP_ENCRYPTION_KEY=your_totp_key_here

# 管理员账号（可选）

[email protected]

ADMIN_PASSWORD=your_admin_password

# 端口（可选，默认 8080）

SERVER_PORT=8080

```

生成安全密钥：

```bash

openssl rand -hex 32

```

每次执行会生成一个 64 位 hex 字符串，分别填入上面的三个字段。

### 6.3 创建数据目录并启动

```bash

mkdir -p data postgres_data redis_data

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

```

-–

## 七、常用命令

```bash

# 查看运行状态

docker compose ps

# 查看日志

docker compose logs -f sub2api

# 停止服务

docker compose down

# 重启服务

docker compose restart

# 更新镜像

docker compose pull

docker compose up -d

# 进入 sub2api 容器

docker compose exec sub2api sh

```

-–

## 八、常见问题

### Q1: Docker Desktop 启动报 WSL 错误

确保 WSL 2 已正确安装：

```powershell

wsl --set-default-version 2

```

### Q2: WSL 中报 `docker: command not found`

未开启 Docker Desktop 的 WSL 集成，参见 3.2 节开启。

### Q3: Docker Desktop 卡在 “Applying settings”

参见 3.2 节踩坑提醒，强制结束 Docker Desktop 进程后重启。

### Q4: 拉取镜像超时 / `connectex: A connection attempt failed`

国内网络无法直连 Docker Hub，参见 3.3 节配置镜像加速。

### Q5: `no configuration file provided: not found`

没有 cd 到 sub2api-deploy 目录就执行了 docker compose，参见 3.7 节。

### Q6: PowerShell 中 `cd /mnt/c/…` 报路径不存在

`/mnt/c/…` 是 WSL 的路径格式，PowerShell 中应使用 `C:\…`，参见 3.7 节。

### Q7: PostgreSQL 启动失败 / `could not change permissions of directory`

Windows NTFS 不支持 Linux chmod，需将 PostgreSQL 数据目录改为 Docker 命名卷，参见 3.7 节。

### Q8: 端口 8080 被占用

修改 `.env` 中的 `SERVER_PORT` 为其他端口，如 `6780`，同时修改 `docker-compose.yml` 中的端口映射。

### Q9: curl 下载脚本失败（网络问题）

使用手动部署方式（第六节），或配置代理：

```bash

export https_proxy=http://127.0.0.1:7890

```

### Q10: 容器启动后无法访问

检查防火墙是否放行对应端口，本地部署一般不会遇到此问题。

### Q11: 忘记管理员密码

删除 data 目录中的数据库文件，重新启动会自动初始化（**会丢失所有数据**）。