Skip to content

SF_README.md

Latest commit

 

History

History
145 lines (92 loc) · 12.4 KB

SF_README.md

File metadata and controls

145 lines (92 loc) · 12.4 KB

Quick Start — mhrv-rs

A short, plain-language version. For the deep technical guide, see the full README.

Quick Start (English) | راهنمای کامل English | راهنمای خلاصه فارسی | راهنمای کامل فارسی

Quick Start

What this is

A free way to bypass internet censorship by routing your traffic through your own free Google account. Your ISP only sees you talking to Google; Google fetches the real websites for you.

What you need

  • A Google account (free, the regular one).
  • 5–10 minutes the first time.
  • The mhrv-rs app — Windows, Mac, Linux, or Android. Download here.

The 3 steps

1. Set up the relay in your Google account (one-time). Go to https://script.google.com, sign in, click New project. Delete the sample code, paste in the Code.gs file from this repo, change AUTH_KEY = "..." to a password only you know. Click Deploy → New deployment → Web app, set "Execute as: Me", "Who has access: Anyone". Copy the long ID from the URL — that's your Deployment ID.

Can't reach script.google.com because it's blocked? Run mhrv-rs first in google_only mode (use config.google-only.example.json). It only relays Google sites and lets you reach the Apps Script editor through the bypass tunnel. Do step 1 in your browser, then switch back to normal mode.

2. Install and run mhrv-rs. Download the package for your system from Releases and unzip it.

If you have Do this
Windows double-click run.bat
Mac double-click run.command
Linux run ./run.sh in a terminal
Android install the APK from Releases

The first run asks for your password — only to install a small local certificate so HTTPS sites work through the tunnel. Nothing is uploaded.

3. Paste your details and connect. In the app, paste:

  • Deployment ID — from step 1
  • Auth key — the password you put in Code.gs

Click Connect (or Start on desktop). Done. Your browser, Telegram, etc. will work normally.

Browser: the Connect button on Android sets up a system-wide VPN — every app uses it automatically. On desktop, set your browser HTTP proxy to 127.0.0.1:8085, or use SOCKS5 on 127.0.0.1:8086.

Common issues (most people hit at least one)

