feat: allow branch selection via CLI and improve auto-detection logic in installation script and update documentation

2026-09-05 15:46:45 +08:00 · 2026-05-31 14:30:29 +08:00
parent 8be03e0e33
commit ec0e4b2ee6
2 changed files with 99 additions and 27 deletions
@@ -19,29 +19,59 @@ AimiliVPN 是一款基于官方 VPNGate 开放协议的高性能、零依赖 VPN

 ### 🚀 一键极速部署 (支持 Debian/Ubuntu/CentOS/Alpine 等 Linux 系统)

-在您的 Linux VPS 上以 root 用户执行以下对应命令：
+在您的 Linux VPS 上以 root 用户执行以下对应命令（推荐显式传入分支参数）：

 #### 🌟 正式稳定版本 (main 分支)
 ```bash
-bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh)
+bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh) main
 ```

 #### 🧪 测试开发版本 (bate 分支)
 ```bash
-bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/bate/install.sh)
+bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/bate/install.sh) bate
 ```

-> 💡 **小贴士**：部署完成后，终端会输出管理网页的专属链接（含安全后缀）。在终端中输入 `ml` 命令可以随时调出交互式管理菜单。
+> 💡 **小贴士**：部署完成后，终端会输出管理网页的专属链接（含随机安全后缀，如 `http://your_vps_ip:8787/u71e9IXp4TPx`）。在终端中输入 `ml` 命令可以随时调出交互式命令行管理菜单。

 ---

-### 🛠️ 核心功能一览
-* **一键傻瓜化部署**：全自动配置运行环境，生成随机安全凭证，支持主流 Linux 系统（含轻量化 Alpine）。
-* **极简双效网关**：内置代理服务器在单一端口同时提供 HTTP 和 SOCKS5 代理服务（默认端口 `7928`）。
-* **精美 Web 管理后台**：现代化暗黑玻璃拟物风格 UI，支持手机、平板、电脑自适应布局。
-* **智能测速与连接**：自动并发测试空闲免费节点，支持 **智能自动配置（失效秒级漂移）**、**固定 IP 节点** 和 **固定国家地区** 三种出站路由模式。
-* **实时系统诊断**：内置网关服务心跳监测、后台守护线程运行状态跟踪。
-* **滚动终端日志**：支持分类过滤、实时滚动、一键复制和导出运行日志。
+### 💡 快速使用指南 (小白必看)
+
+部署成功后，如何使用它进行科学上网？
+
+#### 第一步：登录 Web 管理后台
+打开浏览器，访问部署完成时提示的专属后台地址（含安全后缀），即可进入精美的暗黑玻璃拟物风管理界面。
+
+#### 第二步：获取并连接节点
+1. 首次进入后台，节点列表可能正在进行首次自动测速与拉取。
+2. 点击 **“更新节点”** 按钮（或通过网页下方的网关/日志进行状态检查），程序会在后台通过多线程并发测速，自动筛选出延迟最低、可连接的 VPNGate 节点。
+3. 选择您喜欢的出站路由模式：
+   - **智能自动配置**（推荐）：如果当前连接的节点失效，系统会在数秒内自动漂移连接至其他备用健康节点，无需手动干预。
+   - **固定国家地区**：只选择指定国家（如日本 JP、韩国 KR、美国 US）的最佳节点。
+   - **固定 IP 节点**：始终锁定连接到这一个特定节点。
+
+#### 第三步：配置客户端代理 (核心步骤)
+AimiliVPN 内置的代理服务器在单一端口 **`7928`** 同时提供 **SOCKS5** 和 **HTTP** 双协议自适应服务。您只需要将客户端的代理指向：`您的VPS公网IP:7928`。
+
+* **💻 电脑端 (以 v2rayN / Clash / browser 插件为例)**:
+  - **v2rayN**: 点击“服务器” -> “添加Socks服务器”，服务器地址填 `VPS_IP`，端口填 `7928`。
+  - **Clash (YAML配置)**: 添加一个类型为 `socks5` 的 proxy，例如：
+    `{ name: "AimiliVPN", type: socks5, server: VPS_IP, port: 7928 }`
+  - **SwitchyOmega (浏览器扩展)**: 新建情景模式 -> 选择代理协议为 `SOCKS5` (或 `HTTP`)，代理服务器填 `VPS_IP`，端口填 `7928`。
+* **📱 手机端 (以 Shadowrocket 小火箭为例)**:
+  - 点击右上角 `+` 号添加节点，类型选择 `SOCKS5` (或 `HTTP`)，服务器填 `VPS_IP`，端口填 `7928` 即可。
+
+---
+
+### 🛠️ 核心功能与操作说明
+
+* **合并操作面板**：将“更新节点”与“立即检测补齐”合并，一键触发多线程拉取与测速。
+* **网关状态面板**：
+  - **系统诊断**：检测网关心跳及后台各个子守护线程（网页服务、VPN连接管理、出站网关服务）是否正常运行。若有脚本未运行，会提示具体的异常原因。
+  - **本地代理出口检测**：在网页端直接一键检测 VPS 后台对海外的实际连通状况，并回显真实的代理出站 IP 和所在地理位置。
+* **日志追踪面板**：
+  - **分类过滤**：可精准筛选查看特定功能的日志（如 VPN 连接日志、API 请求日志、系统异常等）。
+  - **实时滚动与管理**：日志实时滚动加载，支持一键复制代码、一键导出 `.log` 日志文件到本地。

 ---

