深入auto_reg核心架构:FastAPI+React+APScheduler的任务调度与插件注册表设计

原创2026-10-15 14:56:571,405 阅读

深入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/ 目录下。

auto_reg仪表盘:多平台账号总览与状态分布

⚙️ 后端骨架: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")

工作机制分三步:

  1. 装饰器登记:每个平台插件用 @register 标记自己的类,例如 platforms/cursor/plugin.py 中的 CursorPlatform;
  2. 自动扫描:load_all() 通过 pkgutil.iter_modules 遍历 platforms/ 下所有子包,逐个导入其 plugin.py——导入过程本身就会触发装饰器执行;
  3. 按名取用:任务执行时通过 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() 重新加载,保证定时注册不丢失。

执行链路:一次定时任务是如何跑起来的

  1. 调度线程发现任务到期,生成带时间戳的 run_task_id,启动新线程执行;
  2. 调用 api/tasks.py 的 _run_register():从注册表 get(platform) 取出插件类,创建邮箱实例,从代理池取 IP;
  3. 按 count 逐个(或并发最多 10 个)执行 platform.register(),受控于随机延迟;
  4. 注册成功后写入数据库,并可自动同步到 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 中声明。

auto_reg全局配置页面:外部集成与批量操作管理

💾 数据与配置持久化

  • 数据库: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。

登录后查看全文
auto_reg