Codex Register 架构解析与使用指南

项目简介

Codex Register 是一个用于 Microsoft 账户批量注册与管理的命令行工具，主要功能：

• 批量注册：自动化注册流程，支持代理池
• 双重远程：同时管理两个远程 Git 仓库
• 邮件服务：支持自建邮件服务或第三方邮件 API
• CPA 重试：注册失败时自动重试
• 账户信息管理：统一管理账户凭据、令牌、注册时间

技术栈

• 语言：Python 3.11+
• 异步：asyncio + httpx
• 配置：YAML
• CLI：Typer + Rich
• 存储：SQLite（轻量）/ PostgreSQL（生产）
• 部署：Docker / systemd

架构图

┌─────────────────────────────────────────────────┐
│                    CLI (Typer)                  │
├─────────────────────────────────────────────────┤
│         Account Manager Service                 │
├────────────┬────────────┬───────────┬───────────┤
│  Microsoft │  Email     │   Proxy   │  Storage  │
│  Graph API │  Service   │   Pool    │  (SQLite) │
├────────────┼────────────┼───────────┴───────────┤
│       HTTP Client (httpx + retry)              │
└─────────────────────────────────────────────────┘

核心模块

1. Account Service

负责 Microsoft 账户的 OAuth 流程、令牌管理、自动刷新。

async def acquire_token(client_id: str, scope: str, proxy: Proxy | None = None) -> Token:
    flow = OAuthFlow(client_id, scope)
    return await flow.acquire(proxy=proxy)

2. Email Service

抽象的邮件接收接口，支持：

• 自建 IMAP 邮件服务器
• 第三方邮件 API（如 Outlook、Hotmail 自带的 outlook.office.com）

class EmailService(Protocol):
    async def fetch_verification_code(self, account: str, timeout: int = 60) -> str: ...

3. Proxy Pool

代理池管理，支持：

• 文件加载（proxies.txt）
• HTTP API（自定义代理源）
• 健康检查（自动剔除失效代理）

class ProxyPool:
    async def acquire(self) -> Proxy:
        # 从池中取一个健康的代理
        ...

    async def report_failure(self, proxy: Proxy):
        # 上报失败的代理，降低权重
        ...

4. CPA Retry

CPA（Continuation Pattern Acquisition）是一种注册流程状态机模式。当注册过程中某一步失败时，可以从该步骤继续，而不是从头开始：

async def register_with_retry(account: Account) -> Account:
    state = await load_state(account) or State.STEP_0
    for step in steps[state:]:
        try:
            await step(account)
            state = step.next
            await save_state(account, state)
        except RetryableError as e:
            # 退避重试
            await backoff(e)
            continue
    return account

部署

本地

git clone https://github.com/wyclab/codex-register
cd codex-register
poetry install
poetry run codex-register --help

Docker

docker run -it --rm \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/app/data \
  ghcr.io/wyclab/codex-register:latest \
  register --config /app/config/config.yaml

后续规划

• Web UI（基于 FastAPI + Vue 3）
• 分布式部署（多机协同注册）
• 更多账户类型支持（GitHub、Twitter 等）

参考

• GitHub: https://github.com/wyclab/codex-register
• 文档：https://codex-register.wyclab.com