10 KiB
10 KiB
InsightReply 系统架构 (Architecture Overview)
本文档描述 InsightReply 的整体技术架构、各组件职责与数据流。
一、架构全景图
┌─────────────────────────────────────────────────────────────────┐
│ 用户浏览器 (Chrome / Edge) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ X (Twitter) 页面 │ │
│ │ ┌──────────────┐ ┌──────────────────────────────┐ │ │
│ │ │ Content │ │ InsightReply Sidebar │ │ │
│ │ │ Script │───▶│ (Shadow DOM 隔离) │ │ │
│ │ │ - DOM 感知 │ │ - 策略选择 │ │ │
│ │ │ - 按钮注入 │ │ - 评论展示 │ │ │
│ │ │ - 数据提取 │ │ - 一键复制 │ │ │
│ │ └──────────────┘ └──────────┬───────────────────┘ │ │
│ └───────────────────────────────────┼─────────────────────┘ │
│ │ chrome.runtime │
│ ┌───────────────────────────────────┼─────────────────────┐ │
│ │ Background Service Worker │ │
│ │ - 消息中转 │ │
│ │ - JWT Token 管理 │ │
│ │ - API 请求代理 │ │
│ └───────────────────────────────────┼─────────────────────┘ │
└──────────────────────────────────────┼──────────────────────────┘
│ HTTPS
▼
┌──────────────────────────────────────────────────────────────────┐
│ Nginx / Caddy (TLS 终结) │
└──────────────────────────────────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Go 后端服务 (Docker Container) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Handler │─▶│ Service │─▶│Repository│─▶│ PostgreSQL │ │
│ │ (HTTP) │ │ (BizLogic│ │ (GORM) │ │ (Tailscale) │ │
│ └──────────┘ └────┬─────┘ └──────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ LLM Gateway │──▶ OpenAI / Claude / DeepSeek │
│ │ (Timeout + │ │
│ │ Breaker + │ │
│ │ Retry) │ │
│ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Radar Scheduler (定时任务) │ │
│ │ - Asynq (Redis Queue) │ │
│ │ - Nitter Scraper │ │
│ │ - 热度计算引擎 │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
二、分层架构 (Clean Architecture)
cmd/server/main.go ← 入口：配置加载、依赖注入、路由注册
│
├── internal/handler/ ← 表现层：HTTP 请求解析 → 调用 Service → 返回 JSON
│ ├── ai_handler.go
│ ├── user_handler.go
│ └── common.go ← 统一 Response 工具函数
│
├── internal/service/ ← 业务层：核心逻辑（LLM 调用、热度计算、权限校验）
│ ├── ai_service.go
│ └── user_service.go
│
├── internal/repository/ ← 数据层：封装所有 SQL / GORM 操作
│ └── user_repository.go
│
├── internal/model/ ← 数据模型：Go struct 定义
│ └── user.go
│
├── config/ ← 配置读取（环境变量 → 结构体）
├── pkg/ ← 跨模块共享工具包
└── prompts/ ← Prompt 模板文件 (规划中)
调用链规则：Handler → Service → Repository，严禁跨层调用。
三、数据流
3.1 核心链路：用户生成评论
sequenceDiagram
participant U as 用户 (X 页面)
participant CS as Content Script
participant BG as Background SW
participant API as Go 后端
participant LLM as OpenAI
U->>CS: 点击 Insight 按钮
CS->>CS: 提取推文 DOM 数据
CS->>BG: chrome.runtime.sendMessage
BG->>API: POST /ai/generate (带 JWT)
API->>API: 验证 Token + Rate Limit
API->>LLM: ChatCompletion (含 Prompt)
LLM-->>API: 生成结果
API-->>BG: JSON 响应 (10 条候选)
BG-->>CS: sendResponse
CS->>U: Sidebar 展示评论
U->>U: 选择 → 一键复制 → 粘贴发布
3.2 雷达链路：后台监控推文 (规划中)
sequenceDiagram
participant SCH as Scheduler
participant Q as Asynq (Redis)
participant SC as Scraper Worker
participant NIT as Nitter 实例
participant DB as PostgreSQL
SCH->>Q: 定时投放抓取任务
Q->>SC: 消费任务
SC->>SC: Jitter 延迟 (1-5s)
SC->>NIT: HTTP GET (指纹轮换)
alt 正常响应
NIT-->>SC: HTML
SC->>SC: goquery 解析
SC->>DB: Batch UPSERT tweets
SC->>DB: 计算 heat_score
else 429/503
SC->>SC: 触发 Circuit Breaker
SC->>Q: 指数退避后重新入队
end
四、部署架构
Internet
│
┌────────┴────────┐
│ Nginx / Caddy │ ← TLS + 反代 → :8080
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
│ Oracle ARM VPS │
│ 144.24.60.0 │
│ │
│ ┌────────────────────────────┐ │
│ │ Docker │ │
│ │ ├── insight-reply-server │ │
│ │ └── (未来: redis) │ │
│ └────────────────────────────┘ │
│ │
└──────────────────┼──────────────────┘
│ Tailscale VPN
▼
┌────────────────┐
│ PostgreSQL │
│ 100.64.0.5 │
└────────────────┘
五、技术栈一览
| 层级 | 技术 | 版本 |
|---|---|---|
| 前端插件 | Vue 3 + Composition API | 3.5 |
| 样式 | Tailwind CSS | v4 |
| 打包 | Vite + CRXJS | 7.x |
| 后端 | Go (chi router) | 1.24 |
| ORM | GORM + pgx | 1.31 |
| 数据库 | PostgreSQL | 15+ |
| LLM | OpenAI (go-openai) | GPT-4o Mini |
| 任务队列 (规划) | Asynq (Redis) | - |
| 容器 | Docker + Docker Compose | 24.x |
| CI/CD | Gitea Actions | - |
| VPN | Tailscale | - |