proxy-pool-manager 1.0.1 → 1.0.3

package/README.md

@@ -4,9 +4,10 @@
 
 ## ✨ 特性
 
-- 🔄 **智能代理管理**：支持从 MongoDB 加载代理，自动验证和轮换
-- 🌐 **HTTP 请求封装**：内置 HTTP 客户端，支持自动代理切换
-- 📊 **代理健康检查**：自动检测代理可用性，支持自定义检测规则
+- 🪶 **轻量级模式**：无需 MongoDB，仅使用请求和队列功能
+- 🔄 **智能代理管理**：支持从 MongoDB 加载代理，自动验证和轮换（可选）
+- 🌐 **HTTP 请求封装**：内置 HTTP 客户端，支持自动代理切换或直接指定代理
+- 📊 **代理健康检查**：自动检测代理可用性，支持自定义检测规则（可选）
 - 🎯 **多种代理策略**：支持顺序、随机、故障转移三种策略
 - 📦 **批量操作**：支持批量插入和管理代理
 - 🔍 **日志系统**：基于 Winston 的完整日志记录
@@ -21,12 +22,76 @@ npm install proxy-pool-manager
 
 ## 🚀 快速开始
 
-### 基本使用
+### 轻量级模式（推荐，无需 MongoDB）
+
+如果你只需要使用 HTTP 请求和队列功能，不需要代理管理，可以使用轻量级模式：
 
 ```typescript
 import { createProxyRequest } from 'proxy-pool-manager';
 
-// 创建 SDK 实例
+// 创建轻量级 SDK 实例（不连接 MongoDB）
+const sdk = await createProxyRequest({
+  maxRetries: 3,
+  timeout: 30,
+  logLevel: 'info'
+});
+
+// 发送 GET 请求
+const response = await sdk.get('https://api.example.com/data', {
+  params: { page: 1 }
+});
+
+// 在请求中直接指定代理（可选）
+const responseWithProxy = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  proxy: 'http://proxy.example.com:8080',  // 直接指定代理
+  timeout: 10
+});
+
+console.log(response.data);
+```
+
+### 轻量级模式 + 代理数组（支持异常时自动轮换）
+
+如果你需要代理管理但不想连接 MongoDB，可以传入代理数组：
+
+```typescript
+import { createProxyRequest } from 'proxy-pool-manager';
+
+// 创建轻量级 SDK 实例 + 代理数组（不连接 MongoDB）
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'sequential',  // 顺序策略
+  maxRetries: 3,
+  timeout: 30,
+  logLevel: 'info'
+});
+
+// 发送请求，会自动使用代理管理器选择的代理
+// 如果代理失败，会自动轮换到下一个代理并重试
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  timeout: 10
+});
+
+console.log('当前使用的代理:', sdk.getCurrentProxy());
+console.log('可用代理列表:', sdk.getAvailableProxies());
+```
+
+### 完整模式（包含代理管理功能）
+
+如果需要代理管理功能（自动轮换、健康检查等），需要提供 MongoDB 连接：
+
+```typescript
+import { createProxyRequest } from 'proxy-pool-manager';
+
+// 创建完整 SDK 实例（包含代理管理）
 const sdk = await createProxyRequest({
   mongoUri: 'mongodb://localhost:27017/proxy_db',
   proxyStrategy: 'sequential',
@@ -38,14 +103,51 @@ const sdk = await createProxyRequest({
   }
 });
 
-// 发送 GET 请求
+// 发送 GET 请求（自动使用代理管理器选择的代理）
 const response = await sdk.get('https://api.example.com/data', {
   params: { page: 1 }
 });
 
+// 或者为特定请求指定代理（优先级高于自动选择）
+const responseWithSpecificProxy = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  proxy: 'http://specific-proxy.com:8080',  // 请求级代理优先
+  timeout: 10
+});
+
 console.log(response.data);
 ```
 
