Architecture Design · v1.0

# 穿山甲 整体架构设计

极简、轻量、亲和的跨平台网络加速应用。本设计覆盖前端五端（移动 / iPad / 桌面 / 官网 / 用户中心）、Go 控制面、MySQL 数据层、弹性节点拓扑、Web 安全与灾备、以及贯穿全局的安全与断网应对策略。UI 实现以 `design/ui_kits/` React 原型为像素基准，100% 还原既有设计系统。

2026-06-11 依据 design/ + plan/ + server/ARCHITECTURE.md v0.1

## §1关键架构决策

领域 | 决策 | 理由 / 相对蓝本的变化
--- | --- | ---
数据面协议 | sing-box：VLESS + Vision + REALITY 主线，Hysteria2 备线（端口跳跃） | 替换蓝本 v0.1 的 WireGuard——WG 协议特征明显，在目标网络环境必被识别阻断；plan/ phase-0~3 已实测选定 REALITY。API 契约形状保留，仅 `connect` 语义适配（见 02 章）。
数据库 | MySQL 8.x（InnoDB / utf8mb4）+ Redis | 按本次要求替换蓝本的 Postgres；schema 全量移植并做类型适配（见 03 章）。
移动 / iPad / 桌面客户端 | Flutter（共享 ~90% UI 代码）+ sing-box libbox 内核；iPad = 移动端工程宽度 ≥900 自适应切侧栏分栏（像素基准 `ui_kits/tablet/`） | `design/flutter/` 起步包即为此准备；原生 VPN 壳（NetworkExtension / VpnService / TUN）性能与稳定性最优。
官网 | Astro SSG → Cloudflare Pages 多镜像 | 纯静态、秒级整站复制到新域名，抗封锁；`ui_kits/website` JSX 近乎逐字迁移。
Web 用户中心 | Next.js（React） | `ui_kits/usercenter` 本身是 React——组件直接复用，还原保真度最高。
节点拓扑 | 三层弹性拓扑（入口 / 中转 / 落地）+ 节点生命周期状态机 + 一键/自动换节点换 IP | 补全 plan/ 中"IP 轮换自动化"的具体设计：判封探针、多厂商 VPS 池、目录版本灰度（见 04 章）。

## §2系统全景

移动 App Flutter · iOS/Android/iPad
桌面客户端 Flutter · Win/macOS
用户中心 Next.js
官网 Astro · 静态
│ HTTPS（域名池 + CDN 前置 + IP 直连兜底）
CDN / 域名池 Cloudflare · 源站隐藏
→
API 控制面 Go 单体 · 模块分包
→
MySQL 8 主数据 · 加密异地备份
Redis 验证码/限流/节点状态
发卡店 Webhook 激活码入库（签名）
→ 控制面 ←
管理端内网 · 白名单 + 2FA
探针系统多 ISP 拨测 · 判封
│ mTLS gRPC（节点注册 / 心跳 / 凭证下发 / 回收）
入口节点池消耗品 IP · 可秒换
→
中转层（可选）隧道转发
→
落地节点池精品 IP · 稳定出口
用户流量（REALITY / Hysteria2）只走数据面，绝不经过 API；节点零用户库。
控制面 / 数据面彻底分离 · 节点目录带版本灰度 · 任一节点被封不影响全局

四条铁律（继承蓝本 §0）：① 控制面/数据面分离；② App 内无支付，资金流全部外部化为激活码；③ 节点可秒级灰度，客户端缓存最后一份可用目录兜底；④ 最小数据原则——不记录浏览内容与目的地，仅保留计费所需的字节数/分钟数。

## §3章节导航

01 前端架构

五端技术栈选型、100% 还原策略（令牌 / 像素基准 / 验收清单）、客户端断网弹性。

02 后端设计

Go 模块化单体、API 契约 v1（遵循设计蓝本）、激活码 / 试用 / 广告解锁关键流程。

03 数据库

MySQL 8 全量 schema（蓝本移植 + 拓扑扩展）、Redis 键设计、备份与恢复策略。

04 机器与网络拓扑

三层弹性拓扑、节点生命周期状态机、一键/自动换节点换 IP、判封探针与调度。

05 Web 安全与灾备

CDN 前置与源站隐藏、域名池、备份体系、被封应对 Runbook、应急广播。

06 安全总纲

威胁模型总表、身份隔离红线、无日志口径、密码学口径、断网应对策略矩阵。

## §4设计依据与文档关系

来源 | 角色 | 本设计如何使用
--- | --- | ---
`design/CLAUDE.md` + `colors_and_type.css` | 设计铁律与令牌真相源 | 13 条铁律作为前端验收清单；套餐口径（§7）为所有界面/接口数字的单一来源。
`design/ui_kits/*` | 像素验收标准 | 各端实现逐屏对照 React 原型（含新增 `tablet/` iPad kit），差异即缺陷。
`design/server/ARCHITECTURE.md`（v0.1） | 后端蓝本 | API 契约、数据模型、激活码流程全部继承；数据面协议与 DB 选型按本设计修订。
`plan/phase-0~3` + `plan/security-运营安全.md` | 实施路线与威胁模型 | 协议选型（REALITY/Hy2）、IP 分级（消耗品/精品池）、身份隔离红线全部纳入。

套餐口径（引用 design/CLAUDE.md §7，改数字先改那里） 注册享 7 天免费试用（不限时长与节点）→ 之后免费版 1 个基础节点 + 每日 10 分钟 + 每日使用前看激励视频解锁；PRO ¥25/月（年付 ¥20/月），80+ 线路，5 台设备；团队版 ¥99/月 10 席位。收款走外部渠道（发卡店 / USDT TRC20 / Telegram / LINE / 邮箱），App 与官网内无支付表单。