架构概览

系统架构

Sentinel 是一个基于 AI 的代码审查平台，采用现代化的全栈架构设计。

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                         用户层                               │
│  Web Browser ──► Next.js Frontend (React 19 + Kumo UI)     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS / REST API
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      应用服务层                              │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Rust Backend (Axum Framework)                │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │  │
│  │  │   Auth      │  │  Projects   │  │  Analysis   │ │  │
│  │  │  Module     │  │   Module    │  │   Module    │ │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘ │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │  │
│  │  │Repositories │  │Integrations │  │     SSE     │ │  │
│  │  │   Module    │  │   Module    │  │   Module    │ │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ SQL / Protocol Buffer
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据存储层                              │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ PostgreSQL   │  │ TimescaleDB  │  │ Object Store │     │
│  │  (主数据库)  │  │  (时序数据)  │  │   (S3/R2)    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │
┌─────────────────────────────────────────────────────────────┐
│                      外部服务层                              │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  GitHub API  │  │ Claude API   │  │  Cloudflare  │     │
│  │   (OAuth)    │  │  (AI Model)  │  │  (Turnstile) │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

技术栈

后端技术栈

技术	版本	用途
Rust	1.83+	主要编程语言
Axum	0.8+	Web 框架
SQLx	0.8+	数据库驱动
PostgreSQL	16+	主数据库
TimescaleDB	2.17+	时序数据
Tokio	1.42+	异步运行时
Tower	0.5+	中间件

前端技术栈

技术	版本	用途
Next.js	16.2+	React 框架
React	19.2+	UI 库
TypeScript	6.0+	类型系统
Kumo UI	2.5+	组件库
TanStack Query	5.62+	数据获取
Zustand	5.0+	状态管理
Tailwind CSS	4.3+	样式框架

架构分层

后端分层架构

┌─────────────────────────────────────────┐
│           Routes Layer                  │  HTTP 路由定义
│  (routes.rs in each module)             │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│          Handler Layer                  │  请求处理和验证
│  (handlers with CurrentUser extractor)  │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Repository Layer                │  数据访问逻辑
│  (repository.rs with SQLx)              │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│          Database Layer                 │  PostgreSQL + TimescaleDB
└─────────────────────────────────────────┘

分层职责：

• Routes Layer: 定义 HTTP 端点和路由映射
• Handler Layer: 处理请求、参数验证、业务逻辑编排、错误处理
• Repository Layer: 数据访问抽象、SQL 查询、事务管理
• Database Layer: 持久化存储

前端分层架构

┌─────────────────────────────────────────┐
│            App Layer                    │  Next.js App Router
│  (pages, layouts, route groups)         │  页面和路由
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│            Core Layer                   │  
│  ┌──────────┐  ┌──────────┐            │
│  │   API    │  │  Hooks   │            │  业务逻辑核心
│  └──────────┘  └──────────┘            │
│  ┌──────────┐  ┌──────────┐            │
│  │  Stores  │  │  Types   │            │
│  └──────────┘  └──────────┘            │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           Shared Layer                  │
│  (UI components, layouts, utils)        │  共享组件和工具
└─────────────────────────────────────────┘

分层职责：

• App Layer: 页面路由、布局组合、SEO 优化
• Core Layer: API 客户端、React Query Hooks、状态管理、类型定义
• Shared Layer: UI 组件库、布局组件、工具函数

设计原则

1. 模块化设计

每个功能模块独立组织，包含：

• routes.rs - 路由定义
• repository.rs - 数据访问
• mod.rs - 模块导出

2. 类型安全

• 后端: Rust 强类型系统，编译时类型检查
• 前端: TypeScript 完整类型定义，无 any 类型

3. 错误处理

• 后端: Result 类型 + 自定义 AppError
• 前端: React Query 错误边界 + Toast 通知

4. 异步优先

• 后端: Tokio 异步运行时
• 前端: React Query 异步数据获取

5. 实时通信

• Server-Sent Events (SSE) 用于分析状态实时更新
• WebSocket 预留用于未来扩展

核心模块

模块	职责	技术要点
auth	用户认证授权	JWT Token、GitHub OAuth、Argon2 密码哈希
projects	项目管理	CRUD 操作、Slug 唯一性
repositories	仓库管理	GitHub 仓库导入、设置管理
analysis	分析引擎	任务调度、Agent 执行、结果收集
integrations	第三方集成	GitHub App、API 同步
sse	实时通信	事件流、连接管理
webhooks	Webhook 处理	GitHub 事件接收、签名验证

数据流

典型请求流程

1. 用户操作
   ↓
2. 前端发起 API 请求 (Axios)
   ↓
3. 后端路由匹配
   ↓
4. 认证中间件验证 Token
   ↓
5. Handler 处理请求
   ↓
6. Repository 访问数据库
   ↓
7. 返回 JSON 响应
   ↓
8. React Query 缓存更新
   ↓
9. UI 自动重新渲染

实时更新流程

1. 分析任务创建
   ↓
2. Agent 开始执行
   ↓
3. SSE 连接建立
   ↓
4. 状态变更事件推送
   ↓
5. 前端接收事件
   ↓
6. React Query 失效缓存
   ↓
7. 自动重新获取数据
   ↓
8. UI 实时更新

安全设计

认证安全

• JWT Token 有效期 24 小时
• Argon2id 密码哈希
• GitHub OAuth 2.0

API 安全

• CORS 严格配置
• Bearer Token 认证
• 请求频率限制（计划中）

数据安全

• 密码重置 Token 10 分钟有效期
• OAuth State 防 CSRF
• 用户数据隔离

性能优化

后端优化

• 数据库连接池 (SQLx)
• 索引优化
• 异步 I/O

前端优化

• React Query 缓存策略
• 代码分割 (Next.js)
• 图片优化 (next/image)

可扩展性

水平扩展

• 无状态 API 设计
• 数据库读写分离（计划中）
• 负载均衡支持

垂直扩展

• Agent 多线程执行
• 数据库分区（TimescaleDB）

监控与日志

日志系统

• tracing 结构化日志
• 不同级别日志输出
• 错误追踪

监控指标

• HTTP 请求统计
• 数据库查询性能
• Agent 执行时间

下一步阅读

• 后端架构详解
• 前端架构详解
• 模块划分说明
• 数据库设计