+### 完整模式 + 代理数组（支持异常时自动轮换）
+
+如果需要代理管理功能，并且想预先设置代理列表：
+
+```typescript
+import { createProxyRequest } from 'proxy-pool-manager';
+
+// 创建完整 SDK 实例 + 代理数组（连接 MongoDB）
+const sdk = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'failover',  // 故障转移策略
+  maxRetries: 3,
+  timeout: 30,
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check',
+    timeout: 10,
+  }
+});
+
+// 代理会被保存到 MongoDB，并支持自动轮换
+// 如果请求失败，会自动轮换到下一个代理并重试
+const response = await sdk.get('https://api.example.com/data');
+```
+
 ### 添加代理
 
 ```typescript
@@ -111,15 +213,22 @@ const customResponse = await sdk.request({
 
 ```typescript
 interface SDKOptions {
-  mongoUri: string;                    // MongoDB 连接 URI（必需）
-  maxRetries?: number;                 // 最大重试次数，默认 3
-  timeout?: number;                    // 请求超时时间（秒），默认 30
-  proxyStrategy?: ProxyStrategy;       // 代理策略，默认 'sequential'
-  logLevel?: LogLevel;                 // 日志级别，默认 'info'
-  instanceId?: string;                 // 实例 ID，用于多实例场景
-  proxyCheckOptions: {                 // 代理检查配置（必需）
-    mainUrl: string;                   // 代理检查主 URL（必需）
-    testUrls?: string[];               // 额外的测试 URL
+  mongoUri?: string;                    // MongoDB 连接 URI（可选，启用代理管理时需要）
+  maxRetries?: number;                  // 最大重试次数，默认 3
+  timeout?: number;                     // 请求超时时间（秒），默认 30
+  proxyStrategy?: ProxyStrategy;        // 代理策略，默认 'sequential'
+  logLevel?: LogLevel;                  // 日志级别，默认 'info'
+  instanceId?: string;                  // 实例 ID，用于多实例场景
+  proxies?: string[];                   // 代理数组，支持异常时自动轮换
+  proxy?: string;                       // 单个代理
+  retryDelay?: number;                   // 重试间隔（毫秒），默认使用指数退避策略
+  retryDelayBase?: number;              // 指数退避的基础延迟（毫秒），默认 1000
+  retryDelayMultiplier?: number;        // 指数退避的倍数，默认 2
+  proxyCheckEnabled?: boolean;          // 是否启用代理检查，默认 true
+  proxyLimit?: number;                  // 代理加载限制，0 表示不加载，默认 0
+  proxyCheckOptions?: {                 // 代理检查配置（启用代理管理时需要）
+    mainUrl: string;                   // 代理检查主 URL（启用代理管理时必需）
+    testUrls?: string[];                // 额外的测试 URL
     timeout?: number;                  // 检查超时时间（秒）
     successStatusCodes?: number[];     // 成功状态码列表
     checkInterval?: number;            // 检查间隔（毫秒）
@@ -129,6 +238,15 @@ interface SDKOptions {
 }
 ```
 
+**配置说明：**
+
+- **轻量级模式**：不提供 `mongoUri` 和 `proxyCheckOptions`，SDK 将以轻量级模式运行，不连接 MongoDB，不初始化代理管理功能
+- **轻量级模式 + 代理数组**：提供 `proxies` 或 `proxy` 但不提供 `mongoUri`，SDK 将以轻量级模式运行，代理仅存储在内存中，支持异常时自动轮换
+- **完整模式**：提供 `mongoUri` 或 `proxyCheckOptions`，SDK 将启用代理管理功能
+- **完整模式 + 代理数组**：同时提供 `mongoUri` 和 `proxies`，代理会被保存到 MongoDB，并支持异常时自动轮换
+- **禁用代理检查**：设置 `proxyCheckEnabled: false` 可禁用代理检查
+- **不加载代理**：设置 `proxyLimit: 0` 可不从数据库加载代理
+
 #### 方法
 
 ##### 请求方法
@@ -140,7 +258,7 @@ interface SDKOptions {
 - `patch<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>`
 - `request<T>(config: RequestConfig): Promise<HttpResponse<T>>`
 
-##### 代理管理方法
+##### 代理管理方法（仅在启用代理管理功能时可用）
 
 - `addProxy(proxyUrl: string): Promise<ProxyItem | null>` - 添加代理
 - `deleteProxy(proxyUrl: string): Promise<boolean>` - 删除代理
@@ -151,6 +269,7 @@ interface SDKOptions {
 - `checkProxy(proxy?: string): Promise<boolean>` - 检查代理可用性
 - `triggerProxyCheck(): Promise<void>` - 触发代理检查
 - `getProxyDetails(proxyUrl: string): ProxyItem | undefined` - 获取代理详情
+- `hasProxyManagement(): boolean` - 检查是否启用了代理管理功能
 
 ##### 批量操作
 
@@ -171,11 +290,256 @@ interface SDKOptions {
 
 ### 代理策略
 
-支持三种代理选择策略：
+支持三种代理选择策略，每种策略都有不同的使用场景和特点：
+
+#### 1. sequential（顺序策略）
+
+**特点：**
+
+- 按照代理列表的顺序依次使用代理
+- 每次请求后自动切换到下一个代理
+- 简单、可预测，适合需要均匀分配请求的场景
+
+**使用场景：**
+
+- 需要均匀分配请求到各个代理
+- 代理质量相近，不需要特别优化
+- 需要可预测的代理使用顺序
+
+**示例：**
+```typescript
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'sequential'
+});
+
+// 第一次请求使用 proxy1
+const response1 = await sdk.get('https://api.example.com/data');
+// 第二次请求使用 proxy2
+const response2 = await sdk.get('https://api.example.com/data');
+// 第三次请求使用 proxy3
+const response3 = await sdk.get('https://api.example.com/data');
+// 第四次请求又回到 proxy1（循环）
+```
+
+**轮换机制：**
+
+- 请求失败时，自动切换到下一个代理并重试
+- 如果所有代理都失败，停止重试
+
+#### 2. random（随机策略）
+
+**特点：**
+
+- 从可用代理中随机选择一个使用
+- 避免重复使用同一个代理，直到所有代理都被使用过
+- 适合需要避免代理被过度使用的场景
+
+**使用场景：**
+
+- 需要避免某些代理被过度使用
+- 代理质量相近，随机分配即可
+- 需要分散请求负载
+
+**示例：**
+```typescript
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'random'
+});
+
+// 每次请求随机选择一个代理
+const response1 = await sdk.get('https://api.example.com/data');
+const response2 = await sdk.get('https://api.example.com/data');
+const response3 = await sdk.get('https://api.example.com/data');
+```
+
+**轮换机制：**
+
+- 随机选择代理，避免重复使用
+- 当所有代理都被使用过后，重置使用记录
+- 请求失败时，从剩余未使用的代理中随机选择并重试
+
+#### 3. failover（故障转移策略）⭐ 推荐
+
+**特点：**
+
+- 智能选择最佳可用代理
+- 根据代理的历史表现（失败率、响应时间）自动选择最优代理
+- 优先使用失败率低、响应时间短的代理
+- 适合需要高可用性和性能的场景
+- **不需要 MongoDB**：统计信息存储在内存中，实时更新
+
+**选择优先级：**
+
+1. **连续失败次数**：优先选择连续失败次数最少的代理
+2. **失败率**：在连续失败次数相同的情况下，选择失败率最低的代理
+3. **响应时间**：在失败率相同的情况下，选择平均响应时间最短的代理
+
+**使用场景：**
+
+- 需要高可用性和性能的场景
+- 代理质量差异较大，需要自动选择最优代理
+- 需要自动排除故障代理
+- 对请求成功率要求较高的场景
+- **轻量级模式**：不需要 MongoDB，仅使用内存统计
+
+**示例：**
+
+```typescript
+// 轻量级模式 + failover（不需要 MongoDB）
+const sdk1 = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',  // 高质量代理
+    'proxy2.example.com:8080:user2:pass2',  // 中等质量代理
+    'proxy3.example.com:8080:user3:pass3'   // 低质量代理
+  ],
+  proxyStrategy: 'failover'  // 不需要 MongoDB，统计信息存储在内存中
+});
+
+// 自动选择最优代理（失败率低、响应时间短）
+const response = await sdk1.get('https://api.example.com/data');
+```
+
+```typescript
+// 完整模式 + failover（使用 MongoDB 持久化统计信息）
+const sdk2 = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'failover',
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check'
+  }
+});
+
+// 统计信息会被持久化到 MongoDB，重启后仍然保留历史数据
+const response = await sdk2.get('https://api.example.com/data');
+```
+
+**统计信息说明：**
+
+- **内存模式**（不提供 `mongoUri`）：
+  - 统计信息存储在内存中，实时更新
+  - 重启后统计信息会重置
+  - 适合临时使用或单次运行场景
+
+- **持久化模式**（提供 `mongoUri`）：
+  - 统计信息会保存到 MongoDB
+  - 重启后仍然保留历史数据
+  - 适合长期运行或需要历史数据的场景
+
+**轮换机制：**
+
+- 请求失败时，自动标记当前代理的失败次数
+- 下次请求时，自动选择表现最好的代理
+- 连续失败超过阈值的代理会被标记为无效，不再使用
+- 代理恢复后（成功请求），会自动重新启用
+
+**故障转移流程：**
+
+```text
+1. 选择最优代理（连续失败次数最少 → 失败率最低 → 响应时间最短）
+2. 发送请求
+3. 如果失败：
+   - 增加代理的失败计数
+   - 如果连续失败次数超过阈值，标记为无效
+   - 下次请求时自动选择下一个最优代理
+4. 如果成功：
+   - 重置连续失败次数
+   - 更新平均响应时间
+   - 如果之前被标记为无效，自动恢复为有效状态
+```
+
+**性能优化：**
+
+- 自动排除故障代理，避免重复尝试
+- 优先使用高质量代理，提高成功率
+- 动态调整代理优先级，适应代理质量变化
+
+**重要说明：**
+
+- ✅ **不需要 MongoDB**：failover 策略可以在轻量级模式下使用，统计信息存储在内存中
+- ✅ **实时更新**：每次请求后，统计信息会立即更新（成功/失败次数、响应时间等）
+- ✅ **自动学习**：随着请求的进行，系统会自动学习每个代理的质量，并优先使用高质量代理
+- 💡 **MongoDB 的作用**：如果提供 MongoDB，统计信息会被持久化，重启后仍然保留历史数据，有助于更快地识别高质量代理
+
+### 重试间隔配置
+
+支持两种重试间隔策略：
+
+#### 1. 指数退避策略（默认）
+
+每次重试前等待时间递增，适合大多数场景：
+
+```typescript
+const sdk = await createProxyRequest({
+  maxRetries: 3,
+  retryDelayBase: 1000,      // 基础延迟 1000ms（默认）
+  retryDelayMultiplier: 2    // 倍数 2（默认）
+});
+
+// 重试间隔：第1次 1000ms，第2次 2000ms，第3次 4000ms
+```
+
+**计算公式：** `waitTime = retryDelayBase × retryDelayMultiplier^(attempt-1)`
+
+**示例：**
+- 第1次重试：1000ms × 2^0 = 1000ms
+- 第2次重试：1000ms × 2^1 = 2000ms
+- 第3次重试：1000ms × 2^2 = 4000ms
+
+#### 2. 固定间隔策略
+
+每次重试前等待固定时间，适合需要稳定重试间隔的场景：
 
-- **sequential**（顺序）：按顺序使用代理列表中的代理
-- **random**（随机）：随机选择可用代理
-- **failover**（故障转移）：当前代理失败时自动切换到下一个
+```typescript
+const sdk = await createProxyRequest({
+  maxRetries: 3,
+  retryDelay: 2000  // 每次重试都等待 2000ms
+});
+
+// 重试间隔：每次都是 2000ms
+```
+
+**使用场景：**
+- **指数退避**：适合网络不稳定、需要避免服务器压力的场景
+- **固定间隔**：适合需要稳定重试节奏、便于调试的场景
+
+**自定义配置示例：**
+
+```typescript
+// 快速重试（500ms 基础，1.5倍递增）
+const sdk1 = await createProxyRequest({
+  retryDelayBase: 500,
+  retryDelayMultiplier: 1.5
+  // 重试间隔：500ms → 750ms → 1125ms
+});
+
+// 慢速重试（2000ms 基础，2倍递增）
+const sdk2 = await createProxyRequest({
+  retryDelayBase: 2000,
+  retryDelayMultiplier: 2
+  // 重试间隔：2000ms → 4000ms → 8000ms
+});
+
+// 固定间隔 3 秒
+const sdk3 = await createProxyRequest({
+  retryDelay: 3000
+  // 重试间隔：每次都是 3000ms
+});
+```
 
 ### 日志级别
 
@@ -188,6 +552,98 @@ interface SDKOptions {
 
 ## 🔧 高级用法
 
+### 使用场景选择
+
+#### 场景 1：仅需要 HTTP 请求功能（推荐轻量级模式）
+
+```typescript
+// 不需要代理管理，只需要发送 HTTP 请求
+const sdk = await createProxyRequest({
+  maxRetries: 3,
+  timeout: 30,
+  logLevel: 'info'
+});
+
+// 直接使用，无需 MongoDB
+const response = await sdk.get('https://api.example.com/data');
+```
+
+#### 场景 2：需要临时使用代理
+
+```typescript
+// 轻量级模式 + 直接指定代理
+const sdk = await createProxyRequest({
+  maxRetries: 3,
+  timeout: 30
+});
+
+// 在请求中直接指定代理
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  proxy: 'http://proxy.example.com:8080:user:pass'  // 直接指定代理
+});
+```
+
+#### 场景 2.5：使用代理数组 + 异常时自动轮换（推荐）
+
+```typescript
+// 轻量级模式 + 代理数组（不连接 MongoDB）
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'failover',  // 故障转移策略
+  maxRetries: 3,
+  timeout: 30
+});
+
+// 发送请求，如果代理失败会自动轮换到下一个代理
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  timeout: 10
+});
+```
+
+#### 场景 3：需要代理管理功能
+
+```typescript
+// 完整模式，启用代理管理
+const sdk = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check',
+    timeout: 10,
+  }
+});
+
+// 添加代理到管理器
+await sdk.addProxy('proxy1.example.com:8080:user1:pass1');
+
+// 自动使用代理管理器选择的代理
+const response = await sdk.get('https://api.example.com/data');
+```
+
+#### 场景 4：禁用代理检查，但仍使用代理管理
+
+```typescript
+// 使用代理管理，但禁用代理检查
+const sdk = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxyCheckEnabled: false,  // 禁用代理检查
+  proxyLimit: 0,             // 不加载代理
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check',  // 仍然需要提供（用于后续启用）
+  }
+});
+
+// 手动添加代理，不进行自动检查
+await sdk.addProxy('proxy.example.com:8080:user:pass');
+```
+
 ### 多实例场景
 
 ```typescript
