README_EN.md

🚀 Cloudflare GitHub-Proxy Worker

High-Performance GitHub Acceleration Proxy on Cloudflare Workers

基于 Cloudflare Workers 的高性能 GitHub 文件加速代理

📖 中文文档 / Chinese Documentation

---

📚 Table of Contents

• ✨ Key Features
• 🎨 Interface Features
• 📊 Caching Strategy
• 🚀 Quick Deployment
• 📖 Usage Guide
• ⚙️ Configuration
• 🔍 Performance Optimization
• 📊 Response Headers
• ⚠️ Important Notes
• 🔧 Troubleshooting
• 🤝 Contributing

✨ Key Features

🚀 Zero Configuration No KV storage required One-click deployment	⚡ Intelligent Caching Multi-layer caching strategy Auto-adjusts TTL by path type	🌐 Full Domain Support Supports github.com and all GitHub-related domains
📦 Complete Features Resumable downloads, CORS ETag validation	🔧 High Reliability Retry mechanism, timeout control Connection optimization	🎨 Beautiful Homepage Bilingual interface Dark/Light theme support

🎨 Interface Features

• 🌓 Smart Theme - Auto-follows system light/dark theme with manual toggle
• 🌍 Auto Language Detection - Automatically selects Chinese/English based on browser language
• 🔄 Real-time Theme Sync - Auto-switches when system theme changes, no refresh needed
• 📋 Dynamic Domain Replacement - Example URLs automatically show current accessing domain
• 🎯 Preference Memory - Uses sessionStorage to save user preferences, resets to system on refresh

📊 Caching Strategy

The system automatically selects the optimal caching strategy based on file paths:

Path Type	Example	Edge Cache	Browser Cache	Version Control
Dynamic Content	/latest/, /main/, /nightly/	1 hour	5 minutes	ETag
Versioned Paths	/v1.0/, /tags/, /releases/download/v1.0/	30 days	1 day	Date
Regular Paths	All other paths	1 day	1 hour	ETag

🚀 Quick Deployment

💡 Get Started in 30 Seconds

1. Click the Deploy to Cloudflare Workers button above
2. Log in to Cloudflare and authorize GitHub repository access
3. Click Deploy button, wait for 1-2 minutes
4. Get your Worker URL: https://your-worker.workers.dev
5. Replace GitHub URL domain with your Worker domain to use!

Method 1: One-Click Deploy (Recommended)

Click the button below to automatically deploy to Cloudflare Workers:

Method 2: Manual Deployment

📖 Click to expand detailed steps

Prerequisites:

• Cloudflare account (Free Sign Up)
• (Recommended) A domain hosted on Cloudflare - For binding custom domain to avoid *.workers.dev blocking risks

Deployment Steps:

1. Log in to Cloudflare Dashboard

   Visit: https://dash.cloudflare.com/
   

2. Create Worker

   • Click Workers & Pages in the left menu
   • Click Create Application
   • Select Create Worker
   • Enter Worker name (e.g., github-proxy)
   • Click Deploy

3. Deploy Code

   • Click the Edit Code button
   • Delete the default code
   • Copy the complete content of worker.js
   • Paste into the editor
   • Click Save and Deploy in the top right

4. Bind Custom Domain (Optional)

   • On the Worker details page, click Settings → Triggers
   • Click Add Custom Domain
   • Enter domain (e.g., gh.example.com)
   • Wait for DNS configuration to take effect (usually 1-5 minutes)

5. Deployment Complete ✅

   • Default URL: https://your-worker.workers.dev
   • Custom domain: https://gh.example.com (if configured)

Method 3: Auto-Deployment (Recommended for Ongoing Maintenance)

Configure GitHub Actions to automatically deploy when code is pushed, keeping your Worker synchronized with the repository.

⚠️ Note: One-click deploy only works when the button is clicked. GitHub code updates won't automatically sync to the Worker. For ongoing maintenance, auto-deployment is recommended.

📖 Configuration Steps: See Auto-Deployment Configuration Guide

📖 Usage Guide

Basic Usage

Replace the domain in GitHub URLs with your Worker domain:

# Original URL
https://github.com/torvalds/linux/archive/refs/tags/v6.6.tar.gz

# Accelerated URL (domain path format)
https://your-worker.workers.dev/github.com/torvalds/linux/archive/refs/tags/v6.6.tar.gz

# Or use full URL format (paste the complete URL after proxy domain)
https://your-worker.workers.dev/https://github.com/torvalds/linux/archive/refs/tags/v6.6.tar.gz

Supported Path Formats

Format	Description	Example
📦 Domain Path	Remove https://, keep domain and path	proxy.dev/github.com/user/repo/...
🔗 Full URL	Paste full GitHub URL directly	proxy.dev/https://github.com/user/repo/...

Practical Examples

📥 Download Release Files

# Download Clash Meta core
wget https://your-worker.workers.dev/github.com/MetaCubeX/mihomo/releases/download/v1.18.0/mihomo-linux-amd64

# Download Node.js source code
curl -O https://your-worker.workers.dev/github.com/nodejs/node/archive/refs/tags/v20.10.0.tar.gz

📄 Get Raw Files

