278 lines
19 KiB
Markdown
278 lines
19 KiB
Markdown
# Cursor Auto Register 项目总览
|
||
|
||
**项目简介**: 本项目是一个开源的自动化 Cursor Pro 账户注册和管理工具，旨在为学习和技术交流提供参考。
|
||
|
||
**主要目的**: 本项目旨在简化 Cursor Pro 账户的获取流程，并提供 API 接口供二次开发或集成。
|
||
|
||
**参考项目**:
|
||
* [chengazhen/cursor-auto-free](https://github.com/chengazhen/cursor-auto-free)
|
||
* [cursor-account-api](https://github.com/Elawen-Carl/cursor-account-api)
|
||
|
||
**免责声明**: 本项目仅供学习和测试使用，使用风险自负。建议参考项目根目录下的 `README.md` 文件获取更详细的免责声明和许可信息。
|
||
|
||
## 核心功能
|
||
|
||
* 自动化账户注册与激活：能够自动完成 Cursor 账户的注册流程。
|
||
* 提供 RESTful API 进行账户管理：包括创建、查询（支持分页、搜索、排序）、随机获取、状态更新、数据导入/导出等功能。
|
||
* 提供简单的 Web UI：用于查看系统状态、账户列表、配置信息，并进行基本操作。
|
||
* 集成临时邮箱服务：自动化获取注册过程中所需的邮件验证码。
|
||
* 支持配置项管理：允许用户通过 `.env` 文件或 API 修改如最大账户数、API 服务参数、浏览器行为等配置。
|
||
* 账户数据持久化存储：使用 SQLite 数据库 (`accounts.db`) 保存账户信息及使用记录。
|
||
* 详细的日志记录：记录系统运行状态、注册过程、错误信息等，便于追踪和调试。
|
||
* 后台任务管理：支持启动、停止和监控后台的自动注册任务。
|
||
* 系统辅助功能：如重置机器ID、服务重启等。
|
||
|
||
## 技术架构概览
|
||
|
||
* **后端**: 采用 Python 语言和 FastAPI 异步 Web 框架构建，提供高效的 API 服务。
|
||
* **数据库**: 使用 SQLite 进行数据存储，通过 `aiosqlite` 库实现异步数据库操作，确保在高并发场景下的性能。账户信息和相关记录存储在项目根目录的 `accounts.db` 文件中。
|
||
* **前端**: 提供一个基础的 HTML 前端界面 (`index.html`)，结合 `static/` 目录下的静态资源 (CSS, JavaScript)，为用户提供基本的可视化操作和信息展示。
|
||
* **核心依赖与工具**:
|
||
* 编程语言: Python 3.10+
|
||
* Web 框架: FastAPI, Uvicorn (ASGI 服务器)
|
||
* 数据库ORM/Driver: SQLAlchemy (异步模式), aiosqlite
|
||
* 浏览器自动化: 可能通过 Selenium 或 Playwright (封装在 `browser_utils.py` 中) 实现与浏览器的交互。
|
||
* 邮件服务: 依赖外部临时邮箱服务 (如 tempmail.plus) 获取验证码，通常需要用户配置 Cloudflare 邮件路由规则进行转发。
|
||
* 人机验证处理: 包含针对 Cloudflare Turnstile 等验证码的应对逻辑 (体现在 `turnstilePatch/` 目录及相关代码中)。
|
||
* **配置管理**: 通过根目录的 `.env` 文件进行环境变量配置，由 `config.py` 读取和管理。
|
||
* **部署**:
|
||
* 本地运行: 可直接通过 `uvicorn api:app --host <host> --port <port> --reload` 命令启动 (具体命令依据 `README.md` 或启动脚本)。
|
||
* 容器化: 项目提供了 `dockerfile`，支持使用 Docker 进行构建和部署，方便环境隔离和迁移。
|
||
|
||
## 主要模块/组件详解
|
||
|
||
### `api.py` (FastAPI 应用层)
|
||
项目的核心入口和控制中心。基于 FastAPI 构建，定义了所有的 HTTP API 端点，负责：
|
||
* 接收和验证客户端请求。
|
||
* 路由请求到相应的业务逻辑处理函数。
|
||
* 调用其他模块（如 `database.py`, `cursor_pro_keep_alive.py`）完成具体操作。
|
||
* 格式化并返回响应给客户端。
|
||
* 实现诸如账户管理、注册任务控制、系统配置查询与更新、UI服务、API文档（Swagger/ReDoc）等功能。
|
||
* 管理应用的生命周期事件（如启动时初始化数据库）。
|
||
|
||
### `cursor_pro_keep_alive.py` (核心注册逻辑)
|
||
此模块封装了 Cursor 账户自动化注册和激活的核心业务流程。其主要职责包括：
|
||
* 执行完整的账户创建步骤，从访问注册页面到最终激活账户。
|
||
* 周期性地被 `api.py` 中的后台任务调用，以维持设定的账户数量。
|
||
* 协调调用 `get_email_code.py` 来获取邮箱地址和验证码。
|
||
* 利用 `browser_utils.py` 进行浏览器自动化操作（如填写表单、点击链接）。
|
||
* 处理注册过程中可能遇到的 Cloudflare Turnstile 等人机验证（可能调用 `turnstilePatch/` 中的逻辑）。
|
||
* 在注册成功或失败后，更新账户状态并记录相关信息。
|
||
|
||
### `database.py` (数据持久化层)
|
||
负责所有与数据库 (`accounts.db`) 相关的操作。
|
||
* 定义数据模型，如 `AccountModel` (存储账户信息) 和 `AccountUsageRecordModel` (存储账户使用记录)。
|
||
* 提供数据库初始化函数 `init_db()`，在应用启动时创建表结构。
|
||
* 封装了异步的 CRUD (创建、读取、更新、删除) 操作接口，供 `api.py` 等模块调用，以管理账户数据。
|
||
* 使用 SQLAlchemy Core 和 `aiosqlite` 实现与 SQLite 的异步交互。
|
||
|
||
### `get_email_code.py` (邮件处理模块)
|
||
专用于处理邮件相关的任务，特别是自动化获取注册过程中所需的邮件验证码。
|
||
* 与用户配置的临时邮箱服务 (如 tempmail.plus) API 进行交互。
|
||
* 获取可用的临时邮箱地址。
|
||
* 监控邮箱，等待并提取 Cursor 发送的验证码邮件内容。
|
||
|
||
### `config.py` 与 `.env` (配置模块)
|
||
管理项目的各项配置参数。
|
||
* `.env`: 纯文本文件，用于存储用户特定的配置值（如 API 密钥、邮箱账户、数据库路径、服务器端口等），不应提交到版本控制。项目提供了 `.env.example` 作为模板。
|
||
* `config.py`: Python 脚本，定义所有可配置参数的名称、数据类型、默认值，并从 `.env` 文件或环境变量中加载实际配置值。这些配置项在整个应用中被其他模块引用。
|
||
|
||
### `tokenManager/` (Token 管理模块)
|
||
此目录 (特别是 `tokenManager/cursor.py` 中的 `Cursor` 类) 封装了与 Cursor 服务端进行认证和 token 管理的逻辑。
|
||
* 可能包括获取新的用户 token、刷新即将过期的 token、验证 token 有效性等功能。
|
||
* 在账户注册成功后，或在需要代表用户与 Cursor API 交互时被调用。
|
||
|
||
### `browser_utils.py` (浏览器工具)
|
||
提供一系列用于控制和自动化浏览器行为的辅助函数。
|
||
* 封装了与浏览器驱动 (如 ChromeDriver for Selenium) 的交互。
|
||
* 功能可能包括：启动浏览器（有头或无头模式）、打开指定 URL、查找页面元素、模拟用户输入（填写表单）、点击按钮、执行 JavaScript 脚本等。
|
||
* 主要被 `cursor_pro_keep_alive.py` 在自动化注册流程中使用。
|
||
|
||
### `turnstilePatch/` (人机验证处理)
|
||
此目录下的代码专注于处理 Cloudflare Turnstile 等类型的人机验证挑战。
|
||
* 可能包含识别验证码、与第三方验证码识别服务API交互、或尝试其他绕过验证的策略。
|
||
* 在自动化注册过程中，当遇到此类验证时被调用。
|
||
|
||
### `logger.py` (日志系统)
|
||
提供标准化的日志记录功能。
|
||
* 配置日志的格式、级别 (INFO, ERROR, DEBUG 等) 和输出目标 (如控制台、日志文件 `app.log`, `api.log`)。
|
||
* 供项目中所有其他模块调用，以记录关键操作、程序流程、错误信息和调试信息。
|
||
|
||
### `index.html` 与 `static/` (前端展现层)
|
||
构成项目的用户界面。
|
||
* `index.html`: 单页应用的主 HTML 文件，定义了页面的基本骨架。
|
||
* `static/`: 存放 CSS 样式表、JavaScript 脚本、图片等静态资源，用于美化界面和实现前端交互逻辑。
|
||
* 前端通过调用 `api.py` 提供的 API 来获取数据、展示信息和提交用户操作。
|
||
|
||
### `reset_machine.py` (机器ID重置模块)
|
||
提供了一个特定的功能，用于重置或修改被 Cursor 服务识别的机器 ID。
|
||
* 这可能用于解决因同一设备注册过多账户而被限制的问题。
|
||
* 通常通过 `api.py` 中的特定 API 端点 (`/reset-machine`) 触发。
|
||
|
||
## 核心工作流程示例
|
||
|
||
### 新账户自动注册流程
|
||
1. **任务触发**: `api.py` 中的后台任务 (`run_registration`) 按照预设的间隔 (`REGISTRATION_INTERVAL`) 检查当前激活账户数量是否低于 `MAX_ACCOUNTS`。
|
||
2. **启动注册**: 如果需要新账户，任务调用 `cursor_pro_keep_alive.main()` 函数。
|
||
3. **获取邮箱**: `cursor_pro_keep_alive.py` 调用 `get_email_code.py`，后者与临时邮箱服务交互，获取一个临时邮箱地址。
|
||
4. **浏览器操作与表单填写**: `cursor_pro_keep_alive.py` 使用 `browser_utils.py` 控制浏览器（可能是无头模式）打开 Cursor 注册页面，并填入获取的邮箱地址及生成的密码等信息。
|
||
5. **处理人机验证 (如果出现)**: 如果注册页面出现 Cloudflare Turnstile 等人机验证，`cursor_pro_keep_alive.py` 可能会调用 `turnstilePatch/` 中的逻辑尝试解决。
|
||
6. **提交注册与接收验证码**: 提交注册信息后，`cursor_pro_keep_alive.py` 再次通过 `get_email_code.py` 监控临时邮箱，等待并提取 Cursor 发送的验证邮件中的激活链接或验证码。
|
||
7. **账户激活**: 使用获取到的验证码或激活链接，通过 `browser_utils.py` 完成账户激活步骤。
|
||
8. **获取 Token (如果适用)**: 激活后，可能通过 `tokenManager/cursor.py` 获取与该账户关联的 Cursor token。
|
||
9. **数据入库**: 注册成功后，将账户的邮箱、密码、token（如有）、状态等信息通过 `database.py` 提供的接口存入 `accounts.db` 数据库。
|
||
10. **日志记录**: 整个过程中的关键步骤、成功或失败信息都会通过 `logger.py` 记录下来。
|
||
|
||
### 用户通过 API 获取随机账户流程
|
||
1. **API 请求**: 用户或外部应用向 `api.py` 发送 `GET` 请求到 `/account/random` 端点。
|
||
2. **请求处理**: `api.py` 中的对应路由处理函数接收到该请求。
|
||
3. **数据库查询**: 该处理函数调用 `database.py` 中封装的数据库查询方法，从 `accounts` 表中随机选择一个状态为 "active" (或其他可用状态) 的账户记录。
|
||
4. **数据格式化**: `database.py` 返回查询结果给 `api.py`。`api.py` 可能需要将原始数据模型转换为 Pydantic 定义的响应模型，确保返回数据的结构和类型正确。
|
||
5. **API 响应**: `api.py` 将包含随机账户信息的 JSON 数据作为 HTTP 响应返回给请求方。
|
||
6. **日志记录**: API 调用信息（如请求路径、时间、结果等）可能会被 `logger.py` 记录。
|
||
|
||
## 环境要求与部署
|
||
|
||
### 环境要求
|
||
* **Python**: 版本 3.10 或更高。
|
||
* **pip**: Python 包管理器，用于安装项目依赖。
|
||
* **依赖包**: 所有必需的 Python 库均在 `requirements.txt` 文件中列出。可以通过 `pip install -r requirements.txt` 命令一键安装。
|
||
* **外部服务**:
|
||
* 临时邮箱服务 (如 tempmail.plus) 并正确配置 Cloudflare DNS 及邮件路由规则，以便 `get_email_code.py` 能够接收验证码。
|
||
* 网络连接：用于访问 Cursor 网站、临时邮箱服务以及可能的验证码服务。
|
||
|
||
### 配置
|
||
项目的核心配置通过位于根目录下的 `.env` 文件进行管理。在首次运行前，需要根据 `.env.example` 文件创建一个 `.env` 文件，并填入实际的配置值。关键配置项包括：
|
||
* `EMAIL_DOMAINS`: 用于接收邮件的域名（需配合Cloudflare）。
|
||
* `EMAIL_USERNAME`: 临时邮箱服务提供的用户名/邮箱前缀。
|
||
* `EMAIL_PIN`: 临时邮箱服务可能需要的 PIN 码。
|
||
* `DATABASE_URL`: SQLite 数据库文件的路径，默认为 `sqlite+aiosqlite:///./accounts.db`。
|
||
* `API_HOST`: API 服务监听的主机地址 (如 `0.0.0.0` 允许外部访问)。
|
||
* `API_PORT`: API 服务监听的端口号 (如 `8000`)。
|
||
* `ENABLE_UI`: 是否启用 Web UI (True/False)。
|
||
* `MAX_ACCOUNTS`: 系统维护的最大激活账户数量。
|
||
* `CURSOR_PATH` (可选): Cursor 客户端的安装路径，某些功能可能需要。
|
||
* 浏览器相关配置 (如 `BROWSER_HEADLESS`, `BROWSER_PATH`等)。
|
||
* 代理配置 (如 `USE_PROXY`, `PROXY_HOST`, `PROXY_PORT`等)。
|
||
|
||
### 运行与部署
|
||
|
||
**1. 本地开发/直接运行:**
|
||
a. 确保已安装 Python 3.10+ 和 pip。
|
||
b. 克隆项目代码到本地。
|
||
c. 在项目根目录下，复制 `.env.example` 为 `.env`，并修改其中的配置项。
|
||
d. 安装依赖：`pip install -r requirements.txt`
|
||
e. 启动应用：通常使用 Uvicorn 作为 ASGI 服务器来运行 FastAPI 应用。命令如下：
|
||
```bash
|
||
uvicorn api:app --host <API_HOST_VALUE> --port <API_PORT_VALUE> --reload
|
||
```
|
||
将 `<API_HOST_VALUE>` 和 `<API_PORT_VALUE>`替换为 `.env` 中配置的值 (例如 `0.0.0.0` 和 `8000`)。`--reload` 参数可以在代码变更时自动重启服务，适合开发环境。
|
||
项目根目录下的 `启动服务器.bat` (Windows) 可能封装了此命令。
|
||
|
||
**2. Docker 部署:**
|
||
项目提供了 `dockerfile`，可以用于构建 Docker 镜像并进行容器化部署。
|
||
a. 确保已安装 Docker。
|
||
b. 在项目根目录下，构建 Docker 镜像：
|
||
```bash
|
||
docker build -t cursor-auto-register .
|
||
```
|
||
c. 运行 Docker 容器 (需要将 `.env` 文件或环境变量传递给容器)：
|
||
```bash
|
||
docker run -d --env-file .env -p <HOST_PORT>:<CONTAINER_PORT> --name cursor_register_app cursor-auto-register
|
||
```
|
||
将 `<HOST_PORT>` 替换为希望在宿主机上映射的端口，`<CONTAINER_PORT>` 替换为容器内应用监听的端口 (即 `.env` 中配置的 `API_PORT`)。`-d` 参数使容器在后台运行。确保 `.env` 文件在执行 `docker run` 命令的上下文中可访问，或者使用其他方式 (如 `-e` 参数) 传递环境变量。
|
||
|
||
## 使用与API
|
||
|
||
### Web UI
|
||
如果 `ENABLE_UI` 配置为 `True`，在服务成功启动后，可以通过浏览器访问部署的地址来使用 Web UI。默认情况下，如果服务运行在本地且端口为 `8000`，则 UI 地址为：
|
||
`http://localhost:8000/` 或 `http://127.0.0.1:8000/`
|
||
|
||
Web UI 通常提供以下功能：
|
||
* 查看当前系统状态和注册任务信息。
|
||
* 展示已注册的账户列表及其状态。
|
||
* 查看和修改部分系统配置。
|
||
* 手动触发某些操作。
|
||
|
||
### 主要 API 端点
|
||
项目通过 FastAPI 提供了一系列 RESTful API 端点，便于程序化交互和集成。以下是一些核心端点示例：
|
||
|
||
* **`GET /health`**:
|
||
* 描述：检查 API 服务的健康状况。
|
||
* 响应：返回服务运行状态。
|
||
|
||
* **`GET /accounts`**:
|
||
* 描述：获取账户列表，支持分页、搜索和排序。
|
||
* 参数（Query）：`page`, `per_page`, `search`, `sort_by`, `order`。
|
||
* 响应：包含账户列表及分页信息的 JSON 数据。
|
||
|
||
* **`GET /account/random`**:
|
||
* 描述：随机获取一个当前状态为可用的账户。
|
||
* 响应：包含单个账户详细信息的 JSON 数据。
|
||
|
||
* **`POST /account`**:
|
||
* 描述：手动创建一个新的账户记录（注意：这通常区别于后台的自动注册任务，具体用途需参考实现，可能用于导入已有账户或特定测试）。
|
||
* 请求体：包含账户信息的 JSON 对象 (如 `email`, `password`, `token`)。
|
||
* 响应：操作结果及创建的账户信息。
|
||
|
||
* **`DELETE /account/{email}` 或 `DELETE /account/id/{id}`**:
|
||
* 描述：删除指定邮箱或ID的账户。可能支持软删除或硬删除。
|
||
* 响应：操作结果。
|
||
|
||
* **`PUT /account/id/{id}/status`**:
|
||
* 描述：更新指定ID账户的状态。
|
||
* 请求体：包含新状态的 JSON 对象 (如 `{"status": "inactive"}`)。
|
||
* 响应：操作结果及更新后的账户信息。
|
||
|
||
* **`GET /registration/start`**:
|
||
* 描述：启动后台的自动注册任务（如果尚未运行）。
|
||
* 响应：任务启动状态。
|
||
|
||
* **`GET /registration/stop`**:
|
||
* 描述：停止后台的自动注册任务。
|
||
* 响应：任务停止状态。
|
||
|
||
* **`GET /registration/status`**:
|
||
* 描述：获取当前后台自动注册任务的详细状态（如是否运行、上次运行时间、成功/失败次数等）。
|
||
* 响应：包含任务状态信息的 JSON 数据。
|
||
|
||
* **`GET /config`**:
|
||
* 描述：获取当前系统的配置信息。
|
||
* 响应：包含所有可配置项及其当前值的 JSON 数据。
|
||
|
||
* **`POST /config`**:
|
||
* 描述：更新系统配置项。
|
||
* 请求体：包含要修改的配置项及其新值的 JSON 对象。
|
||
* 响应：操作结果。
|
||
|
||
### API 文档
|
||
服务启动后，FastAPI 会自动生成交互式的 API 文档：
|
||
* **Swagger UI**: 可通过访问 `/docs` 路径 (例如 `http://localhost:8000/docs`) 查看和测试 API。
|
||
* **ReDoc**: 可通过访问 `/redoc` 路径 (例如 `http://localhost:8000/redoc`) 获取另一种格式的 API 文档。
|
||
|
||
这些文档详细列出了所有可用的 API 端点、请求参数、请求体结构、响应格式以及示例。
|
||
|
||
## 注意事项与免责声明
|
||
|
||
### 注意事项
|
||
1. **配置准确性**: 请务必确保 `.env` 文件中的各项配置（尤其是 `EMAIL_DOMAINS`, `EMAIL_USERNAME`, 以及 Cloudflare 相关设置）正确无误，错误的配置可能导致注册失败或功能异常。
|
||
2. **依赖服务**: 本项目的许多核心功能（如邮件验证码获取）依赖于第三方服务（如临时邮箱平台、Cloudflare）。这些服务的稳定性、可用性或政策变更可能会直接影响本项目的正常运行。
|
||
3. **Cloudflare 设置**: 使用自定义域名接收邮件时，必须正确配置 Cloudflare 的 DNS 解析以及邮件路由 (Email Routing) 规则，将特定邮件地址或 Catch-all 地址转发到你实际使用的临时邮箱服务能够接收的地址。
|
||
4. **资源权限**: 确保程序运行时对 `accounts.db` 数据库文件以及 `app.log`, `api.log` 等日志文件有足够的读写权限。
|
||
5. **并发与限制**: 自动化注册大量账户可能会触发目标网站（Cursor）的速率限制、更严格的人机验证或账户封禁策略。请合理配置 `MAX_ACCOUNTS` 和 `REGISTRATION_INTERVAL`，避免滥用。
|
||
6. **浏览器与驱动**: 如果项目使用 Selenium/Playwright 等浏览器自动化工具，请确保对应的浏览器已安装，并且浏览器驱动版本与浏览器版本兼容。
|
||
7. **法律与合规**: 用户应自行了解并遵守 Cursor 的服务条款。滥用本工具可能导致违反相关条款。
|
||
|
||
### 免责声明
|
||
本项目 (`Cursor Auto Register`) 严格仅供个人学习、教育和技术研究目的使用。严禁将本项目用于任何商业用途或任何可能违反适用法律法规的活动。
|
||
|
||
开发者不对用户如何使用本项目承担任何责任。用户必须独立承担因使用或无法使用本项目所导致的一切直接或间接风险和后果，包括但不限于：
|
||
* 账户被目标服务（如 Cursor）限制或封禁。
|
||
* 违反目标服务的使用条款。
|
||
* 数据丢失或损坏。
|
||
* 任何经济损失或其他形式的损害。
|
||
|
||
通过下载、复制、修改或使用本项目的任何部分，即表示用户已阅读、理解并同意上述所有条款和条件。如果用户不同意这些条款，请勿使用本项目。
|
||
|
||
开发者保留随时修改或终止本项目的权利，恕不另行通知。
|