@@ -231,15 +687,141 @@ const sdk = await createProxyRequest({
 });
 ```
 
-### 请求级代理指定
+### 代理使用方式
+
+#### 1. 直接指定代理（轻量级模式和完整模式都支持）
 
 ```typescript
-// 为特定请求指定代理
-const response = await sdk.get('https://api.example.com/data', {
-  proxy: 'specific-proxy.com:8080:user:pass'
+// 为特定请求指定代理（优先级最高）
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  proxy: 'http://proxy.example.com:8080:user:pass',  // 直接指定代理
+  timeout: 10
 });
 ```
 
+#### 2. 使用代理数组（支持异常时自动轮换）
+
+```typescript
+// 创建 SDK 时传入代理数组
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'sequential',  // 顺序策略
+  maxRetries: 3
+});
+
+// 发送请求，会自动使用代理管理器选择的代理
+// 如果代理失败，会自动轮换到下一个代理并重试
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  timeout: 10
+});
+
+// 查看当前使用的代理
+console.log('当前代理:', sdk.getCurrentProxy());
+console.log('可用代理:', sdk.getAvailableProxies());
+```
+
+#### 3. 自动使用代理管理器选择的代理（完整模式）
+
+```typescript
+// 先添加代理到管理器
+await sdk.addProxy('proxy1.example.com:8080:user1:pass1');
+await sdk.addProxy('proxy2.example.com:8080:user2:pass2');
+
+// 不指定代理，自动使用代理管理器选择的代理
+const response = await sdk.post('http://your-api.com/request', {
+  url: 'https://api.example.com/data',
+  method: 'GET',
+  // 不指定 proxy，会自动使用 ProxyManager 选择的代理
+  timeout: 10
+});
+```
+
+#### 4. 代理优先级
+
+代理使用遵循以下优先级：
+
+1. **请求级代理**（`options.proxy`）- 最高优先级，总是优先使用
+2. **代理管理器自动选择** - 如果启用了代理管理且没有指定请求级代理
+3. **无代理** - 如果都没有，则直接请求（不使用代理）
+
+#### 5. 异常时自动轮换
+
+当请求失败时（超时、连接错误等），系统会自动轮换到下一个代理并重试：
+
+```typescript
+const sdk = await createProxyRequest({
+  proxies: [
+    'proxy1.example.com:8080:user1:pass1',
+    'proxy2.example.com:8080:user2:pass2',
+    'proxy3.example.com:8080:user3:pass3'
+  ],
+  proxyStrategy: 'failover',  // 推荐使用故障转移策略
+  maxRetries: 3  // 最多重试3次，每次失败会自动轮换代理
+});
+
+// 如果 proxy1 失败，会自动尝试 proxy2，再失败会尝试 proxy3
+const response = await sdk.get('https://api.example.com/data');
+```
+
+**轮换机制说明：**
+
+- 只有在使用代理管理器选择的代理时才会轮换（如果请求中直接指定了代理，不会轮换）
+- 支持两种重试间隔策略：
+  - **指数退避策略**（默认）：每次重试前等待时间递增，公式为 `retryDelayBase × retryDelayMultiplier^(attempt-1)`
+    - 默认值：基础延迟 1000ms，倍数 2
+    - 示例：第1次重试等待 1000ms，第2次等待 2000ms，第3次等待 4000ms
+  - **固定间隔策略**：设置 `retryDelay` 后，每次重试前等待固定时间
+    - 示例：设置 `retryDelay: 2000`，每次重试都等待 2000ms
+- 支持三种代理策略，每种策略的轮换方式不同：
+  - **sequential**：按顺序切换到下一个代理
+  - **random**：从剩余未使用的代理中随机选择
+  - **failover**：自动选择表现最好的代理（推荐）
+
+**不同策略的轮换行为：**
+
+| 策略 | 首次选择 | 失败后轮换 | 特点 |
+|------|---------|-----------|------|
+| sequential | 第一个代理 | 按顺序切换到下一个 | 简单、可预测 |
+| random | 随机选择 | 从剩余代理中随机选择 | 分散负载 |
+| failover | 最优代理 | 选择下一个最优代理 | 智能、高效 ⭐ |
+
+**故障检测：**
+
+系统会自动检测以下类型的错误并触发代理轮换：
+
+- 连接超时（TimeoutError）
+- 连接被拒绝（ECONNREFUSED）
+- 网络错误（网络相关关键词）
+- HTTP 错误（根据配置）
+
+**代理状态管理：**
+
+- 连续失败超过阈值的代理会被标记为无效
+- 无效代理不会参与选择，直到恢复
+- 代理恢复后（成功请求），会自动重新启用
+
+#### 6. 检查代理管理功能状态
+
+```typescript
+// 检查是否启用了代理管理功能
+if (sdk.hasProxyManagement()) {
+  console.log('代理管理功能已启用');
+  // 可以使用代理管理相关方法
+  await sdk.addProxy('proxy.example.com:8080');
+} else {
+  console.log('轻量级模式，仅支持直接指定代理');
+  // 只能通过 options.proxy 指定代理
+}
+```
+
 ### 代理统计信息
 
 ```typescript
