搭建大模型 API 中转并用于国内数据蒸馏：基于 sub2api 的部署

前言：本文给出一个基于 sub2api 的最小可复现部署方案，用于统一接入上游大模型服务，并将其暴露为内部可控的 API 入口，适合需要做数据清洗、批处理、文本标准化或轻量服务编排的个人开发者与小团队。全文重点覆盖环境与版本、部署路径、配置要点、验证方法与运维边界，并补充许可证与合规提醒，帮助你快速判断“能不能用、怎么落地、上线前还缺什么”。

1. 环境 / 简介（含版本 / 许可说明）

1.1 目标与适用场景

本文采用的方案是：使用 Docker 部署 sub2api，将上游模型能力统一封装为本地或内网 API，用于数据清洗与调用管理。

适用场景：

需要统一管理多个上游模型账户或渠道
需要把清洗任务接入脚本、ETL、定时任务或内部服务
希望降低接入复杂度，把调用方式收敛到一个 HTTP API
需要保留日志、配置和数据目录，便于迁移与备份

1.2 复现环境

项目	建议值
OS	Ubuntu 22.04 LTS 或同类 Linux 发行版
CPU	2 vCPU 起
内存	4 GB 起
磁盘	20 GB 起，日志和数据单独挂载更稳妥
容器运行时	Docker Engine + Docker Compose Plugin
网络	可访问 Docker Hub、GitHub 及所需上游服务（可使用国内镜像）

1.3 版本与来源

项目	说明
项目名称	`sub2api`
上游仓库	`Wei-Shaw/sub2api`
部署方式	官方部署脚本 + `docker-compose.local.yml`
镜像与配置	以部署脚本拉取的实际版本为准，建议记录镜像 tag 与仓库 commit
验证命令	`docker version` / `docker compose version`

建议首次部署后立即执行一次版本留档：记录镜像 tag、容器 ID、仓库 commit 和 .env 生成时间，便于后续回滚与排障。

2. 技术方案与关键取舍

2.1 一句话结论

本文采用的方案是：在国内接入 IPLC，中国侧作为入口，服务端部署 sub2api，再通过 IPLC 的韩国出口访问上游；在 sub2api 内部继续做账户与代理的一对一绑定，形成“主链路固定、账户隔离、代理独占”的访问结构。这个方案的重点不是把链路做复杂，而是把服务部署位置、默认出口、账户路径和代理关系固定下来，降低请求漂移、混用和账户被风控成本。

2.2 核心流程

flowchart LR
    A[中国网络入口] --> B[服务器 / sub2api]
    B --> C[IPLC 韩国出口]

    C --> D1[账户 A]
    C --> D2[账户 B]
    C --> D3[账户 C]

    D1 --> E1[代理 A]
    D2 --> E2[代理 B]
    D3 --> E3[代理 C]

    E1 --> F[大模型厂商]
    E2 --> F
    E3 --> F

可以压缩成 5 步理解：

业务请求先进入 IPLC 中国入口。
请求到达部署了 sub2api 的服务器。
服务统一从 IPLC 韩国出口对外访问。
sub2api 按账户维度分配固定代理。
每个账户通过各自代理访问对应的大模型厂商。

3. 对比与选型

3.1 为什么选 Docker 路径

项目	许可证	主要优势	主要劣势 / 注意	典型场景
Docker Compose 部署	取决于项目与镜像	上手快、复现成本低、迁移简单	需要理解卷挂载、端口和环境变量	单机、测试、小规模生产
手工源码部署	取决于项目与依赖	灵活度高、便于深度调试	环境漂移大、维护成本高	开发调试、二次开发
Kubernetes / Helm	取决于项目与 Chart	可扩展、便于标准化运维	初始复杂度高，不适合轻量场景	多实例、团队化运维

小结：

要最快上线验证，优先选 Docker Compose。
要做二次开发或改源码，再考虑手工部署。
要多实例、高可用、团队协作运维，再进入 Kubernetes。

4. 落地实践（部署 / 配置 / 验证）

4.1 安装 Docker

下面这段命令用于在 Ubuntu 上安装 Docker Engine 与 Compose Plugin。发行版不同，仓库源与包名可能不同。

