loopy-iri/RatholeEngine
GitHub: loopy-iri/RatholeEngine
基于 rathole 与 Nginx 的多位置反向隧道编排系统，以单端口、单域名、单证书通过 URL 路径路由多个反向回连节点，专为抗审查场景设计。
Stars: 97 | Forks: 20
# RatholeEngine
**基于 rathole + Nginx 的多位置反向隧道系统**
_一个端口 · 一个域名 · 一个证书 · 通过 URL 路径路由多个海外节点。_
_专为伊朗的抗审查隧道而构建。_
[](https://github.com/loopy-iri/RatholeEngine/actions/workflows/ci.yml)
[](https://github.com/loopy-iri/RatholeEngine/releases/latest)
[](LICENSE)
[](https://github.com/loopy-iri/RatholeEngine/stargazers)
[**English**](#what-is-this) · [**فارسی**](docs/README.fa.md) · [**完整 Wiki**](https://github.com/loopy-iri/RatholeEngine/wiki) · [快速开始](#quick-start) · [文档](#documentation) · [Telegram](https://t.me/l8PY4NET)
## 目录
- [这是什么](#what-is-this)
- [三种角色](#three-roles)
- [传输模式](#transport-modes)
- [快速开始](#quick-start)
- [更新与回滚](#update--rollback)
- [文档](#documentation)
- [仓库结构](#repository-layout)
- [خلاصهی فارسی](#خلاصهی-فارسی)
## 这是什么
一台 **伊朗服务器** —— 在一个域名、一个 Let's Encrypt 证书、一个公共端口 `443` 之后 —— 作为多个通过反向隧道连接回来的**海外节点**的前端。用户流量**根据 URL 路径**路由到相应节点（在 nginx 中使用 `map $uri $backend_port`）。伊朗服务器上仅暴露 `:443` 端口；海外节点不使用任何公共端口。
## 三种角色
| 角色 | 程序 | 职责 |
|------|---------|----------------|
| **伊朗面板** | [`rathole-manager/ratholectl`](rathole-manager/ratholectl) (bash) | rathole **server** + nginx。管理节点清单。生成 `server.toml` + `rathole.conf`。 |
| **海外节点** | [`rathole-manager/ratholenode`](rathole-manager/ratholenode) (bash) | rathole **client**。生成 `client.toml`。 |
| **Hub** | [`rathole-manager/ratholehub/hub.py`](rathole-manager/ratholehub/hub.py) (Python, 仅使用标准库) | 通过 SSH 驱动多台服务器的中央 Web 面板。 |
所有地方的核心设计原则：**变更状态 → 重新生成配置 → 验证 → 热重载**。配置绝不手动编辑；它们会在原处重写（保留 inode），因此 rathole 可以在不中断活动隧道的情况下进行热重载，并且在 `nginx -t` 失败时会自动回滚。
## 传输模式
同一隧道可以通过**五种**方式（外加一种游戏/SNI L4 模式）进行承载——切换传输方式永远不会改变用户服务、token 或路径，只会改变载体。每个节点的载体是**独占**的：hub 将其公开为单个选项（`ws`/`kcp`/`plain`/`noise`/`backhaul`），以此来协调两端。
- **websocket + TLS**（默认）—— `wss://domain:443`，TLS 由 nginx 终结。
- **kcp** —— 用于丢包链路的并行 UDP+FEC 路径（看起来像 UDP/443 上的 QUIC）。
- **plain** —— 连接到独立 HTTP 监听器的无 TLS websocket（更轻量，未加密）。
- **noise** —— 在第二个 rathole 实例上的加密传输（Noise/X25519），无 TLS/证书。
- **backhaul** *(v1.6)* —— rathole 旁边的一个独立的 Go 核心（`Musixal/Backhaul`），它通过 **SMUX** 将许多用户连接多路复用到一个流上；nginx 将硬编码的 `/channel` + `/tunnel` 路径代理到同一个 443 端口，从而保持单端口/单域名。
- **游戏 / SNI** —— 443 端口上的 L4 直通；TLS 在节点上终结（VLESS+TLS+Vision）。
- **自适应故障转移** *(v1.5.0)* —— 定时探测器对每个载体进行分类（`healthy / tls_failed / tcp_timeout / …`），并在 ws 和 kcp 之间自动切换，带有迟滞和冷却机制；使用 plain 需要显式设置 `ALLOW_INSECURE=1`。
- **秘密控制路径** *(v1.5.0)* —— WebSocket 控制路径从 `/` 升级为 `/_rh/<32 hex>`；nginx 仅将该确切路径路由到 rathole；所有其他路径保留伪装网站行为。
详情：[`docs/transport-modes.md`](docs/transport-modes.md)。
## 快速开始
**GitHub 上的一条命令**（下载最新的发布包，然后运行安装程序）。默认使用 `loopy-iri/RatholeEngine` —— 使用 `RATHOLE_GH` 覆盖以使用其分支：
```
# 完全交互式（询问 panel/node 及详细信息）
curl -fsSL https://raw.githubusercontent.com/loopy-iri/RatholeEngine/main/install.sh | sudo bash
# Iran 服务器 (panel)，非交互式：
curl -fsSL https://raw.githubusercontent.com/loopy-iri/RatholeEngine/main/install.sh | sudo bash -s -- --panel \
--domain panel.example.ir \
--fullchain /root/cert/panel.example.ir/fullchain.pem \
--key /root/cert/panel.example.ir/privkey.pem
# 外部 node，非交互式：
curl -fsSL https://raw.githubusercontent.com/loopy-iri/RatholeEngine/main/install.sh | sudo bash -s -- --node -- \
--server panel.example.ir:443 --name trk01 --token
--inbound-port 2087
```
离线 / 本地包（无需下载）依然可以通过直接运行 `bootstrap.sh` 来使用 —— 参见 [`docs/README.fa.md`](docs/README.fa.md)。
然后从伊朗面板添加节点：
```
ratholectl hub on # enable hub on port
ratholectl add trk01 2087 # → path /trk01 routed to that node
ratholectl proxy add mysvc http://127.0.0.1:9000 # /mysvc/ → any upstream, no rathole involved
ratholectl ls # list nodes + user paths
ratholectl status # full dashboard: domain, ports, cert, services, nodes (--json for the hub)
ratholectl paths # every config/file path with a ✓/✗
ratholectl version # manager_version + rathole_version
ratholectl doctor # health check
```
`ratholectl add` 还会打印一条可直接粘贴的 `curl … | sudo bash -s -- --node -- …` 单行命令，用于海外节点，其中已自动填充 token/inbound。
**从 hub 中**，您可以无需 CLI 即可驱动所有这些操作：**全部更新** 会逐一在每台服务器上执行更新（带有进度条和每台服务器的状态，并在每台服务器上显示绿色/黄色的版本徽章），**添加到节点** 会将一个伊朗节点（名称/token/inbound）桥接到海外节点或上游，而 **设置主隧道** 会将节点连接到其伊朗服务器。
## 更新与回滚
更新在改动任何内容之前，会将**完整快照**（CLI + 配置 + systemd 单元）存入 `/var/backups/rathole-manager/`，随后运行基于角色的**健康检查**，如果服务未能启动或 `nginx -t` 中断，则会**自动回滚**到快照。
```
# 原地更新（自动检测 panel/node/hub；快照 + health-check + 自动回滚）
curl -fsSL https://raw.githubusercontent.com/loopy-iri/RatholeEngine/main/install.sh | sudo bash -s -- --update
# 或者，从已安装的目录树： sudo bash /opt/rathole-manager/update.sh
sudo bash update.sh --list-backups # list snapshots
sudo bash update.sh --rollback # revert to the latest snapshot
sudo bash update.sh --rollback 20260713-2210 # revert to a specific one
sudo bash update.sh --no-rollback # update but never auto-revert (snapshot only)
```
完整的 CLI 参考及安装流程（波斯语）：[`docs/README.fa.md`](docs/README.fa.md)。
## 卸载
`bootstrap.sh` 会自动检测已安装的角色（面板 / 节点 / hub），并为每个角色运行匹配的卸载程序：
```
sudo bash bootstrap.sh --uninstall # remove installed roles (asks to confirm)
sudo bash bootstrap.sh --purge --yes # + rathole binary and hub config, no prompt
# 或直接按角色执行： sudo bash uninstall-panel.sh [--purge] [--yes]
```
TLS 证书永远不会被移除。只有当主机上没有其他角色存在时，共享的 `common.sh` 才会被移除。相同的选项是交互式 `bootstrap.sh` 菜单中的第 7 项。
## 文档
| 文档 | 内容 |
|-----|----------|
| [**GitHub Wiki**](https://github.com/loopy-iri/RatholeEngine/wiki) | **完整的 GitHub Wiki**（入门、CLI 参考、自适应过滤、Hub、故障排除）。 |
| [`docs/architecture.md`](docs/architecture.md) | 三种角色，状态→重新生成→重载原则，path==name==map==inbound 不变量。 |
| [`docs/transport-modes.md`](docs/transport-modes.md) | 四种传输载体 + 游戏/SNI，附带图表。 |
| [`docs/traffic-flow.md`](docs/traffic-flow.md) | 逐层数据包路径（Mermaid + SVG 图表）。 |
| [`docs/hub.md`](docs/hub.md) | 中央 Web 面板（`hub.py` + `hubcmds.py` + `ui/`）：REST API、安全模型、白名单操作。 |
| [`docs/performance.md`](docs/performance.md) | 超越隧道的调优（BBR、kcp 配置、非隧道瓶颈）。 |
| [`docs/amneziawg-reverse.md`](docs/amneziawg-reverse.md) | 独立的 AmneziaWG 反向隧道设计（不属于 rathole 流程的一部分）。 |
| [`docs/README.fa.md`](docs/README.fa.md) | **完整的波斯语 CLI 参考 + 安装/卸载流程。** |
| [`docs/install-manual.md`](docs/install-manual.md) | **完整的手动安装指南（英语）：** 伊朗面板 + Pasargad 配置 + 海外节点 + hub，分步说明。 |
| [`docs/install-manual.fa.md`](docs/install-manual.fa.md) | 相同的手动安装指南，**波斯语**。 |
| [`rathole-multilocation-pasargad.md`](rathole-multilocation-pasargad.md) | 原始详细的设计与故障排除文档（波斯语）。 |
## 仓库结构
```
install.sh one-command installer from GitHub (curl | sudo bash)
bootstrap.sh env prep + unpack + hand-off to installer (local or --url)
package.sh build the distributable rathole-manager.zip
.github/workflows/ release.yml (build+publish on tag v*) · ci.yml (lint)
rathole-manager/
ratholectl Iran panel CLI (rathole server + nginx)
ratholenode foreign node CLI (rathole client)
common.sh shared bash helpers
ratholehub/hub.py central web panel (stdlib Python) — router/state/SSH/parsers
ratholehub/hubcmds.py security-critical action→argv allow-list (RE_* regexes)
ratholehub/ui/ web UI assets (index.html, app.css, app.js, i18n.js)
install-*.sh per-role installers (panel/node/hub)
update.sh safe update: snapshot + health-check + rollback
uninstall-*.sh
docs/ documentation + assets/ (SVG/PNG diagrams)
```
## 波斯语摘要
`RatholeEngine` یک سیستم تونل معکوس **چند-موقعیتی** روی **rathole + Nginx** است: یک سرور ایران (پشت یک دامنه، یک گواهی، یک پورت ۴۴۳) جلوی چند نود خارجی قرار میگیرد که با تونل معکوس به آن وصل میشوند و ترافیک با **path** به هر نود مسیریابی میشود. فقط پورت ۴۴۳ روی سرور ایران عمومی است.
**سه نقش:** پنل ایران (`ratholectl` — rathole server + nginx)، نود خارج (`ratholenode` — rathole client)، و هاب مرکزی (`hub.py` — پنل وب مدیریت چند سرور از طریق SSH).
**اصل مرکزی:** تغییر state → بازتولید کانفیگ → `nginx -t` → hot-reload (با حفظ inode و بازگشت خودکار در صورت خطا).
**دستورهای مفید CLI:** `ratholectl status` (داشبورد کامل: دامنه، پورتها، گواهی، سرویسها، نودها — با `--json` برای هاب)، `ratholectl paths` (مسیر همهی فایلها با ✓/✗)، `ratholectl version` (نسخهی مدیر + rathole). `ratholectl add` یک دستور آمادهی `curl … | sudo bash -s -- --node -- …` هم برای نصب نود چاپ میکند.
**از هاب:** دکمهی **«آپدیت همه»** همهی سرورها را یکییکی آپدیت میکند (progress bar + وضعیت هر سرور + badge نسخه سبز/زرد)، **«افزودن به نود»** یک نود ایران را روی نود/آپاستریم خارج سیمکشی میکند، و **«تنظیم تونل اصلی»** نود را به سرور ایرانش وصل میکند.
**شروع سریع و مرجع کامل CLI (فارسی):** [`docs/README.fa.md`](docs/README.fa.md)
**فهرست مستندات فارسی:**
- [معماری](docs/architecture.md) · [حالتهای transport](docs/transport-modes.md) · [مسیر ترافیک](docs/traffic-flow.md)
- [هاب](docs/hub.md) · [پرفورمنس](docs/performance.md) · [AmneziaWG معکوس](docs/amneziawg-reverse.md)
- [سند طراحی تفصیلی اصلی](rathole-multilocation-pasargad.md)标签：Bash, Nginx, Python, Rathole, 内网穿透, 反向代理, 应用安全, 抗审查网络, 无后门, 网络隧道, 逆向工具