431 lines
12 KiB
Markdown
431 lines
12 KiB
Markdown
# Service quản trị Resource trong hệ thống
|
|
|
|
- Hỗ trợ 2 giao thức: http(31249), grpc(31287)
|
|
- Quản trị 2 resource: proxy pool, token pool
|
|
|
|
> **📖 Migration Guide**: Nếu bạn đang sử dụng ProxyPool và muốn migrate sang SmartPool, xem [Migration Guide](./MIGRATION_GUIDE_PROXYPOOL_TO_SMARTPOOL.md)
|
|
|
|
---
|
|
|
|
# ResourcePool Usage Guide
|
|
|
|
This guide provides instructions on how to set up and use **TokenPool** and **ProxyPool** in your project.
|
|
|
|
> **Note**: This repository contains two systems:
|
|
> - **ResourcePool** (Legacy): TokenPool và ProxyPool với gRPC/HTTP API
|
|
> - **SmartPool** (New): Intelligent proxy management với SDK client
|
|
>
|
|
> Xem [SmartPool documentation](./docs/src/Icomm.SmartPool.Proxy/README.md) cho hệ thống mới.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1. Add the following NuGet package references to your project:
|
|
```xml
|
|
<PackageReference Include="Icomm.ResourcePool.Abstractions" Version="x.x.x" />
|
|
<PackageReference Include="Icomm.TokenPool" Version="x.x.x" />
|
|
```
|
|
|
|
---
|
|
|
|
## Service Registration
|
|
|
|
### TokenPool Registration
|
|
|
|
Register TokenPool service in `Startup.cs` or `Program.cs`:
|
|
|
|
```csharp
|
|
using Icomm.TokenPool.Extensions;
|
|
|
|
services
|
|
.AddConfigManager(hostContext.Configuration)
|
|
.AddTokenPool(
|
|
hostContext.Configuration,
|
|
opt =>
|
|
{
|
|
#if DEBUG
|
|
opt.Host = "10.9.3.70";
|
|
opt.protocol = ResourcePool.Core.Protocol.Grpc;
|
|
opt.Port = 31287;
|
|
#endif
|
|
}
|
|
);
|
|
```
|
|
|
|
**Configuration Options:**
|
|
- `Host`: Server host address
|
|
- `Port`: Server port (default: 31287 for gRPC, 31249 for HTTP)
|
|
- `protocol`: `Protocol.Grpc` or `Protocol.Http`
|
|
- `TimeOut`: Request timeout in milliseconds
|
|
|
|
---
|
|
|
|
## Usage TokenPool
|
|
|
|
Once the service is registered, you can inject and use `ITokenPoolService` in your application.
|
|
|
|
### Basic Usage
|
|
|
|
```csharp
|
|
using Icomm.TokenPool.Contracts;
|
|
using Icomm.ResourcePool.Abstractions.Requests;
|
|
using Icomm.ResourcePool.Abstractions.Responses;
|
|
|
|
public class MyService
|
|
{
|
|
private readonly ITokenPoolService _tokenPoolService;
|
|
|
|
public MyService(ITokenPoolService tokenPoolService)
|
|
{
|
|
_tokenPoolService = tokenPoolService;
|
|
}
|
|
|
|
// Example with EstimateRequest
|
|
public async Task UseTokenPool()
|
|
{
|
|
var token = await _tokenPoolService.RequestToken(
|
|
new TokenRequest()
|
|
{
|
|
AccessToken = "your-access-token",
|
|
EstimateRequest = 1,
|
|
Action = "action-name",
|
|
Platform = "1",
|
|
}
|
|
);
|
|
Console.WriteLine($"Retrieved Token: {token.Token}");
|
|
}
|
|
|
|
// Example without EstimateRequest (manual release)
|
|
public async Task UseTokenPoolManual()
|
|
{
|
|
var token = await _tokenPoolService.RequestToken(
|
|
new TokenRequest()
|
|
{
|
|
AccessToken = "your-access-token",
|
|
Action = "action-name",
|
|
Platform = "1",
|
|
}
|
|
);
|
|
|
|
// Use token...
|
|
|
|
// Release token when done
|
|
await _tokenPoolService.UsedToken(token);
|
|
Console.WriteLine($"Token released: {token.Token}");
|
|
}
|
|
}
|
|
```
|
|
|
|
### Available Methods
|
|
|
|
- `RequestToken(TokenRequest request)`: Request a token from the pool
|
|
- `UsedToken(TokenApp token)`: Release a token back to the pool
|
|
- `ExpireByToken(ExpireByTokenRequest request)`: Expire a token by token value
|
|
- `ExpireById(ExpireByTokenIdRequest request)`: Expire a token by ID
|
|
- `UpdateStatus(UpdateResourceStatusRequest request)`: Update token status
|
|
- `ResourceExpired(TokenApp resource, TimeSpan timeExpire, string accessToken)`: Mark token as expired for a duration
|
|
|
|
---
|
|
|
|
## Usage ProxyPool
|
|
|
|
ProxyPool is accessed via **gRPC** or **HTTP REST API** directly. There is no client SDK like TokenPool.
|
|
|
|
### gRPC Usage
|
|
|
|
```csharp
|
|
using Icomm.ResourcePool.Abstractions;
|
|
using Icomm.ResourcePool.Abstractions.Requests;
|
|
using MagicOnion.Client;
|
|
|
|
// Create gRPC channel
|
|
var channel = GrpcChannel.ForAddress("http://10.9.3.70:31287");
|
|
var client = MagicOnionClient.Create<IProxyService>(channel);
|
|
|
|
// Get proxy
|
|
var request = new ProxyRequest
|
|
{
|
|
AccessToken = "your-access-token"
|
|
};
|
|
var response = await client.GetProxy(request);
|
|
var proxy = response.Proxy;
|
|
|
|
// Use proxy with HttpClient
|
|
var handler = new HttpClientHandler
|
|
{
|
|
Proxy = new WebProxy($"{proxy.Host}:{proxy.Port}")
|
|
{
|
|
Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword)
|
|
}
|
|
};
|
|
var httpClient = new HttpClient(handler);
|
|
```
|
|
|
|
### HTTP REST API Usage
|
|
|
|
#### Get Proxy (Simple)
|
|
|
|
**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/get`
|
|
|
|
```csharp
|
|
using RestSharp;
|
|
|
|
var client = new RestClient("http://10.9.3.70:31249");
|
|
var request = new RestRequest("/api/resource-pool/v1/ProxyPool/get", Method.Post);
|
|
request.AddJsonBody(new ProxyRequest
|
|
{
|
|
AccessToken = "your-access-token"
|
|
});
|
|
|
|
var response = await client.ExecuteAsync<ProxyResponse>(request);
|
|
var proxy = response.Data.Proxy;
|
|
|
|
// Use with RestSharp
|
|
var restClient = new RestClient("https://target-site.com")
|
|
{
|
|
Proxy = new WebProxy($"{proxy.Host}:{proxy.Port}")
|
|
{
|
|
Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword)
|
|
}
|
|
};
|
|
```
|
|
|
|
#### Get Proxy By Feature (Advanced)
|
|
|
|
**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/get-v2`
|
|
|
|
Lấy proxy server theo features và chiến lược lọc cụ thể.
|
|
|
|
**Request Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `access_token` | string | **Required** | Access token for authentication |
|
|
| `target_domain` | string | Optional | Domain đích cần truy cập (vd: facebook.com, x.com) |
|
|
| `type` | string | **Required** | Loại proxy ("http", "httpv6", "socks") |
|
|
| `country` | string | Optional | Mã quốc gia proxy ("VN", "US", "JP") |
|
|
| `strategy` | string | **Required** | Chiến lược chọn proxy |
|
|
| `referer_proxy` | object | Optional | Proxy tham chiếu để tìm proxy thay thế tốt nhất |
|
|
|
|
**⚠️ Logic Ưu Tiên Tham Số**
|
|
|
|
Nếu `referer_proxy.id` khác null: Hệ thống sẽ ưu tiên lấy thông tin từ proxy referer làm tham số lọc chính, sau đó mới sử dụng các tham số `type`, `country`, `target_domain` để lọc bổ sung.
|
|
|
|
**Cách hoạt động:**
|
|
1. Hệ thống lấy thông tin của proxy có ID = `referer_proxy.id`
|
|
2. Sử dụng thông tin proxy đó (type, country, location) làm tiêu chí lọc chính
|
|
3. Áp dụng các tham số `type`, `country`, `target_domain` như điều kiện lọc bổ sung
|
|
4. Thực hiện strategy được chọn trên pool đã được lọc
|
|
|
|
**🎯 Available Strategies**
|
|
|
|
##### 1. 🎲 Random Strategy (`strategy: "random"`)
|
|
- **Tham số bắt buộc**: `type`
|
|
- **Tham số tùy chọn**: `country`
|
|
- **Mô tả**: Chọn ngẫu nhiên proxy từ pool phù hợp
|
|
- **Ví dụ**:
|
|
```json
|
|
{
|
|
"access_token": "your-token",
|
|
"type": "httpv6",
|
|
"strategy": "random",
|
|
"country": "VN"
|
|
}
|
|
```
|
|
|
|
##### 2. ⚖️ Round Robin Strategy (`strategy: "round_robin"`)
|
|
- **Tham số bắt buộc**: `type`
|
|
- **Tham số tùy chọn**: `country`
|
|
- **Mô tả**: Phân phối request đều khắp các proxy trong pool
|
|
- **Ví dụ**:
|
|
```json
|
|
{
|
|
"access_token": "your-token",
|
|
"type": "http",
|
|
"strategy": "round_robin",
|
|
"country": "US"
|
|
}
|
|
```
|
|
|
|
##### 3. 📊 Least Used Strategy (`strategy: "least_used"`)
|
|
- **Tham số bắt buộc**: `referer_proxy.id`
|
|
- **Mô tả**: Chọn proxy có tần suất sử dụng thấp nhất
|
|
- **Logic đặc biệt**: Sử dụng thông tin referer_proxy làm tham số lọc chính
|
|
- **Ví dụ**:
|
|
```json
|
|
{
|
|
"access_token": "your-token",
|
|
"strategy": "least_used",
|
|
"referer_proxy": {
|
|
"id": 123
|
|
},
|
|
"type": "httpv6",
|
|
"country": "VN"
|
|
}
|
|
```
|
|
|
|
##### 4. ⚡ Least Delay Strategy (`strategy: "least_delay"`)
|
|
- **Tham số bắt buộc**: `target_domain`, `type`
|
|
- **Tham số tùy chọn**: `country`
|
|
- **Mô tả**: Chọn proxy có độ trễ thấp nhất cho domain cụ thể
|
|
- **Ví dụ**:
|
|
```json
|
|
{
|
|
"access_token": "your-token",
|
|
"target_domain": "facebook.com",
|
|
"type": "httpv6",
|
|
"strategy": "least_delay",
|
|
"country": "US"
|
|
}
|
|
```
|
|
|
|
##### 5. 🏆 Adaptive Ranking Strategy (`strategy: "adaptive_ranking"`)
|
|
- **Tham số bắt buộc**: `target_domain`, `type`
|
|
- **Tham số tùy chọn**: `country`
|
|
- **Mô tả**: Chọn proxy có điểm số cao nhất (tỷ lệ thành công + tốc độ response)
|
|
- **Ví dụ**:
|
|
```json
|
|
{
|
|
"access_token": "your-token",
|
|
"target_domain": "instagram.com",
|
|
"type": "http",
|
|
"strategy": "adaptive_ranking",
|
|
"country": "JP"
|
|
}
|
|
```
|
|
|
|
**📤 Response Format**
|
|
|
|
```json
|
|
{
|
|
"proxy": {
|
|
"id": 123,
|
|
"host": "192.168.1.100",
|
|
"port": 8080,
|
|
"type": "httpv6",
|
|
"country": "VN",
|
|
"location": "Ho Chi Minh City",
|
|
"status": 1,
|
|
"auth_username": "user",
|
|
"auth_password": "password",
|
|
"cluster": "cluster1",
|
|
"source": "manual",
|
|
"updateTime": "2024-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**🔧 Example Usage**
|
|
|
|
**Sử dụng với HttpClient:**
|
|
```csharp
|
|
using System.Net;
|
|
using System.Net.Http;
|
|
using System.Net.Http.Json;
|
|
|
|
var request = new ProxyRequestByFeature
|
|
{
|
|
AccessToken = "your-token",
|
|
Type = "httpv6",
|
|
Strategy = "adaptive_ranking",
|
|
TargetDomain = "facebook.com",
|
|
Country = "VN"
|
|
};
|
|
|
|
var httpClient = new HttpClient();
|
|
var response = await httpClient.PostAsJsonAsync(
|
|
"http://10.9.3.70:31249/api/resource-pool/v1/ProxyPool/get-v2",
|
|
request
|
|
);
|
|
|
|
var proxyData = await response.Content.ReadFromJsonAsync<ProxyResponse>();
|
|
|
|
// Sử dụng proxy với HttpClient
|
|
var handler = new HttpClientHandler
|
|
{
|
|
Proxy = new WebProxy($"{proxyData.Proxy.Host}:{proxyData.Proxy.Port}")
|
|
{
|
|
Credentials = new NetworkCredential(
|
|
proxyData.Proxy.AuthUsername,
|
|
proxyData.Proxy.AuthPassword
|
|
)
|
|
}
|
|
};
|
|
var proxiedClient = new HttpClient(handler);
|
|
```
|
|
|
|
**Sử dụng với RestSharp:**
|
|
```csharp
|
|
using RestSharp;
|
|
using System.Net;
|
|
|
|
var client = new RestClient("http://10.9.3.70:31249");
|
|
var request = new RestRequest("/api/resource-pool/v1/ProxyPool/get-v2", Method.Post);
|
|
request.AddJsonBody(new ProxyRequestByFeature
|
|
{
|
|
AccessToken = "your-token",
|
|
Type = "http",
|
|
Strategy = "least_delay",
|
|
TargetDomain = "instagram.com",
|
|
Country = "US"
|
|
});
|
|
|
|
var response = await client.ExecuteAsync<ProxyResponse>(request);
|
|
var proxy = response.Data.Proxy;
|
|
|
|
var proxyObj = new WebProxy($"{proxy.Host}:{proxy.Port}")
|
|
{
|
|
Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword)
|
|
};
|
|
|
|
var restClient = new RestClient("https://api.example.com")
|
|
{
|
|
Proxy = proxyObj
|
|
};
|
|
```
|
|
|
|
**Log Proxy Usage:**
|
|
|
|
**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/used`
|
|
|
|
```csharp
|
|
var logRequest = new ProxyLogRequest
|
|
{
|
|
AccessToken = "your-token",
|
|
ProxyId = proxy.Id,
|
|
StatusCode = 200,
|
|
ResponseTimeMs = 450
|
|
};
|
|
|
|
var logResponse = await client.PostAsJsonAsync(
|
|
"http://10.9.3.70:31249/api/resource-pool/v1/ProxyPool/used",
|
|
logRequest
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- The `opt.Host`, `opt.Protocol`, and `opt.Port` configuration should match your environment settings.
|
|
- In production, replace the debug configurations with the appropriate production values.
|
|
- TokenPool supports both gRPC and HTTP protocols via `AddTokenPool` extension.
|
|
- ProxyPool is accessed directly via gRPC (`IProxyService`) or HTTP REST API endpoints.
|
|
- For SOCKS5 proxy support, see [HttpToSocks5Proxy](./docs/src/HttpToSocks5Proxy/README.md).
|
|
|
|
---
|
|
|
|
## SmartPool (New System)
|
|
|
|
For the new intelligent proxy management system with SDK client, see:
|
|
- **[SmartPool SDK Documentation](./docs/src/Icomm.SmartPool.Proxy/README.md)**
|
|
- **[SmartPool API Documentation](./docs/src/Icomm.API.SmartPool/README.md)**
|
|
|
|
---
|
|
|
|
## Diagrams
|
|
|
|
- **Proxy Pool Diagram**: 
|
|
- **Token Pool Diagram**: 
|