📖 关于项目

🎯 项目简介

Proxy-v2 Autonomous Server 是一个自主运行的代理池服务端,将传统的"按需获取"模式升级为"自主维护+按需调用"的服务端架构。

系统启动后持续在后台维护代理池,通过定时任务自动执行获取、验证、质量检测和清理,并通过RESTful API返回已验证的最优代理。支持HTTP/SOCKS代理和VMess/Trojan等节点代理,提供完整的Web管理界面。

🚀 快速链接

✅ 功能完整性检查

🎯 三大需求验证

核心功能清单

🚢 部署能力

🔌 集成能力

技术架构

技术栈

系统架构

┌─────────────────────────────────────────────────────────────────┐
│                        Proxy Pool Server                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    │
│  │   FastAPI    │───▶│    Cache     │───▶│   Database   │    │
│  │   (API层)    │    │  (缓存层)    │    │  (数据层)    │    │
│  └──────────────┘    └──────────────┘    └──────────────┘    │
│         │                    │                    │            │
│         │                    │                    │            │
│  ┌──────▼────────────────────▼────────────────────▼──────┐    │
│  │              Task Scheduler (任务调度器)              │    │
│  ├───────────────────────────────────────────────────────┤    │
│  │  • 代理获取任务 (每6小时)                            │    │
│  │  • 代理验证任务 (每4小时)                            │    │
│  │  • 质量检测任务 (每8小时)                            │    │
│  │  • 清理任务 (每天凌晨2点)                            │    │
│  │  • 节点收集任务 (每2小时)                            │    │
│  └───────────────────────────────────────────────────────┘    │
│         │                    │                    │            │
│  ┌──────▼──────┐    ┌────────▼────────┐    ┌─────▼──────┐    │
│  │ Validation  │    │  Quality Check  │    │  Selector  │    │
│  │   Engine    │    │     Engine      │    │   Engine   │    │
│  └─────────────┘    └─────────────────┘    └────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
            ┌───────▼────────┐  ┌──────▼───────┐
            │  Data Sources  │  │   Clients    │
            ├────────────────┤  ├──────────────┤
            │ • 25+ 免费源   │  │ • Python     │
            │ • FOFA API     │  │ • Go         │
            │ • Hunter API   │  │ • JavaScript │
            │ • GitHub订阅   │  │ • cURL       │
            └────────────────┘  └──────────────┘
      

核心组件

• FastAPI应用: 提供RESTful API和Web界面
• Database层: SQLite数据库,管理代理、节点、源和任务日志
• Cache管理器: 内存+Redis双层缓存,提升API响应速度
• Validation引擎: 并发验证代理连通性和响应时间
• Quality检测器: 检测住宅IP、ChatGPT/Google可用性
• Smart选择器: 智能过滤和排序,返回最优代理
• Task调度器: APScheduler管理后台定时任务
• Rate限制器: 控制请求频率,避免触发源的风控
• Error处理器: 自动重试、降级处理、异常捕获

性能指标

🎯 三种使用模式 - 满足所有场景需求

本系统提供三种灵活的使用模式,所有模式均无需二开,满足不同场景需求:

📊 模式对比一览表

详细说明

# 1. 复制 server/ 目录到你的项目
cp -r server/ your-project/

# 2. 在代码中导入使用 (无需启动服务器!)
from server.client import get_proxy

# 获取代理 - 一行代码搞定
proxy = await get_proxy(protocol="http", country="US")
print(f"代理: {proxy.url}, 评分: {proxy.score}")

# 批量获取
proxies = await get_proxies(count=10, min_score=80)

# Docker一键部署
docker-compose up -d

# Python调用
import requests
response = requests.post(
    "http://your-server:8888/api/proxy/acquire",
    json={"protocol": "http", "country": "US"}
)
proxy = response.json()

# Go调用
resp, _ := http.Post("http://your-server:8888/api/proxy/acquire", ...)

# JavaScript调用
const proxy = await fetch('http://your-server:8888/api/proxy/acquire', {
  method: 'POST',
  body: JSON.stringify({protocol: 'http'})
}).then(r => r.json());

# 启动本地代理服务器
cd local-proxy-server
python -m proxy_server

# 方式1: 修改代码中的代理配置
proxies = {'http': 'http://127.0.0.1:9999'}