Bash

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupgsudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpgecho \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullsudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupgsudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpgecho \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullsudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

安装完成后，先验证 Docker 与 Compose 是否可用。

Bash

docker version
docker compose version

docker version
docker compose version

期望输出：

docker version 能返回 Client / Server 版本信息
docker compose version 能返回 Compose 插件版本
无权限时，给当前用户加入 docker 用户组后重新登录再试

4.2 部署 sub2api

下面的命令用于创建部署目录、拉取部署脚本并启动服务。生产环境建议先阅读脚本内容，再执行。

Bash

mkdir -p ~/sub2api-deploy
cd ~/sub2api-deploycurl -sSL \
  https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh \
  | bashdocker compose -f docker-compose.local.yml up -d

mkdir -p ~/sub2api-deploy
cd ~/sub2api-deploycurl -sSL \
  https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh \
  | bashdocker compose -f docker-compose.local.yml up -d

部署脚本通常会完成这些动作：

下载 docker-compose.local.yml 和示例环境文件
生成必要的随机密钥与数据库密码
创建 .env 文件
创建本地数据目录，便于备份与迁移
输出初始化凭证，供首次登录记录

4.3 推荐目录结构

目录结构建议保持简单，重点是把配置、数据和备份分开。

Tree

sub2api-deploy/
├── docker-compose.local.yml
├── .env
├── data/
│   ├── postgres/
│   ├── logs/
│   └── uploads/
├── backup/
└── scripts/

sub2api-deploy/
├── docker-compose.local.yml
├── .env
├── data/
│   ├── postgres/
│   ├── logs/
│   └── uploads/
├── backup/
└── scripts/

4.4 配置要点

这段配置的作用是定义运行所需的关键环境变量。不同版本字段名可能不同，应以实际生成文件为准。

Conf

JWT_SECRET=replace_with_random_secret
TOTP_ENCRYPTION_KEY=replace_with_random_key
POSTGRES_PASSWORD=replace_with_strong_password

JWT_SECRET=replace_with_random_secret
TOTP_ENCRYPTION_KEY=replace_with_random_key
POSTGRES_PASSWORD=replace_with_strong_password

修改原则：

所有密钥使用随机强密码
.env 不要提交到 Git 仓库
生产环境把 .env 权限收紧到最小可读范围
首次启动后立即备份 .env 与数据库卷信息

4.5 启动后查看日志

这段命令用于确认容器是否正常启动，并读取初始化日志。只在你自己的环境中查看和保存凭证，不要把日志直接外发。

Bash

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

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

验证重点：

容器没有持续重启
应用完成初始化
管理入口可访问
首次登录后立即修改默认或初始密码

4.6 启动与验证

下面给出一个固定的验证顺序，先验证容器，再验证页面，再验证 API。

Bash

docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs --tail=100 sub2api
curl -I http://127.0.0.1:你的端口

docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs --tail=100 sub2api
curl -I http://127.0.0.1:你的端口

期望输出：

ps 中服务状态为 Up
日志中无持续性的数据库连接失败、密钥缺失、迁移失败
curl -I 返回 HTTP/1.1 200 OK、302 或符合产品预期的状态码

5. sub2api 核心配置与使用

服务启动后，你需要完成从“基础配置”到“代理绑定”的完整闭环，以确保上游账户的安全。

第一步：基础初始化

修改密码： 登录系统后，第一时间修改默认的账户密码，确保内网或公网暴露的安全性。
建立分组： 在系统中添加“平台分组”，按厂商或用途（如测试组、生产组、清洗组）对模型进行归类管理。

添加平台分组

第二步：配置高质量 IP 代理

大模型厂商（尤其是 Google）对 IP 质量的要求极为严苛。在添加 IP 代理前，请务必通过类似 ping0.cc 的工具进行纯净度检测。你的代理 IP 必须满足以下 “四个必须”：

共享人数： 必须控制在 1-10 人以内（越少越好）。 (注：这类高质量代理获取成本较高，可以找万能的咸鱼购买。)
IP 类型： 必须是家庭宽带（Residential IP）。
风控值： 必须在 20% 以下。
原生属性： 必须是当地原生 IP。

第三步：添加账户与代理的 1v1 绑定（防封号核心）