@@ -57,13 +87,16 @@ bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/ba
  * **UFW (Ubuntu/Debian)**: `ufw allow 8787/tcp && ufw allow 7928/tcp`
  * **Firewalld (CentOS/RHEL)**: `firewall-cmd --zone=public --add-port=8787/tcp --permanent && firewall-cmd --zone=public --add-port=7928/tcp --permanent && firewall-cmd --reload`
 * **原因 2**：云服务商的“安全组”或“网络访问控制列表 (ACL)”未放行端口。
-* **解决办法 2**：登录云服务商控制台（如阿里云、腾讯云、AWS 等），在安全组规则中添加“入站规则”，放行 TCP 协议的 `8787` 和 `7928` 端口。
+* **解决办法 2**：**非常重要！** 登录云服务商控制台（如阿里云、腾讯云、AWS、Oracle Cloud等），找到您 VPS 实例的 **安全组规则 (Security Group)**，在入站规则中添加：
+  - **协议类型**: `TCP`
+  - **端口范围**: `8787` (管理网页) 和 `7928` (代理端口)
+  - **授权对象/源IP**: `0.0.0.0/0` (允许所有人，或指定您自己的家庭公网 IP 提高安全性)

 #### 3. 页面提示 `API Domain Blocked` 且备选节点显示为 0
 * **原因**：您的 VPS DNS 解析异常，或者官方 VPNGate 域名遭防火墙拦截污染，导致无法下载节点列表。
 * **解决办法**：
-  * **设置上游代理**：在网页管理面板中打开“管理员 -> 代理及网络设置”，配置有效的 HTTP/SOCKS5 上游代理，后台会自动通过该代理拉取更新。
-  * **修改 DNS 解析器**：在终端修改 `/etc/resolv.conf`，将域名服务器替换为公共 DNS（如 `8.8.8.8` 和 `1.1.1.1`）。
+  * **设置上游代理**：如果您有其他可用的代理服务，可在网页管理面板中打开“管理员 -> 代理及网络设置”，配置有效的 HTTP/SOCKS5 上游代理，后台会自动通过该代理拉取更新。
+  * **修改 DNS 解析器**：在终端修改 `/etc/resolv.conf`，将域名服务器替换为公共 DNS（如 `nameserver 8.8.8.8` 和 `nameserver 1.1.1.1`）。

 #### 4. VPN 已成功连接，但客户端设置代理后无法上网 (无流量)
 * **原因**：部分系统启用了严格的反向路径过滤（`rp_filter`），导致策略路由的入站/出站数据包被系统误判丢弃。
@@ -90,18 +123,39 @@ Run the corresponding command on your Linux VPS as root:

 #### 🌟 Stable Release (main branch)
 ```bash
-bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh)
+bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh) main
 ```

 #### 🧪 Beta / Development (bate branch)
 ```bash
-bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/bate/install.sh)
+bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/bate/install.sh) bate
 ```

 > 💡 **Quick Note**: Once installed, copy the printed URL from the terminal to access the Web UI. Type the `ml` command in the terminal to summon the interactive CLI management console.

 ---

+### 💡 Quick Start Guide
+
+#### Step 1: Access the Web UI
+Open your browser and navigate to the printed URL (e.g. `http://your_vps_ip:8787/u71e9IXp4TPx`).
+
+#### Step 2: Select Node and Mode
+1. Wait for the program to complete its first automatic node speed benchmarks.
+2. Under "Admin", you can trigger node fetching. The backend concurrently tests official VPNGate nodes and ranks them by latency.
+3. Switch routes mode (Smart Auto, Specific Region, or Specific Server Node) according to your needs.
+
+#### Step 3: Configure Proxy Clients
+The gateway runs a dual SOCKS5/HTTP compatible proxy server on port **`7928`**.
+* **💻 PC (Clash / v2rayN / browser proxy plugins)**:
+  - **SOCKS5/HTTP Proxy Server**: `your_vps_ip`
+  - **Port**: `7928`
+* **📱 Mobile (Shadowrocket / v2rayNG)**:
+  - Add a **Socks5** (or HTTP) node.
+  - Set host to your VPS public IP, port to `7928`.
+
+---
+
 ### ⚠️ Common Troubleshooting (FAQ)

 #### 1. Error: `Cannot allocate tun` or `Cannot open tun/tap dev`
