1. 设计目标与非目标
✅ 目标
① 统一账号：一个 user_id 贯通所有游戏、双平台；② 云存档：任何游戏进度跨会话/跨设备（v2 M1）；③ 一处接入、处处复用：新游戏只需接 SDK + 在游戏库注册一条配置；④ 支撑 v2 变现体系：双货币、分享回流、支付验单、排行榜、签到任务；⑤ 1–5 人团队可运维。
🚫 非目标（明确不做）
① 实时对战/长连接（v2 L3 层级，团队规模不支持）；② 每游戏独立服务端（正是要消灭的形态）；③ 自建账号密码体系（只用平台 openid 静默登录）；④ 第一阶段不做海外版（架构预留即可）。
2. 三端拓扑
┌───────────────────────────── 客户端层 ─────────────────────────────┐
│ 合集小游戏（微信 → 抖音） 独立爆款小游戏（从合集拆出） │
│ ├─ 大厅：游戏库（动态配置下发） ├─ 单款玩法 + 同一 SDK │
│ ├─ 用户中心 / 签到 / 任务 / 商店 └─ 与合集互跳导流 │
│ └─ 15 款游戏分包，统一接 game-sdk.js │
└──────────────────────────────┬─────────────────────────────────────┘
│ HTTPS(api.example.cn, 备案)
┌──────────────────────────────▼─────────────────────────────────────┐
│ 服务端层（中国区 VPS） │
│ Nginx/Caddy ── Hono API ──┬── Postgres：users/saves/orders/… │
│ （TLS·限流） （Node 20） ├── Redis：排行榜 ZSET·会话·限频·缓存 │
│ └── 平台适配：wx code2session / midas 验单 │
│ tt code2session / tt 支付验单 │
└───────┬──────────────────────────────────────────────┬─────────────┘
│ 每日备份(pg_dump→R2) │ /admin/* API
┌───────▼───────────────┐ ┌──────────▼──────────────┐
│ Cloudflare（辅助面） │ │ 管理后台 SPA │
│ R2 冷备·资产源站 │ │ CF Pages 托管 │
│ Workers 定时任务·海外预留│ │ CF Access 登录保护 │
└───────────────────────┘ └─────────────────────────┘
3. 部署约束：为什么是「VPS 主链路 + Cloudflare 辅助」
| 约束 | 事实 | 架构结论 |
|---|
| 小游戏域名白名单 | 微信/抖音要求 request/downloadFile 域名 HTTPS + ICP 备案，且需大陆稳定可达 | 主 API 域名必须解析到国内备案主机（VPS）；备案主体与小游戏主体一致 |
| Cloudflare 大陆可达性 | workers.dev / pages.dev 域名无法备案；CF 全球网络大陆访问不稳定（除中国网络专属方案） | 红线 CF 不承载小游戏直连流量；只做管理后台（运营自用、可接受科学访问）、冷备、定时任务 |
| 静态资源分发 | 小游戏代码包走平台自身 CDN；超包资源需自有 CDN 域名（同样要备案） | 国内 CDN（腾讯云/阿里云/七牛任一）挂 cdn.example.cn，回源 VPS 或对象存储 |
| 数据合规 | 用户数据（openid、存档、订单）产生并服务于境内用户 | 业务数据库落在境内 VPS；CF R2 仅存加密后的备份与非用户资产 |
| 未来出海 | 海外版无备案约束，CF 全家桶是低成本首选 | 选用 Hono（同构跑 Node 与 Workers），海外版可把同一套 API 部署到 CF Workers + D1/Hyperdrive，代码零改写 |
4. 技术选型与理由
| 层 | 选型 | 理由 |
|---|
| API 框架 | Hono（TypeScript） | 同一套代码可跑 Node（VPS 主链路）与 Cloudflare Workers（海外/辅助），路由+中间件极简，1–5 人团队心智负担小 |
| 运行时 | Node 20 LTS + PM2（或 Docker Compose） | 单机部署、进程守护、零停机 reload；Docker 便于日后迁移 |
| 数据库 | Postgres 16（存档字段用 jsonb） | jsonb 天然适合"每款游戏存档结构不同"的统一存档表；事务保证支付发货一致性。ORM 用 Drizzle（同样兼容 Workers） |
| 缓存/榜单 | Redis 7 | 排行榜 ZSET（天然 topN/排名查询）、登录会话、接口限频、游戏库配置缓存 |
| 反向代理 | Caddy（自动 HTTPS）或 Nginx | TLS 终结、gzip、基础限流、静态资源兜底 |
| 管理后台 | Vite + Vue3 + naive-ui/element-plus SPA | 纯静态产物托管在 CF Pages，CF Access（邮箱白名单）做第一道登录；调 VPS 的 /admin/* API（二道 JWT+RBAC） |
| 对象存储/备份 | Cloudflare R2 | 零出口流量费；pg_dump 每日加密上传；管理后台构建产物与文档资产也可放这 |
| 定时任务 | VPS cron（主）+ CF Workers Cron（辅） | 榜单结算/任务刷新等触库任务放 VPS cron；外部巡检（API 探活告警）放 Workers Cron，形成异地监督 |
| 监控告警 | Uptime 探活（Workers Cron）+ 服务器侧 pino 日志 + 每日指标快照入库 | 最小可用监控，不引入重型 APM |
5. 双平台适配层
差异全部收敛在两处：服务端 platform/ 适配模块与客户端 SDK 适配层（见 04）。业务代码不出现 wx./tt. 字样。
| 能力 | 微信 | 抖音 | 服务端抽象 |
|---|
| 登录换取身份 | jscode2session（openid/unionid/session_key） | code2session（openid/unionid） | POST /auth/login {platform, code} → identities 表 → 签发自有 JWT |
| 支付 | 虚拟支付 midas（安卓）；iOS 按当期政策 | tt.pay，安卓 IAP 九一开 | orders 表统一状态机 + 各平台回调验签器（见 03） |
| 激励视频 | createRewardedVideoAd | createRewardedVideoAd（同名不同参） | 客户端 SDK 封装；服务端只收 ad_events 埋点与发奖请求 |
| 分享 | shareAppMessage（不可验证是否分享成功） | 侧边栏/分享能力（另有回流场景值） | 回流发奖模型，share_records/share_visits 表（见 05） |
| 内容安全 | msgSecCheck（昵称/UGC 文本） | 对应内容安全接口 | 服务端统一 secCheck(text) 适配器，昵称/留言入库前必过 |
6. 域名与环境规划
| 域名（示例） | 指向 | 用途 | 备案 |
|---|
api.example.cn | 国内 VPS | 小游戏主 API（prod） | 必须 |
api-test.example.cn | 同 VPS 不同端口/容器 | 体验版/开发版联调（小游戏后台单独配白名单） | 必须 |
cdn.example.cn | 国内 CDN | 超包资源、图集、公告图 | 必须 |
admin.example.com | CF Pages + Access | 管理后台（运营自用，不受备案约束） | 不需要 |
- 环境：dev（本地 docker-compose 起 pg+redis）→ test（VPS 隔离库，供微信体验版）→ prod。两套线上环境共机不共库。
- 发布：git push → VPS 侧脚本拉取构建 → PM2 reload；管理后台 push 即 CF Pages 自动构建。第一阶段不引入完整 CI/CD。
7. 安全基线
- 鉴权：登录后签发短期 JWT（2h）+ 刷新令牌；所有业务接口必须带 token；admin 接口独立签发、独立密钥、加 RBAC（见 07）。
- 请求签名：写接口（提交分数/存档/领奖）附
nonce + timestamp + sign（SDK 内置盐 + 服务端二次校验），配合 Redis 防重放。
- 限频：Nginx 层 IP 级 + Redis 用户级（如存档写 ≤1 次/10s、领奖类 ≤N 次/日）。
- 发货一致性：支付回调→验签→orders 行锁→钱包入账→回执，全程单事务；重复回调幂等（订单状态机）。红线 客户端不得直改任何货币/道具数值。
- 数据：数据库仅监听内网/本机；每日 pg_dump 加密上传 R2，保留 30 天；openid 等标识不出现在日志明文。
8. 成本估算（月，人民币，估算·中）
| 项目 | 规格 | 费用 | 说明 |
|---|
| 国内 VPS | 2C4G（起步）→ 4C8G（放量） | ¥60–100 → ¥200–300 | API+Postgres+Redis 同机起步；DAU 数万内单机足够 |
| 域名 + 备案 | .cn 域名 | ¥30–60/年 | 备案免费但需 2–4 周周期，是阶段 1 的前置项 |
| 国内 CDN | 按量 | ¥10–50 | 前期流量极小 |
| Cloudflare | Pages/Access/R2/Workers 免费档 | ≈¥0 | R2 10GB 免费额度内 |
| 合计 | — | 约 ¥100–200/月起步 | 远低于一次小额买量测试的花费 |
9. 容量与演进
- 起步单机可支撑：DAU 1–5 万、存档写峰值 ~50 QPS（存档节流后实际远低）。瓶颈出现顺序预计：Redis 内存（榜单）→ Postgres 连接 → CPU。
- 第一次拆分（DAU 5 万+）：数据库迁到云数据库（RDS），VPS 只跑无状态 API，可横向加机器。
- 海外版：同一 Hono 代码部署 CF Workers，数据层换 D1/托管 Postgres，客户端 SDK 适配层加 海外平台（如 Telegram/Web）。
本篇结论：按 L2 轻服务端一步建到位（登录 + 云存档 + 排行榜 + 分享回流 + 支付验单），部署形态「国内 VPS 主链路 + Cloudflare 辅助面 + 国内 CDN」，技术栈 Hono/Postgres/Redis 一套代码兼容未来 Workers 部署。前置行动项只有一个：立即启动域名备案（2–4 周周期）。