深入auto_reg核心架构:FastAPI+React+APScheduler的任务调度与插件注册表设计
深入auto_reg核心架构:FastAPI+React+APScheduler的任务调度与插件注册表设计
auto_reg 是一个多平台账号自动注册与管理系统,其核心架构由 FastAPI 后端、React 前端和插件注册表三大支柱构成。理解 auto_reg 的任务调度机制与插件注册表设计,是掌握这套自动化注册系统、甚至扩展新平台的关键。
🗺️ 一图看懂:auto_reg 的分层结构
先建立全局认知。auto_reg 采用清晰的分层架构:
React 前端 (frontend/) ← 仪表盘、注册任务、定时任务、全局配置
│ HTTP /api/*
FastAPI 后端 (api/ + main.py) ← 路由、认证中间件、任务执行入口
│
核心层 (core/) ← 数据库、插件注册表、调度器、执行器、任务运行时
│
平台插件 (platforms/) ← ChatGPT / Cursor / Grok / Kiro ... 每个目录一个插件
前端由 Vite + React + Ant Design 构建,后端以 main.py 为入口启动 FastAPI 服务,核心逻辑集中在 core/ 目录,平台能力则以插件形式平铺在 platforms/ 目录下。
⚙️ 后端骨架:lifespan 生命周期如何把一切串起来
打开 main.py,重点看 lifespan 上下文管理器——它定义了服务启动与关闭时的完整初始化顺序:
@asynccontextmanager
async def lifespan(app: FastAPI):
init_db() # 1. 初始化 SQLite 数据库
load_all() # 2. 扫描并加载 platforms/ 下所有平台插件
scheduler.start() # 3. 启动任务调度器
start_async() # 4. 启动本地 Turnstile 验证码 Solver
yield
# 关闭时反向停止调度器与 Solver
这个顺序很讲究:先建库、再加载插件、最后启动调度,确保调度器启动时注册表已经就绪。此外,main.py 还挂载了账号、任务、平台、代理、配置等 9 个 API 路由,并通过一个轻量 Bearer Token 中间件为 /api/* 接口做登录鉴权。
💡 依赖声明见 requirements.txt:
fastapi、uvicorn、sqlmodel、playwright、curl_cffi等构成了整套技术栈。
🔌 插件注册表:一个装饰器 + 一次目录扫描
这是 auto_reg 最值得学习的部分。整个注册表只有不到 40 行代码,位于 core/registry.py:
_registry: Dict[str, Type[BasePlatform]] = {}
def register(cls): # 装饰器:按 cls.name 登记
_registry[cls.name] = cls
return cls
def load_all(): # 自动扫描 platforms/ 目录
for finder, name, _ in pkgutil.iter_modules(platforms.__path__, ...):
importlib.import_module(f"{name}.plugin")
工作机制分三步:
- 装饰器登记:每个平台插件用
@register标记自己的类,例如 platforms/cursor/plugin.py 中的CursorPlatform; - 自动扫描:
load_all()通过pkgutil.iter_modules遍历platforms/下所有子包,逐个导入其plugin.py——导入过程本身就会触发装饰器执行; - 按名取用:任务执行时通过
get("cursor")拿到对应插件类,未注册的平台会抛出带提示的KeyError。
新增一个平台只需要三步:在 platforms/ 下建目录、继承 BasePlatform、加上 @register 装饰器。后端 API 和前端菜单都会自动感知,零改动接入——这就是插件注册表带来的解耦红利。
🧩 统一平台接口:BasePlatform 与双执行器
所有平台都继承自 core/base_platform.py 的 BasePlatform 抽象基类,它约定了统一契约:
| 成员 | 说明 |
|---|---|
name / display_name / version |
插件身份标识,注册表依赖 name |
register(email, password) |
抽象方法,执行完整注册流程,返回 Account |
check_valid(account) |
抽象方法,检测账号有效性 |
get_platform_actions() |
可选,声明平台特有操作(如"切换桌面应用") |
supported_executors |
声明支持的执行器类型,默认支持全部三种 |
执行层面,core/base_platform.py 提供 _make_executor() 工厂方法,按 executor_type 创建两种执行器:
- protocol(协议执行器):基于
curl_cffi模拟 Chrome TLS 指纹直接发请求,速度快、资源消耗低,见 core/executors/protocol.py; - headless / headed(浏览器执行器):基于 Playwright 驱动真实浏览器,适合需要 JS 渲染或验证码交互的场景,见 core/executors/playwright.py。
邮箱验证码、验证码打码(YesCaptcha / 本地 Solver)等能力也通过 BaseMailbox、BaseCaptcha 工厂方法统一注入,平台插件因此保持极薄。
⏱️ 任务调度:从定时任务到协作式中断
调度器:每分钟一次的轮询循环
调度器实现位于 core/scheduler.py,是一个常驻后台线程:
def _loop(self):
time.sleep(5) # 启动缓冲,等待任务加载
while self._running:
self.check_trial_expiry() # 检查 trial 账号是否到期
self.check_and_run_scheduled_tasks() # 检查到期的定时注册任务
time.sleep(60)
定时任务并非只存在内存中——core/db.py 定义了 ScheduledTaskModel 表,任务配置(平台、数量、间隔类型 minutes/hours、间隔值)持久化在 SQLite 中,服务重启后由 _load_tasks_from_db() 重新加载,保证定时注册不丢失。
执行链路:一次定时任务是如何跑起来的
- 调度线程发现任务到期,生成带时间戳的
run_task_id,启动新线程执行; - 调用 api/tasks.py 的
_run_register():从注册表get(platform)取出插件类,创建邮箱实例,从代理池取 IP; - 按
count逐个(或并发最多 10 个)执行platform.register(),受控于随机延迟; - 注册成功后写入数据库,并可自动同步到 CPA / Sub2API 等外部系统。
任务运行时:支持"停止/跳过"的协作式控制
core/task_runtime.py 设计了非常优雅的协作式中断机制:RegisterTaskControl 维护"请求停止"和"跳过当前账号"两种信号,任务执行在关键节点调用 checkpoint()——若收到信号则抛出 StopTaskRequested 或 SkipCurrentAttemptRequested 异常优雅退出。外层 RegisterTaskStore 以线程安全方式记录任务状态、进度和日志,并通过 cleanup() 自动清理超过 250 条的历史任务,防止内存膨胀。
这套设计让用户在 Web 界面点击"停止"或"跳过"时,正在运行的批量注册能迅速、干净地响应。
🖥️ React 前端:API 驱动的动态菜单
前端最巧妙的一处设计在 frontend/src/App.tsx:
useEffect(() => {
fetch('/api/platforms')
.then(r => r.json())
.then(d => setPlatforms(d.filter(p => p.name !== 'tavily')
.map(p => ({ key: p.name, label: p.display_name }))))
}, [])
侧边栏"平台管理"子菜单不是写死的,而是从后端 /api/platforms 接口动态拉取——而该接口的数据正来自插件注册表。也就是说:你在 platforms/ 下新增一个插件,前端菜单自动多出一个平台页面,前后端通过注册表实现零配置联动。
页面组织清晰:Dashboard(仪表盘)、RegisterTaskPage(注册任务)、ScheduledTasks(定时任务)、Proxies(代理管理)、Settings(全局配置)等分别位于 frontend/src/pages/,路由统一在 frontend/src/App.tsx 中声明。
💾 数据与配置持久化
- 数据库:core/db.py 基于 SQLite + SQLModel,核心表包括
accounts(账号,含extra_json存平台自定义字段)、task_logs(任务日志)、proxies(代理池统计)、scheduled_tasks(定时任务); - 配置存储:core/config_store.py 将界面配置持久化到 SQLite,读取时支持自动回退到环境变量与
.env文件,兼顾了"界面可改"和"部署可用环境变量注入"两种场景; - SPA 回退:前端构建产物放在
static/,main.py 挂载静态资源并配置通配路由回退到index.html,保证深链刷新不 404。
📌 小结:三个核心设计点
| 设计点 | 核心文件 | 带来的收益 |
|---|---|---|
| 插件注册表(装饰器 + 自动扫描) | core/registry.py | 新平台零配置接入,前后端自动联动 |
| 统一平台契约(BasePlatform + 双执行器) | core/base_platform.py | 平台插件保持极薄,执行器/邮箱/验证码可插拔 |
| 调度器 + 协作式任务运行时 | core/scheduler.py、core/task_runtime.py | 定时任务持久化,批量注册可中途停止/跳过 |
如果你打算扩展自己的平台插件,建议从 platforms/cursor/plugin.py 这个最简洁的示例入手,对照 core/base_platform.py 的接口约定实现;更完整的部署与使用文档见 README_CN.md。