配置 2FA： 购买或注册的账户通常会附带双重身份验证（2FA）密钥。推荐使用 2fa.run 等在线工具或本地验证器，填入密钥以便随时接收 6 位验证码。

一对一绑定： 在添加大模型平台账户时，必须为每个账户配置独立的代理 IP。切忌多个账户混用同一个 IP，否则极易触发关联封号。

6. 高频报错排查与风控应对 (Troubleshooting)

在对接谷歌系大模型时，遇到报错不要慌，绝大多数情况都是因为网络环境（IP）和谷歌的安全风控机制引起的。以下是几种最常见的报错及图文解决步骤：

6.1 报错提示：缺少 Project_id

报错现象： 在 sub2api 中添加账号或测试连通性时，返回有关 Project_id 的报错。（Failed to exchange code: google One accounts require a project_id, failed to auto-detect: onboardUser completed but no project_id returned）

原因分析： 当前登录的 Google 账号下没有创建或关联任何 Google Cloud 项目。
解决步骤：

访问 Google Cloud 控制台：https://console.cloud.google.com
使用报错的谷歌账号登录，点击顶部导航栏新建一个项目（New Project）即可。

6.2 报错提示：403 Permission Denied (需要验证账号)

报错现象： Docker 日志中出现 upstream_msg=Verify your account to continue.，或者测试时 API 返回类似以下的 JSON： "error": { "code": 403, "message": "Verify your account to continue.", "status": "PERMISSION_DENIED" }

原因分析： 谷歌账号处于未完全激活或受到安全限制的状态。、
解决步骤：如果没有海外手机号，可以使用接码平台（如 lubansms.com 或 grizzlysms.com，更多平台可参考聚合站 https://233heji.com/28.html）。
复制报错信息里附带的激活链接，在配置了对应代理的浏览器中打开。
页面会要求验证手机号。关键点：尽量使用与当前代理 IP 同区域的手机号，其他地区也可以，但风控风险稍高。

6.3 报错提示：403 API 未启用

报错现象： 返回信息包含 "code": 403, "message": "Gemini for Google Cloud API has not been used in project..."
原因分析： 云项目虽然建好了，但没有手动开启 Gemini API 的调用权限。
解决步骤： 按照报错信息中给出的链接直接点进去，跳转到谷歌云后台，点击“启用（Enable）”激活该应用即可。

6.4 账户各类异常：

账号登录受阻与风控封控排查

情况 ① 与 ②：IP 质量过差导致拦截
- 现象说明：这是近期最频发的问题（尤其是情况 ①）。谷歌安全系统判定当前代理 IP 纯净度极低或已被标记。
- 解决办法：立即弃用当前节点，切换至高质量的家庭宽带 IP（原生、低风控值）重新尝试登录。
情况 ③ 与 ④：频繁变动网络 / 设备导致身份核验失败
- 现象说明：使用了动态代理导致 IP 频繁跳跃，或者在多个设备间来回切换登录，触发了谷歌的异常活动保护，系统无法确认是否为本人操作。
- 解决办法：同样需要固定一个优质的节点 IP 进行登录，切忌网络环境反复横跳。

账号被停用 (Disabled) 与申诉指南

如果页面直接提示“账号已停用”，说明你的操作触发了谷歌的深层风控机制。

唯一解法：提交表单进行申诉。
处理时效：通常提交申诉后 24 小时内就会有结果。只要顺利通过，账号后续即可正常使用，不用过度担心。

⚠️ 核心避坑：申诉话术切忌直接套用！ 直接复制粘贴公开模板大概率会被机器审核秒拒。请务必使用 AI 工具（如输入：“帮我换种说法润色下面这段话，语气诚恳自然点”），对下方的核心意图进行重写后再提交：

申诉核心意图（请务必使用 AI 重写后提交）： 您好，我是一名来自中国的真实用户。由于我所在的地区网络连接不稳定，我不得不经常切换网络节点来访问 Google 服务，这可能导致了 IP 地址的频繁变动，被系统误判为异常活动。这个账号主要用于我的个人日常使用（如邮件、同步数据等），我严格遵守 Google 的政策。请人工审核并恢复我的账号，谢谢。