From 31ba9218d1f16be2d33be5a71872711108cedf3c Mon Sep 17 00:00:00 2001 From: Abolfazl Date: Sat, 9 May 2026 05:11:55 +0330 Subject: [PATCH] Enhance troubleshooting documentation and add Docker guides in Persian --- apps_script/deno_deploy.ts | 2 + docs/TROUBLESHOOTING.md | 20 +++++++ docs/fa/DOCKER.md | 44 ++++++++++++++++ docs/fa/GETTING_STARTED.md | 71 +++++++++++++++++++++++++ docs/fa/LAN_SHARING.md | 52 +++++++++++++++++++ docs/fa/SECURITY.md | 40 ++++++++++++++ docs/fa/TROUBLESHOOTING.md | 104 +++++++++++++++++++++++++++++++++++++ 7 files changed, 333 insertions(+) create mode 100644 docs/fa/DOCKER.md create mode 100644 docs/fa/GETTING_STARTED.md create mode 100644 docs/fa/LAN_SHARING.md create mode 100644 docs/fa/SECURITY.md create mode 100644 docs/fa/TROUBLESHOOTING.md diff --git a/apps_script/deno_deploy.ts b/apps_script/deno_deploy.ts index 003eac6..dbd431f 100644 --- a/apps_script/deno_deploy.ts +++ b/apps_script/deno_deploy.ts @@ -9,6 +9,8 @@ const STRIP_HEADERS = new Set([ "host", "connection", "content-length", + // Deno passes compressed response bytes through. Ask origins for plain bodies. + "accept-encoding", "transfer-encoding", "proxy-connection", "proxy-authorization", diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 0fd2379..bc79f9c 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -62,6 +62,26 @@ Fix: 3. Confirm the deployment is a Web App with **Execute as: Me** and **Who has access: Anyone**. 4. If quota is exhausted, wait for the quota reset or add more deployments with `script_ids`. +## Page Looks Like Random Characters + +Symptoms: + +- A website opens as unreadable text like `�` and random symbols. +- The issue appears only for some users or only on some websites. +- HTML, JavaScript, or JSON is shown as binary-looking output instead of a normal page. + +Most likely cause: + +The target website sent a compressed response, but the browser received it without a usable `Content-Encoding` header. This usually happens when an old Apps Script deployment or exit node still forwards `Accept-Encoding` to the target website. + +Fix: + +1. Update this project and install dependencies again with `pip install -r requirements.txt`. +2. Redeploy [apps_script/Code.gs](../apps_script/Code.gs) as a new Apps Script deployment. +3. Copy the new Deployment ID into `config.json` if it changed. +4. If you use a Deno exit node, redeploy [apps_script/deno_deploy.ts](../apps_script/deno_deploy.ts). +5. Restart the proxy and fully reopen the browser. + ## Connection Timeout The current `google_ip` may be blocked or slow on your network. diff --git a/docs/fa/DOCKER.md b/docs/fa/DOCKER.md new file mode 100644 index 0000000..c9cf348 --- /dev/null +++ b/docs/fa/DOCKER.md @@ -0,0 +1,44 @@ +# راهنمای Docker + +Docker زمانی مفید است که می‌خواهید پروژه را بدون نصب مستقیم Python اجرا کنید. + +## پیش‌نیاز + +- Docker یا Docker Desktop +- فایل `config.json` آماده +- رله Apps Script که از [apps_script/Code.gs](../../apps_script/Code.gs) deploy شده باشد + +## اجرای سریع + +در پوشه پروژه اجرا کنید: + +```bash +docker compose up --build +``` + +پورت‌های پیش‌فرض: + +| سرویس | آدرس | +|-------|------| +| HTTP proxy | `127.0.0.1:8085` | +| SOCKS5 proxy | `127.0.0.1:1080` | + +## تنظیم مرورگر + +مرورگر را روی HTTP proxy با آدرس `127.0.0.1` و پورت `8085` تنظیم کنید. + +اگر از HTTPS استفاده می‌کنید، باید گواهی ساخته‌شده در `ca/ca.crt` را روی سیستم یا مرورگر trust کنید. + +## توقف + +```bash +docker compose down +``` + +## نکته‌ها + +- مقدارهای محرمانه مثل `auth_key` را داخل تصویر Docker منتشر نکنید. +- اگر `config.json` را تغییر دادید، container را restart کنید. +- اگر پورت‌ها اشغال هستند، پورت‌های `docker-compose.yml` را تغییر دهید. + +برای تنظیمات کامل‌تر، [مرجع تنظیمات](CONFIGURATION.md) را بخوانید. diff --git a/docs/fa/GETTING_STARTED.md b/docs/fa/GETTING_STARTED.md new file mode 100644 index 0000000..979e170 --- /dev/null +++ b/docs/fa/GETTING_STARTED.md @@ -0,0 +1,71 @@ +# شروع سریع + +این راهنما مسیر ساده راه‌اندازی را نشان می‌دهد: یک رله Google Apps Script، یک فایل `config.json`، و پراکسی محلی روی سیستم شما. + +## 1. دریافت پروژه + +**با Git:** + +```bash +git clone https://github.com/masterking32/MasterHttpRelayVPN.git +cd MasterHttpRelayVPN +``` + +**با ZIP:** + +1. صفحه [GitHub پروژه](https://github.com/masterking32/MasterHttpRelayVPN) را باز کنید. +2. روی **Code** -> **Download ZIP** کلیک کنید. +3. فایل ZIP را extract کنید. +4. داخل پوشه `MasterHttpRelayVPN` یک terminal باز کنید. + +## 2. ساخت رله Google + +1. به [Google Apps Script](https://script.google.com/) بروید. +2. یک پروژه جدید بسازید. +3. محتوای [apps_script/Code.gs](../../apps_script/Code.gs) را داخل فایل `Code.gs` کپی کنید. +4. مقدار `AUTH_KEY` را به یک رمز طولانی و تصادفی تغییر دهید. +5. از مسیر **Deploy** -> **New deployment** نوع **Web app** را انتخاب کنید. +6. گزینه **Execute as** را روی **Me** و گزینه دسترسی را روی **Anyone** بگذارید. +7. Deploy کنید و `Deployment ID` را نگه دارید. + +بعد از هر تغییر در `Code.gs` باید deployment جدید بسازید. + +## 3. اجرای لانچر + +**Windows:** + +```cmd +start.bat +``` + +**Linux / macOS:** + +```bash +chmod +x start.sh +./start.sh +``` + +لانچر محیط مجازی می‌سازد، وابستگی‌ها را نصب می‌کند، اگر `config.json` وجود نداشته باشد setup wizard را اجرا می‌کند، و سپس پراکسی را بالا می‌آورد. + +## 4. تنظیم مرورگر + +مرورگر را روی پراکسی زیر تنظیم کنید: + +| گزینه | مقدار | +|-------|-------| +| نوع پراکسی | HTTP | +| آدرس | `127.0.0.1` | +| پورت | `8085` | +| SOCKS5، اختیاری | `127.0.0.1:1080` | + +برای HTTPS اگر مرورگر خطای گواهی داد، فایل `ca/ca.crt` را به عنوان trusted root نصب کنید و مرورگر را کامل ببندید و دوباره باز کنید. + +## 5. بررسی سریع + +- اگر `unauthorized` دیدید، مقدار `AUTH_KEY` در Apps Script باید دقیقا با `auth_key` در `config.json` یکی باشد. +- اگر صفحه‌ها باز نمی‌شوند، [رفع مشکل](TROUBLESHOOTING.md) را ببینید. +- اگر سرعت پایین است، دستور `python main.py --scan` را اجرا کنید و IP پیشنهادی را در `config.json` بگذارید. + +## قدم بعدی + +برای همه گزینه‌های تنظیمات، [مرجع تنظیمات](CONFIGURATION.md) را بخوانید. برای مسیرهای خاص مثل ChatGPT یا Turnstile، [راهنمای Exit Node](../exit-node/EXIT_NODE_DEPLOYMENT_FA.md) را ببینید. diff --git a/docs/fa/LAN_SHARING.md b/docs/fa/LAN_SHARING.md new file mode 100644 index 0000000..7123661 --- /dev/null +++ b/docs/fa/LAN_SHARING.md @@ -0,0 +1,52 @@ +# اشتراک‌گذاری LAN + +با LAN sharing می‌توانید پراکسی را برای دستگاه‌های دیگر شبکه محلی مثل گوشی یا لپ‌تاپ دیگر استفاده کنید. + +## هشدار امنیتی + +قبل از فعال کردن LAN، [نکات امنیتی](SECURITY.md) را بخوانید. اگر پراکسی روی شبکه باز باشد، هر دستگاهی که به آن دسترسی داشته باشد می‌تواند از مسیر شما عبور کند. + +## فعال‌سازی + +در `config.json` مقدارها را تنظیم کنید: + +```json +"listen_host": "0.0.0.0", +"lan_sharing": true +``` + +سپس پراکسی را restart کنید. + +## پیدا کردن IP سیستم + +روی Windows: + +```cmd +ipconfig +``` + +روی Linux / macOS: + +```bash +ip addr +``` + +آدرس داخلی معمولا شبیه `192.168.x.x` یا `10.x.x.x` است. + +## تنظیم دستگاه دیگر + +روی دستگاه دوم، پراکسی را این‌طور تنظیم کنید: + +| گزینه | مقدار | +|-------|-------| +| نوع پراکسی | HTTP | +| آدرس | IP سیستم اجراکننده پراکسی | +| پورت | `8085` | + +برای HTTPS باید گواهی `ca/ca.crt` را روی همان دستگاه هم trust کنید. + +## مشکل‌های رایج + +- اگر دستگاه دوم وصل نمی‌شود، firewall سیستم میزبان را چک کنید. +- اگر HTTPS خطا می‌دهد، گواهی روی دستگاه دوم نصب نشده است. +- اگر شبکه عمومی یا ناشناس است، LAN sharing را روشن نکنید. diff --git a/docs/fa/SECURITY.md b/docs/fa/SECURITY.md new file mode 100644 index 0000000..1e42d79 --- /dev/null +++ b/docs/fa/SECURITY.md @@ -0,0 +1,40 @@ +# نکات امنیتی + +این پروژه یک پراکسی محلی و رله شخصی می‌سازد. چند فایل و مقدار باید خصوصی بمانند. + +## محرمانه نگه دارید + +این موارد را با کسی به اشتراک نگذارید: + +- `config.json` +- مقدار `auth_key` +- مقدار `AUTH_KEY` در Apps Script +- پوشه `ca/` و کلیدهای داخل آن +- آدرس Exit Node همراه با PSK معتبر + +## Apps Script + +- برای `AUTH_KEY` از رمز طولانی و تصادفی استفاده کنید. +- بعد از تغییر `Code.gs` همیشه deployment جدید بسازید. +- اگر فکر می‌کنید رمز لو رفته، `AUTH_KEY` و `auth_key` را عوض کنید و deployment جدید بسازید. + +## گواهی محلی + +پروژه برای MITM محلی یک CA می‌سازد تا مرورگر بتواند HTTPS را از پراکسی عبور دهد. این CA فقط باید روی دستگاه‌های خودتان trust شود. + +- فایل‌های داخل `ca/` را منتشر نکنید. +- اگر فایل‌های CA لو رفتند، پوشه `ca/` را حذف کنید، گواهی trust شده قبلی را از سیستم پاک کنید، و پروژه را دوباره اجرا کنید تا CA جدید بسازد. + +## LAN sharing + +فقط روی شبکه‌های قابل اعتماد فعال کنید. وقتی `listen_host` روی `0.0.0.0` است، دستگاه‌های دیگر شبکه می‌توانند به پراکسی وصل شوند. + +## Exit Node + +- برای PSK از رمز جدا و قوی استفاده کنید. +- Exit Node عمومی یا بدون رمز راه‌اندازی نکنید. +- اگر از VPS استفاده می‌کنید، firewall و لاگ‌ها را بررسی کنید. + +## مسئولیت استفاده + +این پروژه برای آموزش، تست، و پژوهش ارائه شده است. مسئولیت رعایت قوانین و شرایط سرویس‌ها با کاربر است. diff --git a/docs/fa/TROUBLESHOOTING.md b/docs/fa/TROUBLESHOOTING.md new file mode 100644 index 0000000..3563710 --- /dev/null +++ b/docs/fa/TROUBLESHOOTING.md @@ -0,0 +1,104 @@ +# رفع مشکل + +از نشانه‌ای شروع کنید که می‌بینید. بیشتر مشکل‌ها از تنظیمات، اعتماد گواهی، یا deployment قدیمی Apps Script می‌آیند. + +## خطاهای Certificate + +نشانه‌ها: + +- مرورگر می‌گوید اتصال امن نیست. +- بعضی برنامه‌ها کار می‌کنند اما سایت‌های HTTPS در مرورگر باز نمی‌شوند. +- بعد از نصب گواهی هنوز Chrome یا Edge خطا می‌دهد. + +راه‌حل: + +1. یک بار پراکسی را اجرا کنید تا فایل `ca/ca.crt` ساخته شود. +2. فایل `ca/ca.crt` را به عنوان trusted root certificate نصب کنید. +3. مرورگر را کامل ببندید و دوباره باز کنید. در Windows، Task Manager را هم چک کنید. +4. در Firefox گواهی را جداگانه از مسیر **Settings** -> **Privacy & Security** -> **Certificates** وارد کنید. + +می‌توانید این دستور را هم اجرا کنید: + +```bash +python main.py --install-cert +``` + +## `unauthorized` + +رمز مشترک یکی نیست. + +راه‌حل: + +1. فایل [apps_script/Code.gs](../../apps_script/Code.gs) را باز کنید. +2. مقدار `const AUTH_KEY = "...";` را پیدا کنید. +3. مطمئن شوید دقیقا با `auth_key` در `config.json` یکی است. +4. بعد از تغییر [apps_script/Code.gs](../../apps_script/Code.gs)، یک deployment جدید بسازید. + +## `Config not found` + +setup wizard را اجرا کنید: + +```bash +python setup.py +``` + +یا فایل [config.example.json](../../config.example.json) را به `config.json` کپی کنید و مقدارهای `script_id` و `auth_key` را پر کنید. + +## `502 Bad JSON` + +Google به جای JSON رله، HTML یا پاسخ غیرمنتظره برگردانده است. + +علت‌های رایج: + +- `Deployment ID` اشتباه است. +- quota روزانه Apps Script تمام شده است. +- `Code.gs` را تغییر داده‌اید اما deployment جدید نساخته‌اید. +- دسترسی Web App روی **Anyone** نیست. + +راه‌حل: + +1. یک deployment جدید Apps Script بسازید. +2. `Deployment ID` جدید را داخل `config.json` بگذارید. +3. مطمئن شوید Web App با **Execute as: Me** و **Who has access: Anyone** deploy شده است. +4. اگر quota تمام شده، صبر کنید تا reset شود یا چند deployment دیگر با `script_ids` اضافه کنید. + +## صفحه به شکل کاراکترهای عجیب باز می‌شود + +نشانه‌ها: + +- صفحه با متن‌هایی مثل `�` و علامت‌های تصادفی باز می‌شود. +- مشکل فقط برای بعضی کاربران یا بعضی سایت‌ها دیده می‌شود. +- HTML، JavaScript، یا JSON شبیه خروجی باینری نمایش داده می‌شود. + +علت احتمالی: + +سایت مقصد پاسخ فشرده فرستاده، اما مرورگر آن را بدون header درست `Content-Encoding` دریافت کرده است. این معمولا وقتی رخ می‌دهد که deployment قدیمی Apps Script یا یک Exit Node هنوز `Accept-Encoding` را به سایت مقصد پاس می‌دهد. + +راه‌حل: + +1. پروژه را به‌روز کنید و وابستگی‌ها را دوباره با `pip install -r requirements.txt` نصب کنید. +2. فایل [apps_script/Code.gs](../../apps_script/Code.gs) را دوباره به عنوان deployment جدید Apps Script منتشر کنید. +3. اگر `Deployment ID` عوض شد، آن را در `config.json` جایگزین کنید. +4. اگر از Deno Exit Node استفاده می‌کنید، [apps_script/deno_deploy.ts](../../apps_script/deno_deploy.ts) را دوباره deploy کنید. +5. پراکسی و مرورگر را کامل restart کنید. + +## Timeout اتصال + +ممکن است `google_ip` فعلی روی شبکه شما کند یا مسدود باشد. + +اجرا کنید: + +```bash +python main.py --scan +``` + +سپس IP پیشنهادی را در `config.json` بگذارید و پراکسی را restart کنید. + +## مرورگر روی پراکسی است اما سایت‌ها باز نمی‌شوند + +چک کنید: + +1. terminal نشان می‌دهد HTTP proxy روی `127.0.0.1:8085` فعال است. +2. نوع پراکسی مرورگر **HTTP** است، نه HTTPS. +3. ترافیک HTTPS هم از همان HTTP proxy عبور می‌کند. +4. گواهی نصب شده و مرورگر کامل restart شده است.