fire_goal/docs/03-架构设计.md

03 · 架构设计

用户端(uni-app 多端) + 管理后台(Web) + 腾讯云 VPS 后端(Go·域名·certbot HTTPS) + 本地优先同步。

一、整体架构图

用户端（unibest / uni-app · Vue3）         后端（腾讯云 VPS · Docker · HTTPS）
┌─────────────────────────────┐         ┌────────────────────────────┐
│  ① 每日打卡                  │         │  域名 + Nginx + certbot     │
│  ② 目标进度 & 净资产曲线      │  HTTPS  │  Go + Gin + GORM           │
│  ③ FIRE 测算器               │ ─REST→  │  ├─ JWT 单用户鉴权          │
│  ④ 持仓 & 分红跟踪            │ ←同步─  │  ├─ API: 打卡/快照/持仓/设置 │
│  本地缓存（离线优先）         │         │  └─ SQLite(纯Go驱动·可备份)  │
└─────────────────────────────┘         └────────────────────────────┘
        │                                  由同一个 Go 进程托管 ▲
        ├─ 浏览器 → 网页 / PWA                              │ html/template
        ├─ 云打包 → Android (.apk/.aab)                    │ 渲染(共用DB)
        └─ 云打包 → iOS (.ipa，需苹果账号)     ┌─────────────────────────┐
                                            │ 管理后台（Web · 电脑端）   │
                                            │ Gin html/template +      │
                                            │ HTMX + Alpine + Tabler   │
                                            │ 无构建·数据增删改查/报表   │
                                            └─────────────────────────┘

二、前端结构

• 页面：四大模块各一主页面 + 设置页，普通 vue 页面（不碰 nvue）。
• 图表：统一用 qiun-data-charts，图表页避免 nvue，数据做抽稀。
• 状态/数据层：本地优先，所有读写先走"存储抽象层"，再异步同步到后端。

存储抽象层（关键设计）

各端存储能力不同，必须封装统一接口，内部用条件编译分端实现：

端	底层实现	注意
H5	IndexedDB（大数据）/ localStorage	localStorage ~5MB 上限
App	uni.storage / 原生 SQLite 插件	历史快照/流水量大时用 SQLite
小程序	uni.storage	总量约 10MB，存流水易爆

interface Store {
  get(key), set(key, val), query(table, filter), bulkSave(...)
}
// #ifdef H5 → IndexedDB 实现
// #ifdef APP-PLUS → SQLite/uni.storage 实现
// #ifdef MP → uni.storage 实现

三、后端结构（腾讯云 VPS · Go）

• 技术栈：Go + Gin（Web）+ GORM（ORM）+ SQLite（纯 Go 驱动 modernc.org/sqlite，免 CGO，编译/部署最省心）+ JWT 鉴权。
• 部署：编译为单个静态二进制，Docker 化部署到腾讯云 VPS；前置 Nginx 反向代理，由 certbot（Let's Encrypt） 签发并自动续期 HTTPS。
• 域名：使用用户已有域名，解析到 VPS 公网 IP。
• 数据表（初版）：checkins（打卡）、snapshots（资产快照）、holdings（持仓）、settings（参数）、users（单用户）。
• 接口：标准 REST（增删改查 + 拉取增量），全程 HTTPS；用户端与管理后台共用同一套 API。
• 备份：SQLite 单文件，定时备份到对象存储/本地。

为什么用 Go 而非 Node：单二进制、内存占用小、Docker 镜像可压到几 MB，更适合常驻的小 VPS 自托管；前后端经 REST/JSON 解耦，后端语言对 uni-app 前端无影响。

三-B、管理后台（Web 管理端 · 无构建）

