🌐 Clash Subscription Aggregator

Clash / mihomo Multi-Subscription Proxy Bridge

Merge multiple Clash/mihomo proxy subscriptions into one unified HTTP/SOCKS5 proxy endpoint.
Web dashboard + RESTful API for node management, line switching, and health checking.

将多个 Clash 代理订阅聚合为统一代理入口，提供 Web 管理面板 + REST API，集中管理节点、切换线路、健康检查

🔗 多订阅聚合

🖥️ Web 面板

🎯 地区过滤

🔀 API 切换

📡 标准代理

🛡️ Token 认证

🔄 进程守护

💊 健康检查

---

📸 界面预览

Token 登录	订阅管理
节点列表 & 切换	健康检查

---

工作原理

                          ┌──────────────────────────┐
程序/脚本/Proxifier  ───→  │  VPS (代理端口)           │ ───→ 代理节点 ───→ 目标网站
                          │  mihomo 内核              │
浏览器/curl         ───→  │  VPS (Web 面板 + API)     │
                          └──────────────────────────┘

---

🚀 快速开始

1. 安装 mihomo

wget https://github.com/MetaCubeX/mihomo/releases/download/v1.19.20/mihomo-linux-amd64-v1.19.20.gz
gunzip mihomo-linux-amd64-v1.19.20.gz
chmod +x mihomo-linux-amd64-v1.19.20
mv mihomo-linux-amd64-v1.19.20 /usr/local/bin/mihomo

2. 编译运行

git clone https://github.com/LordVibeCoding/clash-sub-aggregator.git
cd clash-sub-aggregator
vim configs/app.yaml  # 修改 token 和端口
make run              # 自动编译前端 + 后端并启动

3. Docker

docker compose up -d

📋 Systemd 部署（推荐生产环境）

make build

cat > /etc/systemd/system/clash-aggregator.service << EOF
[Unit]
Description=Clash Subscription Aggregator
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/clash-aggregator
ExecStart=/opt/clash-aggregator/clash-sub-aggregator
Restart=always
RestartSec=5
Environment=CONFIG_PATH=configs/app.yaml

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now clash-aggregator

🔒 Nginx + HTTPS（推荐）

server {
    listen 80;
    server_name your-domain.com;

    root /opt/clash-aggregator/static;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 120s;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

# 自动申请 SSL 证书
certbot --nginx -d your-domain.com

---

⚙️ 配置

server:
  port: 8080                    # 管理 API 端口
  token: "your-secure-token"    # API 认证 Token（必须修改）

mihomo:
  binary: "/usr/local/bin/mihomo"
  config_dir: "./data"
  http_port: 7890               # HTTP/SOCKS5 混合代理端口
  socks_port: 7891              # SOCKS5 代理端口
  controller_port: 9090
  controller_secret: ""

data_dir: "./data"

---

📖 API

所有请求需携带 Authorization: Bearer <token>

方法	路径	说明
POST	/api/subscriptions	添加订阅
GET	/api/subscriptions	列出所有订阅
DELETE	/api/subscriptions/:id	删除订阅
POST	/api/subscriptions/refresh	刷新所有订阅
POST	/api/subscriptions/:id/refresh	刷新单个订阅
GET	/api/proxies	列出所有代理节点
PUT	/api/proxies/:group/:name	切换节点
GET	/api/proxies/:name/delay	测试节点延迟
GET	/api/status	服务状态
GET	/api/health	健康检查状态
POST	/api/health/check	手动触发健康检查

📝 API 使用示例

订阅管理

# 添加订阅
curl -X POST http://your-server:8080/api/subscriptions \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Provider-A", "url": "https://example.com/subscribe?token=xxx"}'

# 刷新所有订阅
curl -X POST http://your-server:8080/api/subscriptions/refresh \
  -H "Authorization: Bearer your-token"

节点控制

# 列出所有节点
curl http://your-server:8080/api/proxies \
  -H "Authorization: Bearer your-token"

# 切换节点（节点名需 URL 编码）
curl -X PUT "http://your-server:8080/api/proxies/PROXY/%E8%8A%82%E7%82%B9%E5%90%8D" \
  -H "Authorization: Bearer your-token"

# 测试延迟
curl "http://your-server:8080/api/proxies/%E8%8A%82%E7%82%B9%E5%90%8D/delay" \
  -H "Authorization: Bearer your-token"

健康检查

# 触发检查（异步）
curl -X POST http://your-server:8080/api/health/check \
  -H "Authorization: Bearer your-token"

# 查看结果
curl http://your-server:8080/api/health \
  -H "Authorization: Bearer your-token"

---

🖥️ 客户端接入

方式	配置
环境变量	export http_proxy=http://your-server:7890 export https_proxy=http://your-server:7890
Python	import requests proxies = {"http": "http://your-server:7890", "https": "http://your-server:7890"} requests.get("https://example.com", proxies=proxies)
Node.js	HTTP_PROXY=http://your-server:7890 node app.js
curl	curl -x http://your-server:7890 https://api.example.com
Proxifier	类型 HTTP，地址 your-server，端口 7890

---

💊 健康检查

特性	说明
触发方式	API 按需触发，无定时器
并发控制	最多 5 节点并行测速
超时阈值	单节点 5 秒
黑名单	失败节点自动移除，恢复后自动加回
配置重载	黑名单变化时自动重启 mihomo
持久化	仅内存，重启后重新检测

---

🌏 节点过滤

默认只保留低延迟地区节点：

地区	匹配关键词
🇭🇰 香港	HK HKG 香港
🇸🇬 新加坡	SG SGP 新加坡
🇹🇼 台湾	TW TWN 台湾
🇯🇵 日本	JP JPN 日本

修改过滤规则：编辑 internal/subscription/parser.go 中的 allowedRegions

---

🔄 进程守护

mihomo 异常退出时自动重启，最多重试 3 次（间隔 3s → 6s → 9s）。连续失败后停止重试，等待人工介入。

---

📁 项目结构

clash-sub-aggregator/
├── main.go                          # 入口
├── web/                             # 前端 (React + TypeScript + shadcn/ui)
│   ├── src/
│   │   ├── App.tsx                  # 主应用 + 登录门控
│   │   ├── components/
│   │   │   ├── LoginPage.tsx        # Token 登录页
│   │   │   ├── SubscriptionPanel.tsx # 订阅管理
│   │   │   ├── ProxyPanel.tsx       # 节点列表 & 切换
│   │   │   ├── HealthPanel.tsx      # 健康检查
│   │   │   └── StatusBar.tsx        # 状态栏
│   │   └── lib/api.ts              # API 客户端
│   └── package.json
├── static/                          # 前端构建产物 (Go 直接 serve)
├── internal/
│   ├── api/
│   │   ├── router.go               # 路由 + 静态文件 serve
│   │   ├── middleware.go            # Token 认证
│   │   ├── subscription_handler.go  # 订阅 CRUD
│   │   ├── proxy_handler.go        # 代理控制
│   │   └── health_handler.go       # 健康检查 API
│   ├── health/
│   │   └── checker.go              # 健康检查 + 黑名单
│   ├── clash/
│   │   ├── config.go               # mihomo 配置生成
│   │   └── process.go              # mihomo 进程管理 + 守护
│   ├── subscription/
│   │   ├── manager.go              # 订阅拉取 + 管理
│   │   └── parser.go               # 订阅解析 + 地区过滤
│   ├── model/
│   │   └── model.go                # 数据模型
│   └── store/
│       └── store.go                # JSON 文件持久化
├── configs/app.yaml                # 应用配置
├── Dockerfile
├── docker-compose.yaml
└── Makefile

---

MIT License