# 方式2: 设置环境变量 (全局生效,无需修改代码)
export http_proxy=http://127.0.0.1:9999
export https_proxy=http://127.0.0.1:9999

# 所有程序自动使用代理
curl https://api.ipify.org
python your_script.py

🎯 如何选择?

部署方式

Docker部署 (推荐)

# 一键部署
./deploy.sh

# 或手动部署
docker-compose up -d

# 查看日志
docker-compose logs -f

系统服务部署

# 安装依赖
pip install -r requirements.txt

# 创建systemd服务
sudo cp proxy-pool.service /etc/systemd/system/
sudo systemctl enable proxy-pool
sudo systemctl start proxy-pool

Nginx反向代理

# 配置Nginx
sudo cp nginx.conf /etc/nginx/sites-available/proxy-pool
sudo ln -s /etc/nginx/sites-available/proxy-pool /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

详细部署指南请参考 DEPLOYMENT.md

后台任务

系统自动执行以下后台任务,无需手动干预:

数据源

HTTP/SOCKS代理源

• 免费源: 25+ 免费代理网站 (ProxyList, FreeProxyList, GeoNode等)
• FOFA搜索引擎: 通过FOFA API搜索全球代理服务器 (需要API密钥)
• Hunter搜索引擎: 网络空间搜索引擎 (需要API密钥)
• Kookeey API: 付费代理API服务 (需要API密钥)

节点代理源

• GitHub订阅源: 15+ GitHub仓库的免费节点订阅
• 自定义订阅: 支持添加自定义订阅URL

速率限制保护

• GitHub请求间隔: 最小10秒
• 并发限制: 最多5个并发请求
• User-Agent轮换: 避免被识别为爬虫
• 指数退避重试: 失败后自动重试

质量保证

验证机制

• 连通性验证: 测试代理是否能够正常连接
• 响应时间记录: 记录每个代理的响应时间
• 成功率统计: 计算代理的历史成功率
• 并发验证: 最多50个并发线程,快速验证大量代理

质量检测

• 住宅IP识别: 区分数据中心IP和住宅IP
• ChatGPT可用性: 测试是否能访问ChatGPT
• Google可用性: 测试是否能访问Google
• IP地理位置: 获取IP的国家、城市信息
• 风险评估: 评估IP的风险等级和风险分数

智能评分

综合考虑多个因素计算代理评分(0-100):

• 响应时间 (30%): 越快评分越高
• 成功率 (30%): 历史成功率越高评分越高
• 质量属性 (40%): 住宅IP、ChatGPT/Google可用性加分

测试覆盖

项目包含完整的测试套件,确保代码质量和功能正确性:

测试类型

• 单元测试: 测试各个模块的独立功能
• 集成测试: 测试多个组件协作
• API测试: 测试所有API端点
• 性能测试: 验证API响应时间和并发能力
• 压力测试: 测试大量数据场景(10,000+ 代理, 50,000+ 节点)

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_integration.py

# 生成覆盖率报告
pytest --cov=. --cov-report=html

文档资源

📖 使用指南

• API文档 - 完整的API接口文档和使用示例
• Swagger文档 - 交互式API文档,可在线测试
• README.md - 项目介绍和快速开始指南
• DUAL_MODE.md - 嵌入式模块和独立服务端双模式说明

🚢 部署指南

• DEPLOYMENT.md - 生产环境部署指南
• DOCKER_DEPLOYMENT.md - Docker部署详细指南
• 本地代理服务器文档 - 零代码集成模式说明

🔧 开发与维护

• DEVELOPMENT.md - 开发者指南和代码规范
• TROUBLESHOOTING.md - 故障排查和常见问题

开发历程

项目采用Spec驱动开发方法论,经过10个阶段的系统化开发:

许可证

本项目采用 MIT License 开源许可证。

联系方式

如有问题或建议,请通过以下方式联系:

• GitHub Issues: 提交Issue
• Pull Requests: 欢迎贡献代码
• 文档: 查看项目文档获取更多信息

致谢

感谢以下开源项目和服务:

• FastAPI - 现代化的Python Web框架
• SQLite - 轻量级嵌入式数据库
• Redis - 高性能缓存系统
• APScheduler - Python任务调度库
• Chart.js - 数据可视化库
• ZenProxy - UI设计灵感来源
• 所有免费代理源 - 提供免费代理数据