168 lines
14 KiB
Markdown
168 lines
14 KiB
Markdown
# Module Documentation: api.py
|
||
|
||
## 1. 概述 (Overview)
|
||
|
||
`api.py` 文件实现了一个基于 FastAPI 的 Web 应用，其核心目的是提供一套 API 接口来管理 Cursor IDE 的账号。此应用不仅支持账号的增删改查、导入导出等基本管理功能，还集成了一个自动化的后台任务来注册新账号，直到达到预设的上限。此外，它还能跟踪账号的使用情况、管理系统配置，并提供与本地 Cursor 客户端集成的功能，如更新认证 Token 和重置机器ID。
|
||
|
||
主要技术栈包括：
|
||
* **FastAPI**: 用于构建高性能 API。
|
||
* **SQLAlchemy**: 作为 ORM 与数据库进行异步交互。
|
||
* **Pydantic**: 用于数据校验和 API 的请求/响应模型定义。
|
||
* **Uvicorn**: 作为 ASGI 服务器运行应用。
|
||
* **Asyncio**: 支持异步操作和并发任务，特别是后台注册进程。
|
||
|
||
## 2. 核心功能 (Core Features)
|
||
|
||
### 2.1. 账号管理 (Account Management)
|
||
该模块提供了全面的账号管理功能：
|
||
- **创建账号**: 通过 `POST /account` 端点，可以添加新的 Cursor 账号信息到数据库。
|
||
- **读取账号**:
|
||
- `GET /accounts`: 获取所有账号列表，支持分页、按邮件模糊搜索以及按字段（如创建时间、ID、邮箱）升序或降序排序。
|
||
- `GET /account/random`: 随机获取一个当前可用的账号及其 Token。
|
||
- `GET /account/{email}/usage`: 查询指定邮箱账号的详细使用情况（如剩余额度、天数）并更新数据库记录。
|
||
- **更新账号状态**: 通过 `PUT /account/id/{id}/status` 端点，可以修改指定 ID 账号的状态（如 active, disabled, deleted）。
|
||
- **删除账号**:
|
||
- `DELETE /account/{email}`: 根据邮箱停用（逻辑删除）或永久删除（物理删除，需 `hard_delete=True`）账号。
|
||
- `DELETE /account/id/{id}`: 根据账号 ID 停用或永久删除账号。
|
||
- **导入/导出账号**:
|
||
- `POST /accounts/import`: 从上传的 JSON 文件批量导入或更新账号信息。
|
||
- `GET /accounts/export`: 将所有账号信息导出为 JSON 文件。
|
||
|
||
### 2.2. 自动注册 (Automated Registration)
|
||
应用包含一个后台服务，用于自动注册新的 Cursor 账号：
|
||
- **后台任务**: `run_registration` 异步函数是注册逻辑的核心，它会循环尝试注册新账号。
|
||
- **启动与停止**:
|
||
- `GET /registration/start`: 手动启动后台注册任务。如果任务已运行或账号已满，会返回相应状态。
|
||
- `GET /registration/stop`: 手动停止当前运行的注册任务。
|
||
- **状态查询**: `GET /registration/status` 提供注册任务的当前状态，包括是否正在运行、上次运行时间、下次运行时间、成功/失败次数统计以及当前账号数量与最大限制。
|
||
- **监控模式**: 当数据库中激活的账号数量达到 `MAX_ACCOUNTS` 设定的上限时，注册任务会暂停实际注册操作，进入监控模式，并定期检查账号数量，一旦账号数量低于上限则自动恢复注册。
|
||
|
||
### 2.3. 账号使用情况 (Account Usage)
|
||
跟踪和管理账号的实际使用量：
|
||
- **查询所有账号使用情况**: `GET /usage` 并发查询并返回所有已存账号的剩余额度和试用天数，结果会进行缓存以提高性能。
|
||
- **查询单个账号使用情况**: `GET /account/{email}/usage` 查询特定邮箱账号的余额和剩余天数，并据此更新数据库中的记录。
|
||
- **更新所有账号使用情况**: `POST /update_all_usage` 批量更新所有账号的余量信息到数据库。
|
||
- **记录账号使用行为**: `GET /account/{id}/usage-records` 获取指定账号的历史使用记录（如IP地址、User-Agent、使用时间）。
|
||
|
||
### 2.4. 系统配置管理 (System Configuration)
|
||
允许动态管理应用的配置参数（通常存储在 `.env` 文件中）：
|
||
- **读取配置**: `GET /config` 返回当前系统配置信息，如浏览器设置、邮箱服务详情、代理设置等。
|
||
- **更新配置**: `POST /config` 允许通过 API 请求更新 `.env` 文件中的配置项，并重新加载。
|
||
|
||
### 2.5. Cursor 客户端集成 (Cursor Client Integration)
|
||
提供与本地安装的 Cursor IDE 进行交互的功能：
|
||
- **使用账号 Token 更新认证**: `POST /account/use-token/{id}` 使用指定账号的 Access Token 来更新本地 Cursor IDE 的认证配置。可以选择是否同时重置机器ID。
|
||
- **重置机器 ID**: `GET /reset-machine` 调用脚本重置本地 Cursor IDE 的机器识别码。
|
||
|
||
### 2.6. Web UI 与 API 文档 (Web UI & API Documentation)
|
||
- **静态首页服务**: `GET /` 提供一个简单的 `index.html` 页面作为应用的 Web UI 入口。
|
||
- **Swagger UI**: `GET /docs` 提供交互式的 API 文档界面。
|
||
- **ReDoc**: `GET /redoc` 提供另一种风格的 API 文档。
|
||
|
||
## 3. 架构与关键组件 (Architecture & Key Components)
|
||
|
||
### 3.1. FastAPI 应用实例 (`app`)
|
||
- **初始化**: `app = FastAPI(...)` 创建主应用实例，配置了标题、描述、版本、文档URL以及 `lifespan` 管理器。
|
||
- **中间件**: `app.add_middleware(CORSMiddleware, ...)` 添加了 CORS 中间件以支持跨域请求。
|
||
- **生命周期事件**: `@asynccontextmanager async def lifespan(app: FastAPI): ...` 定义了应用的生命周期事件。在应用启动时，会调用 `init_db()` 初始化数据库。
|
||
|
||
### 3.2. 数据库交互 (Database Interaction)
|
||
- **`database.py` (外部模块)**: 此模块（未直接提供，但从导入推断）负责数据库的连接管理 (`get_session`)，定义数据模型 (`AccountModel`, `AccountUsageRecordModel`)，以及数据库初始化逻辑 (`init_db`)。
|
||
- **SQLAlchemy ORM**: 应用通过 SQLAlchemy Core 的查询构造语法（如 `select()`, `delete()`, `func.count()`）和异步会话 (`async with get_session() as session:`) 与数据库进行交互。
|
||
|
||
### 3.3. 路由与端点 (Routing & Endpoints)
|
||
- API 端点通过 FastAPI 的装饰器（如 `@app.get`, `@app.post`, `@app.put`, `@app.delete`）绑定到相应的异步处理函数。
|
||
- 端点通过 `tags` 参数在 API 文档中进行分组，主要包括: `General`, `Accounts`, `Registration`, `Config`, `System`。
|
||
|
||
### 3.4. 后台注册任务 (`run_registration`)
|
||
- 这是一个核心的异步函数，通过 `asyncio.create_task(run_registration())` 在 `/registration/start` 端点被调用时启动。
|
||
- 任务在一个无限循环中运行（受 `registration_status["is_running"]` 控制），依次执行：检查当前激活账号数是否小于 `MAX_ACCOUNTS`，调用 `register_account`（一个外部同步函数，通过 `run_in_executor` 异步执行）进行实际注册，处理成功/失败结果，更新统计信息，然后根据 `REGISTRATION_INTERVAL` 等待下一轮。
|
||
|
||
### 3.5. 全局状态管理 (Global State Management)
|
||
- **`registration_status` (字典)**: 用于实时跟踪和存储自动注册任务的各种状态信息，如是否正在运行 (`is_running`)、上次运行时间 (`last_run`)、上次状态 (`last_status`)、下次计划运行时间 (`next_run`)，以及运行次数、成功和失败的统计。
|
||
- **`background_tasks` (字典)**: 主要用于存储 `run_registration` 任务的 `asyncio.Task` 实例，键为 `"registration_task"`。这允许其他部分代码检查任务是否正在运行或取消任务。
|
||
|
||
### 3.6. 配置管理 (Configuration Management)
|
||
- **`config.py` (外部模块)**: 定义了应用的一些关键配置常量，如 `MAX_ACCOUNTS`（最大账号数）、`REGISTRATION_INTERVAL`（注册间隔时间）、`API_HOST`、`API_PORT` 等。
|
||
- **`.env` 文件**: 应用启动时及配置更新后，会通过 `python-dotenv` 库的 `load_dotenv()` 函数从项目根目录下的 `.env` 文件加载环境变量。这些变量通常包含敏感信息或环境特定配置。
|
||
|
||
### 3.7. 日志系统 (Logging)
|
||
- **`logger.py` (外部模块)**: 应用从该模块导入 `info` 和 `error` 函数，用于在控制台或日志文件（取决于 `logger.py` 的配置）中记录不同级别的事件信息和错误详情，包括堆栈跟踪。
|
||
|
||
### 3.8. 辅助函数与类 (Utility Functions & Classes)
|
||
- **数据库查询辅助函数**: `get_active_account_count()` 和 `get_account_count()` 用于高效查询数据库中符合特定条件的账号数量。
|
||
- **`Cursor` 类 (from `tokenManager.cursor`)**: 封装了与 Cursor 服务进行交互的逻辑，例如 `get_remaining_balance()` 和 `get_trial_remaining_days()` 方法用于查询账号的额度和试用期。
|
||
- **`CursorAuthManager` 类 (from `cursor_auth_manager`)**: 负责更新本地 Cursor IDE 的认证文件。
|
||
- **`CursorShadowPatcher` 类 (from `cursor_shadow_patcher`)**: 负责重置本地 Cursor IDE 的机器 ID。
|
||
|
||
## 4. 数据模型 (Data Models - Pydantic)
|
||
|
||
Pydantic 模型在 FastAPI 中扮演着数据校验、序列化和文档生成的关键角色：
|
||
- **`Account`**: 定义了一个 Cursor 账号的主要属性，如 `email`, `password`, `token`, `user`, `usage_limit`, `created_at`, `status`, `id`。它用于创建账号 (`POST /account`) 的请求体，并在多个响应中作为数据结构。`Config.from_attributes = True` 允许从 ORM 对象创建 Pydantic 模型实例。
|
||
- **`AccountResponse`**: 一个通用的响应模型，封装了操作是否成功 (`success`)、返回的数据 (`data`，通常是 `Account` 模型或其列表)以及可选的消息 (`message`)。
|
||
- **`StatusUpdate`**: 用于 `PUT /account/id/{id}/status` 端点的请求体，包含一个新的 `status` 字符串。
|
||
- **`ConfigModel`**: 定义了 `POST /config` 端点接受的配置项及其类型，例如 `BROWSER_HEADLESS`, `MAX_ACCOUNTS`, `EMAIL_DOMAINS`, 代理相关设置等。
|
||
|
||
这些模型确保了 API 接收的数据符合预期格式，并且响应数据也以结构化的方式返回。
|
||
|
||
## 5. 错误处理 (Error Handling)
|
||
|
||
应用实现了全局异常处理机制：
|
||
- **`@app.exception_handler(HTTPException)`**: 捕获 FastAPI 自身或其他地方抛出的 `HTTPException`。它会记录错误并通过 `JSONResponse` 返回一个包含 `success: False` 和错误详情（`exc.detail`）的 JSON 响应，状态码与原始异常一致。
|
||
- **`@app.exception_handler(Exception)`**: 捕获所有其他未被处理的 Python 异常。这确保了即使发生意外错误，应用也不会崩溃，而是返回一个标准的 500 内部服务器错误响应，其中包含 `success: False` 和通用错误消息。在调试模式下（`app.debug` 为 True），响应中可能还会包含异常的详细信息。
|
||
|
||
这种集中的错误处理方式有助于提供一致的 API 错误响应格式。
|
||
|
||
## 6. 依赖与环境 (Dependencies & Environment)
|
||
|
||
### 主要依赖:
|
||
- **FastAPI**: Web 框架。
|
||
- **Uvicorn**: ASGI 服务器。
|
||
- **SQLAlchemy**: ORM，用于数据库异步操作 (需要配合相应的数据库驱动，如 `asyncpg` for PostgreSQL, `aiomysql` for MySQL)。
|
||
- **Pydantic**: 数据验证和模型定义。
|
||
- **python-dotenv**: 加载 `.env` 文件中的环境变量。
|
||
- **requests**: (推断) `tokenManager.cursor.Cursor` 类可能使用此库进行 HTTP 请求以查询 Cursor API。
|
||
- **concurrent.futures**: 用于在 `check_usage` 接口中并发执行账号状态检查。
|
||
|
||
### 运行环境:
|
||
- **Python**: 版本 3.7+ (基于 FastAPI 和 `async/await` 语法)。
|
||
- **`.env` 文件**: 必须在项目根目录下存在，并包含所有必要的配置变量 (如数据库连接信息、API 密钥、邮箱配置、代理配置等)。`get_config` 和 `update_config` 端点直接与此文件交互。
|
||
- **数据库服务**: 需要一个 SQLAlchemy 支持的数据库正在运行，并在 `.env` 中配置好连接参数。
|
||
- **网络访问**: 自动注册和账号使用情况查询功能需要网络访问权限，以连接到 Cursor 服务和可能的邮件服务。
|
||
|
||
## 7. 部署与运行 (Deployment & Execution)
|
||
|
||
该 FastAPI 应用通过 Uvicorn ASGI 服务器运行。文件末尾的 `if __name__ == "__main__":` 块提供了一个直接运行应用的入口点：
|
||
```python
|
||
if __name__ == "__main__":
|
||
uvicorn.run(
|
||
"api:app",
|
||
host=API_HOST,
|
||
port=API_PORT,
|
||
reload=API_DEBUG,
|
||
access_log=True,
|
||
log_level="error",
|
||
workers=API_WORKERS,
|
||
loop="asyncio",
|
||
)
|
||
```
|
||
- `"api:app"`: 指示 Uvicorn 加载 `api.py` 文件中的 `app` FastAPI 实例。
|
||
- `host=API_HOST`, `port=API_PORT`: 从 `config.py` (或 `.env`) 加载监听的主机和端口。
|
||
- `reload=API_DEBUG`: 如果 `API_DEBUG` 为 True，则启用热重载功能，代码更改时服务器会自动重启。
|
||
- `access_log=True`: 启用访问日志。
|
||
- `log_level="error"`: 设置 Uvicorn 的日志级别。
|
||
- `workers=API_WORKERS`: 配置工作进程数量。对于生产环境，可以根据服务器核心数调整。
|
||
- `loop="asyncio"`: 明确指定使用 asyncio 事件循环。
|
||
|
||
## 8. 注意事项 (Considerations)
|
||
|
||
- **并发安全**: 虽然 FastAPI 和 asyncio 处理并发请求，但对全局变量 `registration_status` 和 `background_tasks` 的直接修改可能需要审慎处理，以避免潜在的竞争条件，尤其是在多 worker 配置下（尽管 Python 的 GIL 使得纯 Python 代码的并发问题不如其他语言复杂）。
|
||
- **安全性**:
|
||
- **敏感信息**: `.env` 文件中存储了大量敏感配置。需要确保此文件的权限得到妥善管理。
|
||
- **密码存储**: 如果 `AccountModel` 直接存储明文密码，这是严重的安全风险。密码应始终进行哈希处理 (如使用 bcrypt 或 Argon2) 后再存储。
|
||
- **API 认证/授权**: 当前 API 似乎没有实现任何认证或授权机制来保护其端点。在生产环境中，应考虑添加如 OAuth2 或 API 密钥等机制来限制对敏感操作的访问。
|
||
- **配置热重载**: `/restart` 接口通过修改 `.env` 文件中的一个时间戳变量来尝试触发 Uvicorn 的热重载。这种方法的有效性依赖于 Uvicorn 的 `--reload` 选项及其文件监控机制，可能并非在所有情况下都可靠或即时。
|
||
- **外部依赖**: 自动注册功能依赖于外部的 `register_account` 函数和 `tokenManager.cursor` 模块。这些外部组件的稳定性和行为直接影响本应用的功能。
|
||
- **错误处理细节**: 虽然有全局异常处理，但某些函数内部的 `try-except` 块可能会捕获并记录错误，然后继续执行或返回特定响应，这需要仔细审查以确保所有错误路径都得到妥善处理。
|
||
- **数据库迁移**: 随着 `AccountModel` 或 `AccountUsageRecordModel` 的演变，需要一个数据库迁移策略 (如使用 Alembic) 来管理数据库模式的变更。
|