# KOGUN 算力共享平台 v7.2.0 技术说明书
> 版本：7.2.0 | 日期：2026-05-26 | 技术栈：FastAPI + PostgreSQL 16 + SQLAlchemy 2.0 + WebSocket
---
## 一、平台概述
**KOGUN**（算力共享平台）是一个分布式 GPU/CPU 算力调度与共享平台，将全球闲置算力汇聚为统一的 AI 推理服务。设备贡献者通过共享 GPU 获得收益，企业/开发者通过 OpenAI 兼容 API 消费算力。
### 核心价值
| 角色 | 价值 |
|------|------|
| **算力贡献者** | 闲置 GPU 变现，阶梯收益 + 高峰溢价，最高时薪 ¥3.5/h |
| **AI 开发者** | OpenAI 兼容 API 一键接入，按 Token 用量计费，无需采购硬件 |
| **企业管理者** | 企业控制台 + 账单 + 用量统计，统一管理团队 API Key |
| **平台运营者** | 20% 抽成 + 实时监控 + 多维调度，自动化运营 |
### 技术指标
| 指标 | 数值 |
|------|------|
| 代码行数 | 9,216 行（后端 5,101 + 前端 4,115） |
| API 端点 | 89 个 |
| 数据库表 | 13 张 |
| 模块数 | 7 个独立 Python 模块 |
| 并发模型 | async/await + asyncio 协程 |
| 连接池 | PostgreSQL 20 连接 + 10 溢出 |
---
## 二、系统架构
```
┌──────────────────────────────────┐
│ 客户端 / 设备端 │
│ 浏览器 (SPA) | CLI | SDK | App │
└──────────┬───────────────────────┘
│ HTTP / WebSocket
┌──────────▼───────────────────────┐
│ FastAPI (v7.2.0) │
│ ┌──────────────────────────────┐ │
│ │ CORS | 限流 (slowapi) | JWT │ │
│ └──────────────────────────────┘ │
│ ┌───────┐ ┌────────┐ ┌────────┐ │
│ │pricing│ │proxy.py│ │ws_mgr │ │
│ └───────┘ └────────┘ └────────┘ │
│ ┌──────────────────────────────┐ │
│ │ scheduler.py (3协程) │ │
│ │ HeartbeatMonitor (30s) │ │
│ │ TaskScheduler (10s) │ │
│ │ SimDataGenerator (5s) │ │
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ database.py (ORM层) │ │
│ │ SQLAlchemy 2.0 + asyncpg │ │
│ └──────────────────────────────┘ │
└──────────┬───────────────────────┘
│ asyncpg
┌──────────▼───────────────────────┐
│ PostgreSQL 16 │
│ 13 tables | 7 indexes | 触发器 │
└──────────────────────────────────┘
```
### 模块职责
| 模块 | 文件 | 行数 | 职责 |
|------|------|------|------|
| **API 路由** | `main.py` | 2,897 | 认证、设备管理、任务调度、OpenAI API、监控 |
| **ORM 层** | `database.py` | 1,193 | 13 个模型、52 个 CRUD 方法、datetime 类型转换 |
| **定价引擎** | `pricing.py` | 74 | GPU 定价、高峰溢价、阶梯收益、收益计算 |
| **调度器** | `scheduler.py` | 275 | 心跳监控、任务调度、模拟数据生成（3 独立协程） |
| **推理代理** | `proxy.py` | 177 | 上游 API 代理（流式/非流式）、模型映射、降级 |
| **WS 管理器** | `ws_manager.py` | 46 | WebSocket 连接管理、JSON 广播 |
| **数据迁移** | `migrate.py` | 439 | JSON → PostgreSQL 一次性迁移 + 校验 |
---
## 三、数据库设计
### 3.1 表结构
| 表名 | 说明 | 关键字段 |
|------|------|---------|
| `users` | 用户账户 | id, username, role(admin/user), credit_balance |
| `nodes` | 算力节点 | id, user_id, gpu_name, status, is_simulated |
| `tasks` | 计算任务 | id, user_id, status, claimed_by, assigned_node |
| `transactions` | 交易流水 | id, user_id, type(earning/consumption/withdraw) |
| `api_keys` | API 密钥 | id, key(sk-kogun-*), status, call_count |
| `enterprises` | 企业客户 | id, user_id, license, status(pending/approved) |
| `notifications` | 通知消息 | id, user_id, type, is_read |
| `settings` | 系统配置 | key, value (TEXT) |
| `withdrawals` | 提现申请 | id, user_id, amount, status |
| `verify_codes` | 设备验证码 | id, node_id, code, verified |
| `agreements` | 协议签署 | id, user_id, agreement_type |
| `scheduler_jobs` | 调度任务 | id, type, cron_expr |
| `platform_revenue` | 平台收入 | id(main), total_commission, today_commission |
### 3.2 索引策略
- **status 字段**：users、nodes、tasks 均建立 B-tree 索引（高频过滤查询）
- **外键字段**：user_id、assigned_node、claimed_by 自动建索引
- **时间字段**：tasks.submitted_at 建索引（按时间排序查询）
- **触发器**：所有表自动更新 `updated_at`（`update_timestamp()` 函数）
### 3.3 数据量
| 表 | 当前行数 |
|----|---------|
| nodes | 509 |
| transactions | 107 |
| tasks | 27 |
| api_keys | 8 |
| users | 3 |
| notifications | 10 |
---
## 四、API 参考手册
### 4.1 认证模块 `/api/auth`
| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/auth/register` | POST | 用户注册（支持邀请码） | 无 |
| `/api/auth/login` | POST | 登录，返回 JWT token | 无 |
| `/api/auth/me` | GET | 获取当前用户信息 | Bearer |
| `/api/auth/change-password` | POST | 修改密码 | Bearer |
| `/api/auth/update-profile` | POST | 更新个人资料 | Bearer |
**登录示例：**
```bash
curl -X POST http://localhost:8000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "demo", "password": "demo123"}'
# 返回: {"token": "eyJ...", "user": {...}}
```
### 4.2 设备管理 `/api/devices`
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/devices/detect` | GET | 浏览器设备信息检测 |
| `/api/devices/register` | POST | 注册设备（SHA-256 指纹） |
| `/api/devices/{id}/verify` | POST | 验证设备归属（6位验证码） |
| `/api/devices/{id}/resend-code` | POST | 重发验证码 |
| `/api/devices/{id}/heartbeat` | POST | 心跳上报（维持在线+GPU/CPU数据） |
| `/api/devices/{id}/status` | GET | 设备实时状态（含90s超时检测） |
| `/api/my-devices` | GET | 我的所有设备 |
**设备指纹算法：**
```
fingerprint = SHA-256(gpu_name + cpu_cores + ram_gb + os_info + user_id_salt)
```
**心跳超时机制：**
- 设备每 30s 上报心跳
- 服务端 `HeartbeatMonitor` 每 30s 检测
- 超过 **90 秒**无心跳 → 自动标记 `offline`
- 有执行中任务 → 标记 `failed` 并触发重试（最多 3 次）
### 4.3 任务调度 `/api/tasks`
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/tasks` | GET | 任务列表（支持 status/type 过滤） |
| `/api/tasks/{id}` | GET | 任务详情 |
| `/api/tasks` | POST | 创建任务（始终以 pending 创建） |
| `/api/tasks/{id}/claim` | POST | **设备端领取任务** |
| `/api/tasks/{id}/complete` | POST | **设备端上报完成** |
| `/api/tasks/{id}/fail` | POST | **设备端上报失败** |
| `/api/tasks/{id}/cancel` | POST | 取消任务 |
**任务生命周期：**
```
创建(pending) ──60s宽限期──→ 自动分配(running) ──进度推进──→ 完成(completed)
│ │
└── 设备 claim ──────────────┘
└── 失败(failed) → 重试3次 → pending
```
**60 秒宽限期：** 任务创建后 60 秒内不被自动调度，给设备端通过 `/claim` API 主动领取的时间窗口。
### 4.4 OpenAI 兼容 API `/v1`
| 端点 | 方法 | 限流 | 说明 |
|------|------|------|------|
| `/v1/models` | GET | 60/min | 列出可用模型 |
| `/v1/chat/completions` | POST | 30/min | 对话补全（支持流式） |
| `/v1/images/generations` | POST | 20/min | 图像生成 |
| `/v1/audio/transcriptions` | POST | 30/min | 语音转文字 |
| `/v1/embeddings` | POST | 30/min | 文本向量化 |
| `/v1/compute/submit` | POST | — | 自定义计算任务 |
| `/v1/compute/status/{id}` | GET | — | 查询任务状态 |
| `/v1/compute/result/{id}` | GET | — | 获取计算结果 |
| `/v1/dashboard/billing` | GET | — | 账单统计 |
**鉴权方式：** `Authorization: Bearer sk-kogun-xxxx`
**对话示例：**
```bash
curl -X POST http://localhost:8000/v1/chat/completions \
-H "Authorization: Bearer sk-kogun-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "kogun-qwen-72b",
"messages": [{"role": "user", "content": "你好"}],
"stream": true
}'
```
**流式响应格式（SSE）：**
```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"你"}}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"好"}}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
```
### 4.5 支持模型
| 模型 ID | 类型 | 输入价格(/M tokens) | 输出价格(/M tokens) |
|---------|------|---------------------|---------------------|
| kogun-qwen-72b | chat | ¥0.50 | ¥2.00 |
| kogun-qwen-7b | chat | ¥0.10 | ¥0.40 |
| kogun-sdxl | image | ¥0.03/次 | — |
| kogun-whisper-v3 | audio | ¥0.006/min | — |
| kogun-embedding | embedding | ¥0.10 | — |
| kogun-deepseek-v3 | chat | ¥0.30 | ¥1.20 |
| kogun-llama-70b | chat | ¥0.40 | ¥1.50 |
### 4.6 管理端点 `/api/admin`
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/admin/users` | GET | 用户列表 |
| `/api/admin/users/{id}/ban` | POST | 封禁用户 |
| `/api/admin/users/{id}/unban` | POST | 解封用户 |
| `/api/admin/finance` | GET | 财务报表 |
| `/api/admin/enterprise` | GET/POST | 企业客户管理 |
| `/api/admin/enterprise/{id}/approve` | POST | 企业审批 |
| `/api/admin/withdrawals` | GET | 提现申请列表 |
| `/api/admin/withdrawals/{id}/approve` | POST | 批准提现 |
| `/api/admin/withdrawals/{id}/reject` | POST | 拒绝提现 |
| `/api/admin/monitor` | GET | **系统监控面板** |
| `/api/admin/cleanup-test-data` | POST | 清理测试数据 |
| `/api/admin/reset-demo` | POST | 重置演示数据 |
| `/api/admin/data-stats` | GET | 数据统计 |
### 4.7 其他端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/dashboard` | GET | 仪表盘数据 |
| `/api/my-dashboard` | GET | 个人仪表盘 |
| `/api/my-earnings` | GET | 收益统计 |
| `/api/my-referral` | GET | 邀请返利 |
| `/api/pricing` | GET | 当前定价信息 |
| `/api/notifications` | GET | 通知列表 |
| `/api/notifications/{id}/read` | POST | 标记已读 |
| `/api/api-keys/create` | POST | 创建 API Key |
| `/api/api-keys` | GET | API Key 列表（脱敏） |
| `/api/api-keys/{id}` | DELETE | 撤销 API Key |
| `/api/marketplace/categories` | GET | 任务市场分类 |
| `/api/marketplace/tasks` | GET | 市场可用任务 |
| `/api/marketplace/submit` | POST | 提交任务到市场 |
| `/api/health` | GET | 健康检查（无需认证） |
| `/ws` | WebSocket | 实时状态推送 |
---
## 五、定价引擎
### 5.1 GPU 型号定价
| GPU 型号 | 显存 | TFLOPS | 时薪(¥) |
|----------|------|--------|---------|
| RTX 4090 | 24GB | 82.6 | 3.50 |
| RTX 3090 | 24GB | 35.6 | 2.50 |
| RTX 3080 | 12GB | 29.8 | 2.00 |
| RTX 3070 | 8GB | 20.3 | 1.50 |
| RTX 3060 | 12GB | 12.7 | 1.00 |
| RTX 2080 Ti | 11GB | 13.4 | 0.80 |
| GTX 1080 Ti | 11GB | 11.3 | 0.50 |
### 5.2 收益计算公式
```
基础收益 = (时薪 / 3600) × 秒数 × (TFLOPS / 82.6)
阶梯加成 = 基础收益 × 阶梯系数
高峰溢价 = 阶梯加成 × 1.5（20:00-02:00）
贡献者收益 = 高峰溢价 × 80%
平台抽成 = 高峰溢价 × 20%
```
### 5.3 阶梯收益
| 在线时长 | 加成系数 |
|----------|---------|
| 0-4 小时 | ×1.0（基础） |
| 4-8 小时 | ×1.1（+10%） |
| 8-12 小时 | ×1.2（+20%） |
| 12+ 小时 | ×1.35（+35%） |
### 5.4 收益示例
> RTX 4090 在线 10 小时（高峰时段），5 秒计算周期：
>
> 基础 = 3.5/3600 × 5 × 82.6/82.6 = ¥0.00486
>
> 阶梯 = 0.00486 × 1.2 = ¥0.00583
>
> 高峰 = 0.00583 × 1.5 = ¥0.00875
>
> 贡献者 = ¥0.007 | 平台 = ¥0.00175
---
## 六、调度器架构
### 6.1 三协程分离设计
| 协程 | 间隔 | 职责 | 影响范围 |
|------|------|------|---------|
| **HeartbeatMonitor** | 30s | 心跳超时检测 → 节点下线 + 任务重试 | 所有节点 |
| **TaskScheduler** | 10s | pending→running 调度 + running→completed 推进 | 所有任务 |
| **SimDataGenerator** | 5s | GPU/CPU 负载波动 + 收益累计 | **仅 is_simulated=True 节点** |
### 6.2 关键设计决策
- **模拟/真实设备分离**：`is_simulated` 字段标记节点类型。真实设备（通过 `/api/devices/register` 注册）的数据完全由心跳 API 上报，SimDataGenerator 不会干扰。
- **60 秒宽限期**：任务创建后 60 秒内不被自动分配，给设备端 claim API 时间窗口。
- **心跳超时重试**：节点离线时任务自动重置为 pending（而非直接失败），支持 max_retries 次重试。
---
## 七、推理代理
### 7.1 双模式架构
```
请求 → proxy.py ──上游已配置──→ 真实 AI 服务（流式/非流式）→ 按实际用量扣费
└──上游未配置──→ 模拟响应 → 按估算扣费
```
### 7.2 配置方式
```bash
# 环境变量配置（支持火山引擎 Ark / OpenAI / 自建模型）
export UPSTREAM_API_URL="https://ark.cn-beijing.volces.com/api/v3"
export UPSTREAM_API_KEY="your-api-key"
export UPSTREAM_MODELS='{"kogun-qwen-72b":"ep-2024xxxx-xxxxx","kogun-embedding":"ep-2024yyyy-yyyyy"}'
```
### 7.3 代理行为
| 场景 | 行为 |
|------|------|
| 上游可用 | 请求透传 + 模型名映射 + 实际 Token 用量扣费 |
| 上游超时 | 降级为模拟 + 日志警告 |
| 上游未配置 | 直接使用模拟响应 |
---
## 八、安全设计
### 8.1 认证体系
| 机制 | 适用场景 | 格式 |
|------|---------|------|
| JWT Token | Web 端认证 | `Authorization: Bearer ` |
| API Key | 外部 API 调用 | `Authorization: Bearer sk-kogun-xxxx` |
| 管理员校验 | 管理端点 | JWT + role=admin 双重校验 |
### 8.2 安全措施
- **设备指纹**：SHA-256(gpu+cpu+ram+os+user_salt)，防重复注册
- **设备验证码**：6 位验证码，绑定 node_id + user_id
- **API Key 脱敏**：列表接口返回 `sk-kogun-e...8019` 格式
- **请求限流**：slowapi 按用户/IP 限流，OpenAI API 独立限制
- **心跳超时**：90 秒无心跳自动下线，释放任务资源
- **CORS**：跨域白名单（生产环境需配置具体域名）
### 8.3 限流策略
| 端点 | 限流 |
|------|------|
| 通用 API | 120 次/分钟 |
| `/v1/models` | 60 次/分钟 |
| `/v1/chat/completions` | 30 次/分钟 |
| `/v1/images/generations` | 20 次/分钟 |
| `/v1/audio/transcriptions` | 30 次/分钟 |
| `/v1/embeddings` | 30 次/分钟 |
---
## 九、部署指南
### 9.1 Docker Compose 一键部署
```bash
# 1. 克隆项目
cd /workspace/kogun-platform
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 设置 DB_PASSWORD 和 SECRET_KEY
# 3. 启动
docker compose up -d
# 4. 验证
curl http://localhost:8000/api/health
```
### 9.2 手动部署
```bash
# 1. 安装 PostgreSQL 16
sudo apt install postgresql-16
sudo -u postgres createdb kogun
sudo -u postgres createuser kogun -P
# 2. 初始化数据库
PGPASSWORD=xxx psql -U kogun -d kogun -f deploy/db/schema.sql
# 3. 安装依赖
pip install -r requirements.txt
# 4. 启动
uvicorn main:app --host 0.0.0.0 --port 8000
```
### 9.3 数据迁移（从旧版 JSON）
```bash
python migrate.py --source data.json --verify
```
### 9.4 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DATABASE_URL` | `postgresql+asyncpg://kogun:...@localhost:5432/kogun` | 异步数据库连接 |
| `DATABASE_URL_SYNC` | `postgresql://kogun:...@localhost:5432/kogun` | 同步数据库连接 |
| `SECRET_KEY` | `kogun-platform-secret-key-2026` | JWT 签名密钥 |
| `DEBUG` | 空 | 设置任意值启用详细错误 |
| `UPSTREAM_API_URL` | 空 | 上游推理 API URL |
| `UPSTREAM_API_KEY` | 空 | 上游推理 API Key |
| `UPSTREAM_MODELS` | `{}` | 模型映射 JSON |
---
## 十、监控与运维
### 10.1 健康检查
```bash
curl http://localhost:8000/api/health
```
```json
{
"api": "ok",
"version": "7.2.0",
"database": "ok",
"scheduler": "running",
"scheduler_coroutines": 3,
"proxy": {"upstream_enabled": false, "upstream_url": "not configured"},
"ws_connections": 0
}
```
### 10.2 系统监控（管理员）
```bash
curl -H "Authorization: Bearer " \
http://localhost:8000/api/admin/monitor
```
返回：CPU/内存/磁盘使用率 + 集群 TFLOPS + VRAM 利用率 + 任务统计 + 收益 + 代理状态
### 10.3 Swagger 文档
- **Swagger UI**：`http://localhost:8000/docs`
- **ReDoc**：`http://localhost:8000/redoc`
---
## 十一、WebSocket 实时推送
连接地址：`ws://localhost:8000/ws`
### 消息类型
| type | 说明 | 触发时机 |
|------|------|---------|
| `state_update` | 全局状态更新 | 调度器每次循环 |
| `node_update` | 节点状态变更 | 心跳/状态切换 |
| `node_timeout` | 节点超时下线 | 心跳 > 90s |
| `task_update` | 任务状态变更 | claim/complete/fail |
| `task_auto_assigned` | 任务自动分配 | 60s 宽限期后调度 |
| `task_added` | 新任务创建 | POST /api/tasks |
---
## 十二、版本历史
| 版本 | 日期 | 里程碑 |
|------|------|---------|
| v1.0 | 2026-05 | MVP 闭环：认证 + 节点管理 + 模拟数据 |
| v2.0 | 2026-05 | 定价引擎 + 邀请返利 + 交易系统 + 信用评分 |
| v3.0 | 2026-05 | 任务市场 + 落地页 + 通知系统 + 提现流程 |
| v4.0 | 2026-05 | OpenAI 兼容 API + AI 应用中心 + 企业控制台 |
| v5.0 | 2026-05 | 设备心跳 + 任务领取/完成 + 安全加固 + 暗色主题 |
| v6.0 | 2026-05 | 生产部署 + 20-100 设备测试框架 + 数据清理 |
| v7.0 | 2026-05 | **PostgreSQL 迁移**（JSON → 13 表 + SQLAlchemy ORM） |
| v7.1 | 2026-05 | **模块化重构**（scheduler/pricing/ws_manager 分离） |
| v7.2 | 2026-05 | **生产级加固**（限流 + 推理代理 + 监控面板 + CORS + Docker） |
---
## 十三、项目文件结构
```
kogun-platform/
├── main.py # API 路由 (2,897 行)
├── database.py # ORM + CRUD (1,193 行)
├── pricing.py # 定价引擎 (74 行)
├── scheduler.py # 调度器 (275 行)
├── proxy.py # 推理代理 (177 行)
├── ws_manager.py # WebSocket (46 行)
├── migrate.py # 数据迁移 (439 行)
├── Dockerfile # 容器构建
├── docker-compose.yml # 编排配置
├── requirements.txt # Python 依赖
├── .env.example # 环境变量模板
├── deploy/
│ └── db/
│ └── schema.sql # DDL (268 行)
├── templates/
│ └── index.html # 前端 SPA (4,115 行)
├── static/ # 静态资源
├── testing/ # 测试脚本
└── watchdog.sh # 进程守护
```
---
> **KOGUN v7.2.0** — 让每一块 GPU 都有价值