feat: 部署初版测试
This commit is contained in:
zs
189
docs/ARCHITECTURE.md
Normal file
189
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 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 | - |
|
||||
Reference in New Issue
Block a user