• 定位：电脑端网页，给本人用来增删改查数据、查看报表、调整参数（如目标本金、提取率、收益率假设）。
• 技术（无构建）：Gin html/template 服务端渲染 + HTMX（局部刷新）+ Alpine.js（小交互）+ Tabler 后台模板（Bootstrap5，自带登录/侧边栏/仪表盘/表格/表单皮肤）+ Chart.js（图表）。全部走 <script>/<link> 引入，不需要 Node 工具链、不需要 build。
• 骨架：直接采用 Tabler 现成页面（登录、侧边栏布局、仪表盘卡片、表格表单），相当于 admin 端的 unibest。
• 托管：由同一个 Go 进程直接渲染并提供（路由如 /admin/*）；模板与静态资源用 //go:embed 打进二进制 → 部署仍是单文件。
• 数据：与用户端共用同一个 Go 后端与 SQLite（HTMX 路由返回 HTML 片段，不另起服务）。
• 鉴权：JWT/会话，单用户。
• 范围：单人自管，不做多用户/复杂权限。

为什么不用 Vue3+Element Plus：那需要独立 build 流水线和 admin/ 子项目。管理端本质是 CRUD+报表，用 HTMX 超媒体方案零构建、Go 一把托管，仓库更简单、部署仍单二进制。

四、同步策略（刻意从简）

单用户场景不追求复杂冲突合并：

1. 本地优先：所有操作先写本地、立即可用、离线可用。
2. 时间戳 + 后写覆盖：每条记录带 updatedAt，同步时以较新者为准。
3. 后端为历史数据权威源：本地仅作缓存，换设备从后端拉全量。

不使用 uniCloud（绑定 DCloud 云，非自托管），坚持自建 VPS 后端。

五、各端后端连通性注意

已有「域名 + certbot 正经 HTTPS」后，App / H5 的后端要求全部满足；小程序只剩"域名备案 + 配置合法域名白名单"一步。

端	对后端要求	当前状态（VPS + 域名 + certbot）
H5	需处理 CORS	✅ 同域部署或配置 CORS 即可
App	正经 HTTPS	✅ certbot 证书满足，不再有自签被拒问题
小程序	强制 HTTPS + 备案域名 + 合法域名白名单	⚠️ HTTPS 已满足；仅需域名 ICP 备案（腾讯云可办）+ 小程序后台配 request 合法域名

六、HTTPS 与安全（腾讯云 VPS）

• HTTPS：域名解析到 VPS → Nginx 占用 80/443 → certbot --nginx 签发证书 → 自动续期（certbot renew cron/timer）。
• 安全加固（后端已暴露公网，务必做）：
  • 仅开放必要端口（80/443/SSH），其余用腾讯云安全组 + 防火墙关闭；
  • 强 Token/密码鉴权，接口加速率限制，强制 HTTPS（HTTP 301 跳转）；
  • SSH 改密钥登录、装 fail2ban；
  • SQLite 定时备份；财务数据在公网，敏感字段可考虑加密存储。

七、部署形态

• 开发期：WSL 内 pnpm dev:h5 跑 unibest 前端实时预览；go run 起 Go 后端（同时托管管理后台 /admin，改模板刷新即见，无需 build）。
• 自用期：Go 后端二进制 Docker 跑在腾讯云 VPS（Nginx + certbot HTTPS），管理后台由 Go 进程自身托管；用户端 H5 静态文件由 Nginx 同域托管；手机装 PWA。
• App 期：HBuilderX 云打包出 Android/iOS。

八、WSL2 开发环境配置

在 WSL2 Ubuntu 中开发，Windows 浏览器中预览——这是本项目的标准开发模式。

原理

WSL2 会自动将内部端口转发到 Windows 的 localhost，所以 WSL2 里启动的 dev server，Windows 浏览器直接用 http://localhost:端口 访问，热更新也正常生效。

必须的 Vite 配置

Vite 默认只监听 127.0.0.1（WSL2 内部），需改为监听所有网卡，否则 Windows 浏览器无法访问。

在 app/vite.config.ts 中添加：

server: {
  host: '0.0.0.0',   // 允许 WSL2 外部（Windows）访问
  port: 5173,
},

或临时用命令行参数（不改配置时）：

pnpm dev:h5 --host

访问方式

场景	地址
Windows 浏览器调试	http://localhost:5173
手机扫码调试（同 WiFi）	http://<Windows局域网IP>:5173（ipconfig 查 WiFi 的 IPv4）

注意：手机调试时用的是 Windows 的局域网 IP，不是 WSL2 的内部 IP（172.x.x.x）。

开发流程示意

WSL2 Ubuntu
  ├─ pnpm dev:h5 --host   →  Vite 监听 0.0.0.0:5173
  └─ go run .             →  Go 后端监听 0.0.0.0:8080
                                      ↓ WSL2 自动转发
Windows
  ├─ Chrome localhost:5173   ✅ 前端热更新正常
  └─ 接口请求 localhost:8080  ✅ 后端 API 正常

九、代码仓库结构（建议）

fire_goal/
├─ app/        # unibest 用户端（uni-app，需 build 出 H5/App）
├─ server/     # Go 后端（Gin + GORM + SQLite）
│  ├─ templates/   # 管理后台 html/template（无构建）
│  └─ static/      # htmx/alpine/tabler/chart.js 等，//go:embed 进二进制
├─ deploy/     # Dockerfile / docker-compose / Nginx / certbot 脚本
└─ docs/       # 本文档目录

管理后台不再是独立子项目，已并入 server/（模板 + 静态资源），与后端同进程、同部署。