OpenAI Pool Orchestrator

项目愿景

自动化 OpenAI 账号注册、Token 管理与多平台账号池维护工具。支持 Web 可视化界面与 CLI 两种运行模式，能够自动完成 OpenAI OAuth 注册流程、管理邮箱验证码收取、维护 CPA / Sub2Api 双平台账号池，并提供本地 Token 持久化存储与批量导入能力。

架构总览

单体 Python 应用，后端基于 FastAPI + Uvicorn，前端为原生 HTML/CSS/JS（嵌入式 SPA）。核心业务分为三大模块：注册引擎、邮箱提供商适配层、账号池维护器。通过 SSE（Server-Sent Events）实现前后端实时日志推送与任务状态同步。

技术栈：Python 3.10+ / FastAPI / Uvicorn / curl-cffi / aiohttp / requests 版本：v2.0.0（pyproject.toml）/ 前端 v5.2.1（index.html）协议：MIT 运行端口：18421

openai_pool_orchestrator/          -- 项目根目录
|-- run.py                         -- 快捷启动脚本（Web 或 CLI 模式）
|-- pyproject.toml                 -- 项目元数据与依赖
|-- requirements.txt               -- pip 依赖锁定
|-- Dockerfile                     -- Docker 构建文件
|-- docker-compose.yml             -- Docker Compose 编排
|-- AGENTS.md                      -- Codex/Agent 使用指南
|-- config/
|   `-- sync_config.example.json   -- 配置模板
|-- openai_pool_orchestrator/      -- 主包
|   |-- __init__.py                -- 包初始化、路径常量
|   |-- __main__.py                -- python -m 入口、Uvicorn 启动
|   |-- server.py                  -- FastAPI 服务、全部 REST API + SSE
|   |-- register.py                -- OpenAI OAuth 注册引擎（核心业务逻辑）
|   |-- pool_maintainer.py         -- CPA / Sub2Api 双平台池维护
|   |-- mail_providers.py          -- 邮箱提供商抽象层（4 种实现）
|   `-- static/
|       |-- index.html             -- Web UI 主页面
|       |-- app.js                 -- 前端交互逻辑
|       `-- style.css              -- iOS Flat Design 样式
`-- data/                          -- 运行时数据（.gitignore 排除）
    |-- sync_config.json           -- 实际运行配置
    |-- state.json                 -- 成功/失败计数持久化
    `-- tokens/                    -- 注册获取的 Token 文件

模块结构图

graph TD
    A["(根) openai_pool_orchestrator"] --> B["openai_pool_orchestrator (主包)"]
    A --> C["config"]
    A --> D["run.py 启动入口"]
    B --> E["server.py<br/>FastAPI 服务"]
    B --> F["register.py<br/>注册引擎"]
    B --> G["pool_maintainer.py<br/>池维护"]
    B --> H["mail_providers.py<br/>邮箱适配层"]
    B --> I["static/<br/>Web 前端"]
    E --> F
    E --> G
    E --> H
    F --> H

    click B "./openai_pool_orchestrator/CLAUDE.md" "查看主包模块文档"

模块索引

模块路径	语言	职责	入口文件	代码行数(估)	测试
`openai_pool_orchestrator/`	Python	核心业务包（注册、服务、池维护、邮箱）	`__init__.py` / `__main__.py`	~5800+	无
`openai_pool_orchestrator/static/`	HTML/CSS/JS	Web 可视化界面	`index.html`	~2500+	无
`config/`	JSON	配置模板	`sync_config.example.json`	55	N/A

运行与开发

安装依赖

pip install -r requirements.txt
pip install -e .           # 可编辑安装，注册 openai-pool 命令

启动方式

# Web 服务模式（推荐）
python run.py
# 访问 http://localhost:18421

# 模块方式启动
python -m openai_pool_orchestrator

# CLI 单次注册
python run.py --cli --proxy http://127.0.0.1:7897 --once

# Docker
docker compose up -d

配置

复制 config/sync_config.example.json 为 data/sync_config.json
在 Web UI 配置中心或直接编辑 JSON 填入敏感信息（代理、平台地址、Token、邮箱提供商配置）
运行时数据持久化到 data/ 目录

Docker 部署

docker compose up -d
# 数据卷映射：/opt/openai-pool/data -> /app/data, /opt/openai-pool/config -> /app/config
# 使用 host 网络模式，端口 18421

语法检查

python -m compileall openai_pool_orchestrator

测试策略

当前状态：项目尚未建立测试套件。

建议：

测试目录：tests/，文件命名 test_*.py
运行：python -m pytest
优先覆盖：注册异常路径、邮箱提供商切换与容错、关键 API 端点行为、池维护逻辑

编码规范

Python 3.10+ 语法，遵循 PEP 8，4 空格缩进
命名：模块/函数/变量 snake_case，类 PascalCase，常量 UPPER_SNAKE_CASE
server.py 路由处理保持简洁，可复用逻辑下沉到独立模块
前端保持原生 JS/CSS，轻量修改
不提交密钥、Token 或 data/ 下运行态文件
Conventional Commits 格式：feat: 增加邮箱超时重试

API 概览

FastAPI 服务提供 40+ REST API 端点，主要分组：

分组	端点前缀	功能
任务控制	`POST /api/start`, `/api/stop`	启停注册任务
代理管理	`/api/proxy`, `/api/check-proxy`, `/api/proxy-pool/*`	代理配置、检测、代理池
配置管理	`/api/sync-config`, `/api/pool/config`, `/api/mail/config`	同步配置、池配置、邮箱配置
Token 管理	`/api/tokens`, `/api/sync-now`, `/api/sync-batch`	本地 Token CRUD、批量导入
CPA 池	`/api/pool/*`	CPA 状态、探测、维护、自动维护
Sub2Api 池	`/api/sub2api/*`	Sub2Api 账号列表、探测、删除、维护、去重
实时日志	`GET /api/logs` (SSE)	结构化 SSE 事件流
上传策略	`POST /api/upload-mode`	串行补平台 / 双平台同传

AI 使用指引

核心业务逻辑集中在 register.py（~1600 行）和 server.py（~3500 行），修改前请仔细理解上下文
server.py 中 TaskState 类管理全局任务状态与多 Worker 运行时快照
邮箱提供商通过 MailProvider 抽象基类 + 工厂模式扩展，新增提供商需实现 create_mailbox() 和 wait_for_otp()
池维护器分 PoolMaintainer（CPA）和 Sub2ApiMaintainer（Sub2Api），各自独立
配置通过内存 + data/sync_config.json 双层持久化，读写有锁保护
前端通过 SSE 接收结构化事件（task_snapshot、runtime_snapshot、stats、log 等）

变更记录 (Changelog)

时间	操作	说明
2026-03-18 09:19:57	初始扫描	首次生成 CLAUDE.md，覆盖全部源文件

6.5 KiB Raw Blame History Unescape Escape