@@ -114,7 +168,7 @@ bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/ba
  * **UFW**: `ufw allow 8787/tcp && ufw allow 7928/tcp`
  * **Firewalld**: `firewall-cmd --add-port=8787/tcp --permanent && firewall-cmd --add-port=7928/tcp --permanent && firewall-cmd --reload`
 * **Reason 2**: Service provider security group blocking ports.
-* **Solution 2**: Log in to cloud console (AWS, Aliyun, Oracle Cloud, etc.) and add inbound rules for TCP `8787` and `7928`.
+* **Solution 2**: **Crucial!** Log in to your cloud provider console (AWS, Aliyun, Oracle Cloud, etc.), locate the **Security Group** for your instance, and add an inbound TCP rule to allow ports `8787` and `7928` from `0.0.0.0/0`.

 #### 3. "API Domain Blocked" / Candidate nodes pool is empty (0 nodes)
 * **Reason**: The official VPNGate domain is blocked or DNS resolution failed on your VPS.
@@ -82,14 +82,29 @@ fi

 # 4. Clone or pull the repository
 INSTALL_DIR="/opt/aimilivpn"
-DEFAULT_DEPLOY_BRANCH="bate"
+# 默认部署分支，生产正式版设为 main
+DEFAULT_DEPLOY_BRANCH="main"

-# Auto-detect checked-out branch if it's already installed
+# 优先获取外部传入的参数作为目标分支，例如 bash install.sh bate
+CMD_BRANCH="$1"
+
+# 自动检测本地已安装版本当前所在的分支
 CURRENT_BRANCH=""
 if [ -d "${INSTALL_DIR}/.git" ]; then
    CURRENT_BRANCH=$(cd "${INSTALL_DIR}" && git rev-parse --abbrev-ref HEAD 2>/dev/null)
 fi
-DEPLOY_BRANCH="${CURRENT_BRANCH:-$DEFAULT_DEPLOY_BRANCH}"
+
+# 确立部署分支优先级：
+# 1. 命令行传入的参数 (如 $1 = main/bate)
+# 2. 已安装则使用当前分支 CURRENT_BRANCH
+# 3. 默认兜底使用 DEFAULT_DEPLOY_BRANCH (即 main)
+if [ -n "$CMD_BRANCH" ]; then
+    DEPLOY_BRANCH="$CMD_BRANCH"
+elif [ -n "$CURRENT_BRANCH" ]; then
+    DEPLOY_BRANCH="$CURRENT_BRANCH"
+else
+    DEPLOY_BRANCH="$DEFAULT_DEPLOY_BRANCH"
+fi

 echo -e "\n${YELLOW}[2/4] 正在从 GitHub 部署源代码到 ${INSTALL_DIR} (目标分支: ${DEPLOY_BRANCH})...${PLAIN}"
 if [ -f "${INSTALL_DIR}/.local_dev" ]; then
@@ -526,13 +541,16 @@ def update_service():
            # Fetch remote origin updates
            subprocess.run(["git", "fetch", "--all"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            
-            # Detect remote branch (check origin/main, then origin/master)
-            branch = "main"
-            for b in ["main", "master"]:
-                chk = subprocess.run(["git", "rev-parse", "--verify", f"origin/{b}"], capture_output=True, text=True)
-                if chk.returncode == 0:
-                    branch = b
-                    break
+            # Detect remote branch (prefer current local branch, fallback to origin/main or origin/master)
+            curr = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], capture_output=True, text=True)
+            branch = curr.stdout.strip() if curr.returncode == 0 else ""
+            if not branch or branch == "HEAD":
+                branch = "main"
+                for b in ["main", "master"]:
+                    chk = subprocess.run(["git", "rev-parse", "--verify", f"origin/{b}"], capture_output=True, text=True)
+                    if chk.returncode == 0:
+                        branch = b
+                        break
            
            local_commit = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip()
            remote_commit = subprocess.run(["git", "rev-parse", f"origin/{branch}"], capture_output=True, text=True).stdout.strip()