docs: publish sub2api-overdraft fork
This commit is contained in:
bmiddle1.backend.zhangfucheng committed
1 parent
e91ba0a8dc
commit
cdf8c1d659
10 files changed
+667
-22
No files matched your search
@@ -0,0 +1,511 @@
|
||||
# sub2api-overdraft 部署与运维指南
|
||||
|
||||
本文档面向希望部署本项目、验证 Codex 5h / 7d 额度透支状态，以及后续安全升级的使用者。
|
||||
|
||||
本项目是 [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api) 的非官方衍生版本，公开项目名为 **sub2api-overdraft**。内部二进制名、Docker 服务名、数据目录和 Go module 仍保留 `sub2api`，这是为了兼容原项目并降低同步上游更新时的冲突。
|
||||
|
||||
## 重要说明
|
||||
|
||||
- 本功能仅表示：当 Codex 5h 或 7d 页面额度达到 100% 后，通过真实请求确认上游是否仍允许继续调用。
|
||||
- `passed` 只代表探测时上游仍返回有效响应，不承诺之后始终可用，也不会绕过认证失效、账号禁用、网络故障或其他风控限制。
|
||||
- 探测请求和透支期请求都可能产生真实上游用量和费用。
|
||||
- 此行为可能不符合上游服务条款。部署者必须自行确认合规性，并承担账号限制、服务中断等风险。
|
||||
- 官方 Sub2API 安装脚本和 `weishaw/sub2api:latest` 镜像不包含本 Fork 的透支功能。
|
||||
|
||||
## 功能范围
|
||||
|
||||
开启 `gateway.codex_quota_overdraft_enabled` 后，本项目会：
|
||||
|
||||
- 对符合条件的 OpenAI OAuth 普通账号和 Agent Identity 账号启用透支调度，Shadow 子账号除外。
|
||||
- 支持 `/v1/responses`、转换为 Responses 的 `/v1/chat/completions` 和 `/v1/messages`，以及 Responses WebSocket v2。
|
||||
- 在适用请求的最后一条用户消息后注入一对无操作工具调用，用于保持与参考实现一致的请求形态。
|
||||
- 当 5h 或 7d 额度首次达到 100%，或收到带明确额度证据的 429 时，最多执行 5 次真实探测。
|
||||
- 分别维护 5h、7d 透支周期，并在管理页面显示状态、请求数、Token、账号金额和预计恢复时间。
|
||||
- 将探测状态保存在现有 `accounts.extra` JSONB 字段中，不新增数据库表，不需要手动执行数据库迁移（migration）。
|
||||
|
||||
以下端点不启用透支：`/responses/compact`、图片生成、Embedding、Count Tokens 和 Live。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- Linux amd64 或 arm64 服务器
|
||||
- Git
|
||||
- Docker 20.10 或更高版本
|
||||
- Docker Compose v2，命令为 `docker compose`
|
||||
- 建议至少 2 核 CPU、4 GB 内存和 20 GB 可用磁盘
|
||||
- 可以访问 GitHub、Docker Hub、Go module 和 npm/pnpm 依赖源
|
||||
|
||||
首次源码构建时间取决于服务器性能和网络状况。PostgreSQL 与 Redis 已包含在 Compose 中，不需要提前单独安装。
|
||||
|
||||
## 全新部署
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt
|
||||
cd /opt
|
||||
sudo git clone https://github.com/DeanZFC/sub2api-overdraft.git
|
||||
sudo chown -R "$(id -u):$(id -g)" /opt/sub2api-overdraft
|
||||
cd /opt/sub2api-overdraft/deploy
|
||||
```
|
||||
|
||||
仓库默认分支是 `codex-overdraft`。确认当前分支：
|
||||
|
||||
```bash
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
```text
|
||||
codex-overdraft
|
||||
```
|
||||
|
||||
### 2. 创建环境配置
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
至少设置以下值，不要把真实密钥提交到 Git：
|
||||
|
||||
```bash
|
||||
POSTGRES_PASSWORD=替换为随机密码
|
||||
JWT_SECRET=替换为随机密钥
|
||||
TOTP_ENCRYPTION_KEY=替换为随机密钥
|
||||
ADMIN_EMAIL=你的管理员邮箱
|
||||
ADMIN_PASSWORD=替换为强密码
|
||||
SERVER_PORT=8080
|
||||
```
|
||||
|
||||
可分别使用以下命令生成随机值：
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
透支开关在公开部署覆盖文件中默认开启。也可以在 `.env` 中显式配置：
|
||||
|
||||
```bash
|
||||
GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED=true
|
||||
```
|
||||
|
||||
### 3. 创建数据目录
|
||||
|
||||
```bash
|
||||
mkdir -p data postgres_data redis_data
|
||||
```
|
||||
|
||||
这些目录和 `.env` 已被 Git 忽略，不会在正常的 `git add .` 中上传。
|
||||
|
||||
### 4. 从源码构建并启动
|
||||
|
||||
后续所有 Compose 命令都应同时带上这两个文件：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build
|
||||
```
|
||||
|
||||
`docker-compose.local.yml` 提供应用、PostgreSQL、Redis、网络和数据卷；`docker-compose.overdraft.yml` 把应用镜像切换为本仓库源码构建，并默认开启透支功能。
|
||||
|
||||
查看容器状态：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
ps
|
||||
```
|
||||
|
||||
三个容器应处于 `Up` 或 `healthy` 状态：
|
||||
|
||||
```text
|
||||
sub2api
|
||||
sub2api-postgres
|
||||
sub2api-redis
|
||||
```
|
||||
|
||||
查看启动日志：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
logs -f sub2api
|
||||
```
|
||||
|
||||
默认访问地址为 `http://服务器IP:8080`。
|
||||
|
||||
## 配置文件位置与优先级
|
||||
|
||||
源码仓库中的 `deploy/config.example.yaml` 只是完整配置模板，不是容器实际读取的运行配置。
|
||||
|
||||
Compose 本地目录部署的实际配置通常位于：
|
||||
|
||||
```text
|
||||
/opt/sub2api-overdraft/deploy/data/config.yaml
|
||||
```
|
||||
|
||||
它在容器内对应：
|
||||
|
||||
```text
|
||||
/app/data/config.yaml
|
||||
```
|
||||
|
||||
如果手动通过 YAML 开启，请确保层级正确：
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
codex_quota_overdraft_enabled: true
|
||||
```
|
||||
|
||||
环境变量 `GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED` 的优先级高于 YAML。本项目提供的 Compose 覆盖文件默认将它设为 `true`，因此全新部署不需要手动编辑 `data/config.yaml`。
|
||||
|
||||
检查容器实际收到的环境变量：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
exec sub2api sh -lc 'printf "%s\n" "$GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED"'
|
||||
```
|
||||
|
||||
预期输出为 `true`。
|
||||
|
||||
## 从现有 Sub2API 部署迁移
|
||||
|
||||
迁移前先备份 `.env`、运行配置和数据库。不要删除 `data`、`postgres_data`、`redis_data`。
|
||||
|
||||
如果服务器上的 `/opt/sub2api` 已经是 Git 仓库，并且包含手工修改，先检查：
|
||||
|
||||
```bash
|
||||
cd /opt/sub2api
|
||||
git status --short
|
||||
git branch --show-current
|
||||
git remote -v
|
||||
```
|
||||
|
||||
有未提交代码时先保存：
|
||||
|
||||
```bash
|
||||
git stash push -u -m "server changes before codex-overdraft switch"
|
||||
```
|
||||
|
||||
然后连接本 Fork 并切换到公开分支：
|
||||
|
||||
```bash
|
||||
git remote set-url origin https://github.com/DeanZFC/sub2api-overdraft.git
|
||||
git fetch origin
|
||||
git switch codex-overdraft 2>/dev/null || \
|
||||
git switch -c codex-overdraft --track origin/codex-overdraft
|
||||
git pull --ff-only origin codex-overdraft
|
||||
```
|
||||
|
||||
如果 Git 报 `detected dubious ownership`，确认目录确实是本项目后再执行：
|
||||
|
||||
```bash
|
||||
git config --global --add safe.directory /opt/sub2api
|
||||
```
|
||||
|
||||
已有的服务器专用 Compose 文件可以保留，但推荐改用仓库内公开的覆盖文件：
|
||||
|
||||
```bash
|
||||
cd /opt/sub2api/deploy
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build --force-recreate sub2api
|
||||
```
|
||||
|
||||
切换分支后不要直接执行 `git stash pop`。先用 `git stash show --stat` 检查旧 stash；本分支已经包含透支代码，直接恢复旧代码可能造成重复修改和冲突。
|
||||
|
||||
## 判断功能是否生效
|
||||
|
||||
### 第一层：确认运行的是源码构建镜像
|
||||
|
||||
```bash
|
||||
docker inspect sub2api --format '{{.Config.Image}}'
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
```text
|
||||
sub2api-overdraft:local
|
||||
```
|
||||
|
||||
如果输出 `weishaw/sub2api:latest`，说明当前仍在运行官方镜像，本功能不会生效。
|
||||
|
||||
### 第二层：确认开关已开启
|
||||
|
||||
```bash
|
||||
docker exec sub2api sh -lc 'printf "%s\n" "$GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED"'
|
||||
```
|
||||
|
||||
预期输出 `true`。修改 `.env` 后必须重建或重新创建应用容器：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --force-recreate sub2api
|
||||
```
|
||||
|
||||
### 第三层：查看真实探测日志
|
||||
|
||||
只有账号 5h/7d 额度达到 100%，或者收到带明确额度信息的上游 429，才会启动探测。额度未耗尽时没有相关日志是正常现象。
|
||||
|
||||
```bash
|
||||
docker logs --since 30m sub2api 2>&1 | \
|
||||
grep -E 'codex_quota_overdraft_(probe|state|pause)'
|
||||
```
|
||||
|
||||
关键日志：
|
||||
|
||||
| 日志 | 含义 |
|
||||
| --- | --- |
|
||||
| `codex_quota_overdraft_probe_passed` | 至少一次真实探测成功，透支成立，账号继续参与调度 |
|
||||
| `codex_quota_overdraft_probe_failed` | 5 次都明确返回额度限制，账号暂停至额度恢复时间 |
|
||||
| `codex_quota_overdraft_probe_inconclusive` | 网络、超时、5xx 等导致无法确认，约 1 分钟后可重试 |
|
||||
| `codex_quota_overdraft_probe_claim_failed` | 无法在 PostgreSQL 中原子领取探测任务，需要排查数据库或版本 |
|
||||
| `codex_quota_overdraft_state_persist_failed` | 状态无法写入 `accounts.extra`，页面可能不显示最新结果 |
|
||||
|
||||
真正“透支成功”的最直接证据是：
|
||||
|
||||
```text
|
||||
codex_quota_overdraft_probe_passed
|
||||
```
|
||||
|
||||
其中会包含 `account_id`、`attempts`、`model` 和 `quota_window`。
|
||||
|
||||
### 第四层：查看数据库持久化状态
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
exec -T postgres sh -lc \
|
||||
'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -x -c "
|
||||
SELECT id, name, extra->'\''codex_quota_overdraft_probe'\'' AS overdraft_probe
|
||||
FROM accounts
|
||||
WHERE platform = '\''openai'\'' AND type = '\''oauth'\''
|
||||
ORDER BY id;
|
||||
"'
|
||||
```
|
||||
|
||||
重点看 JSON 中的 `status`：
|
||||
|
||||
| 状态 | 页面显示 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| `pending` | 透支探测中 | 最多 5 次真实探测正在执行 |
|
||||
| `passed` | 透支中 | 上游仍可调用，账号继续调度并开始统计透支用量 |
|
||||
| `failed` | 已确认限额 | 5 次均明确受额度限制，暂停到恢复时间 |
|
||||
| `inconclusive` | 探测无法确认 | 暂时无法判断，查看 `reason_code` 和 `retry_at` |
|
||||
| `recovered` | 额度已恢复 | 原额度周期结束，相关暂停已清理 |
|
||||
|
||||
页面显示 `透支中`，数据库为 `passed`，并且后续业务请求返回成功，三者同时满足即可确认功能完整生效。
|
||||
|
||||
## 探测逻辑
|
||||
|
||||
每个额度周期最多探测 5 次，每次最长 20 秒。模型按以下顺序循环：
|
||||
|
||||
```text
|
||||
首选模型 -> gpt-5.5 -> gpt-5.4-mini -> 首选模型 -> gpt-5.5
|
||||
```
|
||||
|
||||
- 任意一次返回有效 `response.completed` 或 `response.output_item.done`，立即记为 `passed`。
|
||||
- 只有 5 次都明确返回 `quota_limited`，才记为 `failed`。
|
||||
- 网络错误、超时、5xx、普通瞬时 429、无效响应等记为 `inconclusive`，不会因此误停账号。
|
||||
- 401/403 继续由原有认证失效逻辑处理。
|
||||
- 账号禁用、过载、代理故障、模型冷却等非额度限制不会被本功能绕过。
|
||||
|
||||
多实例部署通过 PostgreSQL 原子领取（atomic claim）保证同一账号、同一额度周期只有一个实例发起探测。
|
||||
|
||||
## 反向代理
|
||||
|
||||
Nginx 需要把请求转发到宿主机的 `8080` 端口。使用 Codex CLI 时，建议在 Nginx `http` 块启用：
|
||||
|
||||
```nginx
|
||||
underscores_in_headers on;
|
||||
```
|
||||
|
||||
流式响应位置至少应包含：
|
||||
|
||||
```nginx
|
||||
proxy_http_version 1.1;
|
||||
proxy_buffering off;
|
||||
proxy_cache off;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
```
|
||||
|
||||
出现 `duplicate upstream "sub2api_backend"` 时，表示多个 Nginx 配置文件定义了同名 `upstream`。使用以下命令找出重复项，然后只保留一个定义：
|
||||
|
||||
```bash
|
||||
grep -Rns 'upstream sub2api_backend' /etc/nginx/nginx.conf /etc/nginx/conf.d /etc/nginx/sites-enabled
|
||||
```
|
||||
|
||||
修改后先验证再重载：
|
||||
|
||||
```bash
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## 日常升级本 Fork
|
||||
|
||||
运行数据均位于被 Git 忽略的目录中，正常 `git pull` 不会覆盖：
|
||||
|
||||
```text
|
||||
deploy/.env
|
||||
deploy/data/
|
||||
deploy/postgres_data/
|
||||
deploy/redis_data/
|
||||
```
|
||||
|
||||
升级步骤：
|
||||
|
||||
```bash
|
||||
cd /opt/sub2api-overdraft
|
||||
git status --short
|
||||
git switch codex-overdraft
|
||||
git pull --ff-only origin codex-overdraft
|
||||
|
||||
cd deploy
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build
|
||||
```
|
||||
|
||||
如果服务器目录是 `/opt/sub2api`，只需替换第一条路径。升级完成后重新执行“判断功能是否生效”中的镜像、环境变量和日志检查。
|
||||
|
||||
## 合并 Sub2API 官方更新
|
||||
|
||||
本仓库保留两个分支角色：
|
||||
|
||||
- `main`：尽量跟随官方 `Wei-Shaw/sub2api`，作为上游基线。
|
||||
- `codex-overdraft`：本项目默认分支，包含透支功能和公开文档。
|
||||
|
||||
维护者可这样合并官方更新：
|
||||
|
||||
```bash
|
||||
git remote get-url upstream >/dev/null 2>&1 || \
|
||||
git remote add upstream https://github.com/Wei-Shaw/sub2api.git
|
||||
git fetch upstream
|
||||
git switch codex-overdraft
|
||||
git merge upstream/main
|
||||
```
|
||||
|
||||
解决冲突后执行项目测试，提交并推送：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
go test -tags=unit ./internal/repository ./internal/handler ./internal/service \
|
||||
-run 'CodexQuotaOverdraft|AccountSchedulingThreshold|SchedulerSnapshot|SchedulableAccountQueryScopesCodex' \
|
||||
-count=1
|
||||
go test ./internal/repository ./internal/handler ./internal/service ./cmd/server \
|
||||
-run '^$' -count=1
|
||||
|
||||
cd ../frontend
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm run typecheck
|
||||
pnpm exec vitest run \
|
||||
src/components/account/__tests__/UsageProgressBar.spec.ts \
|
||||
src/components/account/__tests__/AccountUsageCell.spec.ts
|
||||
|
||||
cd ..
|
||||
git diff --check
|
||||
git push origin codex-overdraft
|
||||
```
|
||||
|
||||
更详细的实现文件和升级核对清单见 [CODEX_QUOTA_OVERDRAFT_CUSTOMIZATION.md](CODEX_QUOTA_OVERDRAFT_CUSTOMIZATION.md)。
|
||||
|
||||
## 关闭与回滚
|
||||
|
||||
如遇上游兼容问题，在 `deploy/.env` 设置：
|
||||
|
||||
```bash
|
||||
GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED=false
|
||||
```
|
||||
|
||||
然后重新创建应用容器：
|
||||
|
||||
```bash
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --force-recreate sub2api
|
||||
```
|
||||
|
||||
关闭后会恢复官方调度与请求行为。数据库中已有的历史探测 JSON 可以保留，不影响关闭状态。
|
||||
|
||||
## 备份
|
||||
|
||||
数据库建议使用 `pg_dump` 做一致性备份：
|
||||
|
||||
```bash
|
||||
cd /opt/sub2api-overdraft/deploy
|
||||
mkdir -p backups
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
exec -T postgres sh -lc \
|
||||
'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
|
||||
> "backups/sub2api-$(date +%Y%m%d-%H%M%S).dump"
|
||||
```
|
||||
|
||||
另外单独备份 `deploy/.env` 和 `deploy/data/config.yaml`。不要把备份、数据库目录、API Key 或 OAuth 凭证上传到公开仓库。
|
||||
|
||||
## 常见故障
|
||||
|
||||
### 没有任何透支日志
|
||||
|
||||
先确认镜像和开关。若账号 5h/7d 尚未达到 100%，没有探测日志属于正常情况。使用管理页面的主动刷新获取最新额度后，再发送一次符合范围的文本请求。
|
||||
|
||||
### 页面仍显示“限流中”
|
||||
|
||||
本功能只绕过 5h/7d 额度阈值产生的预暂停。以下情况仍会正常限流或暂停：账号禁用、401/403、5 次探测均确认额度耗尽、代理/网络错误、模型级冷却、并发限制或其他上游 429。先按 `account_id` 检查应用日志和数据库中的 `reason_code`。
|
||||
|
||||
### `pq: could not determine data type of parameter $1`
|
||||
|
||||
这是旧版原子领取（atomic claim）SQL 的 PostgreSQL 参数类型问题。当前代码已使用：
|
||||
|
||||
```sql
|
||||
jsonb_build_object($1::text, $2::jsonb)
|
||||
```
|
||||
|
||||
拉取最新 `codex-overdraft` 分支并使用 `--build --force-recreate` 重建应用容器。
|
||||
|
||||
### API 返回 503 `no available accounts`
|
||||
|
||||
这表示账号调度阶段没有可用账号，不是 Nginx 连接故障。检查账号是否属于 API Key 对应分组、是否启用、是否认证有效、是否被其他原因暂停，以及探测状态是否为 `failed`。
|
||||
|
||||
### 容器无法绑定 8080
|
||||
|
||||
查找占用者：
|
||||
|
||||
```bash
|
||||
sudo ss -ltnp 'sport = :8080'
|
||||
```
|
||||
|
||||
如果是旧的 systemd 版 `sub2api`，先确认后停止并禁用：
|
||||
|
||||
```bash
|
||||
sudo systemctl disable --now sub2api
|
||||
```
|
||||
|
||||
也可以在 `.env` 将 `SERVER_PORT` 改为其他未占用端口。
|
||||
|
||||
### PostgreSQL 或 Redis 主机名无法解析
|
||||
|
||||
应用、PostgreSQL 和 Redis 必须加入同一个 Compose 网络。始终使用两个 Compose 文件一起启动完整服务，不要只用 `docker run` 单独启动应用容器。
|
||||
|
||||
## 开源与归属
|
||||
|
||||
- 上游项目：[Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api)
|
||||
- 透支逻辑参考：[Mxucc/cpa-account-config-manager](https://github.com/Mxucc/cpa-account-config-manager)
|
||||
- 本项目遵循仓库中的 [GNU LGPL-3.0](LICENSE) 许可证。
|
||||
- 本项目不是 Sub2API 官方发行版，也不受 OpenAI 或其他上游服务商认可或支持。
|
||||
@@ -1,4 +1,7 @@
|
||||
# Codex 5h / 7d 额度透支定制记录
|
||||
# sub2api-overdraft 5h / 7d 额度透支定制记录
|
||||
|
||||
本文件是维护者实现与升级记录。面向部署者的完整安装、验证、升级和故障排查说明见
|
||||
[CODEX_OVERDRAFT_DEPLOYMENT_CN.md](CODEX_OVERDRAFT_DEPLOYMENT_CN.md)。
|
||||
|
||||
## 基本信息
|
||||
|
||||
@@ -52,7 +55,7 @@ gateway:
|
||||
|
||||
状态值包括 `pending`、`passed`、`failed`、`inconclusive`、`recovered`。账号用量页面显示探测状态、尝试次数、额度周期、透支期成功请求数、Token、账号金额及预计恢复时间。
|
||||
|
||||
不需要新增数据库表或执行 schema migration；周期状态保存在现有 `accounts.extra` JSONB 字段，透支统计读取现有 `usage_logs`。
|
||||
不需要新增数据库表或执行数据库结构迁移（schema migration）；周期状态保存在现有 `accounts.extra` JSONB 字段，透支统计读取现有 `usage_logs`。
|
||||
|
||||
`/responses/compact`、生图请求、Embedding、Count Tokens、Live 等端点不启用额度透支。
|
||||
|
||||
|
||||
+4
-3
@@ -108,9 +108,10 @@ FROM ${POSTGRES_IMAGE} AS pg-client
|
||||
FROM ${ALPINE_IMAGE}
|
||||
|
||||
# Labels
|
||||
LABEL maintainer="Wei-Shaw <github.com/Wei-Shaw>"
|
||||
LABEL description="Sub2API - AI API Gateway Platform"
|
||||
LABEL org.opencontainers.image.source="https://github.com/Wei-Shaw/sub2api"
|
||||
LABEL maintainer="DeanZFC <github.com/DeanZFC>"
|
||||
LABEL description="sub2api-overdraft - Sub2API fork with Codex quota overdraft support"
|
||||
LABEL org.opencontainers.image.source="https://github.com/DeanZFC/sub2api-overdraft"
|
||||
LABEL org.opencontainers.image.licenses="LGPL-3.0-or-later"
|
||||
|
||||
# Install runtime dependencies
|
||||
RUN apk add --no-cache \
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="assets/logo.svg" alt="Sub2API Logo" width="128" />
|
||||
<img src="assets/logo.svg" alt="sub2api-overdraft Logo" width="128" />
|
||||
|
||||
# Sub2API
|
||||
# sub2api-overdraft
|
||||
|
||||
[](https://golang.org/)
|
||||
[](https://vuejs.org/)
|
||||
@@ -10,14 +10,43 @@
|
||||
[](https://redis.io/)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
<a href="https://trendshift.io/repositories/21823" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21823" alt="Wei-Shaw%2Fsub2api | Trendshift" width="250" height="55"/></a>
|
||||
|
||||
**AI API Gateway Platform for Subscription Quota Distribution**
|
||||
**AI API gateway with Codex 5h / 7d quota overdraft probing, tracking, and recovery**
|
||||
|
||||
English | [中文](README_CN.md) | [日本語](README_JA.md)
|
||||
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This is an unofficial fork of [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api), not an official Sub2API release. The upstream install script and `weishaw/sub2api:latest` image do not contain the overdraft feature. Build this fork from source as documented below.
|
||||
|
||||
## Fork Features
|
||||
|
||||
- Runs up to five real probes after the reported Codex 5h or 7d quota reaches 100%.
|
||||
- Keeps an account schedulable after a successful probe and tracks overdraft requests, tokens, cost, and recovery for both windows independently.
|
||||
- Exposes `pending`, `passed`, `failed`, `inconclusive`, and `recovered` states in the admin UI and PostgreSQL.
|
||||
- Uses an atomic PostgreSQL claim for multi-instance deployments and requires no schema migration.
|
||||
- Supports an immediate configuration rollback to the upstream scheduling behavior.
|
||||
|
||||
See the **[Chinese deployment and operations guide](CODEX_OVERDRAFT_DEPLOYMENT_CN.md)** for source builds, migration, verification, upgrades, rollback, Nginx, and troubleshooting. Maintainers should also read [CODEX_QUOTA_OVERDRAFT_CUSTOMIZATION.md](CODEX_QUOTA_OVERDRAFT_CUSTOMIZATION.md).
|
||||
|
||||
Quick start:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/DeanZFC/sub2api-overdraft.git
|
||||
cd sub2api-overdraft/deploy
|
||||
cp .env.example .env
|
||||
# Set POSTGRES_PASSWORD, JWT_SECRET, and TOTP_ENCRYPTION_KEY in .env
|
||||
mkdir -p data postgres_data redis_data
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build
|
||||
```
|
||||
|
||||
This fork remains licensed under [GNU LGPL-3.0](LICENSE) and preserves upstream attribution. The overdraft behavior may conflict with upstream provider terms and may incur real usage or account restrictions. Operators are responsible for compliance and risk.
|
||||
|
||||
The remaining feature, deployment, sponsor, and license text is inherited from the upstream Sub2API documentation. Upstream sponsorship does not imply sponsorship or endorsement of this fork.
|
||||
|
||||
## ⚠️ Important Notice
|
||||
|
||||
Please read the following carefully before using this project:
|
||||
|
||||
+64
-5
@@ -1,8 +1,8 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="assets/logo.svg" alt="Sub2API Logo" width="128" />
|
||||
<img src="assets/logo.svg" alt="sub2api-overdraft Logo" width="128" />
|
||||
|
||||
# Sub2API
|
||||
# sub2api-overdraft
|
||||
|
||||
[](https://golang.org/)
|
||||
[](https://vuejs.org/)
|
||||
@@ -10,14 +10,73 @@
|
||||
[](https://redis.io/)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
<a href="https://trendshift.io/repositories/21823" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21823" alt="Wei-Shaw%2Fsub2api | Trendshift" width="250" height="55"/></a>
|
||||
|
||||
**AI API 网关平台 - 订阅配额分发管理**
|
||||
**带 Codex 5h / 7d 额度透支探测、统计与恢复的 AI API 网关**
|
||||
|
||||
[English](README.md) | 中文 | [日本語](README_JA.md)
|
||||
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 这是基于 [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api) 的非官方 Fork，不是 Sub2API 官方发行版。官方安装脚本和 `weishaw/sub2api:latest` 镜像不包含本项目的透支功能，请按本仓库的源码构建文档部署。
|
||||
|
||||
## 本 Fork 增加的功能
|
||||
|
||||
- Codex 5h / 7d 额度达到 100% 后，最多执行 5 次真实请求探测，判断账号是否仍可继续调用。
|
||||
- 探测成功后继续参与账号调度，并分别统计 5h / 7d 透支期请求数、Token 和金额。
|
||||
- 管理页面显示“透支探测中”“透支中”“已确认限额”“探测无法确认”和“额度已恢复”。
|
||||
- 网络、超时、5xx 和普通瞬时 429 不会被误判为额度耗尽；401/403、账号禁用和其他风控仍使用原有策略。
|
||||
- 多实例通过 PostgreSQL 原子领取（atomic claim）去重；状态保存在现有 `accounts.extra`，无需新增数据表。
|
||||
- 可通过一个配置开关立即关闭，恢复上游 Sub2API 的调度和请求行为。
|
||||
|
||||
## 快速部署
|
||||
|
||||
完整步骤、现有服务器迁移、Nginx、验证、升级和故障排查请阅读：
|
||||
|
||||
**[sub2api-overdraft 部署与运维指南](CODEX_OVERDRAFT_DEPLOYMENT_CN.md)**
|
||||
|
||||
最短部署流程：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/DeanZFC/sub2api-overdraft.git
|
||||
cd sub2api-overdraft/deploy
|
||||
cp .env.example .env
|
||||
chmod 600 .env
|
||||
# 编辑 .env，至少设置 POSTGRES_PASSWORD、JWT_SECRET 和 TOTP_ENCRYPTION_KEY
|
||||
mkdir -p data postgres_data redis_data
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build
|
||||
```
|
||||
|
||||
源码中的 `deploy/config.example.yaml` 只是模板。运行配置通常位于 `deploy/data/config.yaml`。透支开关为：
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
codex_quota_overdraft_enabled: true
|
||||
```
|
||||
|
||||
公开的 `docker-compose.overdraft.yml` 已通过环境变量默认开启该功能。
|
||||
|
||||
## 如何确认透支成功
|
||||
|
||||
账号额度达到 100% 后检查日志：
|
||||
|
||||
```bash
|
||||
docker logs --since 30m sub2api 2>&1 | \
|
||||
grep -E 'codex_quota_overdraft_(probe|state|pause)'
|
||||
```
|
||||
|
||||
出现 `codex_quota_overdraft_probe_passed`，页面显示“透支中”，并且后续真实业务请求成功，即可确认透支功能完整生效。额度未达到 100% 时没有探测日志是正常现象。
|
||||
|
||||
## 来源、许可证与风险
|
||||
|
||||
- 上游项目：[Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api)
|
||||
- 透支逻辑参考：[Mxucc/cpa-account-config-manager](https://github.com/Mxucc/cpa-account-config-manager)
|
||||
- 许可证：[GNU LGPL-3.0](LICENSE)，保留上游版权和许可证声明。
|
||||
- 本功能不保证上游一定允许超额调用，探测和后续请求可能产生真实用量，也可能触发账号限制。请自行核对上游服务条款并承担使用风险。
|
||||
|
||||
下面的功能、部署和赞助信息继承自上游 Sub2API 文档。上游赞助关系不代表这些组织赞助或认可本 Fork；需要透支功能时，请以上方本 Fork 部署指南为准。
|
||||
|
||||
## ⚠️ 重要提醒
|
||||
|
||||
|
||||
+29
-5
@@ -1,8 +1,8 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="assets/logo.svg" alt="Sub2API Logo" width="128" />
|
||||
<img src="assets/logo.svg" alt="sub2api-overdraft Logo" width="128" />
|
||||
|
||||
# Sub2API
|
||||
# sub2api-overdraft
|
||||
|
||||
[](https://golang.org/)
|
||||
[](https://vuejs.org/)
|
||||
@@ -10,14 +10,38 @@
|
||||
[](https://redis.io/)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
<a href="https://trendshift.io/repositories/21823" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21823" alt="Wei-Shaw%2Fsub2api | Trendshift" width="250" height="55"/></a>
|
||||
|
||||
**サブスクリプションクォータ配分のための AI API ゲートウェイプラットフォーム**
|
||||
**Codex 5h / 7d クォータのオーバードラフト検証・集計・回復機能を追加した AI API ゲートウェイ**
|
||||
|
||||
[English](README.md) | [中文](README_CN.md) | 日本語
|
||||
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> これは [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api) の非公式 Fork であり、Sub2API の公式リリースではありません。公式インストールスクリプトと `weishaw/sub2api:latest` イメージには、本 Fork のオーバードラフト機能は含まれていません。
|
||||
|
||||
## Fork の追加機能
|
||||
|
||||
- Codex の 5h または 7d クォータが 100% に達した後、最大 5 回の実リクエストで利用可否を検証します。
|
||||
- 検証成功後もアカウントをスケジュール対象に保ち、リクエスト数、Token、コスト、回復時刻を表示します。
|
||||
- `pending`、`passed`、`failed`、`inconclusive`、`recovered` の状態を管理画面と PostgreSQL に保存します。
|
||||
- PostgreSQL の atomic claim により複数インスタンスで重複検証を防ぎ、追加の schema migration は不要です。
|
||||
|
||||
ソースビルド、既存環境からの移行、検証、更新、ロールバック、Nginx、トラブルシューティングについては、**[中国語のデプロイ・運用ガイド](CODEX_OVERDRAFT_DEPLOYMENT_CN.md)** を参照してください。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/DeanZFC/sub2api-overdraft.git
|
||||
cd sub2api-overdraft/deploy
|
||||
cp .env.example .env
|
||||
# .env に POSTGRES_PASSWORD、JWT_SECRET、TOTP_ENCRYPTION_KEY を設定
|
||||
mkdir -p data postgres_data redis_data
|
||||
docker compose \
|
||||
-f docker-compose.local.yml \
|
||||
-f docker-compose.overdraft.yml \
|
||||
up -d --build
|
||||
```
|
||||
|
||||
本 Fork は [GNU LGPL-3.0](LICENSE) を継承し、上流の著作権表示を保持します。以下の機能、デプロイ、スポンサー情報は上流 Sub2API の文書を継承したものであり、上流のスポンサーが本 Fork を支援または承認していることを意味しません。
|
||||
|
||||
## ⚠️ 重要なお知らせ
|
||||
|
||||
本プロジェクトをご利用になる前に、以下の内容を必ずよくお読みください：
|
||||
|
||||
@@ -280,6 +280,9 @@ RATE_LIMIT_OVERLOAD_COOLDOWN_MINUTES=10
|
||||
#
|
||||
# 默认：false
|
||||
GATEWAY_FORCE_CODEX_CLI=false
|
||||
# sub2api-overdraft: Codex 5h/7d 额度达到 100% 后启用真实探测和透支调度。
|
||||
# 设为 false 可立即恢复上游 Sub2API 的调度和请求行为。
|
||||
GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED=true
|
||||
# OpenAI /responses/compact 上游模型（默认 gpt-5.4）。
|
||||
# 当 compact 端点暂未支持更新模型时，可通过这里降级规避失败。
|
||||
GATEWAY_OPENAI_COMPACT_MODEL=gpt-5.4
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
# Copy this file to /etc/sub2api/config.yaml and modify as needed
|
||||
# 复制此文件到 /etc/sub2api/config.yaml 并根据需要修改
|
||||
#
|
||||
# Documentation / 文档: https://github.com/Wei-Shaw/sub2api
|
||||
# Documentation / 文档: https://github.com/DeanZFC/sub2api-overdraft
|
||||
|
||||
# =============================================================================
|
||||
# Server Configuration
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# sub2api-overdraft source-build overlay.
|
||||
# Use together with docker-compose.local.yml from this directory:
|
||||
# docker compose -f docker-compose.local.yml -f docker-compose.overdraft.yml up -d --build
|
||||
|
||||
services:
|
||||
sub2api:
|
||||
image: sub2api-overdraft:local
|
||||
build:
|
||||
context: ..
|
||||
dockerfile: Dockerfile
|
||||
args:
|
||||
VERSION: ${BUILD_VERSION:-codex-overdraft}
|
||||
COMMIT: ${BUILD_COMMIT:-local}
|
||||
environment:
|
||||
- GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED=${GATEWAY_CODEX_QUOTA_OVERDRAFT_ENABLED:-true}
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
<meta charset="UTF-8" />
|
||||
<link rel="icon" type="image/svg+xml" href="/logo.svg" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Sub2API - AI API Gateway</title>
|
||||
<title>sub2api-overdraft - AI API Gateway</title>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
|
||||
Reference in new issue
Block a user