系统总体架构
架构哲学
前后端分离 + GraphRAG 中台 + 多模态供应商池 —— 三层架构、单机部署、零外部依赖。
整体架构图
整体分为三层：
- 前端层：React 19 + Vite 6 + PWA，6 个核心页面
- 服务层：Go net/http 中台，6 个核心模块（含 GraphRAG 引擎）
- 基础设施层：SQLite + 知识图谱存储 + 多模态供应商池
三层架构详解
Layer 1: 浏览器层
| 模块 | 技术 | 职责 |
|---|---|---|
| UI 框架 | React 19 + Tailwind | 组件渲染、样式 |
| 构建工具 | Vite 6 | HMR + 生产构建 |
| 路由 | React Router | SPA 路由 |
| 状态管理 | React State + localStorage | 简单可控 |
| 持久化 | IndexedDB | 大文件 + 长会话 |
| PWA | vite-plugin-pwa | 离线缓存 |
浏览器层亮点
- 图片直连：浏览器直接调用 Gemini / OpenAI 图片接口，节省服务端带宽
- PWA 离线：Service Worker 注册，Lighthouse PWA 90 分
- 海量历史：IndexedDB 承载 GB 级图片，千张级历史秒级加载
Layer 2: Go 后端中台
| 模块 | 实现 | 职责 |
|---|---|---|
| HTTP Server | net/http 标准库 | 路由分发 |
| 认证 | HttpOnly Cookie + Session | 登录态 |
| 鉴权 | RBAC 中间件 | 角色权限 |
| 配额 | 行级事务 + reaper goroutine | 三类配额扣减 + 失败回滚 |
| GraphRAG | 实体抽取 + 子图召回 | 核心创新模块 |
| 模型路由 | priority + weight 加权随机 | 多供应商调度 |
| 日志 | request_logs 表 | 审计链 |
后端架构亮点
- 零外部依赖：纯 Go 实现，仅依赖 SQLite 单文件
- 单二进制：交叉编译后 ≤ 30MB，可放 U 盘演示
- 启动迁移：自动执行
migrations/*.sql，零运维
Layer 3: 数据 + 供应商层
| 子层 | 实现 | 职责 |
|---|---|---|
| 关系型数据 | SQLite (modernc.org/sqlite) | 用户、会话、配额、日志 |
| 知识图谱 | 复用 SQLite + 1024 维向量 | GraphRAG 实体 + 关系 |
| 多模态供应商 | HTTP 客户端 + 路由 | Gemini / OpenAI / Veo |
数据流向
流向 1：图片生成（直连模式）
两段式协议：
text
浏览器 ──[1] POST /api/generate/image/prepare──→ Go 后端
↑ │
│ ▼
│ ┌──────────┐
│ │ 配额预扣 │
│ │ 写 pending│
│ └────┬─────┘
│ │
[2] 返回供应商配置 │
←────────────────────────────────── │
│ │
│ │
▼ │
Gemini / OpenAI │
│ │
│ [3] 直连调用图片接口 │
↓ │
生成图片（Blob） │
│ │
├──[4] POST /api/generate/image/complete──→ Go 后端
│ ↓
│ ┌──────────┐
│ │ 扣次/回滚 │
│ │ 改日志 │
│ └──────────┘流向 2：文案 / 视频（代理模式）
text
浏览器 ──[1] POST /api/generate/copy──→ Go 后端
↑ │
│ ▼
│ ┌──────────────┐
│ │ GraphRAG 注入│
│ │ Prompt 模板 │
│ └──────┬───────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ 调用 GPT 5.5 │
│ └──────┬───────┘
│ │
│ [2] 流式返回 token │
←───────────────────────────────┘
│
├──[3] 完成后扣次（无需 complete 接口）
↓
前端展示为什么图片直连，文案代理？
| 方面 | 图片 | 文案 |
|---|---|---|
| 数据大小 | MB 级（Blob） | KB 级（文本） |
| 服务端转发成本 | 高（占带宽） | 低 |
| 上下文管理 | 无状态 | 多轮对话 |
| GraphRAG 注入 | 提示词层 | System Prompt 层 |
| 配额扣减 | 预扣 + 回滚 | 同步扣减 |
→ 图片直连节省带宽，文案代理便于流式输出与上下文管理。
流向 3：GraphRAG 知识图谱
text
用户输入商品 ──→ Go 后端
│
▼
┌──────────────────┐
│ 实体抽取 LLM │
│ (Gemini 3 Pro) │
└──────┬───────────┘
│
▼
┌──────────────────┐
│ 关系建模 │
│ + 1024 维向量 │
└──────┬───────────┘
│
▼
┌──────────────────┐
│ kg_entities │
│ kg_relations │ ← SQLite
└──────┬───────────┘
│
│ 后续生成任务
▼
┌──────────────────┐
│ 子图召回 │
│ + Prompt 注入 │
└──────────────────┘端口与协议
| 服务 | 端口 | 协议 |
|---|---|---|
| 前端 Dev | :3000 | HTTP（Vite） |
| 后端 API | :8788 | HTTP / HTTPS |
| 前端代理 | /api/* → :8788 | Vite 代理 |
| 生产部署 | 单端口 :8788 | Go 后端托管前端静态文件 |
关键设计决策
1. 为什么 Go + SQLite？
决策理由
| 候选 | 优势 | 劣势 | 决策 |
|---|---|---|---|
| Node.js + Postgres | 生态丰富 | 依赖多、部署重 | ❌ |
| Python + Redis | AI 生态完整 | GIL 性能瓶颈 | ❌ |
| Java + MySQL | 企业级 | JVM 启动慢、内存大 | ❌ |
| Go + SQLite | 单二进制 + 单文件 | 生态相对小 | ✅ |
比赛展示场景核心需求是"git clone + 一行命令启动"，Go + SQLite 完美契合。
2. 为什么图片直连？
- 节省带宽：图片大文件不经过我们的服务器（节省 60% 带宽成本）
- 降低延迟：浏览器直接到 CDN 边缘节点
- 可靠性：失败时通过 prepare/complete 两段式协议保证配额一致性
3. 为什么 PWA + IndexedDB？
- 离线访问：地铁、咖啡馆等弱网环境也可查看历史
- 海量存储：IndexedDB GB 级容量，远超 localStorage 5MB
- 性能：异步 API 不阻塞 UI
部署形态
双模式启动：
text
开发环境（双端口）
npm run dev
├── Vite (:3000) ──/api 代理──→ Go (:8788)
└── Hot Reload + Source Map
生产环境（单端口）
npm run build && npm run start
└── Go (:8788)
├── 托管 frontend/dist 静态文件
└── 处理 /api/* 接口性能指标
| 指标 | 数值 | 说明 |
|---|---|---|
/api/me P95 延迟 | 38 ms | Go 单进程，无 ORM |
| 100 并发 Apache Bench | 全部 < 100ms | 单 SQLite 写读 |
| Listing 生成耗时 | 平均 8.4s | GPT-5.5 网络抖动 |
| 主图生成耗时 | 平均 14s | Gemini 3 Pro Image |
| GraphRAG 子图召回 | < 60ms | 1 万节点规模 |
| 前端 gzip 大小 | 612 KB | Vite 6 优化 |
| Lighthouse PWA | 90 分 | 已注册 SW |