aggregator

1. 免费代理聚合项目使用手册

1.1. 如何同步原仓库的更新

1.2. 添加上游仓库（只需要设置一次）

# 查看当前远程仓库
git remote -v

# 添加上游仓库（假设原仓库是 wzdnzd/aggregator）
git remote add upstream https://github.com/wzdnzd/aggregator.git

1.3. 项目简介

这是一个自动抓取、验证和聚合免费代理节点的项目。它可以：

  • 自动抓取多个来源的免费节点
  • 自动验证节点可用性
  • 转换为 Clash/V2ray 等多种格式
  • 自动更新到 Gist 用于订阅

1.4. 使用前准备

1.5. 必要条件

  • Python 3.6+
  • Git
  • GitHub 账号（用于创建 Gist）

1.6. 克隆项目

git clone https://github.com/baoyu0/aggregator.git
cd aggregator

1.7. 首先需要准备环境

# 1. 创建并激活 Python 虚拟环境
conda create -n aggregator python=3.12
conda activate aggregator

1.8. 安装依赖

pip install -r requirements.txt

1.9. 配置必要的环境变量

需要在项目根目录创建 .env 文件,包含以下配置:

# 订阅配置文件路径
SUBSCRIBE_CONF=subscribe/config/config.json

# GitHub Personal Access Token (需要自行创建)
PUSH_TOKEN=your_github_token

# GitHub Gist 信息 (需要自行创建)
GIST_LINK=your_username/your_gist_id

# 其他配置项
SKIP_ALIVE_CHECK=false  # 是否跳过节点存活检查
SKIP_REMARK=false      # 是否跳过备注
ENABLE_SPECIAL_PROTOCOLS=false  # 是否启用特殊协议

1.10. 配置订阅信息

需要在 subscribe/config/ 目录下创建 config.json 文件,配置代理服务器信息。可以参考 tools/config.json 的格式。

1.11. 复制配置文件模板

cp subscribe/config/config.default.json subscribe/config/config.json

1.12. 创建 .env 文件并配置相应参数

1.12.1. 在 Windows 10 系统中，有几种方法可以使用 PowerShell 创建 .env 文件

1.12.2. 使用 New-Item 命令（推荐）

New-Item .env -ItemType File

1.12.3. 使用 Echo 命令

echo "" > .env

1.12.4. 如果需要同时创建文件并添加初始内容

@"
NODE_ENV=development
PORT=3000
DATABASE_URL=your_database_url
API_KEY=your_api_key
"@ | Out-File -FilePath .env -Encoding UTF8

[!NOTE] 注意事项：

  • 建议使用 UTF8 编码，避免中文显示乱码
  • .env 文件应该添加到 .gitignore 中，避免敏感信息泄露
  • 建议同时创建一个 .env.example 文件作为模板，供团队成员参考，但不包含实际的敏感信息

1.12.5. 如果需要将 .env 添加到 .gitignore，可以执行

echo ".env" >> .gitignore

1.13. 配置文件模版

SUBSCRIBE_CONF=subscribe/config/config.json
PUSH_TOKEN=your_github_token    # GitHub 个人访问令牌
GIST_LINK=your_gist_id         # Gist ID
SKIP_ALIVE_CHECK=false
SKIP_REMARK=false
ENABLE_SPECIAL_PROTOCOLS=false

1.14. 实际配置文件

# 订阅配置文件路径
SUBSCRIBE_CONF=subscribe/config/config.json

# GitHub Personal Access Token (需要自行创建)
PUSH_TOKEN=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

# GitHub Gist 信息 (需要自行创建)
GIST_LINK=baoyu0/91e0de90aafc53d1c690260523c972fd

# 其他配置项
SKIP_ALIVE_CHECK=false  # 是否跳过节点存活检查
SKIP_REMARK=false      # 是否跳过备注
ENABLE_SPECIAL_PROTOCOLS=false  # 是否启用特殊协议

1.15. 基本使用

1.16. 运行项目

根据 README.md 的说明,有两个主要入口:

# 方式一: 使用 collect.py (基础功能)
python subscribe/collect.py

# 方式二: 使用 process.py (推荐,功能更完整)
python subscribe/process.py

1.17. Docker 运行 (可选)

也可以使用 Docker 运行:

# 构建镜像
docker buildx build --platform linux/amd64 -f Dockerfile -t aggregator:latest .

# 运行容器
docker run -d \
  -e GIST_PAT="your_github_token" \
  -e GIST_LINK="your_username/your_gist_id" \
  aggregator:latest

1.18. 完整的参数说明

python subscribe/process.py --help  # 查看帮助信息

# 常用参数说明：
# -h, --help            显示帮助信息
# -c, --check          仅检查配置
# -e ENVIRONMENT       指定环境配置文件
# -f, --force          强制更新
# -i, --invisible      隐藏进度条
# -n NUM, --num NUM    并发数量
# -o, --overwrite      覆盖现有配置
# -r RETRY, --retry RETRY  重试次数
# -s SERVER, --server SERVER  服务器地址
# -t TIMEOUT, --timeout TIMEOUT  超时时间
# -u URL, --url URL    指定URL

1.19. 使用生成的订阅

程序会生成两种格式的订阅链接：

1.20. Clash 配置

1.20.1. 模版

https://gist.githubusercontent.com/你的用户名/gist_id/raw/clash.yaml

1.20.2. 实际配置

https://gist.githubusercontent.com/baoyu0/91e0de90aafc53d1c690260523c972fd/raw/clash.yaml

1.21. V2ray 配置

1.21.1. 模板

https://gist.githubusercontent.com/你的用户名/gist_id/raw/v2ray.txt

1.21.2. 实际配置

https://gist.githubusercontent.com/baoyu0/91e0de90aafc53d1c690260523c972fd/raw/v2ray.txt

1.22. 在客户端中使用

1.23. Clash 用户

  1. 打开 Clash 客户端
  2. 转到配置页面
  3. 添加订阅,粘贴 Clash 配置链接
  4. 点击下载/更新

1.24. V2ray 用户

  1. 打开 V2rayN
  2. 点击订阅设置
  3. 添加订阅,粘贴 V2ray 配置链接
  4. 更新订阅

1.25. 进阶配置

1.26. 添加自定义节点源

修改 config.json 中的 domains 部分以添加新的节点源。

{
    "domains": [
        {
            "name": "自定义名称",
            "enable": true,
            "push_to": ["default"],
            "sub": ["订阅链接1", "订阅链接2"]
        }
    ]
}

1.27. 自动更新

项目通过 GitHub Actions 实现自动更新：

  1. 每天 03:05 和 11:05 自动运行
  2. 自动检测节点可用性
  3. 自动更新到 Gist

1.28. 常见问题

1.29. 节点无法使用

  1. 这些是免费节点，稳定性无法保证。
  2. 建议设置客户端定期自动更新订阅。
  3. 程序会自动过滤不可用节点。

1.30. 配置文件错误

  1. 检查 .env 文件中的 token 是否正确。
  2. 确保 Gist ID 填写正确。
  3. 确保配置文件格式正确。

1.31. 更新频率

  1. 默认每天自动更新两次
  2. 也可以手动运行程序更新
  3. 建议客户端设置为每天自动更新订阅

1.32. 注意事项

  1. 仅供学习交流使用
  2. 请勿用于非法用途
  3. 免费节点稳定性有限
  4. 建议定期更新订阅