164 lines
6.5 KiB
Markdown
164 lines
6.5 KiB
Markdown
# 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 文件
|
||
```
|
||
|
||
## 模块结构图
|
||
|
||
```mermaid
|
||
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 |
|
||
|
||
## 运行与开发
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
pip install -e . # 可编辑安装，注册 openai-pool 命令
|
||
```
|
||
|
||
### 启动方式
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 配置
|
||
|
||
1. 复制 `config/sync_config.example.json` 为 `data/sync_config.json`
|
||
2. 在 Web UI 配置中心或直接编辑 JSON 填入敏感信息（代理、平台地址、Token、邮箱提供商配置）
|
||
3. 运行时数据持久化到 `data/` 目录
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
docker compose up -d
|
||
# 数据卷映射：/opt/openai-pool/data -> /app/data, /opt/openai-pool/config -> /app/config
|
||
# 使用 host 网络模式，端口 18421
|
||
```
|
||
|
||
### 语法检查
|
||
|
||
```bash
|
||
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，覆盖全部源文件 |
|