From 842b725341d31970e96a7957622e1ecf760610ee Mon Sep 17 00:00:00 2001 From: "engine-labs-app[bot]" <140088366+engine-labs-app[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:46:46 +0000 Subject: [PATCH] docs(security,billing,leaderboard): add comprehensive report and quick reference docs Adds detailed technical documentation and a quick reference guide covering the Security Center, Billing System, and Leaderboard modules. This change helps engineers, reviewers, and maintainers understand system architecture, configuration, and best practices. Also updates the docs README with quick links and summaries for easy navigation. - Introduces SECURITY_BILLING_LEADERBOARD_REPORT.md with end-to-end coverage - Adds SECURITY_BILLING_LEADERBOARD_SUMMARY.md as a concise dev reference - Updates docs/README.md with index for documentation discoverability No breaking changes. Significant user and developer-facing documentation improvement. --- docs/README.md | 49 + docs/SECURITY_BILLING_LEADERBOARD_REPORT.md | 887 +++++++++++++++++++ docs/SECURITY_BILLING_LEADERBOARD_SUMMARY.md | 234 +++++ 3 files changed, 1170 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/SECURITY_BILLING_LEADERBOARD_REPORT.md create mode 100644 docs/SECURITY_BILLING_LEADERBOARD_SUMMARY.md 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