Skip to content

quickstart.md

Latest commit

 

History

History
261 lines (190 loc) · 5.02 KB

quickstart.md

File metadata and controls

261 lines (190 loc) · 5.02 KB

Quickstart Guide: Subscription Aggregation Service

Feature: Subscription Aggregation Service | Date: 2026-03-29

Overview

This guide helps you get started with SubHub - a subscription aggregation service for Clash/mihomo proxies.

Prerequisites

  • Docker installed (or Python 3.12+ and uv for local development)
  • One or more airport subscription URLs
  • A Clash/mihomo template file (optional, a default is provided)

Installation

Option 1: Docker (Recommended)

  1. Clone the repository:

    git clone <repository-url>
cd subhub

  2. Configure your subscriptions: Edit config/config.yaml:

    sources:
  - id: "a1b2c3d4e5f6789abcdef123"  # Generate with: openssl rand -hex 12
    name: "my-airport"
    url: "https://your-airport.com/sub"
    enabled: true
    cache_expiry: 7200  # 2 hours

template_path: "config/template.yaml"
cache_dir: "cache"
listen_port: 8080
listen_host: "0.0.0.0"

  3. Run the container:

    docker run -d \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/cache:/app/cache \
  --name subhub \
  subhub:latest

Option 2: Local Development

  1. Install dependencies with uv:

    uv sync

  2. Run the service:

    uv run python -m src.main

Verification

Test the service is running:

curl http://localhost:8080/health

Expected response:

{"status": "healthy", "version": "1.0.0", "uptime_seconds": 10}

Getting Your Subscription

Basic Usage

# Replace with your source ID from config.yaml
curl http://localhost:8080/subscription/a1b2c3d4e5f6789abcdef123 -o clash.yaml

Force Refresh (Bypass Cache)

curl http://localhost:8080/subscription/a1b2c3d4e5f6789abcdef123?refresh=true -o clash.yaml

Check Source Status

curl http://localhost:8080/sources

Configuring Clash/mihomo

Method 1: Direct Import

  1. Download the subscription:

    curl http://localhost:8080/subscription/a1b2c3d4e5f6789abcdef123 -o clash-config.yaml

  2. Import into Clash/mihomo client

Method 2: Proxy Provider

Add to your Clash config:

proxy-providers:
  subhub:
    type: http
    url: "http://localhost:8080/subscription/a1b2c3d4e5f6789abcdef123"
    interval: 7200
    path: ./proxies.yaml
    health-check:
      enable: true
      interval: 600
      url: http://www.gstatic.com/generate_204

Configuration Reference

sources

List of subscription sources to aggregate.

sources:
  - id: "a1b2c3d4e5f6789abcdef123"  # Unique ID (generate: openssl rand -hex 12)
    name: "airport1"        # Display name (non-unique)
    url: "https://..."      # Subscription URL
    enabled: true           # Whether to fetch from this source
    cache_expiry: 7200      # Cache TTL in seconds (default: 7200)

template_path

Path to your Clash template YAML file. The template should contain:

  • proxy-groups: Your proxy group definitions
  • rules: Your routing rules
  • proxies: Empty list (will be filled by the service)

cache_dir

Directory for caching subscription content. Ensure this directory is writable.

Template Example

# config/template.yaml
proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - DIRECT
      # Injected proxies will be appended here

  - name: "Auto"
    type: url-test
    proxies:
      - PROXY
    url: "http://www.gstatic.com/generate_204"
    interval: 300

rules:
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,youtube.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

proxies: []  # This will be replaced with actual proxies

Troubleshooting

Service won't start

  1. Check if port 8080 is already in use
  2. Verify config.yaml syntax is valid
  3. Check cache directory is writable

No proxies returned

  1. Check source status: curl http://localhost:8080/sources
  2. Verify airport URLs are accessible
  3. Check service logs for errors

Cache not working

  1. Ensure cache_dir exists and is writable
  2. Check file permissions on cache directory
  3. Force refresh with ?refresh=true

Production Deployment

Using Docker Compose

version: '3.8'
services:
  subhub:
    image: subhub:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config:ro
      - ./cache:/app/cache
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Behind Nginx (HTTPS)

server {
    listen 443 ssl;
    server_name subhub.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Next Steps