Skip to content

Commit d6edc08

Browse files
wzdnzdwzdnzd
committed
chore: add user guides
1 parent e71597a commit d6edc08

4 files changed

Lines changed: 2915 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 227 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,236 @@
1-
<!--
2-
* @Author: wzdnzd
3-
* @Date: 2022-03-06 14:51:29
4-
* @Description:
5-
* Copyright (c) 2022 by wzdnzd, All Rights Reserved.
6-
-->
1+
# Aggregator - 免费代理池构建工具
72

8-
## 功能
9-
打造免费代理池，爬一切可爬节点
10-
> 拥有灵活的插件系统，如果目标网站特殊，现有功能未能覆盖，可针对性地通过插件实现
3+
[![GitHub stars](https://img.shields.io/github/stars/wzdnzd/aggregator.svg)](https://github.com/wzdnzd/aggregator/stargazers)
4+
[![GitHub forks](https://img.shields.io/github/forks/wzdnzd/aggregator.svg)](https://github.com/wzdnzd/aggregator/network)
5+
[![GitHub issues](https://img.shields.io/github/issues/wzdnzd/aggregator.svg)](https://github.com/wzdnzd/aggregator/issues)
6+
[![License](https://img.shields.io/github/license/wzdnzd/aggregator.svg)](https://github.com/wzdnzd/aggregator/blob/main/LICENSE)
117

12-
> 欢迎 Star 及 PR。对于质量较高且普适的爬取目标，亦可在 Issues 中列出，将在评估后选择性添加
138

14-
## 使用方法
15-
> 可前往 [Issue #91](https://github.com/wzdnzd/aggregator/issues/91) 食用**共享订阅**，量大质优。**请勿浪费**
16-
17-
略，自行探索。我才不会告诉你入口是 `collect.py` 和 `process.py`。**强烈建议使用后者，前者只是个小玩具**，配置参考 `subscribe/config/config.default.json`，详细文档见 [DeepWiki](https://deepwiki.com/wzdnzd/aggregator)
189

10+
## 🎯 项目简介
11+
12+
一个强大的免费代理池构建工具，通过爬取多个平台/网页的代理资源，自动验证、聚合并转换为各种客户端所需格式。
13+
14+
### ✨ 核心特性
15+
16+
- **🕷️ 多源爬取** - Telegram、GitHub、Google、Yandex、Twitter 等
17+
- **🔍 智能验证** - 自动检测代理活性和质量
18+
- **🔄 格式转换** - 支持 Clash、V2Ray、SingBox 等格式
19+
- **💾 灵活存储** - GitHub Gist、PasteGG、Imperial 等多种后端
20+
- **🔌 插件系统** - 可扩展的自定义爬取架构
21+
- **⚡ 高效处理** - 多线程并发，批量处理
22+
23+
### 🌐 支持协议
24+
VMess | Trojan | SS | SSR | Snell | Hysteria2 | VLESS | Hysteria | TUIC | AnyTLS | HTTP | SOCKS
25+
26+
## 🚀 两种使用方式
27+
28+
### 方式一：process.py（推荐）
29+
**完整功能版本** - 支持复杂配置、多源爬取、自定义规则
30+
31+
```bash
32+
# 1. 准备配置文件
33+
cp subscribe/config/config.default.json my-config.json
34+
35+
# 2. 设置环境变量
36+
export PUSH_TOKEN=your_github_token
37+
38+
# 3. 运行处理
39+
python subscribe/process.py -s my-config.json
40+
```
41+
42+
**适用场景**：
43+
- 需要精细控制爬取规则
44+
- 多分组输出管理
45+
- 自定义存储后端
46+
- 定时自动化运行
47+
48+
### 方式二：collect.py
49+
**简化版本** - 快速收集机场订阅
50+
51+
```bash
52+
# 直接运行，自动收集并上传到 Gist
53+
python subscribe/collect.py \
54+
-g username/gist-id \
55+
-k your-github-token \
56+
-t clash v2ray singbox
57+
```
58+
59+
**适用场景**：
60+
- 快速获取免费代理
61+
- 个人日常使用
62+
- 不需要复杂配置
63+
64+
### 🎁 共享订阅
65+
> 可前往 [Issue #91](https://github.com/wzdnzd/aggregator/issues/91) 获取现成的**共享订阅**，量大质优。**请勿浪费**
66+
67+
## 📊 工作流程
68+
69+
```mermaid
70+
graph LR
71+
A[开始] --> B{选择方式}
72+
B -->|简单| C[collect.py]
73+
B -->|完整| D[process.py]
74+
75+
C --> E[自动收集机场]
76+
E --> F[注册账号]
77+
F --> G[获取订阅]
78+
G --> H[验证代理]
79+
H --> I[上传到Gist]
80+
81+
D --> J[加载配置]
82+
J --> K[多源爬取]
83+
K --> L[聚合处理]
84+
L --> M[质量检测]
85+
M --> N[格式转换]
86+
N --> O[推送存储]
87+
```
88+
89+
## ⚡ 快速配置
90+
91+
### 最小配置示例
92+
93+
**process.py 配置**：
94+
```json
95+
{
96+
"domains": [
97+
{
98+
"name": "example-airport",
99+
"domain": "example.com",
100+
"push_to": ["free"]
101+
}
102+
],
103+
"crawl": {
104+
"enable": true,
105+
"telegram": {
106+
"enable": true,
107+
"users": {
108+
"proxy_channel": {
109+
"push_to": ["free"]
110+
}
111+
}
112+
}
113+
},
114+
"groups": {
115+
"free": {
116+
"targets": {"clash": "free-clash"}
117+
}
118+
},
119+
"storage": {
120+
"engine": "gist",
121+
"items": {
122+
"free-clash": {
123+
"username": "your-username",
124+
"gistid": "your-gist-id",
125+
"filename": "clash.yaml"
126+
}
127+
}
128+
}
129+
}
130+
```
131+
132+
**环境变量**：
133+
```bash
134+
export PUSH_TOKEN=your_github_token
135+
```
136+
137+
### 常用命令
138+
139+
```bash
140+
# 快速收集（推荐新手）
141+
python subscribe/collect.py -g username/gist-id -k token
142+
143+
# 完整处理（推荐进阶）
144+
python subscribe/process.py -s config.json
145+
146+
# 仅检查代理活性
147+
python subscribe/process.py -s config.json --check
148+
149+
# 高性能模式
150+
python subscribe/process.py -s config.json -n 128
151+
```
152+
153+
154+
## 📚 相关文档
155+
156+
| 文档 | 说明 | 适用人群 |
157+
| ---------------------------- | --------------- | ------------------- |
158+
| [完整文档](README_CN.md) | 详细配置说明 | 进阶用户 |
159+
| [English Docs](README_EN.md) | English version | International users |
160+
161+
162+
## 🔧 常见问题
163+
164+
| 问题 | 解决方案 |
165+
| ------------ | ------------------------------------------ |
166+
| 配置文件错误 | `python -m json.tool config.json` 验证语法 |
167+
| Token 无效 | 检查 GitHub Token 权限和有效期 |
168+
| 网络超时 | 增加超时 `-t 15000` 或减少线程 `-n 16` |
169+
| 无代理输出 | 检查爬取源配置和网络连接 |
170+
171+
172+
### 插件开发
173+
拥有灵活的插件系统，支持自定义爬取目标。欢迎贡献高质量的爬取插件！
174+
175+
## 🚧 TODO 路线图
176+
177+
### 架构重构
178+
- [ ] **核心接口设计** - 抽象出 `ICrawler`、`IStorage`、`IConverter` 等核心接口
179+
- [ ] **基类实现** - 创建 `BaseCrawler`、`BaseStorage`、`BaseConverter` 抽象基类
180+
- [ ] **具体实现重构** - 将现有爬虫、存储、转换模块改为继承基类并实现接口
181+
- [ ] **工厂模式** - 使用工厂模式动态创建爬虫和存储实例，提升扩展性
182+
- [ ] **模块解耦** - 通过接口依赖替代直接依赖，降低模块间耦合度
183+
184+
### 插件化架构
185+
- [ ] **爬虫插件化** - 将 Telegram、GitHub、Google 等爬虫重构为独立插件
186+
- [ ] **存储插件化** - 将 Gist、PasteGG、Imperial 等存储后端重构为插件
187+
- [ ] **插件注册机制** - 实现插件自动发现和注册系统
188+
- [ ] **插件配置标准化** - 定义统一的插件配置规范和验证机制
189+
190+
### 配置系统优化
191+
- [ ] **配置模型化** - 使用 Pydantic 定义强类型配置模型
192+
- [ ] **配置验证增强** - 实现配置完整性检查和错误提示
193+
- [ ] **配置模板化** - 提供常用场景的配置模板和生成工具
194+
- [ ] **配置文档化** - 自动生成配置项说明文档
195+
196+
### 代码质量提升
197+
- [ ] **类型系统完善** - 全面引入类型注解，提升 IDE 支持和代码安全性
198+
- [ ] **异常体系重构** - 设计统一的异常层次结构和错误码系统
199+
- [ ] **日志标准化** - 实现结构化日志和统一的日志格式
200+
- [ ] **代码风格统一** - 集成 Black、isort、flake8 等工具链
201+
202+
### 性能与稳定性
203+
- [ ] **并发模型优化** - 改进线程池管理和任务调度机制
204+
- [ ] **资源管理** - 实现连接池和资源自动回收机制
205+
- [ ] **容错能力增强** - 完善重试策略和降级处理逻辑
206+
- [ ] **内存优化** - 优化大数据处理的内存使用效率
207+
208+
---
209+
210+
## ⚖️ 免责声明
19211

20-
## 免责申明
21212
+ 本项目仅用作学习爬虫技术，请勿滥用，不要通过此工具做任何违法乱纪或有损国家利益之事
22213
+ 禁止使用该项目进行任何盈利活动，对一切非法使用所产生的后果，本人概不负责
214+
+ 使用者应遵守当地法律法规，尊重网站服务条款，合理使用网络资源
215+
216+
## 🙏 致谢
217+
218+
### 核心依赖
219+
- [Subconverter](https://github.com/asdlokj1qpi233/subconverter) - 订阅转换核心
220+
- [Mihomo](https://github.com/MetaCubeX/mihomo) - 代理测试引擎
221+
222+
### 赞助支持
223+
感谢以下组织的赞助支持：
224+
- [![YXVM](https://support.nodeget.com/page/promotion?id=250)](https://yxvm.com)
225+
- [NodeSupport](https://github.com/NodeSeekDev/NodeSupport)
226+
227+
### 社区贡献
228+
感谢所有为项目贡献代码、提出建议和报告问题的开发者们！
229+
230+
<div align="center">
231+
232+
**如果这个项目对你有帮助，请给它一个 ⭐**
23233

24-
## 致谢
25-
1. <u>[Subconverter](https://github.com/asdlokj1qpi233/subconverter)</u>、<u>[Mihomo](https://github.com/MetaCubeX/mihomo)</u>
234+
[报告问题](https://github.com/wzdnzd/aggregator/issues) · [功能请求](https://github.com/wzdnzd/aggregator/issues) · [贡献代码](https://github.com/wzdnzd/aggregator/pulls)
26235

27-
2. 感谢 [![YXVM](https://support.nodeget.com/page/promotion?id=250)](https://yxvm.com)
28-
[NodeSupport](https://github.com/NodeSeekDev/NodeSupport) 赞助了本项目
236+
</div>

0 commit comments

Comments
 (0)