aheh/MasterHttpRelayVPN
1
0
Fork 0
mirror of https://github.com/masterking32/MasterHttpRelayVPN.git synced 2026-05-17 21:24:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive documentation for MasterHttpRelayVPN

Browse Source 
- Introduced ARCHITECTURE.md to outline the system architecture and flow.
- Created CONFIGURATION.md detailing configuration options and their meanings.
- Added DOCKER.md for Docker setup instructions and usage.
- Developed GETTING_STARTED.md to guide users through initial setup and usage.
- Included LAN_SHARING.md to explain how to enable LAN sharing for the proxy.
- Established SECURITY.md to highlight security practices and responsibilities.
- Compiled TROUBLESHOOTING.md to assist users in resolving common issues.
- Translated documentation into Persian, including ARCHITECTURE.md and CONFIGURATION.md.
This commit is contained in:
Abolfazl
2026-05-09 05:01:08 +03:30
parent 9dfa3386dc
commit 70bbcf217f
11 changed files with 1007 additions and 1086 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+63 -578
View File
@@ -2,611 +2,96 @@
[![GitHub](https://img.shields.io/badge/GitHub-MasterHttpRelayVPN-blue?logo=github)](https://github.com/masterking32/MasterHttpRelayVPN) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/masterking32/MasterHttpRelayVPN) [![oosmetrics](https://api.oosmetrics.com/api/v1/badge/achievement/85a1f608-5c6d-4fcd-9b7f-b1ff8b680852.svg)](https://oosmetrics.com/repo/masterking32/MasterHttpRelayVPN) [![oosmetrics](https://api.oosmetrics.com/api/v1/badge/achievement/de9bee73-bc68-4f98-ba83-6957007046b1.svg)](https://oosmetrics.com/repo/masterking32/MasterHttpRelayVPN)
**[🇮🇷 راهنمای فارسی (Persian)](README_FA.md)**
**Language:** English | [Persian / فارسی](README_FA.md)
A free tool that lets you access the internet freely by hiding your traffic behind trusted websites like Google. No VPS or server needed — just a free Google account.
MasterHttpRelayVPN is a local proxy that routes browser traffic through a Google Apps Script relay using domain fronting. The simple path needs only this project and a free Google account. For sites that block Google egress, you can optionally add an exit node later.
> **How it works in simple terms:** Your browser talks to this tool on your computer. This tool disguises your traffic to look like normal Google traffic. The firewall/filter sees "google.com" and lets it pass. Behind the scenes, a free Google Apps Script relay fetches the real website for you.
---
## 🎉 Latest Updates
> YouTube restrictions (SafeSearch enforcement, live video blocking) are now resolved and work seamlessly without requiring an exit node. The relay now intelligently handles YouTube's content policies out of the box.
> **✨ YouTube SafeSearch & Live Now Fully Working!**
>
## Announcement and Support Channel 📢
For the latest news, releases, and project updates, follow our Telegram channel: [Telegram Channel](https://t.me/masterdnsvpn)
---
### If you like this project, please support it by starring it on GitHub (⭐). It helps the project get discovered.
---
### Optional Financial Support 💸
- TON network:
`masterking32.ton`
- EVM-compatible networks (ETH and compatible chains):
`0x517f07305D6ED781A089322B6cD93d1461bF8652`
- TRC20 network (TRON):
`TLApdY8APWkFHHoxebxGY8JhMeChiETqFH`
Every contribution and every piece of feedback is appreciated. Support directly helps ongoing development and improvement.
---
## Disclaimer
MasterHttpRelayVPN is provided for educational, testing, and research purposes only.
- **Provided without warranty:** This software is provided "AS IS", without express or implied warranty, including merchantability, fitness for a particular purpose, and non-infringement.
- **Limitation of liability:** The developers and contributors are not responsible for any direct, indirect, incidental, consequential, or other damages resulting from the use of this project or the inability to use it.
- **User responsibility:** Running this project outside controlled test environments may affect networks, accounts, proxies, certificates, or connected systems. You are solely responsible for installation, configuration, and use.
- **Legal compliance:** You are responsible for complying with all local, national, and international laws and regulations before using this software.
- **Google services compliance:** If you use Google Apps Script or other Google services with this project, you are responsible for complying with Google's Terms of Service, acceptable use rules, quotas, and platform policies. Misuse may lead to suspension or termination of your Google account or deployments.
- **License terms:** Use, copying, distribution, and modification of this software are governed by the repository license. Any use outside those terms is prohibited.
---
## How It Works
```
Browser -> Local Proxy -> Google/CDN front -> Your relay -> Target website
|
+-> shows google.com to the network filter
```text
Browser -> Local proxy -> Google front -> Your Apps Script relay -> Target site
network filter sees a Google-facing connection
```
In normal use, the browser sends traffic to the proxy running on your computer.
The proxy sends that traffic through Google-facing infrastructure so the network only sees an allowed domain such as `www.google.com`.
Your deployed relay then fetches the real website and sends the response back through the same path.
## Choose Your Path
This means the filter sees normal-looking Google traffic, while the actual destination stays hidden inside the relay request.
| I want to... | Go here |
|-------------|---------|
| Set it up for the first time | [Getting Started](docs/GETTING_STARTED.md) |
| Run with Docker | [Docker Guide](docs/DOCKER.md) |
| Share the proxy on my LAN | [LAN Sharing](docs/LAN_SHARING.md) |
| Use an exit node for blocked destinations | [Exit Node Guide](docs/exit-node/EXIT_NODE_DEPLOYMENT.md) |
| Understand every config option | [Configuration Reference](docs/CONFIGURATION.md) |
| Fix a problem | [Troubleshooting](docs/TROUBLESHOOTING.md) |
| Review safety notes | [Security Notes](docs/SECURITY.md) |
| Understand the internals | [Architecture](docs/ARCHITECTURE.md) |
---
## Fast Start
## Quick Start (Recommended)
Before running the local proxy, deploy the Google relay from [apps_script/Code.gs](apps_script/Code.gs) and keep two values ready:
One command sets up a virtualenv, installs dependencies, launches an interactive
config wizard, and starts the proxy.
- `Deployment ID` from Google Apps Script
- `AUTH_KEY`, a long secret that must match `auth_key` in your local config
**Windows:**
```cmd
git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
start.bat
```
Download the project with either Git or ZIP, then run the one-click launcher.
**Option A: Git**
**Linux / macOS:**
```bash
git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
```
**Option B: ZIP**
1. Open [the GitHub repository](https://github.com/masterking32/MasterHttpRelayVPN).
2. Click **Code** -> **Download ZIP**.
3. Extract the ZIP file.
4. Open a terminal inside the extracted `MasterHttpRelayVPN` folder.
Then start the app:
**Windows**
```cmd
start.bat
```
**Linux / macOS**
```bash
chmod +x start.sh
./start.sh
```
The first time it runs, the wizard asks for your Google Apps Script Deployment ID
and generates a strong random password for you. Follow the Apps Script deployment
instructions in **Step 2** below before running the wizard so you have a
Deployment ID ready.
The launcher creates a virtual environment, installs dependencies, opens the setup wizard if `config.json` is missing, and starts the proxy.
After it starts, configure your browser to use:
## Step-by-Step Setup Guide (Manual)
| Field | Value |
|-------|-------|
| Proxy type | HTTP |
| Address | `127.0.0.1` |
| Port | `8085` |
| SOCKS5 port, optional | `1080` |
### Step 1: Download This Project
For HTTPS sites, install the generated certificate from `ca/ca.crt` if the app cannot install it automatically. The full setup is in [Getting Started](docs/GETTING_STARTED.md).
```bash
git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
pip install -r requirements.txt
```
## Common Next Steps
> **Can't reach PyPI directly?** Use this mirror instead:
> ```bash
> pip install -r requirements.txt -i https://mirror-pypi.runflare.com/simple/ --trusted-host mirror-pypi.runflare.com
> ```
- If the browser shows certificate warnings, open [Troubleshooting](docs/TROUBLESHOOTING.md#certificate-errors).
- If you see `unauthorized`, make sure `AUTH_KEY` in [apps_script/Code.gs](apps_script/Code.gs) exactly matches `auth_key` in `config.json`.
- If browsing is slow or connections time out, run `python main.py --scan` and see [Configuration Reference](docs/CONFIGURATION.md#diagnostic-commands).
- If ChatGPT, Turnstile, or similar sites block the Google exit IP, use [Exit Node Guide](docs/exit-node/EXIT_NODE_DEPLOYMENT.md).
Or download the ZIP from [GitHub](https://github.com/masterking32/MasterHttpRelayVPN) and extract it.
## Support And Updates
### Step 2: Set Up the Google Relay (Code.gs)
- Telegram channel: [https://t.me/masterdnsvpn](https://t.me/masterdnsvpn)
- Windows client: [MHRWindowsApp](https://github.com/AriPath/MHRWindowsApp)
- Ad blocker filter source: [PersianBlocker](https://github.com/MasterKia/PersianBlocker/)
This is the "relay" that sits on Google's servers and fetches websites for you. It's free.
## Safety
1. Open [Google Apps Script](https://script.google.com/) and sign in with your Google account.
2. Click **New project**.
3. **Delete** all the default code in the editor.
4. Open the [`Code.gs`](apps_script/Code.gs) file from this project (under `apps_script/`), **copy everything**, and paste it into the Apps Script editor.
5. **Important:** Change the password on this line to something only you know:
```javascript
const AUTH_KEY = "your-secret-password-here";
```
6. Click **Deploy** → **New deployment**.
7. Choose **Web app** as the type.
8. Set:
- **Execute as:** Me
- **Who has access:** Anyone
9. Click **Deploy**.
- If prompted, click **Authorize access**.
- You may see **Google hasn't verified this app**. Click **Advanced** then **Go to <your project name> (unsafe)** to continue.
10. **Copy the Deployment ID** (it looks like a long random string). You'll need it in the next step.
This project is provided for educational, testing, and research use. You are responsible for following applicable laws and service terms. Never share `config.json`, `auth_key`, `ca/`, or an exit-node URL together with a valid PSK. Read [Security Notes](docs/SECURITY.md) before sharing the proxy with other devices.
> ⚠️ Remember the password you set in step 5. You'll use the same password in the config file below.
### Step 3: Configure
**Option A — interactive wizard (recommended):**
```bash
python setup.py
```
It'll prompt for your Deployment ID, generate a random `auth_key`, and write
`config.json` for you.
**Option B — manual:**
1. Copy the example config file:
```bash
cp config.example.json config.json
```
On Windows, you can also just copy & rename the file manually.
2. Open `config.json` in any text editor and fill in your values:
```json
{
"google_ip": "216.239.38.120",
"front_domain": "www.google.com",
"script_id": "PASTE_YOUR_DEPLOYMENT_ID_HERE",
"auth_key": "your-secret-password-here",
"listen_host": "127.0.0.1",
"http_port": 8085,
"socks5_port": 1080,
"log_level": "INFO",
"verify_ssl": true
}
```
- `script_id` → Paste the Deployment ID from Step 2.
- `auth_key` → The **same password** you set in `Code.gs`.
### Step 3.5: Optional Exit Node for Full-Tunnel (ChatGPT/Turnstile Friendly)
Some websites block Google datacenter IPs when traffic exits directly from Apps Script.
To fix that, configure an exit node so traffic path becomes:
```text
Browser -> Local Proxy -> Apps Script -> Exit Node (Cloudflare / Deno / VPS) -> Target website
```
You can deploy any one of these exit-node backends:
1. Cloudflare Workers: [`apps_script/cloudflare_worker.js`](apps_script/cloudflare_worker.js)
2. Deno Deploy: [`apps_script/deno_deploy.ts`](apps_script/deno_deploy.ts)
3. Your own VPS server
Full step-by-step deployment guide (all providers):
- [docs/exit-node/EXIT_NODE_DEPLOYMENT.md](docs/exit-node/EXIT_NODE_DEPLOYMENT.md)
Set the same PSK secret inside the exit-node code (`PSK` constant) and in `config.json`.
Then configure provider switching like this:
```json
"exit_node": {
"enabled": true,
"provider": "cloudflare",
"url": "https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev",
"psk": "CHANGE_ME_TO_A_STRONG_SECRET",
"mode": "full",
"hosts": [
"chatgpt.com",
"openai.com",
"claude.ai",
"anthropic.com"
]
}
```
Notes:
- For simple setup, only fill `provider`, `url`, and `psk`.
- Switch provider by changing `exit_node.provider` and `exit_node.url`.
- `mode: "full"` = everything goes through exit node (ignore `hosts`).
- `mode: "selective"` = only domains in `hosts` go through exit node.
- `psk` must exactly match your deployed exit node secret.
Production recommendation:
- Keep `verify_ssl: true`
- Keep `listen_host: 127.0.0.1` unless LAN sharing is explicitly needed
- Rotate both secrets periodically
- Never publish your live exit-node URL with valid PSK
### Step 4: Run
```bash
python3 main.py
```
You should see a message saying the HTTP proxy is running on `127.0.0.1:8085` and SOCKS5 on `127.0.0.1:1080`.
### Step 5: Set Up Your Browser
Set your browser to use the proxy:
- **Proxy Address:** `127.0.0.1`
- **Proxy Port:** `8085`
- **Type:** HTTP
- **Optional SOCKS5 Port:** `1080`
**How to set proxy in common browsers:**
- **Firefox:** Settings → General → Network Settings → Manual proxy → enter `127.0.0.1` port `8085` for HTTP Proxy → check "Also use this proxy for HTTPS"
- **Chrome/Edge:** Uses system proxy. Go to Windows Settings → Network → Proxy → Manual setup → enter `127.0.0.1:8085`
- **Or** use extensions like [FoxyProxy](https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/) or [SwitchyOmega](https://chrome.google.com/webstore/detail/proxy-switchyomega/) for easier switching.
### Step 6: Install the CA Certificate (Required for HTTPS)
When using `apps_script` mode, the tool needs to decrypt and re-encrypt HTTPS traffic locally. It generates a CA certificate on first run. **You must install it** or you'll see security warnings on every website.
The certificate file is created at `ca/ca.crt` inside the project folder after the first run.
#### Windows
1. Double-click `ca/ca.crt`.
2. Click **Install Certificate**.
3. Choose **Current User** (or Local Machine for all users).
4. Select **Place all certificates in the following store** → click **Browse** → choose **Trusted Root Certification Authorities**.
5. Click **Next** → **Finish**.
6. Restart your browser.
#### macOS
1. Double-click `ca/ca.crt` — it opens in Keychain Access.
2. It goes into the **login** keychain.
3. Find the certificate, double-click it.
4. Click on View Certificate then expand **Trust** → set **When using this certificate** to **Always Trust**.
5. Select System in the Keychain section and press add button.
6. Close and enter your password. Restart your browser.
#### Linux (Ubuntu/Debian)
```bash
sudo cp ca/ca.crt /usr/local/share/ca-certificates/masterhttp-relay.crt
sudo update-ca-certificates
```
Restart your browser.
#### Firefox (All Platforms)
Firefox uses its own certificate store, so even after OS-level install you need to do this:
1. Go to **Settings** → **Privacy & Security** → **Certificates** → **View Certificates**.
2. Go to the **Authorities** tab → click **Import**.
3. Select `ca/ca.crt` from the project folder.
4. Check **Trust this CA to identify websites** → click **OK**.
> **Auto-install on startup:** When running in `apps_script` mode the proxy will automatically detect if the CA is not yet trusted and attempt to install it for you. If it succeeds you'll see a confirmation in the log; if it fails (e.g. needs administrator rights) it will print instructions. You can also run `python main.py --install-cert` at any time to (re-)install the certificate.
> **Uninstalling:** To remove the certificate from your system's trust stores, run `python main.py --uninstall-cert` or use `start.bat --uninstall-cert` on Windows. This removes the certificate from all system trust stores and Firefox profiles.
> ⚠️ **Security note:** This certificate only works locally on your machine. Don't share the `ca/` folder with anyone. If you want to start fresh, delete the `ca/` folder and the tool will generate a new one.
---
## LAN Sharing (Optional)
By default, the proxy only listens on `127.0.0.1` (localhost), meaning only your computer can use it. To allow other devices on your local network (LAN) to use the proxy:
1. Set `"lan_sharing": true` in your `config.json`
2. The proxy will automatically listen on all network interfaces (`0.0.0.0`)
3. The startup log will show your LAN IP addresses that other devices can connect to
**Example LAN configuration:**
```json
{
"lan_sharing": true,
"listen_host": "0.0.0.0",
"http_port": 8085
}
```
**Security Warning:** When LAN sharing is enabled, anyone on your local network can use your proxy. Ensure your network is trusted and consider additional security measures.
**On other devices:** Configure them to use your computer's LAN IP (shown in the startup log) and port 8085 as the HTTP proxy.
---
## Docker (Optional)
If you prefer running the proxy in a container instead of managing a Python environment, Docker is supported.
**Requirements:** [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/)
### Setup
1. Copy and fill in your config:
```bash
cp config.example.json config.json
# Edit config.json — set your script_id and auth_key
```
2. Build and start:
```bash
docker compose up -d
```
The container automatically listens on `0.0.0.0`, so both ports are reachable from the host:
- `127.0.0.1:8085` — HTTP proxy
- `127.0.0.1:1080` — SOCKS5 proxy
### CA Certificate in Docker
On first run, the container generates `ca/ca.crt` into the `./ca` volume on your host. Install it in your browser manually — see [Step 6](#step-6-install-the-ca-certificate-required-for-https) above. Running `--install-cert` inside the container has no effect on the host OS certificate store.
### Useful Commands
```bash
docker compose up -d # Start in background
docker compose logs -f # Follow logs
docker compose restart # Restart after config change
docker compose down # Stop and remove container
docker compose build # Rebuild image after code change
```
> **`config.json` is mounted read-only** into the container and is never baked into the image, so your secrets stay on the host.
---
## Modes Overview
This project is centered on the **Apps Script** relay (free, no VPS needed). For destinations that block Google egress, you can optionally chain an edge exit node (Cloudflare Workers, Deno Deploy, or your own VPS).
---
## Configuration Options
### Main Settings
| Setting | What It Does |
|---------|-------------|
| `auth_key` | Password shared between your computer and the relay |
| `script_id` | Your Google Apps Script Deployment ID |
| `listen_host` | Where to listen (`127.0.0.1` = only this computer, `0.0.0.0` = all interfaces for LAN sharing) |
| `http_port` | Which HTTP proxy port to listen on (default: `8085`) |
| `lan_sharing` | Enable LAN sharing to allow other devices on your network to use the proxy (`false` by default) |
| `log_level` | How much detail to show: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
### Advanced Settings
| Setting | Default | What It Does |
|---------|---------|-------------|
| `google_ip` | `216.239.38.120` | Google IP address to connect through |
| `front_domain` | `www.google.com` | Domain shown to the firewall/filter |
| `verify_ssl` | `true` | Verify the TLS certificate on the local fronted connection to Google/CDN |
| `relay_timeout` | `25` | Total timeout for one relayed request before it fails |
| `tls_connect_timeout` | `15` | Timeout for the proxy's TLS connection to the fronted Google/CDN endpoint |
| `tcp_connect_timeout` | `10` | Timeout for direct TCP tunnels and outbound SNI-rewrite connects |
| `script_ids` | — | Multiple Script IDs for load balancing (array) |
| `chunked_download_extensions` | see [config.example.json](config.example.json) | File extensions that should use parallel range downloading. Supports `".*"` to probe all GET downloads. |
| `chunked_download_min_size` | `5242880` | Minimum total file size (5 MB) before range-parallel download stays enabled |
| `chunked_download_chunk_size` | `524288` | Per-range chunk size used by parallel downloads |
| `chunked_download_max_parallel` | `8` | Maximum simultaneous range requests for one download |
| `chunked_download_max_chunks` | `256` | Soft upper bound for total chunk requests; chunk size is raised automatically for very large files |
| `hosts` | `{}` | Manual DNS override map (`hostname` or `.suffix` -> IP). Example: `{ "example.org": "93.184.216.34", ".internal.lan": "192.168.1.10" }`. |
| `block_hosts` | `[]` | Hosts that must never be tunneled (return HTTP 403). Supports exact names (`ads.example.com`) or leading-dot suffixes (`.doubleclick.net`). |
| `direct_hosts` | `[]` | Hosts that must always go direct (no MITM and no relay/domain-fronting). Supports exact names and leading-dot suffixes. |
| `bypass_hosts` | `["localhost", ".local", ".lan", ".home.arpa"]` | Hosts that go direct (no MITM, no relay). Useful for LAN resources or sites that break under MITM. |
| `direct_google_exclude` | see [config.example.json](config.example.json) | Google apps that must use the MITM relay path instead of the fast direct tunnel. |
| `youtube_via_relay` | `false` | Route YouTube (`youtube.com`, `youtu.be`, `youtube-nocookie.com`) through the Apps Script relay instead of the SNI-rewrite path. The SNI-rewrite path uses Google's frontend IP which enforces SafeSearch and can cause **"Video Unavailable"** errors. Setting this to `true` fixes playback at the cost of using more Apps Script executions and slightly higher latency. |
| `exit_node.provider` | `cloudflare` | Selected exit-node backend: `cloudflare`, `deno`, `vps`, or `custom`. |
| `exit_node.url` | `""` | Beginner-friendly single URL for the selected provider. |
Practical host-policy example:
```json
{
"block_hosts": [
"ads.example.com",
".doubleclick.net"
],
"direct_hosts": [
"chat.openai.com",
".openai.com"
],
"hosts": {
"example.org": "93.184.216.34",
".internal.lan": "192.168.1.10"
}
}
```
- `block_hosts`: deny requests entirely (`403`) for exact names or full suffix trees.
- `direct_hosts`: force plain direct tunnel only (no MITM, no relay fronting).
- `hosts`: force DNS mapping before any real lookup (useful for testing/split-DNS workarounds).
Note: the relay response body cap is now a code constant (`MAX_RESPONSE_BODY_BYTES`) in [src/core/constants.py](src/core/constants.py), not a user config key.
### Optional Dependencies
Install everything from [`requirements.txt`](requirements.txt). All listed packages are optional — the proxy runs with no third-party dependencies in basic modes, but without them you lose features:
| Package | Provides |
|---------|----------|
| `cryptography` | MITM TLS interception (required for `apps_script` mode with HTTPS sites) |
| `h2` | HTTP/2 multiplexing to the Apps Script relay (significantly faster) |
| `brotli` | Decompression of `Content-Encoding: br` responses |
| `zstandard` | Decompression of `Content-Encoding: zstd` responses |
### Load Balancing
To increase speed, deploy `Code.gs` multiple times to different Apps Script projects and use all their IDs:
```json
{
"script_ids": [
"DEPLOYMENT_ID_1",
"DEPLOYMENT_ID_2",
"DEPLOYMENT_ID_3"
]
}
```
> ⚠️ **Note:** If you are using multiple deployments, the auth-keys must be identical. (All deployments must use the same auth-key.)
---
## Updating the Google Relay
If you change `Code.gs`, you must **create a new deployment** in Google Apps Script (Deploy → New deployment) and **update the `script_id`** in your `config.json`. Just editing the code does not update the live version.
---
## Command Line Options
```bash
python3 main.py # Normal start
python3 main.py -p 9090 # Use HTTP port 9090 instead
python3 main.py --socks5-port 1081 # Use SOCKS5 port 1081
python3 main.py --log-level DEBUG # Show detailed logs
python3 main.py -c /path/to/config.json # Use a different config file
python3 main.py --install-cert # Install MITM CA certificate and exit
python3 main.py --uninstall-cert # Remove MITM CA certificate and exit
python3 main.py --no-cert-check # Skip automatic CA install check on startup
python3 main.py --scan # Scan Google IPs and find the fastest one
```
> **Auto-install:** On startup (MITM mode), the proxy automatically checks if the CA certificate is trusted and attempts to install it. Use `--no-cert-check` to skip this. If auto-install fails (e.g. needs elevation), run `python main.py --install-cert` manually or follow Step 6 above.
### Scanning for the Fastest Google IP
If your current `google_ip` in `config.json` is blocked or slow, you can scan to find a faster one:
```bash
python3 main.py --scan
```
This will:
1. Probe 27 candidate Google IPs in parallel
2. Measure latency from your network
3. Display results in a table
4. Recommend the fastest IP
5. Exit with exit code 0 if at least one IP is reachable, 1 otherwise
**Example output:**
```
Scanning 27 Google frontend IPs
SNI: www.google.com
Timeout: 4s per IP
Concurrency: 8 parallel probes
IP LATENCY STATUS
-------------------- ------------ -------------------------
216.239.32.120 42ms OK
216.239.34.120 45ms OK
216.239.36.120 52ms OK
142.250.80.142 timeout timeout
...
Result: 15 / 27 reachable
Top 3 fastest IPs:
1. 216.239.32.120 (42ms)
2. 216.239.34.120 (45ms)
3. 216.239.36.120 (52ms)
Recommended: Set "google_ip": "216.239.32.120" in config.json
```
After scanning, update your `config.json` with the recommended IP and restart the proxy.
---
## Architecture
```
┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
│ Browser │────►│ Local Proxy │────►│ CDN / Google │────►│ Relay │──► Internet
│ │◄────│ (this tool) │◄────│ (fronted) │◄────│ Endpoint │◄──
└─────────┘ └──────────────┘ └─────────────┘ └──────────┘
HTTP/CONNECT TLS (SNI: ok) Fetch target
MITM (optional) Host: relay Return response
```
---
## Project Files
```
MasterHttpRelayVPN/
├── main.py # Entry point: starts the proxy
├── setup.py # Interactive wizard — writes config.json
├── start.bat / start.sh # One-click launcher (venv + deps + wizard + run)
├── config.example.json # Copy to config.json and fill in your values
├── requirements.txt # Python dependencies
├── Dockerfile # Container image definition
├── docker-compose.yml # Compose config: ports, volumes, restart policy
├── apps_script/
│ ├── Code.gs # The relay script you deploy to Google Apps Script
│ ├── cloudflare_worker.js # Exit node template for Cloudflare Workers
│ └── deno_deploy.ts # Exit node template for Deno Deploy
├── ca/ # Generated MITM CA (do NOT share)
│ ├── ca.crt
│ └── ca.key
└── src/ # Proxy implementation
├── proxy_server.py # Accepts HTTP CONNECT and SOCKS5
├── domain_fronter.py # Apps Script relay client (fronted through Google)
├── h2_transport.py # Optional HTTP/2 multiplexing
├── mitm.py # On-the-fly TLS interception
├── cert_installer.py # Cross-platform CA installer (Windows/macOS/Linux + Firefox)
├── codec.py # Content-Encoding decoder (gzip/deflate/br/zstd)
├── google_ip_scanner.py # Scanner to find the fastest reachable Google IP
├── constants.py # Tunable defaults and shared data
└── logging_utils.py # Colored, aligned log formatter
```
---
## Troubleshooting
| Problem | Solution |
|---------|----------|
| "Config not found" | Copy `config.example.json` to `config.json` and fill in your values |
| Browser shows certificate errors | Install the CA certificate (see Step 6 above) |
| Telegram works but browser doesn't load sites | Almost certainly the CA certificate is not installed. Follow Step 6 to install `ca/ca.crt`, then **fully close and reopen your browser** (for Chrome/Edge, make sure no Chrome process is running in the background before reopening). |
| Installed the cert but browser still errors | Chrome and Edge cache certificates — you must **completely close** the browser (check Task Manager / system tray) and reopen it for the new cert to take effect. Firefox requires a separate import (see Step 6 Firefox section). |
| "unauthorized" error | Make sure `auth_key` in `config.json` matches `AUTH_KEY` in `Code.gs` exactly |
| Connection timeout | Try a different `google_ip` or check your internet connection |
| Slow browsing | Deploy multiple `Code.gs` copies and use `script_ids` array for load balancing |
| `502 Bad JSON` error | Google returned an unexpected response (HTML instead of JSON). Causes: wrong `script_id`, Apps Script daily quota exhausted, or the deployment wasn't re-created after editing `Code.gs`. Check your `script_id` and create a **new deployment** if you recently changed `Code.gs`. |
| Telegram works on HTTP proxy but not on SOCKS5 | **Expected.** SOCKS5 clients resolve hostnames locally and connect to raw IPs, so Telegram's MTProto-obfuscated bytes reach a blocked IP that we can neither direct-tunnel nor intercept. Configure Telegram as an **HTTP proxy** (`127.0.0.1:8085`) instead — it sends hostnames, which the proxy handles via SNI-rewrite through Google. |
| Google and YouTube open but YouTube videos don't play and other sites don't load | The connection to `script.google.com` was not successfully established. This is likely caused by an issue with the deployment of `Code.gs` on Google Apps Script, or the daily execution quota has been exhausted. Re-deploy `Code.gs` with a new deployment and verify your `script_id`, or wait until the quota resets (midnight Pacific Time / 10:30 AM Iran Time). |
---
## Security Tips
- **Never share your `config.json`** — it has your password in it.
- **Change the default `AUTH_KEY`** in `Code.gs` before deploying.
- **Don't share the `ca/` folder** — it contains your private certificate key.
- Keep `listen_host` as `127.0.0.1` so only your computer can use the proxy.
- Every google scripts deployment has limit of 20,000 requests in 24 hours
---
## Special Thanks
Special thanks to [@abolix](https://github.com/abolix) for making this project possible.
## Sources
- **Ad blocker filter lists:** [PersianBlocker](https://github.com/MasterKia/PersianBlocker/) by MasterKia
---
## Third-Party Projects
- [MHRWindowsApp Windows Client](https://github.com/AriPath/MHRWindowsApp)
> A Windows application built on top of MasterHttpRelay.
> This project is developed by AriPath and allows users to use MHR with just one click, without any setup or technical prerequisites.
---
## License
MIT
README_FA.md
+56 -508
View File
@@ -1,546 +1,94 @@
# MasterHttpRelayVPN
**[English README](README.md)**
**زبان:** [English](README.md) | فارسی
یک ابزار رایگان برای عبور از فیلترینگ و DPI که ترافیک شما را پشت دامنه‌های قابل اعتماد مثل Google پنهان می‌کند. برای حالت ساده، به VPS یا سرور نیاز ندارید و فقط یک اکانت Google کافی است.
> **توضیح ساده:** مرورگر شما به این ابزار روی کامپیوتر خودتان وصل می‌شود. این ابزار ترافیک را شبیه ترافیک عادی Google نشان می‌دهد. فیلتر فقط `google.com` را می‌بیند و اجازه عبور می‌دهد. در پشت صحنه، یک Google Apps Script رایگان سایت واقعی را برای شما دریافت می‌کند.
---
## 🎉 آخرین تغییرات
> **✨ YouTube SafeSearch و YouTube Live بدون Exit Node هم درست کار می‌کنند!**
>
> مشکل محدودیت‌های یوتیوب (از جمله SafeSearch و پخش زنده) برطرف شده و اکنون بدون نیاز به Exit Node هم به‌صورت پایدار کار می‌کند.
---
## کانال اطلاع‌رسانی و پشتیبانی 📢
برای دریافت آخرین اخبار، نسخه‌ها و اطلاعیه‌های پروژه، کانال تلگرام ما را دنبال کنید: [Telegram Channel](https://t.me/masterdnsvpn)
---
### اگر از پروژه راضی‌اید، با دادن ستاره (⭐) در گیت‌هاب از ما حمایت کنید — این کار به دیده‌شدن پروژه کمک می‌کند.
---
### حمایت مالی (اختیاری) 💸
- شبکه TON:
`masterking32.ton`
- آدرس روی شبکه‌های EVM (ETH و سازگارها):
`0x517f07305D6ED781A089322B6cD93d1461bF8652`
- شبکه TRC20 (TRON):
`TLApdY8APWkFHHoxebxGY8JhMeChiETqFH`
از هر نوع حمایت و بازخورد شما سپاسگزاریم — کمک‌ها برای توسعه و بهبود پروژه بسیار ارزشمند است.
---
## سلب مسئولیت
پروژه MasterHttpRelayVPN فقط برای اهداف آموزشی، تست و پژوهش ارائه شده است.
- **بدون ضمانت:** این نرم‌افزار به صورت «همان‌گونه که هست» ارائه می‌شود و هیچ‌گونه ضمانت صریح یا ضمنی، از جمله قابلیت فروش، مناسب بودن برای هدف خاص، یا عدم نقض حقوق دیگران برای آن وجود ندارد.
- **محدودیت مسئولیت:** توسعه‌دهندگان و مشارکت‌کنندگان این پروژه هیچ مسئولیتی در قبال خسارت‌های مستقیم، غیرمستقیم، اتفاقی، تبعی، یا هر نوع خسارت دیگر ناشی از استفاده یا ناتوانی در استفاده از این پروژه ندارند.
- **مسئولیت کاربر:** استفاده از این پروژه خارج از محیط‌های کنترل‌شده و آزمایشی ممکن است بر شبکه، حساب‌ها، پراکسی‌ها، گواهی‌ها یا سیستم‌های متصل اثر بگذارد. تمام مسئولیت نصب، پیکربندی و استفاده بر عهده کاربر است.
- **رعایت قوانین:** پیش از استفاده از این نرم‌افزار، رعایت تمام قوانین و مقررات محلی، کشوری و بین‌المللی بر عهده کاربر است.
- **رعایت قوانین Google:** اگر از Google Apps Script یا دیگر سرویس‌های Google در این پروژه استفاده می‌کنید، مسئولیت رعایت شرایط استفاده، محدودیت‌ها، سهمیه‌ها و سیاست‌های پلتفرم Google با خود شما است. استفاده نادرست ممکن است باعث تعلیق یا غیرفعال شدن اکانت Google یا deployment های شما شود.
- **شرایط مجوز:** استفاده، کپی، توزیع و تغییر این نرم‌افزار فقط تحت شرایط مجوز موجود در مخزن مجاز است و هر استفاده خارج از آن شرایط ممنوع است.
---
## نحوه کار
```
مرورگر -> پراکسی محلی -> Google/CDN -> رله شما -> سایت مقصد
|
+-> فیلتر فقط google.com را می‌بیند
```
مرورگر، درخواست‌ها را به پراکسی محلی می‌فرستد. پراکسی این درخواست‌ها را از مسیر Google عبور می‌دهد تا برای فیلتر شبیه ترافیک عادی به نظر برسد. سپس رله‌ای که شما deploy کرده‌اید، سایت اصلی را دریافت می‌کند و پاسخ را برمی‌گرداند.
---
## راه‌اندازی مرحله‌به‌مرحله
### مرحله 1: دریافت پروژه
```bash
git clone -b python_testing https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
pip install -r requirements.txt
```
> **دسترسی به PyPI ندارید؟** از این mirror استفاده کنید:
> ```bash
> pip install -r requirements.txt -i https://mirror-pypi.runflare.com/simple/ --trusted-host mirror-pypi.runflare.com
> ```
اگر نخواستید با Git کار کنید، می‌توانید فایل ZIP پروژه را از GitHub دانلود و extract کنید.
### مرحله 2: راه‌اندازی رله Google با `Code.gs`
این بخش همان رله‌ای است که روی سرورهای Google اجرا می‌شود و سایت‌ها را برای شما دریافت می‌کند.
1. وارد [Google Apps Script](https://script.google.com/) شوید.
2. روی **New project** کلیک کنید.
3. کد پیش‌فرض را کامل حذف کنید.
4. فایل `apps_script/Code.gs` همین پروژه را باز کنید، همه محتوای آن را کپی کنید و داخل Apps Script قرار دهید.
5. این خط را به یک رمز دلخواه و امن تغییر دهید:
```javascript
const AUTH_KEY = "your-secret-password-here";
```
6. روی **Deploy -> New deployment** کلیک کنید.
7. نوع deployment را **Web app** بگذارید.
8. این تنظیمات را انتخاب کنید:
- **Execute as:** Me
- **Who has access:** Anyone
9. روی **Deploy** بزنید.
- اگر پنجره‌ای باز شد، روی **Authorize access** کلیک کنید.
- اگر Google پیغام **Google hasn't verified this app** نشان داد، روی **Advanced** کلیک کنید و سپس **Go to <نام پروژه> (unsafe)** را بزنید تا ادامه دهید.
10. مقدار **Deployment ID** را کپی کنید. در مرحله بعد به آن نیاز دارید.
نکته: مقداری که برای `AUTH_KEY` می‌گذارید باید دقیقا با `auth_key` در فایل `config.json` یکی باشد.
### مرحله 3: تنظیم `config.json`
ابتدا فایل نمونه را کپی کنید:
```bash
cp config.example.json config.json
```
در ویندوز می‌توانید فایل را دستی کپی و rename کنید.
سپس `config.json` را باز کنید و مقادیر را وارد کنید:
```json
{
"google_ip": "216.239.38.120",
"front_domain": "www.google.com",
"script_id": "PASTE_YOUR_DEPLOYMENT_ID_HERE",
"auth_key": "your-secret-password-here",
"listen_host": "127.0.0.1",
"http_port": 8085,
"socks5_port": 1080,
"log_level": "INFO",
"verify_ssl": true
}
```
- `script_id` : همان Deployment ID مرحله 2
- `auth_key` : همان رمزی که در `Code.gs` گذاشته‌اید
### مرحله 3.5: نود خروجی اختیاری برای Full Tunnel
برخی سایت‌ها (مثل ChatGPT) خروجی مستقیم از IPهای دیتاسنتر Google را مسدود می‌کنند.
برای حل این مورد، نود خروجی (exit node) را فعال کنید تا مسیر این‌گونه شود:
MasterHttpRelayVPN یک پراکسی محلی است که ترافیک مرورگر را از مسیر Google Apps Script و Domain Fronting عبور می‌دهد. برای مسیر ساده فقط همین پروژه و یک اکانت رایگان Google کافی است. اگر بعضی سایت‌ها خروجی Google را مسدود کنند، بعدا می‌توانید Exit Node اضافه کنید.
```text
مرورگر -> پراکسی محلی -> Apps Script -> Exit Node (Cloudflare / Deno / VPS) -> سایت مقصد
مرورگر -> پراکسی محلی -> مسیر Google -> رله Apps Script شما -> سایت مقصد
فیلتر فقط اتصال شبیه Google را می‌بیند
```
می‌توانید یکی از این backend های نود خروجی را deploy کنید:
## مسیر موردنیازتان را انتخاب کنید
1. Cloudflare Workers: [apps_script/cloudflare_worker.js](apps_script/cloudflare_worker.js)
2. Deno Deploy: [apps_script/deno_deploy.ts](apps_script/deno_deploy.ts)
3. سرور VPS شخصی
| می‌خواهید... | اینجا را بخوانید |
|-------------|------------------|
| برای اولین بار راه‌اندازی کنید | [شروع سریع](docs/fa/GETTING_STARTED.md) |
| با Docker اجرا کنید | [راهنمای Docker](docs/fa/DOCKER.md) |
| پراکسی را در شبکه محلی به اشتراک بگذارید | [اشتراک‌گذاری LAN](docs/fa/LAN_SHARING.md) |
| برای سایت‌های حساس Exit Node بگذارید | [راهنمای Exit Node](docs/exit-node/EXIT_NODE_DEPLOYMENT_FA.md) |
| همه تنظیمات را بفهمید | [مرجع تنظیمات](docs/fa/CONFIGURATION.md) |
| مشکلی را رفع کنید | [رفع مشکل](docs/fa/TROUBLESHOOTING.md) |
| نکات امنیتی را ببینید | [نکات امنیتی](docs/fa/SECURITY.md) |
| معماری و فایل‌ها را بشناسید | [معماری](docs/fa/ARCHITECTURE.md) |
راهنمای کامل مرحله‌به‌مرحله برای هر provider:
- [docs/exit-node/EXIT_NODE_DEPLOYMENT_FA.md](docs/exit-node/EXIT_NODE_DEPLOYMENT_FA.md) (فارسی)
- [docs/exit-node/EXIT_NODE_DEPLOYMENT.md](docs/exit-node/EXIT_NODE_DEPLOYMENT.md) (انگلیسی)
## شروع خیلی سریع
سپس همان secret را هم در کد نود خروجی (`PSK`) و هم در `config.json` یکسان بگذارید.
قبل از اجرای پراکسی، رله Google را از فایل [apps_script/Code.gs](apps_script/Code.gs) در Google Apps Script deploy کنید و این دو مقدار را آماده داشته باشید:
نمونه کانفیگ برای سوییچ بین provider ها:
- `Deployment ID` از Google Apps Script
- `AUTH_KEY`، یک رمز طولانی که باید دقیقا با `auth_key` در کانفیگ محلی یکی باشد
```json
"exit_node": {
"enabled": true,
"provider": "cloudflare",
"url": "https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev",
"psk": "CHANGE_ME_TO_A_STRONG_SECRET",
"mode": "full",
"hosts": [
"chatgpt.com",
"openai.com",
"claude.ai",
"anthropic.com"
]
}
```
پروژه را با Git یا ZIP دریافت کنید، سپس لانچر یک‌کلیکی را اجرا کنید.
نکات:
- برای تنظیم ساده، فقط `provider`، `url` و `psk` را پر کنید.
- برای تغییر backend مقدار `exit_node.provider` و `exit_node.url` را عوض کنید.
- `mode: "full"` یعنی همه ترافیک از exit node عبور می‌کند (`hosts` نادیده گرفته می‌شود).
- `mode: "selective"` یعنی فقط دامنه‌های داخل `hosts` از exit node عبور می‌کنند.
- مقدار `psk` باید دقیقا با secret تنظیم‌شده در runtime برابر باشد.
### مرحله 4: اجرا
**گزینه A: Git**
```bash
python3 main.py
git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
```
اگر همه‌چیز درست باشد، پراکسی HTTP روی `127.0.0.1:8085` و SOCKS5 روی `127.0.0.1:1080` بالا می‌آید.
**گزینه B: ZIP**
### مرحله 5: تنظیم مرورگر
1. [صفحه GitHub پروژه](https://github.com/masterking32/MasterHttpRelayVPN) را باز کنید.
2. روی **Code** -> **Download ZIP** کلیک کنید.
3. فایل ZIP را extract کنید.
4. داخل پوشه extract شده `MasterHttpRelayVPN` یک terminal باز کنید.
مرورگر را روی این پراکسی تنظیم کنید:
بعد برنامه را اجرا کنید:
- **Proxy Address:** `127.0.0.1`
- **Proxy Port:** `8085`
- **Type:** HTTP
- **SOCKS5 Port (اختیاری):** `1080`
**Windows**
نمونه تنظیم مرورگرها:
```cmd
start.bat
```
- **Firefox:** Settings -> General -> Network Settings -> Manual proxy
- **Chrome / Edge:** از تنظیمات پراکسی سیستم استفاده می‌کنند
- یا از افزونه‌هایی مثل FoxyProxy استفاده کنید
### مرحله 6: نصب گواهی CA برای HTTPS
در حالت `apps_script`، برنامه برای مدیریت HTTPS یک گواهی محلی می‌سازد. اگر آن را نصب نکنید، مرورگر برای سایت‌ها خطای امنیتی می‌دهد.
فایل گواهی بعد از اولین اجرا در این مسیر ساخته می‌شود:
`ca/ca.crt`
#### ویندوز
1. روی `ca/ca.crt` دوبار کلیک کنید.
2. گزینه **Install Certificate** را بزنید.
3. گزینه **Current User** را انتخاب کنید.
4. گزینه **Place all certificates in the following store** را بزنید.
5. از بخش **Browse**، گزینه **Trusted Root Certification Authorities** را انتخاب کنید.
6. مراحل را تا پایان ادامه دهید.
7. مرورگر را یک بار ببندید و دوباره باز کنید.
#### Firefox
Firefox معمولا certificate store جداگانه دارد:
1. به **Settings -> Privacy & Security -> Certificates** بروید.
2. روی **View Certificates** کلیک کنید.
3. در تب **Authorities**، روی **Import** بزنید.
4. فایل `ca/ca.crt` را انتخاب کنید.
5. گزینه **Trust this CA to identify websites** را فعال کنید.
> **نصب خودکار هنگام اجرا:** در حالت `apps_script`، برنامه به صورت خودکار وضعیت اعتماد گواهی CA را بررسی کرده و در صورت نیاز نصب می‌کند. در صورت موفقیت پیام تأیید در لاگ نمایش داده می‌شود. اگر نصب خودکار ناموفق بود، می‌توانید دستور `python main.py --install-cert` را اجرا کنید.
نکته امنیتی: پوشه `ca/` را با کسی به اشتراک نگذارید. اگر خواستید از اول گواهی جدید بسازید، این پوشه را حذف کنید تا دوباره ساخته شود.
---
## حالت‌های موجود
این پروژه کاملاً روی حالت **Apps Script** تمرکز دارد. فقط به یک اکانت رایگان Google نیاز دارید — بدون VPS، بدون سرور، بدون Cloudflare. همه‌چیز برای همین حالت تنظیم شده است.
---
## اشتراک‌گذاری در شبکه محلی (اختیاری)
به‌طور پیش‌فرض، پروکسی فقط به `127.0.0.1` (localhost) گوش می‌دهد، به این معنی که فقط کامپیوتر شما می‌تواند از آن استفاده کند. برای اینکه سایر دستگاه‌های موجود در شبکه محلی (LAN) شما بتوانند از این پروکسی استفاده کنند:
۱. در فایل `config.json` خود، مقدار `"lan_sharing"` را `true` قرار دهید.
۲. پروکسی به طور خودکار به تمام رابط‌های شبکه (`0.0.0.0`) گوش خواهد داد.
۳. در لاگ راه‌اندازی، آدرس‌های IP شبکه محلی شما که سایر دستگاه‌ها می‌توانند به آن متصل شوند، نمایش داده می‌شود.
**نمونه پیکربندی برای شبکه محلی:**
json
{
"lan_sharing": true,
"listen_host": "0.0.0.0",
"http_port": 8085
}
**هشدار امنیتی:** وقتی اشتراک‌گذاری در شبکه محلی فعال باشد، هر کسی در شبکه محلی شما می‌تواند از پروکسی شما استفاده کند. اطمینان حاصل کنید که شبکه شما مورد اعتماد است و اقدامات امنیتی بیشتری را در نظر بگیرید.
**در سایر دستگاه‌ها:** آن‌ها را طوری پیکربندی کنید که از آدرس IP کامپیوتر شما در شبکه محلی (که در لاگ راه‌اندازی نمایش داده می‌شود) و پورت 8085 به عنوان پروکسی HTTP استفاده کنند.
---
## Docker (اختیاری)
اگر ترجیح می‌دهید پروکسی را در یک container اجرا کنید، Docker پشتیبانی می‌شود.
**پیش‌نیاز:** [Docker](https://docs.docker.com/get-docker/) و [Docker Compose](https://docs.docker.com/compose/)
### راه‌اندازی
۱. فایل config را کپی و تکمیل کنید:
```bash
cp config.example.json config.json
# script_id و auth_key را پر کنید
```
۲. Build و start کنید:
```bash
docker compose up -d
```
Container به‌طور خودکار روی `0.0.0.0` گوش می‌دهد، پس هر دو پورت از host قابل دسترس هستند:
- `127.0.0.1:8085` — HTTP proxy
- `127.0.0.1:1080` — SOCKS5 proxy
### گواهی CA در Docker
در اولین اجرا، container فایل `ca/ca.crt` را داخل volume مربوط به `./ca` روی host می‌سازد. آن را به صورت دستی در مرورگر نصب کنید — مرحله ۶ را ببینید. اجرای `--install-cert` داخل container تأثیری روی cert store سیستم host ندارد.
### دستورهای مفید
**Linux / macOS**
```bash
docker compose up -d # اجرا در پس‌زمینه
docker compose logs -f # دنبال کردن لاگ
docker compose restart # ری‌استارت بعد از تغییر config
docker compose down # توقف و حذف container
docker compose build # بازسازی image بعد از تغییر کد
chmod +x start.sh
./start.sh
```
> **فایل `config.json` به صورت read-only** داخل container mount می‌شود و هرگز داخل image قرار نمی‌گیرد، پس اطلاعات شما روی host باقی می‌ماند.
لانچر virtualenv می‌سازد، وابستگی‌ها را نصب می‌کند، اگر `config.json` وجود نداشته باشد setup wizard را باز می‌کند، و سپس پراکسی را اجرا می‌کند.
---
## تنظیمات اصلی
بعد از اجرا، مرورگر را روی این پراکسی تنظیم کنید:
| تنظیم | توضیح |
|------|-------|
| `auth_key` | رمز مشترک بین کامپیوتر شما و رله |
| `script_id` | شناسه Deployment مربوط به Google Apps Script شما |
| `listen_host` | محل گوش دادن (`127.0.0.1` = فقط همین کامپیوتر، `0.0.0.0` = همه اینترفیس‌ها برای اشتراک‌گذاری LAN) |
| `http_port` | پورت HTTP پروکسی (پیش‌فرض: `8085`) |
| `lan_sharing` | فعال‌سازی اشتراک‌گذاری LAN تا دستگاه‌های دیگر در شبکه شما بتوانند از پروکسی استفاده کنند (به‌صورت پیش‌فرض `false`) |
| `log_level` | میزان جزئیات لاگ: `DEBUG`، `INFO`، `WARNING`، `ERROR` |
| گزینه | مقدار |
|-------|-------|
| نوع پراکسی | HTTP |
| آدرس | `127.0.0.1` |
| پورت | `8085` |
| پورت SOCKS5، اختیاری | `1080` |
### تنظیمات پیشرفته
برای سایت‌های HTTPS، اگر برنامه نتوانست گواهی را خودکار نصب کند، فایل `ca/ca.crt` را نصب کنید. راهنمای کامل در [شروع سریع](docs/fa/GETTING_STARTED.md) است.
| تنظیم | مقدار پیش‌فرض | توضیح |
|------|---------------|-------|
| `google_ip` | `216.239.38.120` | IP مورد استفاده برای مسیر Google |
| `front_domain` | `www.google.com` | دامنه‌ای که فیلتر می‌بیند |
| `verify_ssl` | `true` | بررسی اعتبار TLS فقط برای اتصال fronted محلی به Google/CDN |
| `relay_timeout` | `25` | مهلت کل برای هر درخواست relay قبل از fail شدن |
| `tls_connect_timeout` | `15` | مهلت اتصال TLS پروکسی به endpoint fronted روی Google/CDN |
| `tcp_connect_timeout` | `10` | مهلت اتصال برای tunnel مستقیم و SNI-rewrite |
| `script_ids` | - | چند Deployment ID برای load balancing |
| `chunked_download_extensions` | مطابق [config.example.json](config.example.json) | پسوند فایل‌هایی که باید از دانلود range-parallel استفاده کنند. از `".*"` هم برای probe همه دانلودهای GET پشتیبانی می‌شود. |
| `chunked_download_min_size` | `5242880` | حداقل اندازه کل فایل (۵ مگابایت) برای فعال ماندن دانلود موازی |
| `chunked_download_chunk_size` | `524288` | اندازه هر chunk در دانلود موازی |
| `chunked_download_max_parallel` | `8` | حداکثر تعداد range request همزمان برای یک دانلود |
| `chunked_download_max_chunks` | `256` | سقف نرم برای تعداد کل chunk request ها؛ برای فایل‌های خیلی بزرگ اندازه chunk به‌صورت خودکار بیشتر می‌شود |
| `hosts` | `{}` | نگاشت دستی DNS (`hostname` یا `.suffix` به IP). مثال: `{ "example.org": "93.184.216.34", ".internal.lan": "192.168.1.10" }`. |
| `block_hosts` | `[]` | هاست‌هایی که هرگز نباید tunnel شوند (پاسخ 403). نام دقیق (`ads.example.com`) یا پسوند با نقطه‌ی ابتدایی (`.doubleclick.net`). |
| `direct_hosts` | `[]` | دامنه‌هایی که همیشه باید مستقیم بروند (بدون MITM و بدون relay/domain-fronting). از نام دقیق یا پسوند نقطه‌دار پشتیبانی می‌کند. |
| `bypass_hosts` | `["localhost", ".local", ".lan", ".home.arpa"]` | هاست‌هایی که مستقیم می‌روند (بدون MITM و بدون رله). برای منابع داخلی شبکه یا سایت‌هایی که با MITM مشکل دارند. |
| `direct_google_exclude` | مراجعه به [config.example.json](config.example.json) | اپ‌های Google که باید از مسیر MITM برای رله استفاده کنند به‌جای tunnel مستقیم. |
| `youtube_via_relay` | `false` | مسیردهی YouTube (`youtube.com`، `youtu.be`، `youtube-nocookie.com`) از طریق رله Apps Script به‌جای مسیر SNI-rewrite. مسیر SNI-rewrite از IP فرانت‌اند Google عبور می‌کند که SafeSearch را اجباری می‌کند و می‌تواند باعث خطای **«ویدیو در دسترس نیست»** شود. با فعال کردن این گزینه، پخش ویدیو درست می‌شود اما تعداد اجراهای Apps Script بیشتر و تأخیر اندکی بالاتر می‌رود. |
| `exit_node.provider` | `cloudflare` | backend انتخاب‌شده برای exit node: `cloudflare`، `deno`، `vps` یا `custom`. |
| `exit_node.url` | `""` | آدرس ساده و اصلی برای provider انتخاب‌شده. |
## قدم‌های بعدی رایج
نمونه کاربردی برای policy ها:
- اگر مرورگر خطای certificate نشان می‌دهد، [بخش خطای گواهی](docs/fa/TROUBLESHOOTING.md#خطاهای-certificate) را ببینید.
- اگر خطای `unauthorized` می‌بینید، مقدار `AUTH_KEY` در [apps_script/Code.gs](apps_script/Code.gs) باید دقیقا با `auth_key` در `config.json` یکی باشد.
- اگر سرعت پایین است یا timeout می‌گیرید، دستور `python main.py --scan` را اجرا کنید و [مرجع تنظیمات](docs/fa/CONFIGURATION.md#دستورهای-عیب‌یابی) را ببینید.
- اگر سایت‌هایی مثل ChatGPT یا Turnstile با خروجی Google مشکل دارند، [راهنمای Exit Node](docs/exit-node/EXIT_NODE_DEPLOYMENT_FA.md) را بخوانید.
```json
{
"block_hosts": [
"ads.example.com",
".doubleclick.net"
],
"direct_hosts": [
"chat.openai.com",
".openai.com"
],
"hosts": {
"example.org": "93.184.216.34",
".internal.lan": "192.168.1.10"
}
}
```
## پشتیبانی و اطلاع‌رسانی
- `block_hosts`: این دامنه‌ها کامل مسدود می‌شوند (پاسخ `403`).
- `direct_hosts`: این دامنه‌ها همیشه مستقیم می‌روند (بدون MITM و بدون relay fronting).
- `hosts`: قبل از DNS واقعی، نگاشت دستی اعمال می‌شود (برای تست یا split-DNS workaround).
- کانال Telegram: [https://t.me/masterdnsvpn](https://t.me/masterdnsvpn)
- کلاینت Windows: [MHRWindowsApp](https://github.com/AriPath/MHRWindowsApp)
- منبع فیلتر تبلیغات: [PersianBlocker](https://github.com/MasterKia/PersianBlocker/)
نکته: سقف اندازه پاسخ relay حالا یک مقدار ثابت کدی (`MAX_RESPONSE_BODY_BYTES`) در [src/core/constants.py](src/core/constants.py) است و دیگر گزینه‌ی کاربری config نیست.
## امنیت
### وابستگی‌های اختیاری
همه وابستگی‌های [`requirements.txt`](requirements.txt) اختیاری هستند — در حالت پایه بدون هیچ‌کدام کار می‌کند، ولی با نصب آن‌ها امکانات بیشتری در دسترس است:
| بسته | کاربرد |
|------|---------|
| `cryptography` | رمزگشایی MITM برای HTTPS (در حالت `apps_script` لازم است) |
| `h2` | ارتباط HTTP/2 با رله Apps Script (به‌طور محسوسی سریع‌تر) |
| `brotli` | پشتیبانی از فشرده‌سازی `Content-Encoding: br` |
| `zstandard` | پشتیبانی از فشرده‌سازی `Content-Encoding: zstd` |
### استفاده از چند Script ID
اگر چند نسخه از `Code.gs` را deploy کنید، می‌توانید همه Deployment ID ها را در آرایه `script_ids` بگذارید:
```json
{
"script_ids": [
"DEPLOYMENT_ID_1",
"DEPLOYMENT_ID_2",
"DEPLOYMENT_ID_3"
]
}
```
> **نکته :** اگر از چندین دیپلویمنت آیدی استفاده میکنید توجه داشته باشید که auth_key های همه دیپلویمنت ها باید یکسان باشند.
---
## به‌روزرسانی `Code.gs`
اگر فایل `Code.gs` را تغییر دادید، باید دوباره **Deploy -> New deployment** بزنید و `script_id` جدید را داخل `config.json` قرار دهید. صرفا ذخیره کردن کد، نسخه فعال را عوض نمی‌کند.
---
## دستورهای اجرا
```bash
python3 main.py
python3 main.py -p 9090
python3 main.py --socks5-port 1081
python3 main.py --log-level DEBUG
python3 main.py -c /path/to/config.json
python3 main.py --install-cert # نصب گواهی CA و خروج
python3 main.py --uninstall-cert # حذف گواهی CA و خروج
python3 main.py --no-cert-check # رد شدن از بررسی خودکار گواهی
python3 main.py --scan # اسکن IP های Google و یافتن سریع‌ترین
```
> **نصب خودکار:** هنگام اجرا در حالت `apps_script`، برنامه به‌طور خودکار بررسی می‌کند که آیا گواهی CA قابل اعتماد است یا نه و در صورت نیاز آن را نصب می‌کند. اگر نصب خودکار ناموفق بود (مثلاً نیاز به دسترسی مدیر دارد)، می‌توانید دستور `python main.py --install-cert` را اجرا کنید یا مراحل مرحله ۶ را دنبال کنید.
### اسکن کردن برای یافتن سریع‌ترین IP گوگل
اگر `google_ip` فعلی در `config.json` بلاک شده یا آهسته است، می‌توانید اسکن کنید تا سریع‌ترین آن را پیدا کنید:
```bash
python3 main.py --scan
```
این دستور:
1. ۲۷ IP برای fronting Google را به‌صورت موازی بررسی می‌کند
2. تأخیر (latency) از شبکه شما را اندازه می‌گیرد
3. نتایج را در جدول نمایش می‌دهد
4. سریع‌ترین IP را پیشنهاد می‌دهد
5. اگر حداقل یک IP در دسترس باشد کد خروج ۰، ورنه ۱ را برمی‌گرداند
**نمونه خروجی:**
```
Scanning 27 Google frontend IPs
SNI: www.google.com
Timeout: 4s per IP
Concurrency: 8 parallel probes
IP LATENCY STATUS
-------------------- ------------ -------------------------
216.239.32.120 42ms OK
216.239.34.120 45ms OK
216.239.36.120 52ms OK
142.250.80.142 timeout timeout
...
Result: 15 / 27 reachable
Top 3 fastest IPs:
1. 216.239.32.120 (42ms)
2. 216.239.34.120 (45ms)
3. 216.239.36.120 (52ms)
Recommended: Set "google_ip": "216.239.32.120" in config.json
```
پس از اسکن، مقدار `google_ip` در `config.json` را با IP پیشنهادی به‌روزرسانی کنید و پراکسی را دوباره راه‌اندازی کنید.
---
## معماری
```
┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
│ Browser │────►│ Local Proxy │────►│ CDN / Google │────►│ Relay │──► Internet
│ │◄────│ (this tool) │◄────│ (fronted) │◄────│ Endpoint │◄──
└─────────┘ └──────────────┘ └─────────────┘ └──────────┘
```
---
## فایل‌های پروژه
```
MasterHttpRelayVPN/
├── main.py # نقطه شروع: پراکسی را راه‌اندازی می‌کند
├── config.example.json # نمونه کانفیگ (به config.json کپی شود)
├── requirements.txt # وابستگی‌های اختیاری پایتون
├── apps_script/
│ ├── Code.gs # اسکریپت رله روی Google Apps Script
│ ├── cloudflare_worker.js # template نود خروجی برای Cloudflare Workers
│ └── deno_deploy.ts # template نود خروجی برای Deno Deploy
├── ca/ # گواهی MITM (هرگز به اشتراک نگذارید)
│ ├── ca.crt
│ └── ca.key
└── src/ # پیاده‌سازی پراکسی
├── proxy_server.py # دریافت CONNECT و SOCKS5
├── domain_fronter.py # کلاینت رله Apps Script (fronted از طریق Google)
├── h2_transport.py # ارتباط HTTP/2 (اختیاری)
├── mitm.py # ساخت و مدیریت گواهی‌ها
├── cert_installer.py # نصب خودکار CA در ویندوز/مک/لینوکس + فایرفاکس
├── codec.py # رمزگشای Content-Encoding (gzip/deflate/br/zstd)
├── google_ip_scanner.py # اسکنر IP های Google برای یافتن سریع‌ترین
├── constants.py # مقادیر پیش‌فرض قابل تنظیم
└── logging_utils.py # فرمت‌دهنده‌ی لاگ رنگی و منظم
```
---
## رفع مشکل
| مشکل | راه‌حل |
|------|--------|
| `Config not found` | فایل `config.example.json` را به `config.json` کپی کنید |
| خطای certificate در مرورگر | گواهی CA را نصب کنید (مرحله ۶) |
| تلگرام کار می‌کند ولی مرورگر سایت‌ها را باز نمی‌کند | تقریباً مطمئناً گواهی CA نصب نشده. مرحله ۶ را دنبال کنید، سپس مرورگر را **کاملاً ببندید و دوباره باز کنید** (برای Chrome/Edge مطمئن شوید هیچ پروسه Chrome در پس‌زمینه باز نیست). |
| گواهی نصب شد ولی مرورگر هنوز خطا می‌دهد | Chrome و Edge گواهی‌ها را cache می‌کنند — باید مرورگر را **کاملاً ببندید** (Task Manager یا system tray را چک کنید) و دوباره باز کنید. Firefox نیاز به import جداگانه دارد (بخش Firefox در مرحله ۶). |
| خطای `unauthorized` | مقدار `auth_key` و `AUTH_KEY` باید یکسان باشند |
| timeout | IP دیگری برای Google امتحان کنید |
| سرعت کم | از چند `script_id` برای load balancing استفاده کنید |
| خطای `502 Bad JSON` | Google به‌جای JSON پاسخ HTML برگردانده (مثلاً صفحه quota یا 404). دلایل: `script_id` اشتباه، تجاوز از سهمیه روزانه Apps Script، یا عدم ایجاد deployment جدید پس از ویرایش `Code.gs`. `script_id` را بررسی کنید و یک **deployment جدید** بسازید. |
| تلگرام روی HTTP proxy کار می‌کند ولی روی SOCKS5 نه | **طبیعی است.** کلاینت SOCKS5 نام دامنه را روی سیستم خودش resolve می‌کند و مستقیم به IP وصل می‌شود، پس بایت‌های MTProto تلگرام به IP فیلترشده می‌رسد که نه می‌توانیم direct-tunnel کنیم و نه MITM. تلگرام را به‌جای SOCKS5 به صورت **HTTP proxy** (`127.0.0.1:8085`) تنظیم کنید — در این حالت نام دامنه ارسال می‌شود و پراکسی با SNI-rewrite از طریق Google عبور می‌دهد. |
| گوگل و یوتیوب باز می‌شوند ولی ویدیوهای یوتیوب پخش نمی‌شوند و سایت‌های دیگر باز نمی‌شوند | اتصال به `script.google.com` با موفقیت برقرار نشده. احتمالاً مشکل از deployment فایل `Code.gs` روی Google Apps Script است یا سهمیه روزانه اجرا تمام شده. یک deployment جدید از `Code.gs` بسازید و `script_id` را بررسی کنید، یا منتظر بمانید تا سهمیه reset شود (نیمه‌شب به وقت Pacific / ۱۰:۳۰ ظهر به وقت ایران). |
---
## نکات امنیتی
- فایل `config.json` را با کسی به اشتراک نگذارید.
- مقدار پیش‌فرض `AUTH_KEY` را قبل از deploy عوض کنید.
- پوشه `ca/` را منتشر نکنید.
- بهتر است `listen_host` روی `127.0.0.1` بماند.
- هر دیپلویمنت روی گوگل اسکریپت دارای محدودیت 20,000 درخواست در هر 24 ساعت است
---
## منابع
- **لیست‌های فیلتر آگهی:** [PersianBlocker](https://github.com/MasterKia/PersianBlocker/) نوشته MasterKia
---
## پروژه‌های جانبی
- [کلاینت ویندوز MHRWindowsApp](https://github.com/AriPath/MHRWindowsApp)
> یک اپلیکیشن ویندوز که بر مبنای MasterHttpRelay ساخته شده است.
> این پروژه توسط AriPath توسعه داده شده است و می‌توانید تنها با یک کلیک، بدون هیچ چالش و پیش‌نیازی، از MHR استفاده کنید.
---
این پروژه برای آموزش، تست و پژوهش ارائه شده است. مسئولیت رعایت قوانین و شرایط سرویس‌ها با کاربر است. فایل `config.json`، مقدار `auth_key`، پوشه `ca/`، و آدرس Exit Node همراه با PSK معتبر را با کسی به اشتراک نگذارید. قبل از فعال کردن استفاده در شبکه محلی، [نکات امنیتی](docs/fa/SECURITY.md) را بخوانید.
## License
docs/ARCHITECTURE.md
+58
View File
@@ -0,0 +1,58 @@
# Architecture
MasterHttpRelayVPN is a local proxy plus a user-deployed relay.
## Simple Flow
```text
Browser or app
-> local HTTP/SOCKS5 proxy
-> Google-facing fronted TLS connection
-> Apps Script relay
-> target website
```
The network sees a Google-facing connection. The relay request carries the real target URL inside encrypted traffic.
## Main Pieces
| File or folder | Purpose |
|----------------|---------|
| [main.py](../main.py) | CLI entry point. Loads config, handles cert commands, starts the proxy. |
| [setup.py](../setup.py) | Interactive wizard that writes `config.json`. |
| [start.bat](../start.bat) | Windows one-click launcher. Creates venv, installs deps, runs setup, starts proxy. |
| [start.sh](../start.sh) | Linux/macOS launcher with the same role. |
| [config.example.json](../config.example.json) | Example configuration and defaults. |
| [apps_script/Code.gs](../apps_script/Code.gs) | Google Apps Script relay deployed by the user. |
| [src/proxy/proxy_server.py](../src/proxy/proxy_server.py) | HTTP CONNECT, MITM routing, SOCKS5, host policy decisions. |
| [src/proxy/mitm.py](../src/proxy/mitm.py) | Local certificate authority and generated leaf certificates. |
| [src/relay/domain_fronter.py](../src/relay/domain_fronter.py) | Apps Script relay client, batching, retries, H1/H2 transport selection. |
| [src/relay/h2_transport.py](../src/relay/h2_transport.py) | Optional HTTP/2 transport for multiplexing. |
| [src/core/cert_installer.py](../src/core/cert_installer.py) | CA install/uninstall support for OS and Firefox stores. |
| [src/core/google_ip_scanner.py](../src/core/google_ip_scanner.py) | Google frontend scanner used by `python main.py --scan`. |
## Request Handling
1. The browser sends HTTP or HTTPS proxy traffic to `127.0.0.1:8085`.
2. For HTTPS, the proxy can perform local MITM using the generated CA.
3. Host rules decide whether traffic is direct, blocked, bypassed, or relayed.
4. Relayed requests are encoded as JSON for Apps Script.
5. Apps Script fetches the destination and returns a serialized HTTP response.
6. The local proxy reconstructs the HTTP response for the browser.
## Performance Features
- Warm TLS connection pool for H1 fallback.
- HTTP/2 multiplexing when the `h2` package is installed.
- Batching for static sub-resource bursts.
- Optional multiple `script_ids` for load balancing.
- Optional range-parallel download acceleration for large files.
- Optional exit node for destinations that block Google egress.
## Exit Node Path
```text
Browser -> Local proxy -> Apps Script -> Exit node -> Target website
```
Exit nodes can run on Cloudflare Workers, Deno Deploy, or a VPS. See [Exit Node Guide](exit-node/EXIT_NODE_DEPLOYMENT.md).
docs/CONFIGURATION.md
+159
View File
@@ -0,0 +1,159 @@
# Configuration Reference
Most users only need `script_id`, `auth_key`, and the default local ports. This page explains the rest when you need to tune behavior.
## Required Settings
| Setting | Meaning |
|---------|---------|
| `script_id` | Your Google Apps Script Deployment ID. Use this for one deployment. |
| `script_ids` | Array of Deployment IDs for load balancing. Use instead of `script_id`. |
| `auth_key` | Shared password. Must match `AUTH_KEY` inside [apps_script/Code.gs](../apps_script/Code.gs). |
If you use `script_ids`, every deployed copy of [apps_script/Code.gs](../apps_script/Code.gs) must use the same `AUTH_KEY`.
## Proxy Binding
| Setting | Default | Meaning |
|---------|---------|---------|
| `listen_host` | `127.0.0.1` | Address the proxy listens on. Use `127.0.0.1` for only this computer. |
| `http_port` | `8085` | HTTP proxy port for browsers and most apps. |
| `socks5_port` | `1080` | SOCKS5 proxy port. Some apps resolve hostnames locally, so HTTP proxy is often more reliable. |
| `lan_sharing` | `false` | When true, the app listens on LAN interfaces so other devices can use it. |
See [LAN Sharing](LAN_SHARING.md) before enabling access for other devices.
## Domain Fronting
| Setting | Default | Meaning |
|---------|---------|---------|
| `google_ip` | `216.239.38.120` | Google frontend IP to connect through. |
| `front_domain` | `www.google.com` | Domain visible in the fronted TLS connection. |
| `front_domains` | `www.google.com`, `mail.google.com`, `accounts.google.com` | Optional SNI rotation pool. |
| `verify_ssl` | `true` | Verifies TLS certificates for the Google-facing connection. Keep true in normal use. |
If the current Google IP is blocked or slow, run `python main.py --scan` and use the recommended IP.
## Timeouts And Performance
| Setting | Default | Meaning |
|---------|---------|---------|
| `relay_timeout` | `25` | Maximum time for one relayed request. |
| `tls_connect_timeout` | `15` | Timeout for TLS connection setup to the fronted Google endpoint. |
| `tcp_connect_timeout` | `10` | Timeout for direct TCP tunnels and SNI-rewrite connections. |
| `h2_connections` | `2` | Parallel HTTP/2 connections to the relay. More can improve throughput, but uses more resources. |
| `parallel_relay` | `1` | Number of Apps Script deployments to race per safe request when multiple IDs exist. |
| `enable_sub_batch` | `true` | Allows batch splitting across H2 connections for large or mixed request bursts. |
## Downloads
| Setting | Meaning |
|---------|---------|
| `chunked_download_extensions` | File extensions that can use parallel range downloading. `".*"` probes all GET downloads. |
| `chunked_download_min_size` | Minimum file size before range-parallel downloading remains active. |
| `chunked_download_chunk_size` | Size of each range request. |
| `chunked_download_max_parallel` | Maximum simultaneous range requests for one download. |
| `chunked_download_max_chunks` | Soft maximum chunk count. Chunk size is raised automatically for very large files. |
## Host Policies
| Setting | Meaning |
|---------|---------|
| `block_hosts` | Hosts that should return HTTP 403 and never be tunneled. Supports exact names and `.suffix` patterns. |
| `direct_hosts` | Hosts that should always go direct without MITM or relay fronting. |
| `bypass_hosts` | Local or special hosts that bypass MITM and relay. Useful for `.lan`, `.local`, and internal services. |
| `hosts` | Manual DNS override map. Useful for testing or split-DNS workarounds. |
| `direct_google_exclude` | Google services that should stay on the relay path instead of direct tunnel. |
| `youtube_via_relay` | Routes YouTube through Apps Script relay. Useful if the direct Google path causes playback restrictions. |
Example:
```json
{
"block_hosts": ["ads.example.com", ".doubleclick.net"],
"direct_hosts": ["chat.openai.com", ".openai.com"],
"hosts": {
"example.org": "93.184.216.34",
".internal.lan": "192.168.1.10"
}
}
```
## Exit Node
Use an exit node when a destination blocks Google datacenter egress.
```json
"exit_node": {
"enabled": true,
"provider": "cloudflare",
"url": "https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev",
"psk": "CHANGE_ME_TO_A_STRONG_SECRET",
"mode": "full",
"hosts": ["chatgpt.com", "openai.com"]
}
```
| Setting | Meaning |
|---------|---------|
| `exit_node.enabled` | Turns exit-node routing on or off. |
| `exit_node.provider` | `cloudflare`, `deno`, `vps`, or `custom`. |
| `exit_node.url` | URL for the selected provider. |
| `exit_node.psk` | Shared secret for the exit node. Must match the deployed exit-node code. |
| `exit_node.mode` | `full` for all relayed traffic, `selective` for only listed hosts. |
| `exit_node.hosts` | Host list used by selective mode. |
Deployment steps are in [Exit Node Guide](exit-node/EXIT_NODE_DEPLOYMENT.md).
## Ad Blocking
`adblock_lists` accepts host/domain filter list URLs. The default config uses PersianBlocker lists. Remove the list or set it empty if you do not want this behavior.
## Optional Dependencies
Install everything from [requirements.txt](../requirements.txt) for the full feature set.
| Package | Provides |
|---------|----------|
| `cryptography` | Local MITM certificate generation and HTTPS interception. |
| `h2` | HTTP/2 transport to Apps Script. |
| `brotli` | `Content-Encoding: br` decoding. |
| `zstandard` | `Content-Encoding: zstd` decoding. |
## Command Line Options
```bash
python main.py # Start normally
python main.py -p 9090 # Override HTTP port
python main.py --socks5-port 1081 # Override SOCKS5 port
python main.py --host 0.0.0.0 # Override listen host
python main.py --log-level DEBUG # More logs
python main.py -c path/to/config.json # Use another config file
python main.py --install-cert # Install CA and exit
python main.py --uninstall-cert # Remove CA and exit
python main.py --no-cert-check # Skip automatic CA trust check
python main.py --scan # Find a faster reachable Google IP
```
Environment overrides are also supported: `DFT_CONFIG`, `DFT_AUTH_KEY`, `DFT_SCRIPT_ID`, `DFT_HTTP_PORT`, `DFT_PORT`, `DFT_HOST`, `DFT_SOCKS5_PORT`, and `DFT_LOG_LEVEL`.
## Diagnostic Commands
Scan Google fronting IPs:
```bash
python main.py --scan
```
Install or remove the local CA:
```bash
python main.py --install-cert
python main.py --uninstall-cert
```
Show detailed logs:
```bash
python main.py --log-level DEBUG
```
docs/DOCKER.md
+69
View File
@@ -0,0 +1,69 @@
# Docker Guide
Use Docker when you want the proxy isolated from your system Python environment.
## Requirements
- Docker
- Docker Compose
- A completed `config.json`
## Setup
Create `config.json` first:
```bash
cp config.example.json config.json
```
Edit `config.json` and set at least:
```json
{
"script_id": "YOUR_APPS_SCRIPT_DEPLOYMENT_ID",
"auth_key": "THE_SAME_SECRET_AS_CODE_GS"
}
```
Then start the container:
```bash
docker compose up -d
```
The compose file exposes:
| Port | Use |
|------|-----|
| `8085` | HTTP proxy |
| `1080` | SOCKS5 proxy |
Configure your browser to use HTTP proxy `127.0.0.1:8085`.
## Useful Commands
```bash
docker compose up -d # Start in background
docker compose logs -f # Follow logs
docker compose restart # Restart after config changes
docker compose down # Stop and remove container
docker compose build # Rebuild after code changes
```
## Certificate Handling
The container writes the generated CA into `./ca` on your host because [docker-compose.yml](../docker-compose.yml) mounts that directory.
Install this file on the host, not inside the container:
```text
ca/ca.crt
```
Running `python main.py --install-cert` inside the container cannot update your host OS or browser trust store.
## Config And Secrets
[docker-compose.yml](../docker-compose.yml) mounts `config.json` read-only into the container. Your secrets stay on the host and are not baked into the image.
Do not commit or share your real `config.json`, `auth_key`, `ca/`, or exit-node PSK.
docs/GETTING_STARTED.md
+158
View File
@@ -0,0 +1,158 @@
# Getting Started
This guide keeps only the setup path most users need. Follow it once, then come back to the root README only when you need another topic.
## What You Need
- Python 3.10 or newer
- A free Google account
- Git, or the ZIP download from GitHub
- A browser where you can set an HTTP proxy
## 1. Get The Project
Choose whichever option works on your network.
**Option A: Git**
```bash
git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN
```
**Option B: ZIP**
1. Open [the GitHub repository](https://github.com/masterking32/MasterHttpRelayVPN).
2. Click **Code** -> **Download ZIP**.
3. Extract the ZIP file.
4. Open a terminal inside the extracted `MasterHttpRelayVPN` folder.
## 2. Deploy The Google Relay
The relay is the small Apps Script program that fetches websites for you.
1. Open [Google Apps Script](https://script.google.com/) and sign in.
2. Click **New project**.
3. Delete the default editor content.
4. Open [apps_script/Code.gs](../apps_script/Code.gs), copy everything, and paste it into Apps Script.
5. Change this line to a long secret:
```javascript
const AUTH_KEY = "your-secret-password-here";
```
6. Click **Deploy** -> **New deployment**.
7. Select **Web app**.
8. Set **Execute as** to **Me**.
9. Set **Who has access** to **Anyone**.
10. Click **Deploy**, authorize the app, and copy the **Deployment ID**.
Keep the `AUTH_KEY` and Deployment ID nearby. You need both locally.
## 3. Run The One-Click Launcher
**Windows**
```cmd
start.bat
```
**Linux / macOS**
```bash
chmod +x start.sh
./start.sh
```
The launcher creates `.venv`, installs dependencies, runs `setup.py` if `config.json` is missing, and starts the proxy.
If dependency installation fails through PyPI, the launcher retries through the runflare mirror automatically.
## 4. Answer The Setup Wizard
When the wizard opens:
1. Enter the same `auth_key` you placed inside [apps_script/Code.gs](../apps_script/Code.gs).
2. Paste the Apps Script Deployment ID.
3. Keep the default HTTP proxy port `8085` unless you already use that port.
4. Keep LAN sharing off unless other devices must use this proxy.
The wizard writes `config.json` for you.
## 5. Configure Your Browser
Use the HTTP proxy for normal browsing:
| Field | Value |
|-------|-------|
| Proxy type | HTTP |
| Address | `127.0.0.1` |
| Port | `8085` |
Firefox path: **Settings** -> **General** -> **Network Settings** -> **Manual proxy**. Enter `127.0.0.1` and `8085`, then enable the option to also use it for HTTPS.
Chrome and Edge use the system proxy on Windows. You can also use extensions such as FoxyProxy or SwitchyOmega for easier switching.
## 6. Install The CA Certificate
HTTPS browsing needs the local CA certificate generated by the proxy. The file is created at `ca/ca.crt` after first run.
The app tries to install it automatically. If it cannot, install it manually:
**Windows**
1. Double-click `ca/ca.crt`.
2. Choose **Install Certificate**.
3. Choose **Current User**.
4. Choose **Place all certificates in the following store**.
5. Select **Trusted Root Certification Authorities**.
6. Finish, then fully restart your browser.
**macOS**
1. Open `ca/ca.crt` in Keychain Access.
2. Find the certificate and open it.
3. Expand **Trust**.
4. Set **When using this certificate** to **Always Trust**.
5. Close the dialog, enter your password, and restart your browser.
**Linux Ubuntu / Debian**
```bash
sudo cp ca/ca.crt /usr/local/share/ca-certificates/masterhttp-relay.crt
sudo update-ca-certificates
```
Restart your browser after installing.
**Firefox**
Firefox may use a separate certificate store:
1. Open **Settings** -> **Privacy & Security** -> **Certificates** -> **View Certificates**.
2. Go to **Authorities**.
3. Click **Import** and select `ca/ca.crt`.
4. Enable **Trust this CA to identify websites**.
## Manual Run Commands
Use these only if you are not using the launcher:
```bash
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python setup.py
.venv\Scripts\python main.py
```
On Linux / macOS, replace `.venv\Scripts\python` with `.venv/bin/python`.
## Done
When everything is working, the terminal shows the HTTP proxy on `127.0.0.1:8085` and SOCKS5 on `127.0.0.1:1080`.
Next useful pages:
- [Troubleshooting](TROUBLESHOOTING.md)
- [Configuration Reference](CONFIGURATION.md)
- [Exit Node Guide](exit-node/EXIT_NODE_DEPLOYMENT.md)
docs/LAN_SHARING.md
+41
View File
@@ -0,0 +1,41 @@
# LAN Sharing
By default, MasterHttpRelayVPN listens only on `127.0.0.1`, so only the same computer can use it. LAN sharing lets phones, tablets, or other computers on your local network use your proxy.
## When To Use It
Use LAN sharing only on a trusted private network. Anyone who can reach the proxy can send traffic through it.
## Enable LAN Sharing
Set this in `config.json`:
```json
{
"lan_sharing": true,
"listen_host": "0.0.0.0",
"http_port": 8085
}
```
Restart the proxy. The startup log prints LAN addresses other devices can use.
## Configure Other Devices
On the other device, set the HTTP proxy to:
| Field | Value |
|-------|-------|
| Address | Your computer's LAN IP from the startup log |
| Port | `8085` |
| Type | HTTP |
If the other device browses HTTPS websites, it also needs to trust the CA certificate from `ca/ca.crt`.
## Safety Checklist
- Use this only on networks you trust.
- Turn it off when you do not need it.
- Keep `auth_key` private.
- Never share the `ca/` folder.
- Prefer `127.0.0.1` for normal single-computer use.
docs/SECURITY.md
+50
View File
@@ -0,0 +1,50 @@
# Security Notes
MasterHttpRelayVPN is a powerful local proxy. Treat its secrets and generated certificates carefully.
## Responsibility
This project is provided for educational, testing, and research use. You are responsible for following applicable laws, network rules, account rules, and service terms.
## Secrets You Must Protect
Never share:
- `config.json`
- `auth_key`
- `ca/ca.key`
- the full `ca/` folder
- an exit-node URL together with a valid PSK
- live Apps Script Deployment IDs paired with a valid `auth_key`
## Why The CA Matters
The local CA lets the proxy handle HTTPS traffic from your browser. Anyone with your `ca/ca.key` could impersonate websites for browsers that trust that CA.
Keep `ca/` private. If it is exposed, remove the old certificate from trust stores, delete `ca/`, and let the app generate a new CA.
## Recommended Defaults
- Keep `listen_host` as `127.0.0.1` unless you intentionally use LAN sharing.
- Keep `verify_ssl` as `true`.
- Use a long random `auth_key`.
- Use a separate long random exit-node PSK.
- Rotate secrets if you pasted them into chat, logs, screenshots, or issue reports.
## LAN Sharing Risk
With LAN sharing enabled, other devices on your network can use the proxy. Only enable it on trusted networks and turn it off when finished.
## Google Apps Script Quotas
Apps Script deployments have daily execution quotas. Heavy browsing, video, and multiple users can consume quota quickly. If quota is exhausted, relay responses may fail until the quota resets.
## Removing The CA
Run:
```bash
python main.py --uninstall-cert
```
You can also remove the certificate manually from your OS and browser trust stores.
docs/TROUBLESHOOTING.md
+136
View File
@@ -0,0 +1,136 @@
# Troubleshooting
Start with the symptom you see. Most problems are configuration, certificate trust, or an outdated Apps Script deployment.
## Certificate Errors
Symptoms:
- Browser says the connection is not private.
- Telegram or another app works, but normal HTTPS sites do not.
- Chrome or Edge still fails after you installed the certificate.
Fix:
1. Make sure the proxy has run at least once so `ca/ca.crt` exists.
2. Install `ca/ca.crt` as a trusted root certificate.
3. Fully close and reopen the browser. On Windows, check Task Manager for background Chrome or Edge processes.
4. For Firefox, import the CA separately from **Settings** -> **Privacy & Security** -> **Certificates** -> **View Certificates** -> **Authorities**.
You can also run:
```bash
python main.py --install-cert
```
## `unauthorized`
The shared secret does not match.
Fix:
1. Open [apps_script/Code.gs](../apps_script/Code.gs).
2. Find `const AUTH_KEY = "...";`.
3. Make sure it exactly matches `auth_key` in `config.json`.
4. Deploy a new Apps Script deployment after changing [apps_script/Code.gs](../apps_script/Code.gs).
## `Config not found`
Run the wizard:
```bash
python setup.py
```
Or copy [config.example.json](../config.example.json) to `config.json` and fill `script_id` plus `auth_key`.
## `502 Bad JSON`
Google returned HTML or another unexpected response instead of relay JSON.
Common causes:
- Wrong Deployment ID.
- Apps Script daily quota is exhausted.
- You edited [apps_script/Code.gs](../apps_script/Code.gs) but did not create a new deployment.
- The deployment access setting is not **Anyone**.
Fix:
1. Create a new Apps Script deployment.
2. Copy the new Deployment ID into `config.json`.
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`.
## Connection Timeout
The current `google_ip` may be blocked or slow on your network.
Run:
```bash
python main.py --scan
```
Then set the recommended IP in `config.json`:
```json
"google_ip": "RECOMMENDED_IP"
```
Restart the proxy.
## Slow Browsing
Try these in order:
1. Install all dependencies from [requirements.txt](../requirements.txt), especially `h2`.
2. Run `python main.py --scan` and update `google_ip`.
3. Deploy multiple Apps Script projects and use `script_ids`.
4. Keep `log_level` at `INFO` unless debugging.
5. Use an exit node only when needed, because it adds another hop.
## Browser Proxy Is Set But Sites Do Not Load
Check:
1. The terminal says HTTP proxy is listening on `127.0.0.1:8085`.
2. Browser proxy type is **HTTP**, not HTTPS.
3. HTTPS traffic is also configured to use the same HTTP proxy.
4. The CA is installed and the browser was fully restarted.
## SOCKS5 Works Differently Than HTTP Proxy
Some SOCKS5 clients resolve domains locally and only send raw IPs to the proxy. That can break routes that depend on hostnames.
Use HTTP proxy `127.0.0.1:8085` for browsers and apps that support it. This is especially important for Telegram-style cases where hostname handling matters.
## YouTube Opens But Video Playback Fails
Try:
```json
"youtube_via_relay": true
```
Then restart the proxy. This routes YouTube through the Apps Script relay instead of the direct Google SNI-rewrite path. It may use more Apps Script executions.
If `exit_node.mode` is `full`, YouTube may also be routed through the relay so the exit node can handle all traffic.
## Docker Certificate Confusion
The container generates `ca/ca.crt` into the host `./ca` volume, but certificate installation inside the container does not trust it on your host OS.
Install `ca/ca.crt` manually on the host browser or OS. See [Docker Guide](DOCKER.md).
## Reset The Local Certificate
To remove the certificate from trust stores:
```bash
python main.py --uninstall-cert
```
To generate a fresh CA, stop the proxy and delete the `ca/` folder. The next run will create a new one.
Never share the `ca/` folder.
docs/fa/ARCHITECTURE.md
+58
View File
@@ -0,0 +1,58 @@
# معماری
MasterHttpRelayVPN از یک پراکسی محلی و یک relay که کاربر deploy می‌کند ساخته شده است.
## مسیر ساده
```text
Browser یا app
-> HTTP/SOCKS5 proxy محلی
-> اتصال TLS fronted به سمت Google
-> Apps Script relay
-> سایت مقصد
```
شبکه یک اتصال شبیه Google می‌بیند. URL واقعی مقصد داخل ترافیک رمزگذاری‌شده به relay فرستاده می‌شود.
## بخش‌های اصلی
| فایل یا پوشه | کاربرد |
|--------------|--------|
| [main.py](../../main.py) | نقطه ورود CLI. config را می‌خواند، دستورهای certificate را اجرا می‌کند، و proxy را شروع می‌کند. |
| [setup.py](../../setup.py) | wizard تعاملی که `config.json` می‌سازد. |
| [start.bat](../../start.bat) | لانچر Windows. venv می‌سازد، dependency نصب می‌کند، setup را اجرا می‌کند، و proxy را بالا می‌آورد. |
| [start.sh](../../start.sh) | لانچر Linux/macOS با همین نقش. |
| [config.example.json](../../config.example.json) | نمونه کانفیگ و پیش‌فرض‌ها. |
| [apps_script/Code.gs](../../apps_script/Code.gs) | رله Google Apps Script که کاربر deploy می‌کند. |
| [src/proxy/proxy_server.py](../../src/proxy/proxy_server.py) | HTTP CONNECT، مسیرهای MITM، SOCKS5، و تصمیم‌های مربوط به host policy. |
| [src/proxy/mitm.py](../../src/proxy/mitm.py) | CA محلی و certificate های ساخته‌شده برای سایت‌ها. |
| [src/relay/domain_fronter.py](../../src/relay/domain_fronter.py) | کلاینت Apps Script relay، batch، retry، و انتخاب transport H1/H2. |
| [src/relay/h2_transport.py](../../src/relay/h2_transport.py) | transport اختیاری HTTP/2 برای multiplexing. |
| [src/core/cert_installer.py](../../src/core/cert_installer.py) | نصب و حذف CA برای سیستم‌عامل و Firefox. |
| [src/core/google_ip_scanner.py](../../src/core/google_ip_scanner.py) | اسکنر IPهای Google برای `python main.py --scan`. |
## پردازش درخواست
1. مرورگر ترافیک HTTP یا HTTPS proxy را به `127.0.0.1:8085` می‌فرستد.
2. برای HTTPS، proxy می‌تواند با CA تولیدشده MITM محلی انجام دهد.
3. قوانین host مشخص می‌کنند درخواست مستقیم، blocked، bypass، یا relayed باشد.
4. درخواست‌های relayed به JSON برای Apps Script تبدیل می‌شوند.
5. Apps Script مقصد را fetch می‌کند و پاسخ HTTP سریال‌شده برمی‌گرداند.
6. پراکسی محلی پاسخ HTTP را برای مرورگر بازسازی می‌کند.
## امکانات کارایی
- pool گرم اتصال TLS برای fallback H1.
- HTTP/2 multiplexing وقتی package `h2` نصب باشد.
- batch کردن درخواست‌های static در burst ها.
- چند `script_ids` اختیاری برای load balancing.
- دانلود موازی range برای فایل‌های بزرگ.
- Exit Node اختیاری برای مقصدهایی که خروجی Google را مسدود می‌کنند.
## مسیر Exit Node
```text
Browser -> Local proxy -> Apps Script -> Exit node -> Target website
```
Exit Node می‌تواند روی Cloudflare Workers، Deno Deploy، یا VPS اجرا شود. [راهنمای Exit Node](../exit-node/EXIT_NODE_DEPLOYMENT_FA.md) را ببینید.
docs/fa/CONFIGURATION.md
+159
View File
@@ -0,0 +1,159 @@
# مرجع تنظیمات
بیشتر کاربران فقط به `script_id`، `auth_key`، و پورت‌های پیش‌فرض نیاز دارند. این صفحه برای زمانی است که می‌خواهید رفتار برنامه را دقیق‌تر تنظیم کنید.
## تنظیمات ضروری
| تنظیم | معنی |
|-------|------|
| `script_id` | Deployment ID مربوط به Google Apps Script. برای یک deployment استفاده می‌شود. |
| `script_ids` | آرایه‌ای از چند Deployment ID برای load balancing. به جای `script_id` استفاده می‌شود. |
| `auth_key` | رمز مشترک. باید دقیقا با `AUTH_KEY` داخل [apps_script/Code.gs](../../apps_script/Code.gs) یکی باشد. |
اگر از `script_ids` استفاده می‌کنید، همه deployment ها باید `AUTH_KEY` یکسان داشته باشند.
## اتصال پراکسی
| تنظیم | پیش‌فرض | معنی |
|-------|---------|------|
| `listen_host` | `127.0.0.1` | آدرسی که پراکسی روی آن گوش می‌دهد. برای فقط همین کامپیوتر، همین مقدار را نگه دارید. |
| `http_port` | `8085` | پورت HTTP proxy برای مرورگرها و بیشتر برنامه‌ها. |
| `socks5_port` | `1080` | پورت SOCKS5. بعضی برنامه‌ها hostname را محلی resolve می‌کنند، پس HTTP proxy معمولا قابل اعتمادتر است. |
| `lan_sharing` | `false` | وقتی true باشد، دستگاه‌های دیگر شبکه محلی هم می‌توانند از پراکسی استفاده کنند. |
قبل از فعال کردن، [اشتراک‌گذاری LAN](LAN_SHARING.md) را بخوانید.
## Domain Fronting
| تنظیم | پیش‌فرض | معنی |
|-------|---------|------|
| `google_ip` | `216.239.38.120` | IP فرانت Google که اتصال از آن مسیر می‌رود. |
| `front_domain` | `www.google.com` | دامنه‌ای که در اتصال TLS سمت Google دیده می‌شود. |
| `front_domains` | `www.google.com`, `mail.google.com`, `accounts.google.com` | لیست اختیاری برای چرخش SNI. |
| `verify_ssl` | `true` | اعتبار TLS اتصال سمت Google را بررسی می‌کند. در حالت عادی true بماند. |
اگر IP فعلی کند یا مسدود است، `python main.py --scan` را اجرا کنید و IP پیشنهادی را بگذارید.
## Timeout و کارایی
| تنظیم | پیش‌فرض | معنی |
|-------|---------|------|
| `relay_timeout` | `25` | حداکثر زمان برای یک درخواست relay. |
| `tls_connect_timeout` | `15` | timeout ساخت اتصال TLS به endpoint گوگل. |
| `tcp_connect_timeout` | `10` | timeout اتصال‌های TCP مستقیم و SNI-rewrite. |
| `h2_connections` | `2` | تعداد اتصال‌های HTTP/2 به relay. افزایش آن گاهی throughput را بهتر می‌کند. |
| `parallel_relay` | `1` | تعداد deployment هایی که برای درخواست‌های امن با هم race می‌شوند. |
| `enable_sub_batch` | `true` | اجازه می‌دهد batch ها بین اتصال‌های H2 تقسیم شوند. |
## دانلودها
| تنظیم | معنی |
|-------|------|
| `chunked_download_extensions` | پسوندهایی که می‌توانند از دانلود parallel range استفاده کنند. `".*"` همه دانلودهای GET را probe می‌کند. |
| `chunked_download_min_size` | حداقل اندازه فایل برای فعال ماندن دانلود موازی. |
| `chunked_download_chunk_size` | اندازه هر range request. |
| `chunked_download_max_parallel` | بیشترین تعداد range request همزمان برای یک دانلود. |
| `chunked_download_max_chunks` | سقف نرم تعداد chunk ها. برای فایل‌های بزرگ، اندازه chunk خودکار افزایش می‌یابد. |
## سیاست دامنه‌ها
| تنظیم | معنی |
|-------|------|
| `block_hosts` | دامنه‌هایی که باید 403 بگیرند و هرگز tunnel نشوند. از نام دقیق و الگوی `.suffix` پشتیبانی می‌کند. |
| `direct_hosts` | دامنه‌هایی که همیشه مستقیم می‌روند، بدون MITM و بدون relay. |
| `bypass_hosts` | دامنه‌های محلی یا خاص که از MITM و relay عبور نمی‌کنند. برای `.lan` و `.local` مفید است. |
| `hosts` | نگاشت دستی DNS برای تست یا split-DNS. |
| `direct_google_exclude` | سرویس‌های Google که به جای tunnel مستقیم باید از relay استفاده کنند. |
| `youtube_via_relay` | YouTube را از مسیر Apps Script relay عبور می‌دهد. اگر مسیر مستقیم Google باعث مشکل پخش شود مفید است. |
نمونه:
```json
{
"block_hosts": ["ads.example.com", ".doubleclick.net"],
"direct_hosts": ["chat.openai.com", ".openai.com"],
"hosts": {
"example.org": "93.184.216.34",
".internal.lan": "192.168.1.10"
}
}
```
## Exit Node
وقتی مقصد، خروجی IPهای Google را مسدود می‌کند، Exit Node کمک می‌کند.
```json
"exit_node": {
"enabled": true,
"provider": "cloudflare",
"url": "https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev",
"psk": "CHANGE_ME_TO_A_STRONG_SECRET",
"mode": "full",
"hosts": ["chatgpt.com", "openai.com"]
}
```
| تنظیم | معنی |
|-------|------|
| `exit_node.enabled` | فعال یا غیرفعال کردن مسیر Exit Node. |
| `exit_node.provider` | یکی از `cloudflare`، `deno`، `vps`، یا `custom`. |
| `exit_node.url` | آدرس provider انتخاب‌شده. |
| `exit_node.psk` | رمز مشترک Exit Node. باید با کد deploy شده یکی باشد. |
| `exit_node.mode` | مقدار `full` برای همه ترافیک relay شده، یا `selective` فقط برای host های لیست‌شده. |
| `exit_node.hosts` | لیست host ها در حالت selective. |
مراحل deploy در [راهنمای Exit Node](../exit-node/EXIT_NODE_DEPLOYMENT_FA.md) است.
## Adblock
`adblock_lists` لیست URLهای فیلتر host/domain را می‌گیرد. کانفیگ پیش‌فرض از PersianBlocker استفاده می‌کند. اگر این رفتار را نمی‌خواهید، لیست را خالی کنید.
## وابستگی‌های اختیاری
برای همه امکانات، dependency های [requirements.txt](../../requirements.txt) را نصب کنید.
| بسته | کاربرد |
|------|--------|
| `cryptography` | ساخت certificate محلی و MITM برای HTTPS. |
| `h2` | ارتباط HTTP/2 با Apps Script. |
| `brotli` | decode کردن `Content-Encoding: br`. |
| `zstandard` | decode کردن `Content-Encoding: zstd`. |
## دستورهای اجرا
```bash
python main.py # اجرای عادی
python main.py -p 9090 # تغییر پورت HTTP
python main.py --socks5-port 1081 # تغییر پورت SOCKS5
python main.py --host 0.0.0.0 # تغییر listen host
python main.py --log-level DEBUG # لاگ بیشتر
python main.py -c path/to/config.json # استفاده از config دیگر
python main.py --install-cert # نصب CA و خروج
python main.py --uninstall-cert # حذف CA و خروج
python main.py --no-cert-check # رد شدن از بررسی خودکار CA
python main.py --scan # پیدا کردن IP سریع‌تر Google
```
متغیرهای محیطی پشتیبانی‌شده: `DFT_CONFIG`, `DFT_AUTH_KEY`, `DFT_SCRIPT_ID`, `DFT_HTTP_PORT`, `DFT_PORT`, `DFT_HOST`, `DFT_SOCKS5_PORT`, و `DFT_LOG_LEVEL`.
## دستورهای عیب‌یابی
اسکن IPهای Google:
```bash
python main.py --scan
```
نصب یا حذف CA محلی:
```bash
python main.py --install-cert
python main.py --uninstall-cert
```
لاگ کامل‌تر:
```bash
python main.py --log-level DEBUG
```