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
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
```