YouTube videos look "restricted" or comments are missing? (#61) Turn on "Send YouTube through relay (no SNI rewrite)" in the desktop UI's Advanced section, or set youtube_via_relay: true in config.json. YouTube then goes through the Apps Script relay instead of the direct Google tunnel, which avoids YouTube's SafeSearch-on-SNI behaviour. Trade-off: slightly slower video, and it counts against your daily quota.

"Verify you are human" loop on Cloudflare-protected sites? This can't be fixed in this app. Every Apps Script request comes from a different Google datacenter IP, and Cloudflare's challenge cookie is locked to one IP — so the next request fails the check and re-challenges you. Sites that only check once per session work fine. Sites that check every page won't.

"504 Relay timeout" in the browser? Your Apps Script deployment isn't responding. Go back to https://script.google.com, Deploy → Manage deployments → Edit (pencil), change "Version" to New version, click Deploy. Copy the new Deployment ID and paste it into the app.

Hit your daily limit? Free Google accounts get 20,000 relay requests per day. The desktop and Android apps show a "Usage today" card with how many you've used. Add multiple Deployment IDs (one per line in the UI, or a JSON array in config.json) — each ID has its own quota and they're rotated automatically. You can also click "View quota on Google" to see the official number on Google's dashboard.

App says it's connected but websites don't load?

  • Open the SNI pool section and click Test all. If everything fails, your google_ip value is unreachable from your network — click Auto-detect google_ip to fix.
  • Make sure you actually installed the certificate (the password prompt on first run). If you skipped it, click Install MITM certificate again.

Want more detail?

  • Full English README — every config option, full tunnel mode, OpenWRT, diagnostics, security notes
  • Issue tracker — search before opening a new one; lots of common questions are already answered

Support

This project is free and run by volunteers. If it helped you and you can spare anything: ❤️ sh1n.org/donate

راهنمای خلاصه فارسی

نسخهٔ کوتاه و بدون اصطلاحات فنی. برای جزئیات کامل، راهنمای کامل فارسی را ببینید.

این چیست؟

یک ابزار رایگان برای دور زدن سانسور اینترنت از طریق یک ریلهٔ شخصی روی حساب گوگل خودتان. سرویس‌دهندهٔ شما فقط می‌بیند که در حال صحبت با گوگل هستید؛ گوگل بقیهٔ سایت‌ها را برای شما باز می‌کند.

چه چیزی نیاز دارید؟

  • یک حساب گوگل معمولی (رایگان).
  • بار اول ۵ تا ۱۰ دقیقه وقت.
  • برنامهٔ mhrv-rs برای ویندوز / مک / لینوکس / اندروید — از اینجا دانلود کنید.

سه مرحله

۱. ساخت ریله در حساب گوگل (فقط یک بار). به https://script.google.com بروید، وارد حساب گوگل شوید و روی New project بزنید. کد پیش‌فرض را پاک کنید و محتوای فایل Code.gs همین مخزن را در آن جای‌گذاری کنید. خط AUTH_KEY = "..." را به یک رمز دلخواه که فقط خودتان می‌دانید تغییر دهید. سپس Deploy → New deployment → Web app را بزنید، گزینهٔ "Execute as: Me" و "Who has access: Anyone" را انتخاب کنید. آی‌دی طولانی توی URL را کپی کنید — این Deployment ID شماست.

اگر script.google.com خودش بسته است، اول mhrv-rs را در حالت google_only اجرا کنید (از config.google-only.example.json استفاده کنید). این حالت فقط سایت‌های گوگل را تونل می‌کند تا بتوانید به ویرایشگر Apps Script برسید. مرحلهٔ ۱ را در مرورگر انجام دهید و بعد به حالت معمولی برگردید.

۲. نصب و اجرای mhrv-rs. بستهٔ مخصوص سیستم خودتان را از بخش Releases دانلود کنید و از حالت فشرده در بیاورید.

سیستم کاری که باید بکنید
ویندوز روی run.bat دو بار کلیک کنید
مک روی run.command دو بار کلیک کنید
لینوکس در ترمینال ./run.sh را اجرا کنید
اندروید فایل APK را از Releases نصب کنید

اولین اجرا رمز عبور شما را می‌خواهد — فقط برای نصب یک گواهی محلی کوچک تا سایت‌های HTTPS از تونل عبور کنند. هیچ چیزی به جایی فرستاده نمی‌شود.

۳. مشخصاتتان را وارد کنید و وصل شوید. در برنامه این دو را وارد کنید:

  • Deployment ID — از مرحلهٔ ۱
  • Auth key (کلید احراز) — همان رمزی که در Code.gs گذاشتید

روی اتصال (در اندروید) یا Start (در دسکتاپ) بزنید. تمام شد. مرورگر، تلگرام و بقیهٔ برنامه‌ها مثل قبل کار می‌کنند.

مرورگر: دکمهٔ اتصال در اندروید یک VPN سراسری راه می‌اندازد و همهٔ برنامه‌ها خودکار از آن عبور می‌کنند. در دسکتاپ، باید پروکسی HTTP مرورگر را روی 127.0.0.1:8085 یا SOCKS5 روی 127.0.0.1:8086 تنظیم کنید.

مشکلات رایج (اکثر کاربران حداقل یکی از این‌ها را می‌بینند)

ویدیوهای یوتیوب «محدود» نشان داده می‌شوند یا کامنت‌ها دیده نمی‌شوند؟ (#61) در بخش Advanced دسکتاپ گزینهٔ «Send YouTube through relay (no SNI rewrite)» را روشن کنید، یا در config.json مقدار youtube_via_relay: true بگذارید. در این حالت یوتیوب از مسیر ریلهٔ Apps Script رد می‌شود و فیلتر SafeSearch-on-SNI گوگل دور می‌خورد. تریدآف: ویدیو کمی کندتر و مصرف از سهمیهٔ روزانه.

روی سایت‌های پشت Cloudflare loop «Verify you are human» می‌خورد؟ این مشکل در این ابزار قابل حل نیست. هر درخواست Apps Script از یک IP متفاوت دیتاسنتر گوگل خارج می‌شود و کوکی challenge کلودفلر به یک IP خاص قفل است — درخواست بعدی از IP دیگر دوباره چالش می‌خورد. سایت‌هایی که فقط یک‌بار در ابتدای session چک می‌کنند درست کار می‌کنند. سایت‌هایی که هر صفحه چک می‌کنند، نه.

در مرورگر «504 Relay timeout» نشان می‌دهد؟ Apps Script شما پاسخ نمی‌دهد. به https://script.google.com برگردید، Deploy → Manage deployments → Edit (آیکن مداد) را بزنید، گزینهٔ "Version" را روی New version بگذارید و Deploy کنید. آی‌دی جدید Deployment را کپی کنید و در برنامه جای‌گذاری کنید.

سهمیهٔ روزانه تمام شده؟ هر حساب گوگل رایگان روزانه ۲۰٬۰۰۰ درخواست ریله دارد. کارت «مصرف امروز» در دسکتاپ و اندروید مقدار مصرف فعلی را نشان می‌دهد. می‌توانید چند Deployment ID (هر کدام در یک خط، یا به‌صورت JSON array در config.json) اضافه کنید — هر آی‌دی سهمیهٔ خودش را دارد و به‌صورت چرخشی استفاده می‌شوند. دکمهٔ «مشاهدهٔ سهمیه در گوگل» شما را به داشبورد رسمی گوگل می‌برد.

برنامه می‌گوید وصل است ولی سایت‌ها باز نمی‌شوند؟

  • بخش SNI pool را باز کنید و Test all بزنید. اگر همه fail شدند، یعنی google_ip فعلی از شبکهٔ شما در دسترس نیست — روی Auto-detect google_ip بزنید تا اصلاح شود.
  • مطمئن شوید گواهی را واقعاً نصب کردید (همان رمزی که اولین اجرا خواست). اگر رد کردید، روی Install MITM certificate دوباره بزنید.

جزئیات بیشتر می‌خواهید؟

  • راهنمای کامل فارسی — همهٔ گزینه‌های پیکربندی، حالت تونل کامل، OpenWRT، تشخیص خطا، نکات امنیتی
  • بخش Issues — قبل از ساخت issue جدید جست‌وجو کنید؛ خیلی از سؤالات رایج جواب داده شده‌اند

حمایت از پروژه

این پروژه رایگان و توسط داوطلبان نگه‌داری می‌شود. اگر کمکتان کرد و چیزی از دستتان برمی‌آید: ❤️ sh1n.org/donate