pangolin/docs/技术方案.md

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 的 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