diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..089595187c23 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ + +--- + +## 📋 Security, Billing & Leaderboard Documentation + +This directory contains comprehensive documentation for three core New-API modules: + +### Available Reports +1. **[SECURITY_BILLING_LEADERBOARD_REPORT.md](./SECURITY_BILLING_LEADERBOARD_REPORT.md)** - Full technical documentation (887 lines) + - Detailed security center architecture and features + - Complete billing system design and implementation + - Leaderboard functionality and integration points + - API endpoints, data models, and best practices + - Troubleshooting and extension guidelines + +2. **[SECURITY_BILLING_LEADERBOARD_SUMMARY.md](./SECURITY_BILLING_LEADERBOARD_SUMMARY.md)** - Quick reference guide (234 lines) + - Quick API lookup tables + - Core concepts and configuration + - Common troubleshooting + - Resource links + +### Key Topics + +#### 🔒 Security Center +- Violation detection and recording +- User ban management +- Model redirection configuration +- Automatic ban mechanism +- Dashboard statistics + +#### 💰 Billing System +- Token counting and quota management +- Top-up (recharge) functionality +- Payment gateway integration (EPay, Stripe) +- Subscription plans +- Voucher system +- New Billing Engine architecture + +#### 🏆 Leaderboard +- User statistics and rankings +- Multi-window time support +- Token IP usage tracking +- Performance optimization + +### Quick Links +- [Full Report](./SECURITY_BILLING_LEADERBOARD_REPORT.md) +- [Quick Reference](./SECURITY_BILLING_LEADERBOARD_SUMMARY.md) + +--- diff --git a/docs/SECURITY_BILLING_LEADERBOARD_REPORT.md b/docs/SECURITY_BILLING_LEADERBOARD_REPORT.md new file mode 100644 index 000000000000..8c144b7f48ff --- /dev/null +++ b/docs/SECURITY_BILLING_LEADERBOARD_REPORT.md @@ -0,0 +1,887 @@ +# 安全中心、计费功能和排行榜综合报告 + +## 一、安全中心介绍 + +### 1.1 概述 + +安全中心是 New-API 的核心安全管理模块，用于检测、记录和管理用户的违规行为。它集成了多层次的安全检测机制，包括内容检测、违规追踪、用户封禁管理等功能。 + +### 1.2 核心功能 + +#### 1.2.1 违规检测与记录 + +**功能说明**： +- 自动检测用户请求中的策略违规内容 +- 记录详细的违规信息：用户ID、Token ID、被触发的关键词、IP地址、请求ID等 +- 支持多模型违规追踪 +- 内容敏感数据自动脱敏处理 + +**关键组件**： +- **文件位置**：`service/security.go`、`model/security_violation.go` +- **核心函数**： + - `CheckContentViolation()`: 检查内容是否违规 + - `RecordViolation()`: 记录违规事件 + - `sanitizeContent()`: 脱敏处理 + +**敏感信息保护**： +- 电子邮件地址脱敏：`***@***.***` +- 电话号码脱敏：`***-***-****` +- 信用卡号脱敏：`****-****-****-****` +- 内容长度限制：最多保存500字符 + +#### 1.2.2 用户安全状态管理 + +**数据模型**（`model/user_security.go`）： +```go +type UserSecurity struct { + UserId int // 用户ID + IsBanned bool // 是否被封禁 + RedirectModel string // 重定向模型（违规时用） + ViolationCount int // 违规计数 + LastViolationAt *time.Time // 最后违规时间 + CreatedAt time.Time // 创建时间 + UpdatedAt time.Time // 更新时间 +} +``` + +**主要操作**： +- 追踪用户违规次数 +- 记录最后违规时间 +- 用户级别的模型重定向配置 +- 违规计数达到阈值时自动封禁 + +#### 1.2.3 仪表板统计 + +**统计指标**（时间段范围内）： +- **总违规数**：期间内的违规总计 +- **涉及用户数**：出现违规的独立用户数 +- **热门关键词**：触发最频繁的关键词TOP 10 +- **日趋势数据**：按日期聚合的违规数量变化 + +**API 端点**： +- `GET /api/admin/security/dashboard?start_time=&end_time=` + - 返回指定时间范围内的安全统计数据 + - 默认范围：最近7天 + +### 1.3 用户管理功能 + +#### 1.3.1 用户封禁与解封 + +**功能说明**： +- 管理员可对违规用户实施永久封禁 +- 被封禁的用户无法进行API请求 +- 支持解封操作恢复用户权限 + +**API 端点**： +- `POST /api/admin/security/users/{userId}/ban`：封禁用户 +- `POST /api/admin/security/users/{userId}/unban`：解封用户 + +#### 1.3.2 用户重定向配置 + +**功能说明**： +- 当用户触发违规时，可以将其请求自动重定向至安全的备用模型 +- 支持用户级别和全局级别的重定向策略 + +**API 端点**： +- `POST /api/admin/security/users/{userId}/redirect`：设置用户重定向模型 + ```json + { + "model": "gpt-3.5-turbo" + } + ``` +- `POST /api/admin/security/users/{userId}/redirect/clear`：清除用户重定向 + +**全局设置**： +- `GET /api/admin/security/settings`：获取全局安全设置 +- `PUT /api/admin/security/settings`：更新全局安全设置 + +### 1.4 自动封禁机制 + +**配置项**： +- `auto_ban_enabled`：是否启用自动封禁（默认：false） +- `auto_ban_threshold`：自动封禁的违规次数阈值（默认：10） + +**工作流程**： +1. 用户每次违规时，违规计数递增 +2. 系统检查是否达到阈值 +3. 达到阈值且启用自动封禁，则自动封禁用户 +4. 管理员可手动解除封禁 + +### 1.5 违规记录查询 + +**API 端点**： +- `GET /api/admin/security/violations`：分页查询违规记录 + - 参数：`page`, `page_size`, `user_id`, `start_time`, `end_time`, `keyword` + - 支持按用户、时间范围、关键词搜索 + +- `DELETE /api/admin/security/violations/{id}`：删除指定违规记录 + +### 1.6 缓存策略 + +**缓存机制**： +- 用户安全状态缓存在本地内存，TTL为5分钟 +- 支持Redis缓存同步，TTL为1小时 +- 违规记录每次更新时自动清除缓存 + +**缓存键格式**：`user_security:{userId}` + +### 1.7 与治理模块集成 + +**关键集成点**： +- 安全中心利用 `service/governance` 的关键词检测功能 +- 支持自定义违规关键词配置 +- 可扩展的违规检测规则体系 + +--- + +## 二、计费功能介绍 + +### 2.1 概述 + +计费功能是 New-API 的营收核心，提供灵活的多层级计费体系，包括Token计费、积分包充值、套餐订阅、支付网关集成等。 + +### 2.2 Token 计费机制 + +#### 2.2.1 基本概念 + +**Quota 系统**： +- **单位换算**：1 USD = 500,000 Quota +- **支持显示方式**：USD（美元）、CNY（人民币）、Tokens（Token数） + +#### 2.2.2 Token 统计 + +**文件位置**：`service/token_counter.go` + +**支持的模型**： +- OpenAI 系列（GPT-4, GPT-3.5 等） +- Claude 系列 +- Gemini 系列 +- Realtime 实时音频模型 +- 其他开源和第三方模型 + +**统计类型**： +- 文本Token：基于模型特定的分词器 +- 图片Token：支持tile-based（瓦片算法）和patch-based（补丁算法） +- 音频Token：基于采样率和格式 +- 视频Token：通过帧数和分辨率计算 + +#### 2.2.3 计费公式 + +``` +Total Quota = (InputTokens + OutputTokens × CompletionRatio + + AudioTokens × AudioRatio) × ModelRatio × GroupRatio +``` + +**参数说明**： +- **InputTokens**：输入Token数 +- **OutputTokens**：输出Token数 +- **CompletionRatio**：输出补全倍率（通常 > 1） +- **AudioRatio**：音频倍率 +- **ModelRatio**：模型基础倍率 +- **GroupRatio**：用户分组倍率 + +#### 2.2.4 扣费流程 + +**两段式扣费**（传统Quota模式）： + +``` +预扣费阶段 (PreConsumeQuota) + ├─ 检查用户余额充足性 + ├─ 检查Token配额限制 + ├─ 高额度用户信任优化跳过预扣 + └─ 扣除预估额度 + +请求执行 + └─ 调用AI模型API + +后扣费阶段 (Post*ConsumeQuota) + ├─ 统计实际Token消耗 + ├─ 计算实际消耗额度 + ├─ 补扣或退还差额 + ├─ 更新UsedQuota记录 + └─ 记录消费日志 +``` + +### 2.3 充值功能 + +#### 2.3.1 充值模型 + +**数据模型**（`model/topup.go`）： +```go +type TopUp struct { + Id int // 订单ID + UserId int // 用户ID + Amount int64 // 充值数量（美元） + Money float64 // 支付金额 + TradeNo string // 交易单号 + PaymentMethod string // 支付方式 + CreateTime int64 // 创建时间 + CompleteTime int64 // 完成时间 + Status string // 状态：pending/success/failed +} +``` + +#### 2.3.2 充值流程 + +``` +用户选择充值金额和支付方式 + ↓ +后端创建 TopUp 订单（初始状态：pending） + ↓ +计算应付金额（考虑倍率、折扣、分组倍率） + ↓ +调用支付网关生成支付链接 + ↓ +用户完成支付 + ↓ +支付网关异步回调 + ↓ +验证签名和订单状态 + ↓ +更新订单为 success + ↓ +增加用户 Quota（amount × QuotaPerUnit） + ↓ +记录操作日志 + ↓ +通知用户（可选） +``` + +#### 2.3.3 支付网关集成 + +**易支付（EPay）**： +- 支持支付宝、微信支付、QQ钱包等 +- 配置项： + - `operation_setting.PayAddress`：支付网关地址 + - `operation_setting.EpayId`：商户号 + - `operation_setting.EpayKey`：商户密钥 + +**Stripe 支付**： +- 国际支付解决方案 +- 配置项： + - `setting.StripeApiSecret`：API密钥 + - `setting.StripeWebhookSecret`：Webhook密钥 + - `setting.StripePriceId`：价格ID + - `setting.StripeMinTopUp`：最小充值金额 + +**并发安全**： +- 订单级互斥锁防止并发重复计费 +- 订单幂等性保证 + +#### 2.3.4 充值配置 + +**金额配置**： +- 预设金额选项（`AmountOptions`） +- 自定义金额输入 +- 分组折扣（`AmountDiscount`） +- 分组倍率（`TopupGroupRatio`） +- 最小充值限制（`MinTopUp`） + +**API 端点**： +- `GET /api/topup/info`：获取充值配置 +- `POST /api/topup/request/epay`：发起易支付 +- `POST /api/topup/request/amount`：计算支付金额 +- `GET /api/topup`：查询充值记录（分页、搜索） +- `POST /api/topup/admin/complete`：管理员补单 +- `POST /api/stripe/checkout`：创建Stripe Checkout +- `POST /api/stripe/webhook`：Stripe回调 + +### 2.4 套餐订阅系统 + +#### 2.4.1 套餐定义 + +**数据模型**（`model/plan.go`）： +```go +type Plan struct { + Code string // 套餐代码 + Name string // 套餐名称 + CycleType string // 周期类型：daily/monthly/custom + CycleDurationDays int // 自定义周期天数 + QuotaMetric string // 额度指标：requests/tokens + QuotaAmount int64 // 额度数量 + AllowCarryOver bool // 是否允许结转 + CarryLimitPercent int // 结转限制百分比 + UpstreamAliasWhitelist JSONValue // 上游白名单 + IsActive bool // 是否激活 + IsPublic bool // 是否公开 +} +``` + +**特性说明**： +- **周期类型**：日度、月度、自定义 +- **额度指标**：按请求数或Token数计算 +- **结转机制**：支持周期结束后未使用额度的结转 +- **上游白名单**：限制套餐可用的模型范围 + +#### 2.4.2 套餐分配 + +**数据模型**（`model/plan_assignment.go`）： +```go +type PlanAssignment struct { + SubjectType string // 主体类型：user/token + SubjectId int // 主体ID + PlanId int // 套餐ID + BillingMode string // 计费模式：plan/balance/fallback + ActivatedAt time.Time // 激活时间 + DeactivatedAt *time.Time // 停用时间 + RolloverAmount int64 // 结转额度 + RolloverExpiresAt *time.Time // 结转过期时间 + AutoFallbackEnabled bool // 自动回退到余额 + FallbackPlanId *int // 回退套餐ID +} +``` + +**计费模式**： +- `plan`：优先使用套餐额度 +- `balance`：优先使用账户余额 +- `fallback`：套餐不足时自动切换至余额 +- `auto`：自动决策 + +#### 2.4.3 使用量计数 + +**数据模型**（`model/usage_counter.go`）： +```go +type UsageCounter struct { + PlanAssignmentId int // 套餐分配ID + Metric string // 指标类型 + CycleStart time.Time // 周期开始 + CycleEnd time.Time // 周期结束 + ConsumedAmount int64 // 已消耗额度 +} +``` + +**工作机制**： +- 每个计费周期创建一条计数器 +- 实时更新消耗额度 +- 周期结束时触发结转或清零 + +#### 2.4.4 套餐管理 API + +**管理员接口**： +- `GET /api/admin/plans`：查询所有套餐 +- `POST /api/admin/plans`：创建套餐 +- `PUT /api/admin/plans/{id}`：更新套餐 +- `DELETE /api/admin/plans/{id}`：删除套餐 + +**用户接口**： +- `GET /api/user/plans`：查询订阅的套餐 +- `GET /api/user/plans/{id}/usage`：查询套餐使用情况 + +### 2.5 优惠券系统 + +#### 2.5.1 优惠券类型 + +**两种类型**： +1. **额度型**（credit）：直接增加用户Quota +2. **套餐型**（plan）：绑定套餐到用户 + +#### 2.5.2 限制机制 + +**生成时配置**： +- 每批次最大兑换次数（`max_redemptions`） +- 每用户最大兑换次数（`max_per_user`） +- 有效期限制（`expires_at`） + +**兑换防重**： +- 基于Code的唯一性约束 +- 单用户单优惠券只能兑换一次 + +#### 2.5.3 优惠券 API + +**生成接口**（管理员）： +- `POST /api/admin/vouchers/generate`：生成优惠券批次 + +**兑换接口**（用户）： +- `POST /api/user/voucher/redeem`：兑换优惠券 + +### 2.6 新版 Billing Engine + +#### 2.6.1 架构设计 + +**核心流程**（`service/billing_engine.go`）： + +``` +预授权 (PrepareCharge) + ├─ 解析主体（用户/Token） + ├─ 查询活跃套餐分配 + ├─ 确定计费模式 + ├─ 计算可用额度 + └─ 返回预授权结果 + +事务执行 (CommitCharge) + ├─ 创建 RequestLog（幂等性保障） + ├─ 根据模式扣费： + │ ├─ plan 模式：递增 UsageCounter + │ └─ balance 模式：扣减 User.Quota + ├─ 自动回退逻辑 + └─ 返回审计日志 +``` + +#### 2.6.2 特性优势 + +- **原子性**：数据库事务保证 +- **幂等性**：RequestLog 的 request_id 唯一约束 +- **并发安全**：行级锁（FOR UPDATE） +- **审计完整**：RequestLog 记录所有扣费细节 +- **灵活策略**：支持套餐结转、自动回退、白名单等 + +### 2.7 数据模型总览 + +| 表名 | 关键字段 | 说明 | +|-----|---------|------| +| `users` | `quota`, `used_quota` | 用户账户余额 | +| `tokens` | `remain_quota` | Token额度限制 | +| `topups` | `amount`, `money`, `status` | 充值订单 | +| `plans` | `quota_metric`, `quota_amount` | 套餐定义 | +| `plan_assignments` | `subject_type`, `billing_mode` | 套餐分配 | +| `usage_counters` | `consumed_amount` | 使用量计数 | +| `voucher_batches` | `grant_type`, `credit_amount` | 优惠券批次 | +| `request_logs` | `request_id`, `amount`, `mode` | 扣费审计日志 | + +--- + +## 三、排行榜介绍 + +### 3.1 概述 + +排行榜模块提供用户统计和排名功能，支持多个时间窗口的数据展示，帮助平台了解用户活跃度和消费情况。 + +### 3.2 核心功能 + +#### 3.2.1 用户排行榜 + +**功能说明**： +- 统计用户在指定时间窗口内的活跃度 +- 支持请求数、Token数、Quota消耗多维度排序 +- 可配置的排行榜大小限制 + +**排行指标**（`UserLeaderboardEntry`）： +```go +type UserLeaderboardEntry struct { + UserId int `json:"user_id"` // 用户ID + Username string `json:"username"` // 用户名 + RequestCount int64 `json:"request_count"` // 请求数 + TokenCount int64 `json:"token_count"` // 总Token数 + QuotaConsumed int64 `json:"quota_consumed"` // 消耗额度 + UniqueModels int64 `json:"unique_models"` // 使用的不同模型数 +} +``` + +**排行指标解释**： +- **RequestCount**：用户在时间段内的请求总数 +- **TokenCount**：所有请求的输入+输出Token总和 +- **QuotaConsumed**：消耗的总配额 +- **UniqueModels**：用户使用过的不同模型数量 + +#### 3.2.2 时间窗口支持 + +**支持的时间窗口**： +- `1h`：最近1小时 +- `24h`：最近24小时（默认） +- `7d`：最近7天 +- `30d`：最近30天 +- `all`：所有历史数据 + +**数据源**： +- 从 `logs` 表的消费记录中聚合 +- 支持数据库级别的多种时间格式（MySQL、PostgreSQL、SQLite） + +#### 3.2.3 用户统计 + +**API 端点**： +- `GET /api/user/stats?window=24h`：获取个人统计数据 + +**返回示例**： +```json +{ + "user_id": 123, + "username": "john_doe", + "request_count": 1500, + "token_count": 2850000, + "quota_consumed": 5700000, + "unique_models": 5 +} +``` + +**应用场景**： +- 用户个人中心：查看自己的使用统计 +- 用户自助分析：了解自己的API使用模式 + +#### 3.2.4 排行榜查询 + +**API 端点**： +- `GET /api/leaderboard/users?window=24h&limit=100`：获取用户排行榜 + +**查询参数**： +- `window`：时间窗口（默认：24h） +- `limit`：返回数量限制（默认：100，通常最大1000） + +**返回示例**： +```json +[ + { + "user_id": 1, + "username": "top_user", + "request_count": 5000, + "token_count": 10000000, + "quota_consumed": 20000000, + "unique_models": 8 + }, + { + "user_id": 2, + "username": "second_user", + "request_count": 4500, + "token_count": 9000000, + "quota_consumed": 18000000, + "unique_models": 6 + } + // ... 更多排行条目 +] +``` + +### 3.3 Token IP 统计 + +**功能说明**： +- 追踪Token在不同IP地址上的使用情况 +- 检测异常访问模式 +- 识别Token滥用风险 + +**API 端点**： +- `GET /api/leaderboard/token-ips?token_id={id}&window=24h`：查询Token的IP统计 + +**返回示例**： +```json +{ + "token_id": 456, + "token_name": "my-token", + "unique_ip_count": 5, + "total_requests": 1200, + "window": "24h", + "ip_list": [ + { + "ip": "192.168.1.1", + "requests": 600 + }, + { + "ip": "10.0.0.1", + "requests": 400 + } + // ... 更多IP信息 + ] +} +``` + +### 3.4 实现细节 + +#### 3.4.1 数据库查询 + +**查询逻辑**（`service/leaderboard.go`）： + +```go +func GetUserLeaderboard(window string, limit int) { + // 1. 解析时间窗口 + start, allTime, err := getWindowStart(window) + + // 2. 构建SQL查询 + query := db.Table("logs"). + Select(` + user_id, + username, + COUNT(*) as request_count, + SUM(prompt_tokens + completion_tokens) as token_count, + SUM(quota) as quota_consumed, + COUNT(DISTINCT model_name) as unique_models + `). + Where("type = ?", LogTypeConsume) + + // 3. 应用时间过滤 + if !allTime { + query = query.Where("created_at >= ?", start.Unix()) + } + + // 4. 分组和排序 + query = query.Group("user_id, username"). + Order("request_count DESC"). + Limit(limit) + + // 5. 执行查询 + return query.Scan(&entries) +} +``` + +#### 3.4.2 性能优化 + +**优化策略**： +- 直接在数据库层进行聚合计算 +- 利用索引加快查询速度 +- 支持缓存策略（可选） +- 分页机制减少单次查询数据量 + +#### 3.4.3 多数据库支持 + +**兼容性**： +- MySQL：原生支持 +- PostgreSQL：支持 +- SQLite：支持 + +### 3.5 应用场景 + +**平台运营**： +- 了解用户活跃度排名 +- 识别高价值用户 +- 发现异常消费模式 + +**用户体验**： +- 用户个人中心统计展示 +- 激励排行榜竞争（可选） +- 团队使用情况统计 + +**安全监控**： +- Token异常使用检测 +- 多IP访问识别 +- 滥用行为分析 + +**数据分析**： +- 模型使用热度分析 +- 用户行为分析 +- 成本趋势分析 + +--- + +## 四、核心代码位置索引 + +### 4.1 安全中心相关 + +| 功能 | 文件位置 | +|------|---------| +| 安全Service层 | `service/security.go` | +| 安全Controller | `controller/security.go` | +| 违规记录模型 | `model/security_violation.go` | +| 用户安全模型 | `model/user_security.go` | +| 治理检测 | `service/governance/` | +| 安全中间件 | `middleware/security.go` | + +### 4.2 计费相关 + +| 功能 | 文件位置 | +|------|---------| +| Token统计 | `service/token_counter.go` | +| 额度扣费 | `service/quota.go` | +| 预扣费 | `service/pre_consume_quota.go` | +| 新版计费引擎 | `service/billing_engine.go` | +| 计费网关 | `service/billing_gate.go` | +| 充值接口 | `controller/topup.go` | +| Stripe集成 | `controller/topup_stripe.go` | +| 优惠券 | `service/voucher.go` | +| 用户模型 | `model/user.go` | +| Token模型 | `model/token.go` | +| 充值模型 | `model/topup.go` | +| 套餐模型 | `model/plan.go` | +| 套餐分配 | `model/plan_assignment.go` | +| 使用计数 | `model/usage_counter.go` | +| 请求日志 | `model/request_log.go` | + +### 4.3 排行榜相关 + +| 功能 | 文件位置 | +|------|---------| +| 排行榜Service | `service/leaderboard.go` | +| 排行榜Controller | `controller/leaderboard.go` | + +### 4.4 前端实现 + +| 功能 | 目录位置 | +|------|---------| +| 充值页面 | `web/src/pages/TopUp/` | +| 充值组件 | `web/src/components/topup/` | +| 设置页面 | `web/src/pages/Setting/Payment/` | + +--- + +## 五、系统交互流程 + +### 5.1 完整请求生命周期 + +``` +┌─ 用户发送API请求 +│ +├─ 安全检查 (middleware/security.go) +│ ├─ 检查用户是否被封禁 +│ ├─ 检查是否需要重定向 +│ └─ 初步内容检查 +│ +├─ 计费预授权 (PreConsumeQuota/PrepareCharge) +│ ├─ 验证用户/Token配额 +│ ├─ 确定计费模式（套餐/余额） +│ └─ 预扣费用 +│ +├─ 请求转发 (relay/) +│ ├─ 调用上游AI模型 +│ └─ 获取响应 +│ +├─ Token统计 (token_counter.go) +│ ├─ 统计实际消耗Token +│ └─ 计算最终费用 +│ +├─ 违规检查 (CheckContentViolation) +│ ├─ 检测内容违规 +│ └─ 记录违规事件 (RecordViolation) +│ +├─ 计费提交 (CommitCharge) +│ ├─ 后扣费或补扣 +│ ├─ 更新用户余额 +│ └─ 记录到RequestLog +│ +└─ 返回响应 +``` + +### 5.2 违规处理流程 + +``` +┌─ 内容检测触发违规 +│ +├─ 记录违规事件 +│ ├─ 脱敏敏感内容 +│ ├─ 记录关键词、IP、模型等 +│ └─ 增加用户违规计数 +│ +├─ 检查自动封禁条件 +│ ├─ 是否启用自动封禁 +│ ├─ 是否达到阈值 +│ └─ 满足条件则自动封禁 +│ +├─ 决定处理方案 +│ ├─ 是否有用户级重定向模型 +│ ├─ 是否有全局重定向模型 +│ └─ 可选：拒绝请求或重定向 +│ +└─ 执行处理 +``` + +--- + +## 六、配置参考 + +### 6.1 安全配置 + +**环境变量**： +- `SECURITY_AUTO_BAN_ENABLED`：自动封禁开关 +- `SECURITY_AUTO_BAN_THRESHOLD`：自动封禁阈值（默认10次） + +**数据库选项**： +- `OptionAutobanEnabled` +- `OptionAutobanThreshold` +- `OptionViolationRedirectModel` + +### 6.2 计费配置 + +**金额显示**： +- `QUOTA_DISPLAY_MODE`：USD/CNY/Tokens +- `QUOTA_PER_UNIT`：1美元对应的Quota数（默认500000） + +**支付网关**： +- EPay配置：`operation_setting.EpayId`, `operation_setting.EpayKey` +- Stripe配置：`setting.StripeApiSecret`, `setting.StripeWebhookSecret` + +**模型倍率**： +- 基础倍率：`setting.ModelRatio` +- 输出补全倍率：`setting.CompletionRatio` +- 分组倍率：`setting.GroupRatio` + +### 6.3 排行榜配置 + +**查询限制**： +- 默认时间窗口：24h +- 默认排行榜大小：100 +- 最大排行榜大小：1000（可配置） + +--- + +## 七、最佳实践 + +### 7.1 安全中心最佳实践 + +1. **定期审查**：定期查看违规记录和趋势分析 +2. **阈值调整**：根据平台实际情况调整自动封禁阈值 +3. **关键词管理**：及时更新敏感关键词列表 +4. **数据保护**：正确配置内容脱敏规则 +5. **日志保留**：妥善保留审计日志用于事后分析 + +### 7.2 计费系统最佳实践 + +1. **金额验证**：充值前验证金额计算 +2. **并发处理**：利用互斥锁防止重复扣费 +3. **审计追踪**：所有计费操作都要记录到RequestLog +4. **定期对账**：定期对比用户余额与日志总和 +5. **告警机制**：建立异常消费告警机制 + +### 7.3 排行榜最佳实践 + +1. **查询优化**：使用时间窗口和limit减少数据量 +2. **缓存策略**：对热门排行榜结果进行缓存 +3. **隐私保护**：在必要时隐藏敏感用户信息 +4. **数据验证**：定期验证排行榜数据的准确性 + +--- + +## 八、故障排查 + +### 8.1 安全中心常见问题 + +**问题**：用户被错误封禁 +- **原因**：违规计数异常或自动封禁阈值设置过低 +- **解决**：检查违规记录，手动解除封禁 + +**问题**：重定向模型不生效 +- **原因**：模型不存在或权限不足 +- **解决**：验证模型是否存在，检查用户权限配置 + +### 8.2 计费系统常见问题 + +**问题**：充值失败 +- **原因**：网关配置错误、签名验证失败、订单冲突 +- **解决**：检查支付网关配置，查看订单状态 + +**问题**：余额计算不准 +- **原因**：并发扣费冲突、Token统计错误 +- **解决**：查看RequestLog，手动对账 + +### 8.3 排行榜常见问题 + +**问题**：排行榜数据不更新 +- **原因**：日志表数据不完整、查询条件错误 +- **解决**：检查日志表数据，验证查询逻辑 + +**问题**：排行榜查询缓慢 +- **原因**：数据量过大，缺少索引 +- **解决**：添加索引，使用时间过滤 + +--- + +## 九、扩展方向 + +### 9.1 安全中心可扩展性 + +- 集成更多的内容检测模型（ML模型） +- 支持自定义违规处理规则 +- 增加地理位置识别 +- 实现威胁情报集成 + +### 9.2 计费系统可扩展性 + +- 支持更多支付网关（PayPal、支付宝、微信等） +- 灵活的订阅计费模式 +- 支持企业发票和批量计费 +- 增强的财务报表和分析 + +### 9.3 排行榜可扩展性 + +- 支持自定义排行榜指标 +- 团队/组织级别的排行榜 +- 时间段对比分析 +- 排行榜数据导出功能 + +--- + +**报告生成时间**：2024年11月 +**文档版本**：1.0 diff --git a/docs/SECURITY_BILLING_LEADERBOARD_SUMMARY.md b/docs/SECURITY_BILLING_LEADERBOARD_SUMMARY.md new file mode 100644 index 000000000000..d8efdd9970e9 --- /dev/null +++ b/docs/SECURITY_BILLING_LEADERBOARD_SUMMARY.md @@ -0,0 +1,234 @@ +# 安全中心、计费功能和排行榜 - 快速参考指南 + +## 📋 文档导航 + +本目录包含关于New-API三大核心功能的详细文档： + +### [完整报告](./SECURITY_BILLING_LEADERBOARD_REPORT.md) +包含安全中心、计费功能和排行榜的详细介绍、API文档、实现细节和最佳实践。 + +--- + +## 🔒 安全中心 - 快速查询 + +### 关键功能 +| 功能 | 描述 | API端点 | +|------|------|--------| +| 获取仪表板 | 获取安全统计数据 | `GET /api/admin/security/dashboard` | +| 查询违规 | 分页查询违规记录 | `GET /api/admin/security/violations` | +| 查询用户 | 获取有违规的用户列表 | `GET /api/admin/security/users` | +| 封禁用户 | 封禁用户账户 | `POST /api/admin/security/users/{id}/ban` | +| 解除封禁 | 解除用户封禁 | `POST /api/admin/security/users/{id}/unban` | +| 设置重定向 | 设置用户模型重定向 | `POST /api/admin/security/users/{id}/redirect` | +| 获取设置 | 获取安全配置 | `GET /api/admin/security/settings` | +| 更新设置 | 更新安全配置 | `PUT /api/admin/security/settings` | + +### 核心文件 +- `service/security.go` - 业务逻辑 +- `controller/security.go` - HTTP接口 +- `model/security_violation.go` - 违规记录数据模型 +- `model/user_security.go` - 用户安全状态 + +### 关键指标 +- **ViolationCount**: 用户违规次数 +- **IsBanned**: 是否被封禁 +- **RedirectModel**: 重定向目标模型 +- **LastViolationAt**: 最后违规时间 + +--- + +## 💰 计费功能 - 快速查询 + +### 关键概念 +| 概念 | 说明 | 单位 | +|------|------|------| +| Quota | 账户余额 | 1 USD = 500,000 Quota | +| Token | 模型输入输出字符单位 | 根据模型计算 | +| Plan | 套餐订阅 | 周期性配额 | +| TopUp | 充值订单 | USD/本地货币 | + +### 计费流程 +``` +1. 预扣费 (PreConsumeQuota) + ├─ 检查余额 + └─ 冻结预估金额 + +2. 请求执行 + └─ 调用AI模型 + +3. 后扣费 (Post*ConsumeQuota) + ├─ 统计实际消耗 + └─ 补扣或退款 +``` + +### 主要API +| 功能 | API端点 | 方法 | +|------|--------|------| +| 获取充值配置 | `/api/topup/info` | GET | +| 创建充值订单 | `/api/topup/request/epay` | POST | +| 计算金额 | `/api/topup/request/amount` | POST | +| 查询充值记录 | `/api/topup` | GET | +| 管理员补单 | `/api/topup/admin/complete` | POST | +| Stripe支付 | `/api/stripe/checkout` | POST | +| 兑换优惠券 | `/api/voucher/redeem` | POST | + +### 核心文件 +- `service/token_counter.go` - Token统计 +- `service/quota.go` - 额度扣费 +- `service/billing_engine.go` - 新版计费引擎 +- `controller/topup.go` - 充值接口 +- `model/topup.go` - 充值订单模型 +- `model/plan.go` - 套餐定义 +- `model/plan_assignment.go` - 套餐分配 + +### 支付网关 +- **易支付（EPay）**: 支付宝、微信、QQ钱包等 +- **Stripe**: 国际信用卡支付 + +--- + +## 🏆 排行榜 - 快速查询 + +### 时间窗口 +| 窗口 | 范围 | +|------|------| +| `1h` | 最近1小时 | +| `24h` | 最近24小时（默认） | +| `7d` | 最近7天 | +| `30d` | 最近30天 | +| `all` | 所有历史 | + +### 排行指标 +| 指标 | 说明 | +|------|------| +| RequestCount | 请求数 | +| TokenCount | Token总数 | +| QuotaConsumed | 消耗配额 | +| UniqueModels | 使用的不同模型数 | + +### 主要API +| 功能 | API端点 | 方法 | +|------|--------|------| +| 获取排行榜 | `/api/leaderboard/users?window=24h&limit=100` | GET | +| 获取个人统计 | `/api/user/stats?window=24h` | GET | +| Token IP统计 | `/api/leaderboard/token-ips?token_id={id}` | GET | + +### 核心文件 +- `service/leaderboard.go` - 排行榜逻辑 +- `controller/leaderboard.go` - HTTP接口 + +--- + +## 🔄 系统集成点 + +### 请求处理流程 +``` +用户请求 + ↓ +安全检查 (middleware/security.go) + ├─ 检查封禁 + └─ 检查重定向 + ↓ +计费预授权 + ├─ 检查配额 + └─ 预扣费 + ↓ +请求转发 (relay/) + ↓ +Token统计 + ↓ +违规检查 + ├─ 检测违规 + └─ 记录日志 + ↓ +计费提交 + ├─ 后扣费 + └─ 更新余额 + ↓ +返回响应 +``` + +--- + +## ⚙️ 配置速查 + +### 安全配置 +``` +SECURITY_AUTO_BAN_ENABLED=true # 自动封禁开关 +SECURITY_AUTO_BAN_THRESHOLD=10 # 封禁阈值（违规次数） +``` + +### 计费配置 +``` +QUOTA_DISPLAY_MODE=USD # USD/CNY/Tokens +QUOTA_PER_UNIT=500000 # 1USD = 500,000 Quota +``` + +### 支付网关 - 易支付 +``` +OPERATION_SETTING_EPAY_ID=xxx # 商户号 +OPERATION_SETTING_EPAY_KEY=xxx # 商户密钥 +OPERATION_SETTING_PAY_ADDRESS=xxx # 网关地址 +``` + +### 支付网关 - Stripe +``` +SETTING_STRIPE_API_SECRET=sk_xxx # API密钥 +SETTING_STRIPE_WEBHOOK_SECRET=wh_xxx # Webhook密钥 +SETTING_STRIPE_PRICE_ID=price_xxx # 价格ID +``` + +--- + +## 🐛 常见问题快速解决 + +### 安全中心 +- **用户被误封禁**: 使用解除封禁API恢复 +- **重定向模型不生效**: 检查模型是否存在 +- **违规记录堆积**: 定期清理历史记录 + +### 计费系统 +- **充值失败**: 检查支付网关配置和签名 +- **余额计算错误**: 查看RequestLog进行人工对账 +- **配额不足**: 提示用户充值 + +### 排行榜 +- **数据不更新**: 检查日志表是否有新数据 +- **查询缓慢**: 添加索引，缩小时间范围 +- **数据差异**: 验证日志表的数据完整性 + +--- + +## 📚 资源链接 + +### 源代码 +- **安全中心**: `service/security.go`, `controller/security.go` +- **计费系统**: `service/billing_engine.go`, `controller/topup.go` +- **排行榜**: `service/leaderboard.go`, `controller/leaderboard.go` + +### 数据模型 +- `model/security_violation.go` - 违规记录 +- `model/user_security.go` - 用户安全状态 +- `model/topup.go` - 充值订单 +- `model/plan.go` - 套餐 +- `model/usage_counter.go` - 使用计数 + +### 前端 +- `web/src/pages/TopUp/` - 充值页面 +- `web/src/pages/Setting/Payment/` - 支付设置 + +--- + +## 📞 技术支持 + +遇到问题？请参考： +1. [完整报告](./SECURITY_BILLING_LEADERBOARD_REPORT.md) - 详细文档 +2. 源代码中的注释 +3. 测试文件（如存在） +4. Git日志和提交信息 + +--- + +**最后更新**: 2024年11月 +**维护者**: Development Team +**版本**: 1.0