Skip to content

Commit e27921b

Browse files
itsardalan007-afkitsardalan007-afk
committed
feat(ci sync & betterdocs):add how to use docs and ci sync
1 parent d0be609 commit e27921b

9 files changed

Lines changed: 574 additions & 85 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@
2828
- 🖥️ **Works on** Mac, Windows, Linux, Android, OpenWRT routers
2929
- 🦊 **Any browser or app** that supports HTTP proxy or SOCKS5
3030

31+
## Community helpers
32+
33+
- **[mhrv-helper-extension](https://github.com/ardalan-ab/mhrv-helper-extension)** (Chrome, maintained by [@ardalan-ab](https://github.com/ardalan-ab)) — optional helper to generate an `AUTH_KEY`, copy `Code.gs`, and a `config.json` snippet for Apps Script mode. [How to use (English)](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.md) · [راهنمای فارسی](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.fa.md).
34+
3135
## How it works (the simple picture)
3236

3337
```
@@ -75,7 +79,7 @@ ISPs can't read inside encrypted HTTPS. They only see the address — `www.googl
7579

7680
> **Tip:** if you ever update `Code.gs` later, don't make a new deployment. Edit the code, then go to **Deploy → Manage deployments → ✏️ → Version: New version → Deploy**. The Deployment ID stays the same.
7781
>
78-
> **Optional:** use `chrome-extension/README.md` for a browser helper that generates `Code.gs` and local config automatically.
82+
> **Optional:** use the community [Chrome extension](https://github.com/ardalan-ab/mhrv-helper-extension) — see [How to use](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.md) (English) or [راهنمای فارسی](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.fa.md).
7983
8084
### Step 2 — Download mhrv-rs
8185

@@ -200,6 +204,10 @@ Most of the Rust code in this port was written with [Anthropic's Claude](https:/
200204
- 🖥️ **روی** مک، ویندوز، لینوکس، اندروید، روتر OpenWRT کار می‌کند
201205
- 🦊 **هر مرورگر یا برنامه‌ای** که از HTTP proxy یا SOCKS5 پشتیبانی کند
202206

207+
## ابزارهای جامعه
208+
209+
- **[mhrv-helper-extension](https://github.com/ardalan-ab/mhrv-helper-extension)** (کروم، نگهداری [@ardalan-ab](https://github.com/ardalan-ab)) — افزونهٔ اختیاری برای تولید `AUTH_KEY`، کپی `Code.gs` و قطعهٔ `config.json` در حالت Apps Script. [راهنمای فارسی](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.fa.md) · [How to use (English)](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.md).
210+
203211
## چطور کار می‌کند (تصویر ساده)
204212

205213
```
@@ -246,6 +254,8 @@ ISP داخل HTTPS رمزشده را نمی‌تواند بخواند. فقط آ
246254
۱۱. گوگل یک **Deployment ID** نشانت می‌دهد (یک رشتهٔ تصادفی طولانی). **کپی‌اش کن** — در مرحلهٔ ۳ لازم داری.
247255

248256
> **نکته:** اگر بعداً `Code.gs` را به‌روزرسانی کنی، Deployment جدید نساز. کد را ویرایش کن، بعد **Deploy → Manage deployments → ✏️ → Version: New version → Deploy**. Deployment ID همان قبلی می‌ماند.
257+
>
258+
> **اختیاری:** افزونهٔ اختیاری کروم [mhrv-helper-extension](https://github.com/ardalan-ab/mhrv-helper-extension) — [راهنمای فارسی](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.fa.md) · [How to use (English)](https://github.com/ardalan-ab/mhrv-helper-extension/blob/main/HOW_TO_USE.md).
249259
250260
### مرحلهٔ ۲ — دانلود mhrv-rs
251261

‎chrome-extension/.github/workflows/sync-codegs.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Runs when this folder is the Git repository root (e.g. ardalan-ab/mhrv-helper-extension).
2+
# In the main monorepo, use .github/workflows/chrome-extension.yml instead (same cmp logic).
3+
4+
name: Code.gs sync with upstream
5+
6+
on:
7+
push:
8+
branches: [main, master]
9+
pull_request:
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
15+
jobs:
16+
bundled-matches-upstream-main:
17+
name: bundled Code.gs matches upstream main
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Check out extension repository
21+
uses: actions/checkout@v4
22+
23+
- name: Fetch canonical Code.gs from main project (main branch)
24+
run: |
25+
curl -fsSL \
26+
'https://raw.githubusercontent.com/therealaleph/MasterHttpRelayVPN-RUST/main/assets/apps_script/Code.gs' \
27+
-o /tmp/upstream-Code.gs
28+
29+
- name: Compare with bundled Code.gs
30+
run: |
31+
if ! cmp -s Code.gs /tmp/upstream-Code.gs; then
32+
echo "::error::Bundled Code.gs differs from therealaleph/MasterHttpRelayVPN-RUST main (assets/apps_script/Code.gs). Copy the upstream file into this repo and commit."
33+
diff -u /tmp/upstream-Code.gs Code.gs || true
34+
exit 1
35+
fi
36+
echo "OK: bundled Code.gs matches upstream main."

‎chrome-extension/HOW_TO_USE.fa.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# راهنمای استفاده از افزونهٔ کمک‌کنندهٔ Apps Script برای mhrv-rs (کروم)
2+
3+
[English](HOW_TO_USE.md)
4+
5+
این راهنما برای **کاربر نهایی** است که می‌خواهد با این افزونه، راه‌اندازی Apps Script برای [mhrv-rs](https://github.com/therealaleph/MasterHttpRelayVPN-RUST) را ساده‌تر کند. اسکریپت را هنوز باید در **حساب گوگل خودت** دیپلوی کنی و **mhrv-rs** را روی کامپیوترت اجرا کنی؛ افزونه فقط متن آماده می‌کند و لینک باز می‌کند.
6+
7+
---
8+
9+
## ۱. نصب افزونه (حالت unpacked)
10+
11+
1. پوشهٔ افزونه را بگیر (پوشه‌ای که `manifest.json` داخلش است):
12+
- **پیشنهادی:** مخزن [ardalan-ab/mhrv-helper-extension](https://github.com/ardalan-ab/mhrv-helper-extension) را کلون کن و **ریشهٔ مخزن** را انتخاب کن.
13+
- **جایگزین:** در مخزن اصلی [MasterHttpRelayVPN-RUST](https://github.com/therealaleph/MasterHttpRelayVPN-RUST) از پوشهٔ **`chrome-extension/`** استفاده کن.
14+
2. کروم را باز کن و به `chrome://extensions` برو.
15+
3. **Developer mode** را روشن کن (بالا سمت راست).
16+
4. **Load unpacked** را بزن و همان پوشه را انتخاب کن.
17+
5. (اختیاری) از آیکن پازل، افزونه را **Pin** کن تا همیشه در نوار ابزار باشد.
18+
19+
---
20+
21+
## ۲. باز کردن پاپ‌آپ و انتخاب زبان
22+
23+
1. روی آیکن افزونه کلیک کن.
24+
2. در بالای پاپ‌آپ، **English** یا **فارسی** را انتخاب کن. برای فارسی، چیدمان راست‌به‌چپ است.
25+
26+
---
27+
28+
## ۳. دانلود mhrv-rs (اختیاری ولی مفید)
29+
30+
در **مرحلهٔ ۰**:
31+
32+
- **دانلود mhrv-rs** را بزن — کروم فایل ریلیز مناسب سیستم‌عاملت را از گیت‌هاب باز می‌کند.
33+
- یا **مشاهدهٔ همهٔ انتشارها** را بزن اگر می‌خواهی خودت بیلد دیگری (اندروید، musl و غیره) را انتخاب کنی.
34+
35+
فایل را از حالت فشرده خارج کن و جایی نگه دار که بعداً برنامه را از همانجا اجرا کنی (طبق README اصلی پروژه).
36+
37+
---
38+
39+
## ۴. تولید کلید احراز هویت
40+
41+
در **مرحلهٔ ۱**:
42+
43+
1. **تولید کلید احراز هویت** را بزن. یک رشتهٔ hex به طول ۶۴ کاراکتر در کادر ظاهر می‌شود.
44+
2. در صورت نیاز **کپی کلید** را بزن.
45+
46+
این مقدار را در **دو جا** یکسان استفاده کن:
47+
48+
- داخل **Apps Script** به‌عنوان `AUTH_KEY` در `Code.gs` (وقتی **کپی Code.gs** می‌زنی، افزونه آن را در کد قرار می‌دهد).
49+
- در **mhrv-rs** در فیلد auth key هنگام ذخیرهٔ کانفیگ.
50+
51+
مثل پسورد نگه‌اش دار. افزونه آن را در مرورگر می‌سازد و به سروری ارسال نمی‌کند.
52+
53+
---
54+
55+
## ۵. بردن Code.gs به Google Apps Script
56+
57+
در **مرحلهٔ ۲**:
58+
59+
1. تا زمانی که اسپینر تمام شود و اسکریپت بارگذاری شود صبر کن (از گیت‌هاب، یا نسخهٔ داخل بسته اگر raw مسدود باشد).
60+
2. (اختیاری) **بررسی آخرین نسخه Code.gs** را بزن تا ببینی نسخهٔ بسته با upstream یکی است یا نه.
61+
3. در صورت نیاز **باز کردن Apps Script** را بزن تا تب پروژهٔ جدید باز شود.
62+
4. در Apps Script: **New project** (یا پروژهٔ موجود)، محتوای پیش‌فرض `Code.gs` را پاک کن.
63+
5. در افزونه، **کپی Code.gs** (یا **دانلود Code.gs** و باز کردن فایل) را بزن.
64+
6. در ویرایشگر Apps Script پیست کن و **Save** بزن.
65+
66+
به‌صورت **Web app** مستقر کن (مثل README سریع اصلی): معمولاً **Execute as: Me** و **Who has access: Anyone** (مگر راهنما چیز دیگری بگوید). اگر گوگل دسترسی خواست، تأیید کن.
67+
68+
**Deployment ID** که گوگل نشان می‌دهد را کپی کن (در مرحلهٔ ۳ افزونه می‌چسبانی).
69+
70+
---
71+
72+
## ۶. ساخت قطعهٔ کانفیگ محلی
73+
74+
در **مرحلهٔ ۳**:
75+
76+
1. **شناسهٔ استقرار** را در فیلد مربوطه پیست کن.
77+
2. **کپی قطعهٔ پیکربندی** را بزن.
78+
3. JSON را در **`config.json`** مربوط به `mhrv-rs` ادغام کن (یا در UI گرافیکی برنامه اگر از آن استفاده می‌کنی).
79+
80+
شکل معمول:
81+
82+
```json
83+
{
84+
"mode": "apps_script",
85+
"script_id": "شناسه_استقرار_تو",
86+
"auth_key": "کلید_تو",
87+
"listen_port": 8085
88+
}
89+
```
90+
91+
افزونه از همان چیزی که تولید کرده‌ای و Deployment ID که دادی پرش می‌کند.
92+
93+
---
94+
95+
## ۷. اجرای mhrv-rs و تنظیم پروکسی مرورگر
96+
97+
از بخش «اجرای اول» به بعد **README اصلی پروژه** را دنبال کن: ذخیرهٔ کانفیگ، استارت پروکسی، تنظیم فایرفاکس یا کروم روی `127.0.0.1:8085` (یا SwitchyOmega طبق همان README).
98+
99+
در پاپ‌آپ از **مشاهدهٔ مستندات** و **راهنمای راه‌اندازی** برای لینک به README و راهنمای رسمی استفاده کن.
100+
101+
---
102+
103+
## عیب‌یابی کوتاه
104+
105+
| مشکل | کار پیشنهادی |
106+
|--------|----------------|
107+
| اسکریپت بارگذاری نمی‌شود | ممکن است raw گیت‌هاب مسدود باشد؛ افزونه به `Code.gs` داخل بسته برمی‌گردد. بعد از بهبود شبکه **بررسی آخرین نسخه Code.gs** را بزن. |
108+
| دکمه‌های کپی کار نمی‌کنند | بعضی محیط‌ها کلیپ‌بورد را مسدود می‌کنند؛ پاپ‌آپ را فوکوس کن یا از **دانلود Code.gs** استفاده کن. |
109+
| باینری اشتباه دانلود شد | با **مشاهدهٔ همهٔ انتشارها** دستی فایل مناسب سیستم‌عاملت را انتخاب کن. |
110+
111+
برای موضوعات پیشرفته‌تر (CAPTCHA، تلگرام، Full Tunnel) از [راهنمای کامل](https://github.com/therealaleph/MasterHttpRelayVPN-RUST/blob/main/docs/guide.fa.md) در مخزن اصلی استفاده کن.

‎chrome-extension/HOW_TO_USE.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# How to use the mhrv-rs Apps Script Helper (Chrome)
2+
3+
[فارسی](HOW_TO_USE.fa.md)
4+
5+
This guide is for **end users** who want the extension to help with Apps Script setup for [mhrv-rs](https://github.com/therealaleph/MasterHttpRelayVPN-RUST). You still deploy the script in **your** Google account and run **mhrv-rs** on your computer; the extension only prepares text and opens links.
6+
7+
---
8+
9+
## 1. Install the extension (unpacked)
10+
11+
1. Get the extension folder (the directory that contains `manifest.json`):
12+
- **Recommended:** clone [ardalan-ab/mhrv-helper-extension](https://github.com/ardalan-ab/mhrv-helper-extension) and use the **repo root**.
13+
14+
2. Go to ( chrome://extensions/ )
15+
3. Click on **Devloper mode**
16+
4. Click **Load unpacked** and select that folder.
17+
5. (Optional) Pin the extension from the puzzle icon so it stays in the toolbar.
18+
19+
---
20+
21+
## 2. Open the popup and pick a language
22+
23+
1. Click the extension icon.
24+
2. In the header, choose **English** or **فارسی**. Persian uses RTL layout.
25+
26+
---
27+
28+
## 3. Download mhrv-rs (optional but useful)
29+
30+
In **Step 0**:
31+
32+
- Click **Download mhrv-rs** — Chrome opens the release asset the extension picks for your OS (from GitHub).
33+
- Or use **View all releases** if you want to choose another build (Android, musl, etc.).
34+
35+
Unzip the archive and keep the folder somewhere you will run the app from (see the main project README).
36+
37+
---
38+
39+
## 4. Generate the auth key
40+
41+
In **Step 1**:
42+
43+
1. Click **Generate auth key**. A 64-character hex string appears in the box.
44+
2. Click **Copy key** if you want it on the clipboard.
45+
46+
Use this same value in two places:
47+
48+
- Inside **Apps Script** as `AUTH_KEY` in `Code.gs` (the extension’s **Copy Code.gs** step will embed it for you when you copy).
49+
- In **mhrv-rs** as the auth key field when you save config.
50+
51+
Treat it like a password. The extension generates it in the browser; it is not sent to a server by the extension.
52+
53+
---
54+
55+
## 5. Get Code.gs into Google Apps Script
56+
57+
In **Step 2**:
58+
59+
1. Wait until the spinner disappears and the script has loaded (from GitHub, or bundled fallback if GitHub is blocked).
60+
2. (Optional) Click **Check latest Code.gs** to see if the bundled copy matches the latest file on GitHub.
61+
3. Click **Open Apps Script** if you need a new project tab.
62+
4. In Apps Script: **New project** (or open an existing project), delete the default `Code.gs` content.
63+
5. Back in the extension, click **Copy Code.gs** (or **Download Code.gs** and open the file).
64+
6. Paste into the Apps Script editor and **Save**.
65+
66+
Deploy as a **Web app** (see the main README Quick Start): **Execute as: Me**, **Who has access: Anyone** (unless your setup requires something else). Finish authorization if Google asks.
67+
68+
Copy the **Deployment ID** Google shows you (you will paste it in Step 3 of the extension).
69+
70+
---
71+
72+
## 6. Build your local config snippet
73+
74+
In **Step 3**:
75+
76+
1. Paste the **Deployment ID** into the **Deployment ID** field.
77+
2. Click **Copy config snippet**.
78+
3. Merge the JSON into your **`config.json`** for `mhrv-rs` (or paste into the app’s config UI if you use the graphical mode).
79+
80+
Typical shape:
81+
82+
```json
83+
{
84+
"mode": "apps_script",
85+
"script_id": "YOUR_DEPLOYMENT_ID",
86+
"auth_key": "YOUR_AUTH_KEY",
87+
"listen_port": 8085
88+
}
89+
```
90+
91+
The extension fills `script_id` and `auth_key` from what you entered and generated.
92+
93+
---
94+
95+
## 7. Run mhrv-rs and point the browser at the proxy
96+
97+
Follow the **main project README** from “First run” onward: save config, start the proxy, set Firefox or Chrome to `127.0.0.1:8085` (or use SwitchyOmega as documented there).
98+
99+
Use **View app docs** / **Open setup guide** in the extension footer for links to the official README and guide.
100+
101+
---
102+
103+
## Troubleshooting (short)
104+
105+
| Problem | What to try |
106+
|--------|-------------|
107+
| Script never loads | GitHub raw may be blocked; the extension falls back to bundled `Code.gs`. Use **Check latest Code.gs** after the network improves. |
108+
| Copy buttons do nothing | Some contexts block clipboard; try focusing the popup first or use **Download Code.gs** instead. |
109+
| Wrong binary downloaded | Use **View all releases** and pick the archive for your OS manually. |
110+
111+
For deeper issues (CAPTCHA, Telegram, full tunnel), use [docs/guide.md](https://github.com/therealaleph/MasterHttpRelayVPN-RUST/blob/main/docs/guide.md) in the main repo.

0 commit comments

Comments
 (0)