@@ -645,9 +1227,24 @@ import type {
 
 ## ⚠️ 注意事项
 
-1. **MongoDB 连接**：确保 MongoDB 服务正在运行且连接 URI 正确
-2. **代理格式**：代理 URL 格式为 `host:port:username:password`
-3. **初始化等待**：SDK 初始化是异步的，使用 `waitForReady()` 确保初始化完成
-4. **资源清理**：使用完毕后调用 `destroy()` 方法清理资源
-5. **并发限制**：代理检查的并发数可通过 `maxConcurrentChecks` 配置
+1. **轻量级模式 vs 完整模式**：
+   - **轻量级模式**：不提供 `mongoUri` 和 `proxyCheckOptions`，不连接 MongoDB，仅使用请求和队列功能
+   - **完整模式**：提供 `mongoUri` 或 `proxyCheckOptions`，启用代理管理功能，需要 MongoDB 连接
+
+2. **MongoDB 连接**：仅在启用代理管理功能时需要，确保 MongoDB 服务正在运行且连接 URI 正确
+
+3. **代理格式**：代理 URL 格式为 `host:port:username:password` 或 `http://host:port:username:password`
+
+4. **代理使用**：
+   - 轻量级模式下，只能通过 `options.proxy` 直接指定代理
+   - 完整模式下，可以自动使用代理管理器选择的代理，也可以直接指定代理（优先级更高）
+
+5. **初始化等待**：SDK 初始化是异步的，使用 `waitForReady()` 确保初始化完成
+
+6. **资源清理**：使用完毕后调用 `destroy()` 方法清理资源
+
+7. **并发限制**：代理检查的并发数可通过 `maxConcurrentChecks` 配置
 
+8. **禁用功能**：
+   - 设置 `proxyCheckEnabled: false` 可禁用代理检查
+   - 设置 `proxyLimit: 0` 可不从数据库加载代理