Frequently Asked Questions (FAQ)

If your issue isn't listed here, feel free to submit an Issue or Discussion on GitHub.

Cloudflare Quick Deploy Error: An unknown error occurred

This may be a GitHub/GitLab authorization issue:

Solution Steps:

• Visit https://github.com/settings/installations
• Find the Cloudflare Workers and Pages app
• Uninstall the app
• Re-authorize through the deploy button

Repository Sync

Q: How do I keep my Fork in sync with upstream?

• Open your forked repository homepage and click the Sync fork button in the top right.
• Or locally execute git remote add upstream https://github.com/7Sageer/sublink-worker.git, then sync with git fetch upstream && git merge upstream/main.

---

Q: How do I sync upstream updates after using the Vercel/Cloudflare quick deploy button?

Repositories created via the quick deploy button are independent clones rather than forks, so you cannot use GitHub's "Sync fork" feature. Here are several ways to sync:

Method 1: Manually Add Upstream Remote (Recommended)

# Clone your deployed repository
git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
cd YOUR_REPO_NAME

# Add upstream repository
git remote add upstream https://github.com/7Sageer/sublink-worker.git

# Fetch upstream updates
git fetch upstream

# Merge upstream updates into your main branch
git checkout main
git merge upstream/main

# After resolving any conflicts, push to your repository
git push origin main

After pushing, Vercel/Cloudflare will automatically trigger a redeployment.

Method 2: Delete and Redeploy

If you haven't made any custom modifications to the code:

1. Delete the existing project on Vercel/Cloudflare
2. Delete the automatically created repository on GitHub
3. Click the quick deploy button again

Method 3: Recommended Approach - Fork First, Then Deploy

For easier synchronization of future updates, we recommend the following workflow:

1. First, manually Fork the original repository on GitHub
2. Import your forked repository in Vercel/Cloudflare for deployment
3. You can then use GitHub's Sync fork button directly to sync updates

TIP

If you've already created a project via quick deploy, consider migrating to the Fork approach for easier maintenance.

Access & Domains

Q: Why can't I access the generated subscription in my region?

• *.workers.dev domains are often blocked in certain regions.
• We recommend binding a custom domain in Cloudflare Pages/Workers and hosting DNS resolution on Cloudflare for flexible Rules/SSL configuration.
• If you can't bind a domain temporarily, use a proxy to access or deploy the subscription fetch logic on an overseas server.

KV Persistence

Q: How do I ensure KV persistence when deploying with Node/Docker?

• We recommend using the repository's built-in docker-compose.yml: it will start Redis 7 alongside the worker and load redis.conf to enable RDB snapshots, with data written to the redis-data volume.
• Compose uses the GitHub Actions-pushed image ghcr.io/7sageer/sublink-worker by default. You can change to a self-built image via SUBLINK_WORKER_IMAGE.
• If you prefer hosted KV, configure KV_REST_API_URL & KV_REST_API_TOKEN to directly connect to Upstash/Vercel KV. When both are unset, it falls back to in-memory storage. You can disable this with DISABLE_MEMORY_KV=true.

Other Recommendations

• Before saving base configs or short links, ensure the Worker is connected to persistent KV.
• If you replace default rule sets or add new languages, please update the documentation in your PR.
• When reporting issues, please include: deployment method, runtime logs, input samples, and Worker version for easier troubleshooting.