系统架构

本文档面向开发者和运维人员，详细介绍 Lurus API 的系统架构设计。

整体架构

                           ┌──────────────────────────────────────┐
                           │            Internet                   │
                           └──────────────────────────────────────┘
                                            │
                                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                              Traefik Ingress                                   │
│                         (TLS 终止, 负载均衡, 路由)                             │
│                              api.lurus.cn:443                                  │
└───────────────────────────────────────────────────────────────────────────────┘
                                            │
                                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                           Lurus API Gateway                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  Auth       │  │   Router    │  │   Relay     │  │   Logger    │          │
│  │  认证鉴权   │  │   路由调度   │  │   请求转发   │  │   日志计费   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘          │
│                                                                                │
│  Go + Gin Framework | 运行于 K8s debian 节点 (VPN 出口)                        │
└───────────────────────────────────────────────────────────────────────────────┘
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
            ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
            │ PostgreSQL  │         │    NATS     │         │   MinIO     │
            │   数据库    │         │  消息队列   │         │  对象存储   │
            └─────────────┘         └─────────────┘         └─────────────┘
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
            ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
            │   OpenAI    │         │   Claude    │         │   Gemini    │
            └─────────────┘         └─────────────┘         └─────────────┘

核心组件

1. API Gateway (lurus-api)

主服务进程，负责处理所有 API 请求。

技术栈:

• 语言: Go 1.23
• 框架: Gin
• 数据库: PostgreSQL (GORM)
• 消息队列: NATS JetStream

核心模块:

模块	职责
router/	HTTP 路由定义
controller/	请求处理逻辑
relay/	上游请求转发
model/	数据模型和数据库操作
middleware/	认证、限流、日志中间件

2. 数据存储

PostgreSQL (CNPG)

• 用户、令牌、渠道配置
• 调用日志、用量统计
• 部署: K8s worker-db 节点
• 备份: 每日自动备份到 MinIO

主要数据表:

-- 用户表
users (id, username, password, role, status, quota, ...)

-- API 令牌
tokens (id, user_id, key, name, status, quota, models, ...)

-- 渠道配置
channels (id, name, type, key, base_url, models, priority, weight, ...)

-- 调用日志
logs (id, user_id, token_id, channel_id, model, tokens, quota, ...)

3. 消息队列 (NATS)

用于异步任务处理：

• 日志写入
• 配额更新
• 渠道状态检测
• 任务调度

4. 对象存储 (MinIO)

• PostgreSQL 备份存储
• 大文件存储（未来）
• 部署于本地 Windows 主机

K8s 集群架构

┌─────────────────────────────────────────────────────────────────┐
│                      K3s Cluster (v1.34.3)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ ubuntu2204      │  │ debian          │  │ worker-db       │ │
│  │ (master)        │  │ (messaging)     │  │ (database)      │ │
│  │                 │  │                 │  │                 │ │
│  │ • Traefik       │  │ • lurus-api     │  │ • PostgreSQL    │ │
│  │ • ArgoCD        │  │ • NATS          │  │                 │ │
│  │ • Prometheus    │  │ • CNPG Operator │  │                 │ │
│  │ • Grafana       │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│                                                                 │
│  节点标签:                                                       │
│  • lurus.cn/vpn=true (debian) - VPN 出口节点                    │
│  • lurus/role=database (worker-db) - 数据库专用                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

请求处理流程

1. 请求到达
   Client → Traefik (TLS) → lurus-api

2. 认证鉴权
   解析 Authorization Header → 查询 Token → 验证权限

3. 路由选择
   解析 model 参数 → 匹配可用渠道 → 负载均衡选择

4. 请求转发
   构造上游请求 → 发送到 OpenAI/Claude/... → 接收响应

5. 响应处理
   解析响应 → 统计 Token → 计费 → 记录日志 → 返回客户端

渠道路由算法

// 渠道选择逻辑 (简化)
func selectChannel(model string, group string) *Channel {
    // 1. 筛选支持该模型的渠道
    channels := filterByModel(model)
    
    // 2. 筛选状态正常的渠道
    channels = filterByStatus(channels, StatusEnabled)
    
    // 3. 按优先级排序
    sort.Slice(channels, func(i, j int) bool {
        return channels[i].Priority > channels[j].Priority
    })
    
    // 4. 同优先级按权重随机
    return weightedRandom(channels)
}

高可用设计

故障转移

渠道 A (priority=10, weight=80)  ─┐
                                  ├─→ 请求优先发往 A
渠道 B (priority=10, weight=20)  ─┘
                                       │
                                       ▼ (A 失败)
渠道 C (priority=5)              ─────→ 自动切换到 C

健康检查

• Liveness Probe: /api/status 每 15 秒检查
• Readiness Probe: /api/status 每 5 秒检查
• 渠道探测: 定时测试各渠道可用性

监控与可观测性

组件	用途	地址
Prometheus	指标采集	https://prometheus.lurus.cn
Grafana	可视化	https://grafana.lurus.cn
Loki	日志聚合	https://loki.lurus.cn
Jaeger	链路追踪	https://jaeger.lurus.cn

关键指标

# 请求量
lurus_api_requests_total{model, status}

# 请求延迟
lurus_api_request_duration_seconds{model}

# Token 用量
lurus_api_tokens_total{model, type}

# 渠道状态
lurus_api_channel_status{channel}

安全设计

1. 传输安全: 全站 HTTPS (Let's Encrypt)
2. 认证: API Key 机制，支持多 Key 管理
3. 授权: 基于角色的权限控制 (RBAC)
4. 日志审计: 完整请求日志，支持追溯
5. 网络隔离: K8s NetworkPolicy (规划中)

扩展性

• 水平扩展: 增加 lurus-api 副本数
• 渠道扩展: 动态添加上游供应商
• 存储扩展: PostgreSQL 读写分离 (规划中)