Initial commit: grok-free-register-oss
Open-source Grok free registration CLI, xai_enroller auth pipeline, local auth service, tests and docs.
This commit is contained in:
chaos
370
README.md
Normal file
370
README.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# grok-free-register
|
||||
|
||||
`grok-free-register` 是一个命令行注册工具。程序会启动本机浏览器，完成页面操作、邮箱验证码处理和结果保存。
|
||||
|
||||
运行结果写入 `keys/` 目录。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
git clone <your-fork-or-mirror>/grok-free-register.git
|
||||
cd grok-free-register
|
||||
bash start.sh
|
||||
```
|
||||
|
||||
首次运行会自动创建 `.venv`、安装依赖，并引导生成 `.env`。
|
||||
|
||||
需要完整说明时，按用途查看：
|
||||
|
||||
- [注册教程](docs/guides/registration.md)
|
||||
- [本地认证服务](docs/guides/auth-service.md)
|
||||
- [凭据库存与取用](docs/guides/credential-inventory.md)
|
||||
- [运行状态与排障](docs/guides/runtime-troubleshooting.md)
|
||||
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
bash start.sh # 按当前 .env 前台运行
|
||||
bash start.sh --target 100 # 成功 100 个后停止
|
||||
bash start.sh --max-mem 6G # 自动估算并发时最多使用 6G 内存
|
||||
bash start.sh --reconfig # 重新选择邮箱模式
|
||||
```
|
||||
|
||||
`start.sh` 直接在当前终端显示状态。按 `Ctrl-C` 停止，再次执行同一命令即可重启；不需要额外的会话管理或守护进程依赖。
|
||||
|
||||
代理与 CF 清障是两套配置，不要混：
|
||||
|
||||
```env
|
||||
# 本进程出口（Playwright + httpx 显式挂载；Playwright 不会自己读 env）
|
||||
REGISTER_PROXY=http://127.0.0.1:40080
|
||||
# 或兜底：
|
||||
# HTTP_PROXY=http://127.0.0.1:7890
|
||||
# HTTPS_PROXY=http://127.0.0.1:7890
|
||||
|
||||
# 清障预热：调用外部 FlareSolverr（本仓不跑 FS）
|
||||
CLEARANCE_ENABLED=1
|
||||
FLARESOLVERR_URL=http://127.0.0.1:8191
|
||||
CLEARANCE_URLS=https://accounts.x.ai,https://x.ai,https://status.x.ai,https://console.x.ai,https://auth.x.ai
|
||||
# FS 容器内出口（容器可达名）；走 WARP 时用 docker 网内 privoxy
|
||||
# CLEARANCE_PROXY=http://privoxy:8118
|
||||
```
|
||||
|
||||
## 邮箱模式
|
||||
|
||||
`tempmail` 是默认模式，不需要额外配置，适合快速试跑：
|
||||
|
||||
```env
|
||||
EMAIL_MODE=tempmail
|
||||
```
|
||||
|
||||
`custom` 是自建域名邮箱模式，适合长时间运行。需要一个已接入 Cloudflare Email Routing 的域名，并在运行机器上启动本项目的收信服务。
|
||||
|
||||
配置步骤：
|
||||
|
||||
1. 在 Cloudflare 为域名开启 Email Routing。
|
||||
2. 部署 `cloudflare/email-worker.js`。
|
||||
3. 在 Email Routing 中配置 catch-all，动作选择发送到该 Worker。
|
||||
4. 在运行机器上启动收信服务：
|
||||
|
||||
```bash
|
||||
bash start.sh --email-service
|
||||
```
|
||||
|
||||
5. 在 `.env` 中配置：
|
||||
|
||||
```env
|
||||
EMAIL_MODE=custom
|
||||
EMAIL_DOMAIN=example.com
|
||||
EMAIL_API=http://127.0.0.1:8080
|
||||
```
|
||||
|
||||
如果 Worker 需要回调本机服务，`WEBHOOK_URL` 应使用可访问的域名地址。
|
||||
|
||||
## 配置
|
||||
|
||||
完整模板见 `.env.example`。日常使用通常只需要配置邮箱模式、代理、目标数量和内存预算。
|
||||
|
||||
| 配置 | 默认值 | 说明 |
|
||||
|---|---:|---|
|
||||
| `EMAIL_MODE` | `tempmail` | 邮箱模式，支持 `tempmail` 和 `custom` |
|
||||
| `EMAIL_DOMAIN` | 空 | `custom` 模式使用的域名 |
|
||||
| `EMAIL_API` | `http://127.0.0.1:8080` | 本地收信服务地址 |
|
||||
| `TARGET` | `0` | 成功数量目标，`0` 表示不限 |
|
||||
| `PHYSICAL_CAP` | `0` | 浏览器并发上限，`0` 表示启动时自动估算 |
|
||||
| `PHYSICAL_PER_CPU` | `2` | 自动估算时每个 CPU 核心对应的并发参考值 |
|
||||
| `PHYSICAL_MEM_MB` | `512` | 自动估算时每个浏览器任务的内存预算 |
|
||||
| `MIN_FREE_MEM_MB` | `500` | 自动估算时保留的内存 |
|
||||
| `T_SLOT_CAP` | `8` | token 缓冲容量 |
|
||||
| `Q_SLOT_CAP` | `8` | 验证码缓冲容量 |
|
||||
| `Q_PENDING_CAP` | `12` | 等待验证码返回的请求上限 |
|
||||
| `SOLVER_MOUSE_CLICK_RETRIES` | `3` | token 验证框中心点击次数，`0` 表示关闭 |
|
||||
| `PAGE_BLOCK_STATIC_ASSETS` | `0` | 可选：阻断部分静态资源，降低页面准备成本 |
|
||||
| `C_HOT_PAGE_POOL` | `0` | 可选：复用消费阶段页面，减少页面重建开销 |
|
||||
|
||||
不确定怎么设置时，先保持默认值。性能压测时优先观察 `PHYSICAL_CAP` 和内存，不建议先改 Worker 数量。
|
||||
|
||||
## 运行日志
|
||||
|
||||
直接运行 `bash start.sh` 时，终端只输出任务开始、成功或失败、本次运行平均速度、累计数量和限流等待：
|
||||
|
||||
```text
|
||||
[→] 开始注册 #38
|
||||
[✓] 注册成功 #38 | 运行平均 47/分 | 累计 38
|
||||
[⏸] 触发限流 | 60秒后恢复探测
|
||||
[▶] 限流解除 | 实际等待 61秒
|
||||
```
|
||||
|
||||
需要调试并发、库存和阶段耗时时，使用：
|
||||
|
||||
```bash
|
||||
bash start.sh --debug
|
||||
```
|
||||
|
||||
它会在上述任务事件之外，每 8 秒输出一次完整的 T/Q、物理并发和阶段耗时面板。已有自动化环境也可继续使用 `REGISTER_LOG_MODE=debug`。
|
||||
|
||||
常用字段：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| `T` | 当前可用 token 数量 |
|
||||
| `Q` | 当前可用验证码数量 |
|
||||
| `phys` | 空闲浏览器并发许可 |
|
||||
| `s_phys` / `p_phys` / `c_phys` | S/P/C 获取浏览器许可的平均等待秒数 / 平均持有秒数 |
|
||||
| `p_stage` | P 阶段平均耗时：建邮箱 / 准备页面 / 发送请求 |
|
||||
| `c_stage` | C 阶段平均耗时：拿页面 / 验证码校验 / 注册提交 |
|
||||
| `c_hot` | C 热页池命中 / 未命中次数 |
|
||||
| `t_solve_avg` | 平均 token 获取时间 |
|
||||
| `q_sent` / `q_ret` | 已发送 / 已收到的验证码数量 |
|
||||
| `pair` | 已配对消费次数 |
|
||||
| `ok` / `fail` | 成功 / 失败数量 |
|
||||
| `rate` | 当前累计成功速率 |
|
||||
|
||||
简单判断：
|
||||
|
||||
- `T` 长期为 `0` 且 `Q` 有库存，通常是 token 获取较慢。
|
||||
- `Q` 长期为 `0` 且 `T` 有库存，通常是邮箱或验证码链路较慢。
|
||||
- `phys` 长期为 `0`，说明浏览器并发已经用满。
|
||||
- `t_solve_avg` 明显升高，通常表示浏览器压力、网络质量或 token 服务响应变慢。
|
||||
|
||||
可以用日志分析工具解析已有日志：
|
||||
|
||||
```bash
|
||||
python3 - <<'PY'
|
||||
from pathlib import Path
|
||||
from tools.runtime_log_analyzer import analyze_text
|
||||
print(analyze_text(Path("run.log").read_text()))
|
||||
PY
|
||||
```
|
||||
|
||||
## 输出文件
|
||||
|
||||
成功结果写入：
|
||||
|
||||
```text
|
||||
keys/accounts.txt
|
||||
keys/grok.txt
|
||||
```
|
||||
|
||||
`accounts.txt` 每行格式：
|
||||
|
||||
```text
|
||||
email:password:sso_token
|
||||
```
|
||||
|
||||
`keys/` 目录包含运行结果，默认不会提交到 Git。
|
||||
|
||||
认证成功后的 OAuth 出货默认在：
|
||||
|
||||
```text
|
||||
~/Downloads/grok-free-register-auth/authenticated/
|
||||
```
|
||||
|
||||
可用 `keys/async_auth.sh` 把出货整备成 `keys/cpa_ready/` 并同步探活通过的 `access_token` 到 `keys/acc.md`。
|
||||
|
||||
## 清零流水线（删库跑路）
|
||||
|
||||
只删 `keys/acc.md` / `accounts.txt` **不够**：`acpa_watchdog` 会从
|
||||
`~/Downloads/grok-free-register-auth/authenticated/` 把旧号再整备进
|
||||
`keys/cpa_ready/`，`sync_acc` 再写回 `acc.md`。状态文件 `_state.tsv` 也会残留幽灵 alive。
|
||||
|
||||
**全量清零**用项目根的 `reset_pipeline.sh`（默认 dry-run，必须加 `--yes` 才真删）：
|
||||
|
||||
```bash
|
||||
# 建议先停 register / auth-service / async_auth
|
||||
bash reset_pipeline.sh # dry-run，只列将删内容
|
||||
bash reset_pipeline.sh --yes # 真删：注册源 + 认证出货 + cpa_ready + state
|
||||
bash reset_pipeline.sh --yes --keep-register
|
||||
# 只清认证/CPA，保留 keys 里新注册的 SSO 源
|
||||
bash reset_pipeline.sh --yes --keep-cpa
|
||||
# 只清认证账本/源快照，保留 cpa_ready（少用）
|
||||
bash reset_pipeline.sh --yes --wipe-salt
|
||||
# 连 enrollment ledger salt 一并清（极少需要）
|
||||
```
|
||||
|
||||
会清掉的大致范围：
|
||||
|
||||
| 范围 | 路径 |
|
||||
|------|------|
|
||||
| 注册源 | `keys/accounts.txt`、`keys/grok.txt`、`keys/auth-sessions.jsonl`、`keys/acc.md` |
|
||||
| CPA | `keys/cpa_ready/xai-*.json`、`_state.tsv`、`_discarded/` |
|
||||
| 认证出货 | `$XAI_AUTH_SERVICE_LOCAL_DIR`（默认 `~/Downloads/grok-free-register-auth`）下的 `authenticated/`、`claimed/`、`enrollment-ledger.db*`、`source-snapshot.jsonl` |
|
||||
|
||||
认证目录可用环境变量覆盖：
|
||||
|
||||
```bash
|
||||
export XAI_AUTH_SERVICE_LOCAL_DIR=~/Downloads/grok-free-register-auth
|
||||
# 或
|
||||
export XAI_ENROLLER_LOCAL_AUTH_DIR=~/Downloads/grok-free-register-auth
|
||||
```
|
||||
|
||||
**只清历史归档、不动现网号池**用 `scripts/clean_history.sh`：
|
||||
|
||||
```bash
|
||||
bash scripts/clean_history.sh # dry-run
|
||||
bash scripts/clean_history.sh --yes # 清 zip / _discarded / logs / 杂包
|
||||
bash scripts/clean_history.sh --yes --deep # 再清 source-snapshot 等更深一层
|
||||
```
|
||||
|
||||
清完后重开：
|
||||
|
||||
```bash
|
||||
bash start.sh # 或远端注册机继续跑
|
||||
bash auth-service.sh # device-flow → authenticated/
|
||||
bash keys/async_auth.sh # acpa_watchdog + sync_acc
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
grok_register/ 注册核心与 custom 邮箱服务
|
||||
xai_enroller/ OAuth 认证服务
|
||||
keys/ acpa_watchdog / sync_acc / async_auth（运行时产物 gitignore）
|
||||
cloudflare/email-worker.js Cloudflare Email Routing Worker 示例
|
||||
start.sh 首次配置和运行
|
||||
auth-service.sh 认证服务入口
|
||||
reset_pipeline.sh 全量清零注册→认证→CPA 运行时数据
|
||||
scripts/clean_history.sh 只清历史归档，不动现网号池
|
||||
scripts/push_keys_to_auth.sh 本机 SSO 源推远端 auth（需显式 AUTH_SSH_*）
|
||||
setup.sh 安装依赖
|
||||
.env.example 配置模板
|
||||
tools/ 日志分析 + GrokSession→CPA/sub2api 前端转换
|
||||
tests/ 自动化测试
|
||||
docs/architecture.md 并发架构说明
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
测试依赖与运行依赖分开安装：
|
||||
|
||||
```bash
|
||||
.venv/bin/pip install -r tests/requirements.txt
|
||||
```
|
||||
|
||||
快速检查：
|
||||
|
||||
```bash
|
||||
python3 -m unittest tests.test_admission_gate tests.test_register_runtime_unittest tests.test_inventory_unittest tests.test_runtime_log_analyzer -v
|
||||
```
|
||||
|
||||
完整测试：
|
||||
|
||||
```bash
|
||||
python3 -m pytest tests -q
|
||||
```
|
||||
|
||||
## xAI OAuth Enroller
|
||||
|
||||
`xai_enroller/` 用于把已有 xAI 账号的 SSO 会话转换为 OAuth 凭据，并导入 CPA
|
||||
凭据库。它独立于注册流程运行：注册机不需要启动，已有账号也不需要重新注册。
|
||||
|
||||
### 默认同机模式
|
||||
|
||||
注册和认证在同一个项目目录运行时，无需配置来源：
|
||||
|
||||
```bash
|
||||
bash auth-service.sh
|
||||
```
|
||||
|
||||
认证服务默认读取本项目的 `keys/auth-sessions.jsonl` 和历史
|
||||
`keys/accounts.txt`，每 30 秒生成一次经过校验的原子快照。注册仍可同时运行；认证服务
|
||||
只读取完整记录，不会读取正在追加的半行。
|
||||
|
||||
### 分离设备的 SSH 模式
|
||||
|
||||
注册机和认证服务分开运行时，服务器继续写入注册结果，本地认证服务
|
||||
每 30 秒通过一次性 SSH 导出全量 JSONL 快照。快照经逐行校验、`fsync` 后原子替换到
|
||||
`~/Downloads/grok-free-register-auth/source-snapshot.jsonl`；同步失败会继续使用上一份有效快照。
|
||||
认证使用本机 CloakBrowser Chromium，
|
||||
成功结果写入 `~/Downloads/grok-free-register-auth/authenticated/`，运行状态、同步快照与
|
||||
认证文件分开保存；认证文件格式可以直接供 CPA 使用。
|
||||
|
||||
先把导出器同步到注册机的 `scripts/` 目录：
|
||||
|
||||
```bash
|
||||
scp scripts/export_registered_sessions.py user@your-server:/opt/grok-free-register/scripts/
|
||||
```
|
||||
|
||||
然后在本地配置 SSH 连接：
|
||||
|
||||
下面这些变量既可在终端 `export`，也可写入由 `.env.example` 复制出的 `.env`；
|
||||
`auth-service.sh` 会自动读取该文件。
|
||||
|
||||
```bash
|
||||
export XAI_AUTH_SERVICE_SSH_HOST=user@your-server
|
||||
export XAI_AUTH_SERVICE_SSH_IDENTITY=/path/to/ssh-key.pem # 使用 ssh-agent 时可省略
|
||||
export XAI_AUTH_SERVICE_REMOTE_ROOT=/opt/grok-free-register
|
||||
export XAI_AUTH_SERVICE_SYNC_SEC=30
|
||||
```
|
||||
|
||||
存在 `XAI_AUTH_SERVICE_SSH_HOST` 时会自动选择 SSH。也可显式设置
|
||||
`XAI_AUTH_SERVICE_SOURCE=local|ssh`；默认值 `auto` 优先兼容已有 SSH 配置，否则使用同机来源。
|
||||
|
||||
启动认证服务：
|
||||
|
||||
```bash
|
||||
bash auth-service.sh
|
||||
```
|
||||
|
||||
需要查看队列、重试、节拍和冷却探针时使用：
|
||||
|
||||
```bash
|
||||
bash auth-service.sh --debug
|
||||
```
|
||||
|
||||
默认每次认证至少间隔 10 秒；实测该值比无间隔运行有更高的长期平均成功速率。限流后
|
||||
每 60 秒只进行一次恢复探测。需要覆盖时使用：
|
||||
|
||||
```bash
|
||||
export XAI_AUTH_SERVICE_MIN_INTERVAL_SEC=10
|
||||
export XAI_AUTH_SERVICE_RETRY_SEC=60
|
||||
```
|
||||
|
||||
终端只在账号开始、认证结果、限流状态或控制状态变化时输出，并在底部保持 `认证> ` 输入行。`s` 查看状态，`p` 暂停，
|
||||
`r` 恢复，`c` 取消当前账号，`q` 退出；`Ctrl-C` 同样会退出。在输入行键入 `take 100`
|
||||
会把最新的 100 个可用凭证登记为已取用，并移动到独立批次目录。认证记录仍保留为
|
||||
`imported`，不会因为凭证被取出而重新认证。
|
||||
|
||||
可用凭证保存在：
|
||||
|
||||
```text
|
||||
~/Downloads/grok-free-register-auth/authenticated/
|
||||
```
|
||||
|
||||
已取用批次保存在：
|
||||
|
||||
```text
|
||||
~/Downloads/grok-free-register-auth/claimed/<batch-id>/
|
||||
```
|
||||
|
||||
库存状态保存在 `enrollment-ledger.db` 的 `credential_inventory` 表中，状态为
|
||||
`available`、`claiming` 或 `claimed`。每条记录预留 `note` 字段，默认留空。
|
||||
|
||||
`auth-service.sh` 首次运行会自动安装项目依赖。正式用户流程只需要这个 Bash 入口；底层 Python 模块保留给开发和测试，不作为另一套使用方式。
|
||||
|
||||
## 开发文档
|
||||
|
||||
[docs/architecture.md](docs/architecture.md) 记录并发模型、资源生命周期和必须保持的不变量。
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user