Initial commit: Portable WiFi proxy setup with VLESS+Reality

Complete solution for using MSM8916 portable WiFi as a proxy server
with Xray VLESS+Reality, UPnP auto port mapping, DDNS, WiFi helper,
and watchdog. Includes one-click setup script and apt source fix.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,3 @@
+*.png
+*.bak
+.DS_Store

README.md

@@ -0,0 +1,298 @@
+# Portable WiFi Proxy - 随身WiFi 翻墙方案
+
+将高通 410（MSM8916）随身WiFi 刷入 Debian，部署 Xray VLESS+Reality 代理服务，实现从中国大陆通过美国家庭 IP 上网。
+
+## 特点
+
+- **VLESS + Reality 协议** — 目前抗 GFW 封锁最强的方案，无需域名和证书
+- **全自动运行** — 开机自启 Xray、UPnP 自动端口映射、DDNS 自动更新、看门狗自动恢复
+- **体积小巧** — U 盘大小，低功耗（~2W），随身携带
+- **64 位 AArch64** — Cortex-A53 四核，性能优于玩客云 S805
+- **WiFi 连接** — 无需网线，通过 WiFi 连接家庭路由器
+
+## 硬件需求
+
+- 高通 410（MSM8916）随身WiFi 一个（已刷 Debian / OpenStick）
+- USB 电源（充电头 / 充电宝 / 电脑 USB 口）
+
+## 整体架构
+
+```
+中国手机/电脑 --> GFW --> 美国家庭路由器 --> 随身WiFi(Xray) --> 目标网站
+                              WiFi连接       (VLESS+Reality)
+                          (UPnP自动映射)
+```
+
+---
+
+## 第一步：刷 Debian 系统
+
+### 1.1 准备工具
+
+- 电脑安装 [QFIL](https://qfiltool.com/)（Qualcomm Flash Image Loader）
+- 下载 [OpenStick](https://github.com/OpenStick/OpenStick) 固件或 Debian ARM64 镜像
+- 安装高通 9008 驱动
+
+### 1.2 刷机步骤
+
+1. 短接随身WiFi 主板上的触点，进入 **9008 模式**
+2. USB 连接电脑，QFIL 识别设备
+3. 刷入 Debian / OpenStick 固件
+4. 重启设备
+
+> 搜索关键词 `MSM8916 随身WiFi 刷 Debian` 或 `OpenStick 刷机教程` 可找到大量教程。
+
+### 1.3 首次登录
+
+随身WiFi 插到电脑 USB 口，通过 USB 网络共享登录：
+
+```bash
+ssh root@192.168.68.1
+# 默认密码：1（或根据固件不同可能是 root）
+```
+
+---
+
+## 第二步：一键部署（推荐）
+
+将本项目克隆到随身WiFi 后，运行安装脚本即可自动完成所有配置：
+
+```bash
+apt update && apt install -y git
+git clone https://github.com/你的用户名/portable-wifi-proxy.git
+cd portable-wifi-proxy
+chmod +x setup.sh
+./setup.sh
+```
+
+脚本会自动完成：
+- 修复 apt 软件源
+- 安装 Xray
+- 生成 UUID 和 Reality 密钥
+- 写入配置文件
+- 配置开机自启和看门狗
+- 安装 UPnP 自动端口映射
+- 可选：配置 Cloudflare DDNS
+
+---
+
+## 第三步：手动部署
+
+如果你更喜欢手动操作，按以下步骤进行：
+
+### 3.1 修复 apt 软件源
+
+OpenStick 固件的 sources.list 可能格式有误，先修复：
+
+```bash
+cat > /etc/apt/sources.list << "EOF"
+deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
+deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
+deb https://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free
+EOF
+apt update
+```
+
+### 3.2 安装依赖
+
+```bash
+apt install -y curl wget cron miniupnpc
+```
+
+### 3.3 安装 Xray
+
+```bash
+bash <(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)
+```
+
+### 3.4 生成密钥
+
+```bash
+# 生成 UUID
+xray uuid
+# 输出示例：a1b2c3d4-5678-9abc-def0-123456789abc
+
+# 生成 Reality 密钥对
+xray x25519
+# 记下 PrivateKey 和 PublicKey
+```
+
+### 3.5 写入配置
+
+将 [config/xray-config.json](config/xray-config.json) 复制到 `/usr/local/etc/xray/config.json`，替换其中的 UUID 和 PrivateKey。
+
+```bash
+cp config/xray-config.json /usr/local/etc/xray/config.json
+# 编辑并替换 YOUR_UUID 和 YOUR_PRIVATE_KEY
+nano /usr/local/etc/xray/config.json
+```
+
+### 3.6 启动服务
+
+```bash
+xray run -test -config /usr/local/etc/xray/config.json  # 验证配置
+systemctl enable xray
+systemctl restart xray
+```
+
+### 3.7 配置自动重启
+
+```bash
+cp config/restart.conf /etc/systemd/system/xray.service.d/restart.conf
+systemctl daemon-reload
+```
+
+### 3.8 安装看门狗
+
+```bash
+cp scripts/xray-watchdog.sh /usr/local/bin/
+chmod +x /usr/local/bin/xray-watchdog.sh
+(crontab -l 2>/dev/null; echo "* * * * * /usr/local/bin/xray-watchdog.sh") | crontab -
+```
+
+### 3.9 配置 UPnP
+
+```bash
+cp scripts/upnp-map.sh /usr/local/bin/
+chmod +x /usr/local/bin/upnp-map.sh
+cp config/upnp-map.service /etc/systemd/system/
+cp config/upnp-map.timer /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable upnp-map.service upnp-map.timer
+```
+
+### 3.10 配置 DDNS（可选）
+
+如果你有 Cloudflare 域名：
+
+```bash
+cp scripts/ddns-update.sh /usr/local/bin/
+chmod +x /usr/local/bin/ddns-update.sh
+# 编辑填入你的 Cloudflare Zone ID、Record ID、API Token
+nano /usr/local/bin/ddns-update.sh
+(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/ddns-update.sh") | crontab -
+```
+
+---
+
+## 第四步：连接美国家庭 WiFi
+
+随身WiFi 只有一个无线网卡，WiFi 连接和热点**只能二选一**，因此需要通过 USB 方式配置。
+
+### 到美国后操作（只需做一次）
+
+1. **随身WiFi 插到电脑 USB 口**（供电 + USB 网络共享）
+2. SSH 登录：
+   ```bash
+   ssh root@192.168.68.1
+   ```
+3. 扫描并连接家里 WiFi：
+   ```bash
+   nmcli dev wifi list                              # 扫描附近WiFi
+   nmcli dev wifi connect "WiFi名" password "密码"   # 连接
+   ```
+4. 连好后拔掉 USB，**单独插电源即可**
+
+WiFi 连接会永久保存，以后开机自动连接。
+
+---
+
+## 第五步：客户端配置
+
+### 分享链接格式
+
+```
+vless://YOUR_UUID@你的域名或IP:8443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=www.microsoft.com&fp=chrome&pbk=YOUR_PUBLIC_KEY&sid=abcd1234&type=tcp#WiFi-US
+```
+
+### 推荐客户端
+
+| 平台 | 客户端 |
+|------|--------|
+| Android | [v2rayNG](https://github.com/2dust/v2rayNG) |
+| iOS | Shadowrocket（App Store 美区） |
+| Windows | [v2rayN](https://github.com/2dust/v2rayN) |
+| Mac | [Nekoray](https://github.com/MatsuriDayo/nekoray) / V2rayU |
+
+### 客户端参数
+
+| 参数 | 值 |
+|------|-----|
+| 协议 | VLESS |
+| 地址 | 你的域名或公网 IP |
+| 端口 | 8443 |
+| UUID | 安装时生成的 UUID |
+| 流控 | xtls-rprx-vision |
+| 传输 | tcp |
+| 安全 | reality |
+| SNI | www.microsoft.com |
+| Public Key | 安装时生成的公钥 |
+| Short ID | abcd1234 |
+
+---
+
+## 远程维护（从中国 SSH 到随身WiFi）
+
+代理连通后，可以通过代理 SSH 回设备进行维护：
+
+```bash
+# 通过本地 SOCKS5 代理 SSH
+ssh -o ProxyCommand="nc -x 127.0.0.1:10808 %h %p" root@随身WiFi内网IP
+```
+
+### 故障兜底
+
+- **Xray 崩溃** — 看门狗每分钟自动重启，systemd 也会自动重启
+- **完全失联** — 请人拔掉电源再插上，或用智能插座远程断电重启
+- **编辑配置前备份** — 使用 `xedit` 命令自动备份后再编辑
+
+---
+
+## 注意事项
+
+### USB 口是 Device 模式
+
+随身WiFi 的 USB 口是**从设备模式**（Device），不是主设备模式（Host），因此：
+- ❌ 不能外接 USB 扩展坞、USB 网卡
+- ✅ 可以插电脑获取供电和 USB 网络共享（192.168.68.1）
+
+### WiFi 和热点只能二选一
+
+设备只有一个无线网卡（wlan0），连接 WiFi 和发射热点不能同时进行。连接家庭 WiFi 后热点功能不可用。
+
+### 内存较小
+
+MSM8916 通常只有 512MB 或更少的内存，Xray 运行约占 20-30MB，日常使用没有问题，但不要运行其他重型服务。
+
+---
+
+## 自动化清单
+
+| 功能 | 机制 | 频率 |
+|------|------|------|
+| Xray 自启 | systemctl enable | 开机 |
+| Xray 崩溃重启 | systemd Restart=on-failure | 实时 |
+| Xray 看门狗 | crontab | 每分钟 |
+| UPnP 端口映射 | systemd timer | 开机30s + 每小时 |
+| DDNS 更新 | crontab | 每5分钟 |
+| WiFi 自动重连 | NetworkManager | 开机 |
+
+---
+
+## 与玩客云方案对比
+
+| | 玩客云 S805 | 随身WiFi MSM8916 |
+|--|------------|------------------|
+| CPU | Cortex-A5 单核 32位 | Cortex-A53 四核 64位 |
+| 内存 | 1GB | 382MB |
+| 网络 | 有线网 | WiFi |
+| 体积 | 较大 | U盘大小 |
+| 功耗 | ~5W | ~2W |
+| USB 外接 | 支持 | 不支持（Device模式） |
+| 稳定性 | 有线更稳 | WiFi 偶尔可能断连 |
+
+两个设备可以同时部署，互为备份。
+
+## License
+
+MIT

config/restart.conf

@@ -0,0 +1,3 @@
+[Service]
+Restart=on-failure
+RestartSec=5

config/sources.list

@@ -0,0 +1,3 @@
+deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
+deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
+deb https://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free

config/upnp-map.service

@@ -0,0 +1,12 @@
+[Unit]
+Description=UPnP Port Mapping
+After=network-online.target xray.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/upnp-map.sh
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target

config/upnp-map.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Renew UPnP mapping every hour
+
+[Timer]
+OnBootSec=30
+OnUnitActiveSec=1h
+
+[Install]
+WantedBy=timers.target

config/xray-config.json

@@ -0,0 +1,33 @@
+{
+  "inbounds": [
+    {
+      "listen": "0.0.0.0",
+      "port": 8443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "YOUR_UUID",
+            "flow": "xtls-rprx-vision"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "tcp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "www.microsoft.com:443",
+          "serverNames": ["www.microsoft.com"],
+          "privateKey": "YOUR_PRIVATE_KEY",
+          "shortIds": ["abcd1234"]
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "protocol": "freedom"
+    }
+  ]
+}

scripts/connect-wifi.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Connect to a WiFi network
+# Usage: ./connect-wifi.sh "WiFi_Name" "WiFi_Password"
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <SSID> <Password>"
+    echo ""
+    echo "Available WiFi networks:"
+    nmcli dev wifi list
+    exit 1
+fi
+
+SSID="$1"
+PASSWORD="$2"
+
+echo "Connecting to WiFi: $SSID ..."
+nmcli dev wifi connect "$SSID" password "$PASSWORD"
+
+if [ $? -eq 0 ]; then
+    echo "Connected successfully!"
+    echo "IP address:"
+    hostname -I
+else
+    echo "Connection failed. Please check SSID and password."
+fi

scripts/ddns-update.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Cloudflare DDNS updater
+# Fill in your own values below
+
+ZONE_ID="YOUR_ZONE_ID"
+RECORD_ID="YOUR_RECORD_ID"
+API_TOKEN="YOUR_API_TOKEN"
+DOMAIN="wifi.yourdomain.com"
+
+IP=$(curl -s https://api.ipify.org)
+
+if [ -n "$IP" ]; then
+    curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
+      -H "Authorization: Bearer $API_TOKEN" \
+      -H "Content-Type: application/json" \
+      --data "{\"type\":\"A\",\"name\":\"$DOMAIN\",\"content\":\"$IP\",\"ttl\":60,\"proxied\":false}"
+fi

scripts/upnp-map.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# UPnP automatic port mapping for Xray
+PORT=8443
+
+# Remove old mapping
+upnpc -d $PORT TCP 2>/dev/null
+
+# Add new mapping (valid for 24 hours)
+LOCAL_IP=$(hostname -I | awk '{print $1}')
+upnpc -a "$LOCAL_IP" $PORT $PORT TCP 86400

scripts/xray-watchdog.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Xray watchdog - restarts Xray if it's not running
+if ! systemctl is-active --quiet xray; then
+    systemctl restart xray
+fi

setup.sh

@@ -0,0 +1,181 @@
+#!/bin/bash
+# Portable WiFi Proxy - One-click setup script
+# Run on Debian/OpenStick (MSM8916) after flashing
+
+set -e
+
+echo "========================================="
+echo "  Portable WiFi Proxy Setup"
+echo "  VLESS + Reality + UPnP + DDNS"
+echo "========================================="
+echo ""
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_ok() { echo -e "${GREEN}[OK]${NC} $1"; }
+print_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+print_err() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# Check root
+if [ "$EUID" -ne 0 ]; then
+    print_err "Please run as root"
+    exit 1
+fi
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+
+# Step 1: Fix apt sources
+echo ""
+echo ">>> Fixing apt sources..."
+cp "$SCRIPT_DIR/config/sources.list" /etc/apt/sources.list
+apt update -y
+print_ok "Apt sources fixed"
+
+# Step 2: Install dependencies
+echo ""
+echo ">>> Installing dependencies..."
+apt install -y curl wget cron miniupnpc
+print_ok "Dependencies installed"
+
+# Step 3: Install Xray
+echo ""
+echo ">>> Installing Xray..."
+bash <(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)
+print_ok "Xray installed"
+
+# Step 4: Generate keys
+echo ""
+echo ">>> Generating keys..."
+UUID=$(xray uuid)
+KEYS=$(xray x25519)
+PRIVATE_KEY=$(echo "$KEYS" | grep "PrivateKey" | awk '{print $2}')
+PUBLIC_KEY=$(echo "$KEYS" | grep "PublicKey" | awk '{print $2}')
+
+print_ok "UUID: $UUID"
+print_ok "Private Key: $PRIVATE_KEY"
+print_ok "Public Key: $PUBLIC_KEY"
+
+# Step 5: Write Xray config
+echo ""
+echo ">>> Writing Xray config..."
+sed -e "s/YOUR_UUID/$UUID/" -e "s|YOUR_PRIVATE_KEY|$PRIVATE_KEY|" \
+    "$SCRIPT_DIR/config/xray-config.json" > /usr/local/etc/xray/config.json
+
+xray run -test -config /usr/local/etc/xray/config.json
+print_ok "Xray config written and validated"
+
+# Step 6: Configure auto-restart
+echo ""
+echo ">>> Configuring auto-restart..."
+mkdir -p /etc/systemd/system/xray.service.d
+cp "$SCRIPT_DIR/config/restart.conf" /etc/systemd/system/xray.service.d/restart.conf
+systemctl daemon-reload
+systemctl enable xray
+systemctl restart xray
+print_ok "Xray enabled with auto-restart"
+
+# Step 7: Install watchdog
+echo ""
+echo ">>> Installing watchdog..."
+cp "$SCRIPT_DIR/scripts/xray-watchdog.sh" /usr/local/bin/
+chmod +x /usr/local/bin/xray-watchdog.sh
+(crontab -l 2>/dev/null | grep -v xray-watchdog; echo "* * * * * /usr/local/bin/xray-watchdog.sh") | crontab -
+print_ok "Watchdog installed (checks every minute)"
+
+# Step 8: Configure UPnP
+echo ""
+echo ">>> Configuring UPnP..."
+cp "$SCRIPT_DIR/scripts/upnp-map.sh" /usr/local/bin/
+chmod +x /usr/local/bin/upnp-map.sh
+cp "$SCRIPT_DIR/config/upnp-map.service" /etc/systemd/system/
+cp "$SCRIPT_DIR/config/upnp-map.timer" /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable upnp-map.service upnp-map.timer
+print_ok "UPnP auto port mapping enabled"
+
+# Step 9: Install WiFi connect helper
+cp "$SCRIPT_DIR/scripts/connect-wifi.sh" /usr/local/bin/
+chmod +x /usr/local/bin/connect-wifi.sh
+print_ok "WiFi connect helper installed (use: connect-wifi.sh \"SSID\" \"password\")"
+
+# Step 10: Add config backup alias
+echo 'alias xedit="cp /usr/local/etc/xray/config.json /usr/local/etc/xray/config.json.bak && nano /usr/local/etc/xray/config.json"' >> ~/.bashrc
+print_ok "Config backup alias added (use 'xedit' to safely edit config)"
+
+# Step 11: Optional DDNS
+echo ""
+read -p "Configure Cloudflare DDNS? (y/n): " SETUP_DDNS
+if [ "$SETUP_DDNS" = "y" ]; then
+    read -p "Domain (e.g. wifi.example.com): " DDNS_DOMAIN
+    read -p "Cloudflare Zone ID: " DDNS_ZONE_ID
+    read -p "Cloudflare API Token: " DDNS_API_TOKEN
+
+    # Create DNS record and get Record ID
+    RECORD_RESULT=$(curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$DDNS_ZONE_ID/dns_records" \
+      -H "Authorization: Bearer $DDNS_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      --data "{\"type\":\"A\",\"name\":\"$DDNS_DOMAIN\",\"content\":\"1.1.1.1\",\"ttl\":60,\"proxied\":false}")
+
+    DDNS_RECORD_ID=$(echo "$RECORD_RESULT" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+    if [ -n "$DDNS_RECORD_ID" ]; then
+        sed -e "s/YOUR_ZONE_ID/$DDNS_ZONE_ID/" \
+            -e "s/YOUR_RECORD_ID/$DDNS_RECORD_ID/" \
+            -e "s/YOUR_API_TOKEN/$DDNS_API_TOKEN/" \
+            -e "s|wifi.yourdomain.com|$DDNS_DOMAIN|" \
+            "$SCRIPT_DIR/scripts/ddns-update.sh" > /usr/local/bin/ddns-update.sh
+        chmod +x /usr/local/bin/ddns-update.sh
+        (crontab -l 2>/dev/null | grep -v ddns-update; echo "*/5 * * * * /usr/local/bin/ddns-update.sh") | crontab -
+        /usr/local/bin/ddns-update.sh
+        print_ok "DDNS configured for $DDNS_DOMAIN"
+    else
+        print_err "Failed to create DNS record. Please configure DDNS manually."
+    fi
+fi
+
+# Done - print summary
+echo ""
+echo "========================================="
+echo "  Setup Complete!"
+echo "========================================="
+echo ""
+echo "Your client configuration:"
+echo ""
+echo "  Protocol:    VLESS"
+echo "  Port:        8443"
+echo "  UUID:        $UUID"
+echo "  Flow:        xtls-rprx-vision"
+echo "  Transport:   tcp"
+echo "  Security:    reality"
+echo "  SNI:         www.microsoft.com"
+echo "  Public Key:  $PUBLIC_KEY"
+echo "  Short ID:    abcd1234"
+echo ""
+echo "Share link:"
+echo "  vless://${UUID}@YOUR_IP_OR_DOMAIN:8443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=www.microsoft.com&fp=chrome&pbk=${PUBLIC_KEY}&sid=abcd1234&type=tcp#WiFi-US"
+echo ""
+
+# Generate QR code if qrencode is available
+if command -v qrencode &>/dev/null; then
+    echo "QR Code:"
+    qrencode -t UTF8 "vless://${UUID}@YOUR_IP_OR_DOMAIN:8443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=www.microsoft.com&fp=chrome&pbk=${PUBLIC_KEY}&sid=abcd1234&type=tcp#WiFi-US"
+else
+    echo "Install qrencode for QR code: apt install -y qrencode"
+fi
+
+echo ""
+echo "========================================="
+echo "  Next Steps"
+echo "========================================="
+echo ""
+echo "1. Bring device to the US"
+echo "2. Plug into computer USB, SSH to 192.168.68.1"
+echo "3. Run: connect-wifi.sh \"Your_WiFi_Name\" \"Your_WiFi_Password\""
+echo "4. Unplug USB, connect power only — done!"
+echo ""
+echo "IMPORTANT: Save the UUID and Public Key above!"
+echo "========================================="