oai-reg

鸣谢

本项目参考了 cnlimiter/codex-register，灵感来自 LINUX.do 社区，特此致谢。

免责声明

本工具仅供学习和研究使用，使用本工具产生的一切后果由使用者自行承担。 请遵守相关服务的使用条款，不要用于任何违法或不当用途。 如有侵权，请及时联系，会及时删除。

本地优先的 OpenAI 注册任务与账号运维平台，提供 Web 控制台、任务调度、token 产物管理，以及与 sub2api 的对接能力。

这是什么

oai-reg 是一个偏内部工具风格的项目，目标是把以下能力集中到一个本地可运行的控制台里：

• 注册任务发起与状态跟踪
• token 产物落盘与查看
• Web 控制台管理任务、事件、运行状态
• 与 sub2api 对接，完成批量上传、分组和基础维护
• 对账号池做巡检、坏号识别与批量禁用

它更像一个“任务与运维控制台”，而不是通用 SaaS 产品。

功能概览

• 任务调度：创建、取消、重试、删除注册任务
• Web 控制台：查看任务、事件流、token 产物、运行状态
• sub2api 集成：批量上传 token、按组管理、基础维护操作
• 维护中心：巡检账号池、识别明显坏号、批量禁用
• 本地优先：默认使用本地目录保存数据与运行产物

技术栈

• Python
• FastAPI
• Uvicorn
• SQLite / 本地文件数据目录
• 原生 HTML + JS 控制台

快速开始

1. 安装依赖

pip install -r requirements.txt
npm install   # 可选，仅用于前端 dev server / nodemon

2. 配置环境变量

cp .env.example .env

按需修改：

• PORT
• OPENAI_REG_DATA_DIR
• OPENAI_REG_MAX_WORKERS
• SUB2API_BASE_URL
• SUB2API_EMAIL
• SUB2API_PASSWORD

3. 启动

python server.py

默认访问：

• http://127.0.0.1:8787

sub2api 集成

oai-reg 可以把本地生成的 token 产物接到 sub2api，并围绕分组与账号池做基础运维。

前置条件

你需要准备：

• 一个可访问的 sub2api 实例
• sub2api 管理员邮箱和密码
• 正确的 base URL，例如：
  • http://127.0.0.1:8080
  • http://your-host:8080

注意：

• 不要把 SUB2API_BASE_URL 写成带 /api/v1 的路径
• 项目内部会自动拼接登录和管理接口路径

配置方式

可以通过 .env 配置默认值：

SUB2API_BASE_URL=http://127.0.0.1:8080
SUB2API_EMAIL=admin@example.com
SUB2API_PASSWORD=your-password

也可以直接在 Web 控制台里填写，只在当前会话中使用。

集成能力

当前已接入这些 sub2api 相关能力：

1. 连接测试

   • 通过 /api/sub2api-test 测试地址和管理员凭据是否可用

2. 批量上传 token

   • 通过 /api/upload-batch 把本地 token_*.json / data/tokens/ 下的产物导入 sub2api
   • 成功上传后可移动到 uploaded/ 目录归档

3. 批量分组

   • 通过 /api/sub2api-bulk-group 把账号批量绑定到指定分组
   • 支持按 group_id 或 group_name 操作，例如 codex

4. 批量编辑账号

   • 通过 /api/sub2api-bulk-edit 调整代理、状态、分组等信息

5. 读取分组列表

   • 通过 /api/sub2api/groups 获取当前 sub2api 分组

6. 账号池巡检

   • 通过 /api/sub2api-maintenance/scan 对指定分组做巡检
   • 输出总账号数、可调度数、坏号数、错误原因分布等统计

7. 批量切换 schedulable

   • 通过 /api/sub2api-maintenance/bulk-schedulable 批量启用/禁用账号调度资格

典型接入流程

方案 A：通过 Web 控制台

1. 启动 oai-reg
2. 打开控制台
3. 填写 sub2api 地址、管理员邮箱、密码
4. 先执行连接测试
5. 注册任务跑出 token 后，执行批量上传
6. 按需把上传后的账号批量绑定到目标分组
7. 定期在维护中心巡检坏号并批量摘除

方案 B：通过脚本

项目内置了几个直接可用的脚本：

1. 上传 token 到 sub2api

python sub2api_upload.py --all \
  --base-url http://127.0.0.1:8080 \
  --email admin@example.com \
  --password 'your-password'

也可以只上传指定文件：

python sub2api_upload.py token_xxx.json token_yyy.json \
  --base-url http://127.0.0.1:8080 \
  --email admin@example.com \
  --password 'your-password'

2. 批量绑定分组

python sub2api_bulk_group.py \
  --group-name codex \
  --base-url http://127.0.0.1:8080 \
  --email admin@example.com \
  --password 'your-password'

也支持指定 group-id。

3. 巡检与坏号维护

sub2api_maintenance.py 提供了账号池巡检与坏号识别逻辑，重点关注：

• refresh_token_reused
• invalid_grant
• invalid_token
• 401 / 403
• 明确处于 banned / disabled / error 的账号

项目里的维护策略倾向于：

• 明确坏号 → 设为 schedulable=false
• 可疑号 → 先暂停调度，再人工复核
• 正常号 → 保留在调度池中

当前对接的 sub2api 接口

项目目前使用到的典型 sub2api 管理接口包括：

• POST /api/v1/auth/login
• GET /api/v1/admin/groups
• GET /api/v1/admin/proxies
• GET /api/v1/admin/accounts
• POST /api/v1/admin/accounts/data
• POST /api/v1/admin/accounts/bulk-update
• POST /api/v1/admin/accounts/:id/schedulable

常见问题

1. 登录 / 上传报 404

通常是因为 SUB2API_BASE_URL 写错了。

正确写法：

• http://host:port

错误示例：

• http://host:port/api/v1

2. 能登录但上传失败

先检查 token 文件是否是 sub2api 可识别的数据格式。项目内部会校验：

• type
• accounts
• proxies

3. 分组后效果不对

优先检查：

• group_id / group_name 是否正确
• sub2api 里目标分组是否存在
• 账号是否已经被禁用或不在可调度池中

目录结构

.
├── openai_reg.py              # 注册主流程与 token 产物处理
├── server.py                  # FastAPI 服务入口
├── sub2api_client.py          # sub2api 登录/基础客户端
├── sub2api_upload.py          # token 上传能力
├── sub2api_bulk_group.py      # 分组相关操作
├── sub2api_maintenance.py     # 账号池巡检 / 坏号处理
├── src/
│   ├── db.py
│   ├── event_bus.py
│   ├── http_requests.py
│   ├── logging_utils.py
│   ├── schemas.py
│   ├── settings.py
│   ├── email/
│   └── services/
├── web/                       # 原生前端页面
└── frontend/                  # 开发期前端辅助文件

配置说明

常用环境变量：

变量	默认值	说明
PORT	8787	Web/API 端口
OPENAI_REG_DATA_DIR	./data	数据目录
OPENAI_REG_MAX_WORKERS	5	并发 worker 数
SUB2API_BASE_URL	http://127.0.0.1:8080	sub2api 地址
SUB2API_EMAIL	空	sub2api 管理员邮箱
SUB2API_PASSWORD	空	sub2api 管理员密码

安全提示

本项目会处理敏感运行数据，例如：

• token 产物
• 管理员凭据
• 代理配置
• 账号池状态

请务必注意：

• 不要把 .env、data/、token 文件提交到仓库
• 在受控网络环境中部署
• 对外暴露前先加访问控制与最小权限配置
• 使用前自行评估合规性、上游服务条款与风险边界

许可证

MIT