# Get script file
curl https://your-worker.workers.dev/raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# Get configuration file
wget https://your-worker.workers.dev/raw.githubusercontent.com/torvalds/linux/master/.gitignore

📝 Use in Scripts

#!/bin/bash

# Set proxy address
GITHUB_PROXY="https://your-worker.workers.dev"

# Download file
download_file() {
    local repo=$1
    local tag=$2
    local filename=$3
    
    wget "${GITHUB_PROXY}/github.com/${repo}/releases/download/${tag}/${filename}"
}

# Usage example
download_file "cli/cli" "v2.40.0" "gh_2.40.0_linux_amd64.tar.gz"

🔄 Git Clone Acceleration

# Method 1: Use git config
git config --global url."https://your-worker.workers.dev/github.com/".insteadOf "https://github.com/"
git clone https://github.com/torvalds/linux.git

# Method 2: Direct URL replacement
git clone https://your-worker.workers.dev/github.com/torvalds/linux.git

⚙️ Configuration

Customize the following parameters in worker.js:

Cache Configuration

Parameter	Default	Description
EDGE_CACHE_SECONDS	2592000 (30 days)	Edge cache TTL
SWR_SECONDS	86400 (1 day)	Stale-while-revalidate duration
BROWSER_CACHE_SECONDS	3600 (1 hour)	Browser cache TTL

Performance Configuration

Parameter	Default	Description
ENABLE_COMPRESSION	true	Enable Brotli/Gzip compression
ENABLE_EARLY_HINTS	true	Enable Early Hints (HTTP 103)
MAX_RETRIES	2	Maximum retry attempts
RETRY_DELAY_MS	500	Retry interval (milliseconds)
REQUEST_TIMEOUT_MS	30000	Request timeout (milliseconds)

🔍 Performance Optimization

🌐 Network Layer ✅ HTTP/3 & HTTP/2 - Multiplexing, reduced connection overhead ✅ Early Hints - Pre-connect, lower TTFB ✅ Keep-Alive - Connection reuse, reduced TCP handshake ✅ Smart DNS - Using Cloudflare DNS (1.1.1.1)	💾 Caching ✅ Multi-Layer Cache - Browser → Worker → Edge three-tier caching ✅ Smart Invalidation - Automatic version management based on ETag and date ✅ Vary Support - Cache variants based on encoding type ✅ SWR Mechanism - Background async update, reduced blocking
🛡️ Reliability ✅ Smart Retry - Exponential backoff algorithm ✅ Timeout Control - 30-second timeout ✅ Error Fallback - Support for fallback mirror sources	📦 Content Optimization ✅ Auto Minify - HTML/CSS/JS minification ✅ Image Optimization - Polish lossy compression ✅ Smart Loading - Mirage adaptive images

📊 Response Headers

The Worker adds the following debug headers:

Header	Description	Example Value
X-Cache-Status	Cache hit status	HIT / MISS
X-Cache-Strategy	Cache strategy type	dynamic / versioned / default
X-Mirror-Version	Cache version	20231223 / abc123... (ETag)
X-GitHub-Target	Actual GitHub URL requested	https://github.com/...
X-Response-Time	Response time	1234ms

🔍 Debug Example

curl -I https://your-worker.workers.dev/cli/cli/releases/download/v2.40.0/gh_2.40.0_linux_amd64.tar.gz

HTTP/2 200
x-cache-status: HIT
x-cache-strategy: versioned
x-mirror-version: 20231223
x-response-time: 45ms

⚠️ Important Notes

📌 Limitations

• Free tier: 100,000 requests per day
• Single file size limit: 100MB (Cloudflare limitation)
• CPU execution time: 50ms (free) / unlimited (paid)

💾 Cache Behavior

• Browser cache: Auto-adjusted based on strategy (5min - 1day)
• Edge cache: Auto-adjusted based on strategy (1hour - 30days)
• Version number: Auto-updated daily at UTC 00:00

💡 Recommendations

• Test with small files first before using for large files
• Bind custom domain for frequent access
• Upgrade to Workers Paid plan for high traffic

🗑️ Cache Purging

• Dashboard: Caching → Configuration → Purge Cache
• API: Use Cloudflare API to purge by URL
• Auto: Wait for cache expiration or version update

🔧 Troubleshooting

❌ 404 Not Found

• Check if path format is correct
• Verify the file exists on GitHub
• Check X-GitHub-Target header for target URL

🔄 Cache Miss (X-Cache-Status: MISS)

• First request must be MISS, subsequent should be HIT
• Check if it's a dynamic path (/latest/, etc.)
• Review X-Cache-Strategy to confirm strategy type

🐢 Slow Download Speed

• Check if using Cloudflare CDN nodes
• Verify local network connection quality to Cloudflare
• Review X-Response-Time to analyze latency source

📝 Changelog

See Releases for version history.

---

🤝 Contributing

Issues and Pull Requests are welcome!

🐛 Report Bug · 💡 Request Feature · 📖 Improve Docs

Contribution Steps:

1. Fork the project
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

📄 License

This project is licensed under the GNU General Public License v3.0.

🙏 Acknowledgments

• Cloudflare Workers - Powerful edge computing platform
• GitHub - The world's largest code hosting platform

---

_{Made with ❤️ by Aethersailor}

⭐ Star this project  ·  🍴 Fork this project