Sync README files from source repository [skip ci]
This commit is contained in:
Gitea Actions
@@ -0,0 +1,408 @@
|
||||
# SmartPool Troubleshooting Guide
|
||||
|
||||
## Problem: "No proxy available matching criteria"
|
||||
|
||||
### Quick Fix
|
||||
|
||||
```bash
|
||||
# 1. Initialize database
|
||||
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_init.sql
|
||||
|
||||
# 2. Add test data
|
||||
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_test_data.sql
|
||||
|
||||
# 3. Test API
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"accessToken": "test"}'
|
||||
```
|
||||
|
||||
## Diagnosis Steps
|
||||
|
||||
### Step 1: Verify Database Setup
|
||||
|
||||
```sql
|
||||
-- Check databases exist
|
||||
SHOW DATABASES LIKE '%smart_pool%';
|
||||
|
||||
-- Should show:
|
||||
-- smart_pool_meta
|
||||
-- smart_pool_logs
|
||||
```
|
||||
|
||||
### Step 2: Check Tables
|
||||
|
||||
```sql
|
||||
-- Check meta tables
|
||||
SHOW TABLES FROM smart_pool_meta;
|
||||
|
||||
-- Should show:
|
||||
-- proxy_metadata
|
||||
-- proxy_access_mapping
|
||||
|
||||
-- Check data count
|
||||
SELECT count() FROM smart_pool_meta.proxy_metadata;
|
||||
SELECT count() FROM smart_pool_meta.proxy_access_mapping;
|
||||
```
|
||||
|
||||
### Step 3: Verify Proxy Data
|
||||
|
||||
```sql
|
||||
-- Check proxies
|
||||
SELECT
|
||||
id,
|
||||
host,
|
||||
port,
|
||||
protocol,
|
||||
cluster,
|
||||
status
|
||||
FROM smart_pool_meta.proxy_metadata FINAL
|
||||
LIMIT 10;
|
||||
|
||||
-- Check active proxies
|
||||
SELECT
|
||||
status,
|
||||
count() as count
|
||||
FROM smart_pool_meta.proxy_metadata FINAL
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
### Step 4: Verify Access Mappings
|
||||
|
||||
```sql
|
||||
-- Check your access_token mappings
|
||||
SELECT *
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL
|
||||
WHERE access_token = 'YOUR_TOKEN';
|
||||
|
||||
-- Check all mappings
|
||||
SELECT
|
||||
access_token,
|
||||
cluster,
|
||||
count() as count
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL
|
||||
GROUP BY access_token, cluster;
|
||||
```
|
||||
|
||||
### Step 5: Test the JOIN Query
|
||||
|
||||
```sql
|
||||
-- This is the query SmartPool uses internally
|
||||
SELECT
|
||||
m.id,
|
||||
m.host,
|
||||
m.port,
|
||||
m.protocol,
|
||||
m.cluster
|
||||
FROM smart_pool_meta.proxy_metadata FINAL m
|
||||
INNER JOIN smart_pool_meta.proxy_access_mapping FINAL a
|
||||
ON m.cluster = a.cluster
|
||||
WHERE a.access_token = 'test' -- Replace with your token
|
||||
AND m.status = 1
|
||||
ORDER BY m.id;
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue 1: Empty Result Set
|
||||
|
||||
**Symptoms:**
|
||||
```json
|
||||
{
|
||||
"proxy": null,
|
||||
"message": "No proxy available matching criteria",
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
1. No data in database
|
||||
2. Access token not mapped to any cluster
|
||||
3. All proxies are inactive (status = 0)
|
||||
4. Cluster names don't match between tables
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Add test data
|
||||
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_test_data.sql
|
||||
```
|
||||
|
||||
### Issue 2: Wrong Access Token
|
||||
|
||||
**Symptoms:**
|
||||
- Query returns empty but data exists
|
||||
|
||||
**Check:**
|
||||
```sql
|
||||
-- See which tokens have access
|
||||
SELECT DISTINCT access_token
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL;
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Use one of the existing tokens or add a new mapping:
|
||||
```sql
|
||||
INSERT INTO smart_pool_meta.proxy_access_mapping (access_token, cluster)
|
||||
VALUES ('your_token', 'cluster_vn_http');
|
||||
```
|
||||
|
||||
### Issue 3: No Proxies in Cluster
|
||||
|
||||
**Symptoms:**
|
||||
- Mapping exists but no proxies returned
|
||||
|
||||
**Check:**
|
||||
```sql
|
||||
-- Find orphaned mappings
|
||||
SELECT
|
||||
a.access_token,
|
||||
a.cluster,
|
||||
count(m.id) as proxy_count
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL a
|
||||
LEFT JOIN smart_pool_meta.proxy_metadata FINAL m
|
||||
ON a.cluster = m.cluster AND m.status = 1
|
||||
GROUP BY a.access_token, a.cluster
|
||||
HAVING proxy_count = 0;
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Add proxies to the cluster or change mapping to existing cluster.
|
||||
|
||||
### Issue 4: Proxies Inactive
|
||||
|
||||
**Check:**
|
||||
```sql
|
||||
-- Check inactive proxies
|
||||
SELECT
|
||||
cluster,
|
||||
count() as inactive_count
|
||||
FROM smart_pool_meta.proxy_metadata FINAL
|
||||
WHERE status = 0
|
||||
GROUP BY cluster;
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```sql
|
||||
-- Activate all proxies in a cluster
|
||||
ALTER TABLE smart_pool_meta.proxy_metadata
|
||||
UPDATE status = 1
|
||||
WHERE cluster = 'cluster_vn_http';
|
||||
```
|
||||
|
||||
### Issue 5: Cluster Name Mismatch
|
||||
|
||||
**Check:**
|
||||
```sql
|
||||
-- Clusters in proxy_metadata
|
||||
SELECT DISTINCT cluster
|
||||
FROM smart_pool_meta.proxy_metadata FINAL;
|
||||
|
||||
-- Clusters in proxy_access_mapping
|
||||
SELECT DISTINCT cluster
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL;
|
||||
|
||||
-- Find mismatches
|
||||
SELECT cluster, 'In mapping but not in metadata' as issue
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL
|
||||
WHERE cluster NOT IN (
|
||||
SELECT DISTINCT cluster
|
||||
FROM smart_pool_meta.proxy_metadata FINAL
|
||||
);
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Fix cluster names to match:
|
||||
```sql
|
||||
-- Update cluster name in metadata
|
||||
ALTER TABLE smart_pool_meta.proxy_metadata
|
||||
UPDATE cluster = 'cluster_vn_http'
|
||||
WHERE cluster = 'old_cluster_name';
|
||||
```
|
||||
|
||||
## Testing with cURL
|
||||
|
||||
### Basic Request (No Filters)
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"accessToken": "test"
|
||||
}'
|
||||
```
|
||||
|
||||
### With Strategy
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"accessToken": "test",
|
||||
"strategy": "random"
|
||||
}'
|
||||
```
|
||||
|
||||
### With Filters
|
||||
|
||||
```bash
|
||||
# Filter by country
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"accessToken": "test",
|
||||
"country": "VN"
|
||||
}'
|
||||
|
||||
# Filter by protocol
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"accessToken": "test",
|
||||
"protocol": "socks5"
|
||||
}'
|
||||
|
||||
# Multiple filters
|
||||
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"accessToken": "test",
|
||||
"strategy": "least_delay",
|
||||
"country": "US",
|
||||
"protocol": "http",
|
||||
"ipVersion": "v4",
|
||||
"targetDomain": "example.com"
|
||||
}'
|
||||
```
|
||||
|
||||
## Expected Responses
|
||||
|
||||
### Success Response
|
||||
|
||||
```json
|
||||
{
|
||||
"proxy": {
|
||||
"id": 1,
|
||||
"host": "103.90.227.1",
|
||||
"port": 8080,
|
||||
"protocol": "http",
|
||||
"ipVersion": "v4",
|
||||
"country": "VN",
|
||||
"location": "Hanoi",
|
||||
"authUsername": "",
|
||||
"authPassword": "",
|
||||
"cluster": "cluster_vn_http",
|
||||
"source": "manual",
|
||||
"description": "Vietnam HTTP proxy 1",
|
||||
"status": 1
|
||||
},
|
||||
"message": null,
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response
|
||||
|
||||
```json
|
||||
{
|
||||
"proxy": null,
|
||||
"message": "No proxy available matching criteria",
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
## Filter Logic
|
||||
|
||||
SmartPool uses **optional filters** - if a filter is not provided, it won't be applied:
|
||||
|
||||
| Filter | Behavior if Empty/Null |
|
||||
|--------|----------------------|
|
||||
| `accessToken` | **Required** - returns error if missing |
|
||||
| `strategy` | Defaults to `"random"` |
|
||||
| `targetDomain` | Not filtered - returns all proxies |
|
||||
| `ipVersion` | Not filtered - returns v4 and v6 |
|
||||
| `protocol` | Not filtered - returns http, socks5, etc. |
|
||||
| `country` | Not filtered - returns all countries |
|
||||
| `refererProxy` | Only used in "alternative" strategy |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"accessToken": "test"
|
||||
// No filters = returns ALL proxies accessible by 'test' token
|
||||
}
|
||||
```
|
||||
|
||||
## Debug Queries
|
||||
|
||||
Run these in `clickhouse-client`:
|
||||
|
||||
```bash
|
||||
# Interactive mode
|
||||
clickhouse-client
|
||||
|
||||
# Or load debug script
|
||||
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_debug.sql
|
||||
```
|
||||
|
||||
Key queries:
|
||||
|
||||
```sql
|
||||
-- See everything accessible by a token
|
||||
SELECT
|
||||
m.*
|
||||
FROM smart_pool_meta.proxy_metadata FINAL m
|
||||
INNER JOIN smart_pool_meta.proxy_access_mapping FINAL a
|
||||
ON m.cluster = a.cluster
|
||||
WHERE a.access_token = 'test'
|
||||
AND m.status = 1;
|
||||
|
||||
-- Count by cluster
|
||||
SELECT
|
||||
a.cluster,
|
||||
count(m.id) as proxy_count
|
||||
FROM smart_pool_meta.proxy_access_mapping FINAL a
|
||||
LEFT JOIN smart_pool_meta.proxy_metadata FINAL m
|
||||
ON a.cluster = m.cluster AND m.status = 1
|
||||
WHERE a.access_token = 'test'
|
||||
GROUP BY a.cluster;
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're still having issues:
|
||||
|
||||
1. Check application logs: `logs/smartpool-*.log`
|
||||
2. Check ClickHouse logs
|
||||
3. Enable debug logging in `appsettings.json`:
|
||||
```json
|
||||
{
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Debug"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
4. Run all diagnostic queries in `clickhouse_debug.sql`
|
||||
5. Share the output for further assistance
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `clickhouse_init.sql` | Initialize database schema |
|
||||
| `clickhouse_test_data.sql` | Add sample data for testing |
|
||||
| `clickhouse_debug.sql` | Diagnostic queries |
|
||||
| `README.md` | Full documentation |
|
||||
| `logs/smartpool-*.log` | Application logs |
|
||||
|
||||
## Test Access Tokens
|
||||
|
||||
After running `clickhouse_test_data.sql`, these tokens are available:
|
||||
|
||||
| Token | Access |
|
||||
|-------|--------|
|
||||
| `test` | All clusters (10 proxies) |
|
||||
| `user1_token` | VN clusters only (3 proxies) |
|
||||
| `user2_token` | US + Global (4 proxies) |
|
||||
| `user3_token` | JP clusters only (2 proxies) |
|
||||
Reference in New Issue
Block a user