Phase 0: 容器化数据面 + CI/CD 自动部署

- deploy/: Xray VLESS+REALITY (11443, 经宿主 nginx SNI 分流) + sing-box Hysteria2 (UDP 443) docker-compose - 幂等 deploy.sh / gen-secrets.sh / print-clients.sh;受限 nginx-apply 特权脚本 + 一次性 root-setup - .gitea/workflows/deploy.yml: NAS runner 经 SSH 远程部署到 EC2 - docs/ plan/: 设计方案与实施计划 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 11:48:21 +08:00
parent 833b8365da
commit cf96989e01
23 changed files with 1048 additions and 2 deletions
@@ -0,0 +1,240 @@
+# Pangolin 终端 VPN —— 整体技术方案
+
+> 状态:设计稿 v1 · 日期:2026-05-30
+> 选型基线:客户端 **Flutter 自研 UI**;后端 **先成熟面板、后自研 Go**;协议主推 **REALITY**。
+
+---
+
+## 0. 一句话定位
+
+面向中国大陆用户的「傻瓜式」科学上网工具:一键连接、自动选线、多端统一,
+免费+付费双轨,抗封锁、防跟踪,客户端自研 + 标准订阅兼容三方软件。
+
+### ⚠️ 合规与运营者安全前提(与技术同等重要)
+
+- 在中国境内**运营收费翻墙服务属违法经营**,风险在运营者而非用户。
+- 运营主体、服务器、域名、收款账户一律用**境外身份**,与国内真实身份**完全隔离**。
+- 管理后台不暴露公网;节点不留连接日志;支付走加密货币 / 可随时更换的通道。
+- 本文档只涉及"绕过审查、访问开放互联网"的正当技术,不涉及攻击/入侵他人系统。
+
+---
+
+## 1. 总体架构
+
+```
+                        ┌─────────────────────────────────────┐
+   用户(小白)            │            控制面 (境外)              │
+  ┌──────────┐          │  ┌──────────┐    ┌────────────────┐  │
+  │ Flutter   │──订阅──▶ │  │ 面板/API │───▶│ 用户/订单/流量库 │  │
+  │ 客户端    │          │  │(XBoard+  │    └────────────────┘  │
+  └────┬─────┘          │  │ Marzban) │                         │
+       │                │  └────┬─────┘ 下发配置 / 限速 / 额度    │
+       │  科学上网流量    │       ▼                               │
+       │              ┌─────────────────────────────────────┐  │
+       └─────────────▶│   数据面:多地接入节点 (VPS 集群)      │  │
+                      │  REALITY / Hysteria2 / CDN(WS)中转    │  │
+                      └─────────────────────────────────────┘
+   ┌──────────┐
+   │ 宣传页    │ ← Cloudflare Pages + 备用直连域名 + GitHub/TG 分发
+   └──────────┘
+```
+
+**核心原则:控制面(账号/计费)与数据面(代理节点)分离。**
+客户端只认「订阅链接」,节点可随时增删换 IP;被封换节点不影响账号体系。
+这是所有成熟机场的标准架构。
+
+---
+
+## 2. 协议选型(抗封锁核心)
+
+GFW = 主动探测 + 流量指纹 + IP 封锁。2026 年最优组合:
+
+| 协议 | 用途 | 抗封锁原理 | 速度 |
+|------|------|-----------|------|
+| **VLESS + Vision + REALITY** | 主力 | 偷用真实大站 TLS(如 microsoft.com),无自签指纹,主动探测回落真站 | 高 |
+| **Hysteria2** | 晚高峰/高丢包备线 | QUIC/UDP + 暴力拥塞控制 + 端口跳跃抗 QoS | 极高 |
+| **VLESS + WS + TLS over CDN** | IP 被封保底 | 走 Cloudflare,用户连 CF 的 IP,难整段封 | 中 |
+| TUIC v5 / ShadowTLS | 补充 | QUIC / 套真实 TLS 握手 | 高 |
+
+**主推 REALITY**(快、最难封),**CDN/WS 保底**(REALITY IP 被封自动切),
+**Hysteria2 加速**(晚高峰)。三者 sing-box 内核原生支持,一套内核搞定。
+
+**禁用**:裸 Shadowsocks、VMess、自签证书 Trojan —— 指纹已被识别。
+
+---
+
+## 3. 客户端 —— Flutter 自研 UI(已选)
+
+### 3.1 分层
+
+```
+┌──────────────────────────────────────────┐
+│  Flutter UI (Dart) —— 一套代码,~90% 复用   │  连接按钮 / 节点信号灯 / 额度 / 登录续费
+├──────────────────────────────────────────┤
+│  FFI / Platform Channel 桥接层              │
+├──────────────────────────────────────────┤
+│  sing-box 内核 (Go, libbox)  —— 协议/限速/路由│  只写一次,全平台复用
+├──────────────────────────────────────────┤
+│  各平台 VPN 壳(平台特定,薄)               │
+│  iOS/iPadOS: NetworkExtension PacketTunnel  │
+│  Android:    VpnService                     │
+│  Win/macOS/Linux: TUN 网卡                  │
+└──────────────────────────────────────────┘
+```
+
+- **内核**:[sing-box](https://github.com/SagerNet/sing-box) 的 `libbox`(gomobile 产物)。协议、限速、路由、URLTest 全在内核层,只写一次。
+- **UI**:Flutter,一套 Dart 出 iOS / Android / macOS / Windows / Linux。
+- **可借鉴的开源实现**(遵守各自许可证):**FlClash**、sing-box 官方 app(SFA/SFI/SFM/SFW)。
+- **Web 端**:浏览器做不了系统级 VPN。Web 定位 = **用户中心**(登录、看流量、续费、取订阅、看节点状态)。需浏览器代理时另做 Chrome 扩展(WS over CDN)。
+
+### 3.2 小白友好关键点(差异化卖点)
+
+- 首屏只有一个**大连接按钮** + 当前节点 + 信号灯。
+- 默认「**智能选择/自动**」(URLTest 选延迟最低的可用节点),高级用户才手动切地区。
+- 默认开:**Kill-switch**(断开即断网,防真实 IP 泄露)、防 DNS 泄露、防 WebRTC 泄露。
+- 一键导入订阅 / 扫码登录,免配置。
+
+### 3.3 三方软件兼容(并行提供)
+
+输出标准**订阅链接**(sing-box / Clash.Meta / v2rayN 格式),
+用户可用 v2rayN、Clash Verge、Shadowrocket、Stash、NekoBox 直接导入。
+这是"提供账号信息即用"的落地方式,也是高级用户入口。
+
+### 3.4 上架注意
+
+- **iOS 中国区会下架翻墙 App** → 用海外 Apple 开发者账号 + 海外区上架 / TestFlight / AltStore。
+- Android 走官网 APK + GitHub Releases + 应用商店(海外 Google Play)。
+
+> 开发顺序建议:先用 sing-box 官方 app 改皮肤跑通商业闭环,再切到 Flutter 自研(避免一上来卡在客户端)。
+
+---
+
+## 4. 后端 —— 先面板,后自研(已选)
+
+### 4.1 第一阶段:成熟面板(开箱即用)
+
+| 组件 | 选型 | 职责 |
+|------|------|------|
+| 商业前台 | **XBoard**(或 V2board) | 套餐/下单/支付/工单/邀请返利 |
+| 节点管理 | **Marzban / Marzneshin** | 用户、订阅生成、流量统计、到期、多节点 |
+| 数据面 | 各节点 sing-box / Xray | 真正的代理 |
+
+免费/付费额度、限速、到期,面板原生支持。**起步最快。**
+
+### 4.2 第二阶段:自研 Go 后端(深度定制时迁移)
+
+- **语言**:Go(与团队偏好一致,且与 sing-box 同栈)。
+- **服务**:账号鉴权(JWT)、订阅生成、订单/支付、流量计量、节点健康调度。
+- **DB**:PostgreSQL(用户/订单)+ Redis(限速令牌桶 / 会话 / 节点状态缓存)。
+- **节点 Agent**:每节点 = sing-box + 上报 agent(流量 / 在线 / 延迟 → 控制面)。
+- **迁移策略**:自研时复用面板的数据库 schema 与订阅格式,客户端无感切换。
+
+### 4.3 限速(需求 3,两层)
+
+1. **节点层硬限速**:sing-box/Xray 出站按用户打标 + Linux `tc`(HTB);免费用户单独限速队列。最可靠。
+2. **额度层**:面板按日/月流量配额,超额断流。免费用户每日额度;**看激励视频广告 → 客户端调 API 临时提额**。
+
+### 4.4 接入点 + 网络状态(需求 4)
+
+- 控制面每 ~30s 探测每个节点:延迟 / 丢包 / 在线 / 负载。
+- 订阅下发节点列表 + `status API`;UI 显示**绿/黄/红信号灯 + 延迟 ms**。
+- IP 分级:免费用户用"消耗品 IP 池"(易被封),付费用户用"精品 IP 池"。
+
+---
+
+## 5. 安全 / 抗封锁 / 防跟踪(需求 6)
+
+**抗被墙(数据面)**
+- REALITY 为主(无指纹);IP 用冷门小厂 VPS,定期轮换;CDN 中转保底。
+- Hysteria2 端口跳跃抗 UDP QoS。
+- 订阅域名、控制面 API 也套 CDN/REALITY,防"取订阅"这步被封或被关联。
+
+**防跟踪 / 隐私**
+- 不收集真实身份;注册仅邮箱 / 设备 ID + 卡密。
+- 节点 **no-log**;DNS 走 DoH/DoQ 防污染与泄露。
+- 客户端默认 Kill-switch + 防 DNS / WebRTC 泄露。
+- 控制面与数据面隔离;节点不存用户库,被抄一个节点不暴露全量用户。
+
+**运营者安全(最致命)**
+- 服务器 / 域名 / 支付全用境外身份,与国内真实身份隔离。
+- 加密货币付 VPS;域名隐私保护;管理后台仅 VPN 内网开放。
+
+---
+
+## 6. 宣传页(需求 7)
+
+矛盾:境外部署 + 国内直连 + 安全,三者天然冲突(境外站国内常被墙)。务实方案:
+
+- **静态站**:Astro / Next.js(SSG)纯静态 → **Cloudflare Pages**(免费、全球 CDN、自带 DDoS 防护)。
+- **国内直连对策**:
+  1. 多备用域名 + 自有 IP 直连镜像,主站被污染时引导切换。
+  2. 下载/取订阅入口做成可镜像分发:**GitHub Releases、Telegram 频道、网盘**,不把命脉绑死单域名。
+- **抗封获客靠去中心化**:Telegram 群/频道、Twitter/X、酷安、V2EX、邀请码裂变。宣传页是"信任背书 + 下载入口"。
+- 安全:全站 HTTPS、无第三方追踪脚本、不收集访客信息。
+
+---
+
+## 7. 商业化(需求 2 + 交易)
+
+### 7.1 套餐
+- **免费**:每日 1–2 GB 或限速;**看激励视频广告解锁额外额度**(广告用海外 AdMob/Unity)。走消耗品 IP 池。
+- **付费**:月/季/年 + 流量包;精品线路、不限速、多节点。
+- 转化漏斗:免费体验 → 晚高峰限速 → 推付费精品线路。
+
+### 7.2 收款(国内最大难点)
+
+| 方式 | 说明 | 风险 |
+|------|------|------|
+| **USDT(TRC20)** | 最抗封、最隐私,首选 | 用户门槛高 |
+| **自动发卡(卡密)** | 机场标配,支付宝/微信中转 | 收款码易封,需轮换 |
+| 爱发电 / Ko-fi | 打赏制,规避直接售卖定性 | 平台可能封 |
+| Stripe / Paddle(境外主体) | 正规,但需境外公司 + 外卡 | 主体门槛 |
+
+**建议**:主推 **USDT + 自动发卡**;收款通道与运营主体隔离,随时可换。
+**禁用**绑定真实身份的个人支付宝/微信收款。
+
+### 7.3 目标人群 & 获客
+- **核心**:留学/外贸/跨境电商、程序员/科研、追剧/游戏/ChatGPT 用户、数字游民。
+- **小白向卖点**:一键连接、自动选线、傻瓜 UI(对比 v2rayN 这类极客工具)。
+- **渠道**:Telegram、Twitter/X、YouTube 评测合作、酷安、邀请返利裂变、SEO(关键词:稳定梯子 / ChatGPT 怎么用)。
+
+---
+
+## 8. 技术栈一页纸
+
+| 层 | 选型 |
+|----|------|
+| 代理内核 | **sing-box**(REALITY + Hysteria2 + WS/CDN 保底) |
+| 客户端 | **Flutter**(iOS/Android/Win/macOS/Linux)+ 各端 VPN 壳;Web = 用户中心 |
+| 三方兼容 | 标准订阅(sing-box / Clash.Meta / v2rayN) |
+| 控制面/计费 | **XBoard**(阶段1)→ 自研 **Go**(阶段2) |
+| 节点管理 | **Marzban / Marzneshin** |
+| 数据库 | PostgreSQL + Redis |
+| 限速 | sing-box 出站标记 + tc + 面板配额 |
+| 节点监控 | Go agent 上报 → 客户端信号灯 |
+| 宣传页 | Astro/Next SSG + Cloudflare Pages + 多备份入口 |
+| 收款 | USDT(TRC20)+ 自动发卡;境外 Stripe 可选 |
+| 基础设施 | 多地冷门小厂 VPS + Cloudflare CDN |
+
+---
+
+## 9. 落地阶段(MVP 优先)
+
+| 阶段 | 目标 | 周期 |
+|------|------|------|
+| **0** | 1 台 VPS + sing-box + REALITY,用 v2rayN/Shadowrocket 连通,跑 vpn-test 验证线路 | 1–2 周 |
+| **1** | XBoard + Marzban,通注册/订阅/限速/卡密收款;靠分享订阅 + 三方软件**验证付费意愿** | 2–4 周 |
+| **2** | 先用 sing-box 官方 app 改品牌出客户端,接登录/信号灯/免费额度 | 2–4 周 |
+| **3** | Flutter 自研 UI、广告变现、多节点智能调度、宣传站 | 持续 |
+
+**先验证商业模式(有没有人付费),再投入客户端自研。**
+
+---
+
+## 10. 待决事项 / 下一步
+
+- [ ] 阶段0:出 sing-box 服务端 REALITY 配置 + 一键部署脚本
+- [ ] 选定首批 VPS 服务商与地区(冷门小厂、可加密货币付款)
+- [ ] XBoard + Marzban 的 docker-compose 部署方案
+- [ ] 客户端品牌名 / 域名 / 收款通道确定
+- [ ] Flutter 客户端工程脚手架与 sing-box libbox 桥接 PoC