190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# 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 核心链路：用户生成评论
|
||
|
||
```mermaid
|
||
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 雷达链路：后台监控推文 *(规划中)*
|
||
|
||
```mermaid
|
||
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 | - |
|