KOGUN 算力共享平台 技术说明书 v8.2.1

┌──────────────────────────────────────────────────────┐
│                      用户层                            │
│   浏览器 SPA   │  curl | bash  │  REST API  │  WS      │
│   index.html   │  community   │  /v1/*     │  /ws     │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│                    API 服务层                          │
│    FastAPI + Uvicorn (systemd 自愈, 1 worker)          │
│    ├─ 认证: JWT (HS256) + bcrypt + SHA256 兼容        │
│    ├─ 调度: KogunScheduler (5协程)                    │
│    ├─ 消息: WebSocket + PG NOTIFY 双通道              │
│    ├─ 定价: 五因子 AHP 加权算力模型                    │
│    ├─ 社区: 地图聚合 + 排行榜 + 设备广场               │
│    ├─ 财务: 充值/提现/账单/企业预付                    │
│    └─ 监控: /health + /api/admin/system-status        │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│                      数据层                            │
│    PostgreSQL (kogun_v7, 34表)                         │
│    ├─ 业务表: users, nodes, tasks, transactions...    │
│    ├─ GPU虚拟: gpu_slots, device_capabilities          │
│    ├─ 缓存管理: node_caches                            │
│    ├─ LLM管理: llm_models, llm_providers               │
│    ├─ 财务表: withdrawals, payment_accounts            │
│    ├─ 企业表: enterprises                              │
│    ├─ LISTEN/NOTIFY 消息总线                          │
│    └─ 调度器内存缓存 (CacheIndex + GPUManager)         │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│                    Worker 层                           │
│    kogun-worker.py v2.4 (Python)                       │
│    ├─ GPU 检测: nvidia-smi → VRAM → 并发数             │
│    ├─ 推理引擎: Hermes Agent (LLM) / Python脚本        │
│    ├─ 本地缓存: NVMe SSD (LRU, 50GB上限)              │
│    ├─ 通信: WS 实时 + HTTP 轮询兜底 + PG NOTIFY       │
│    └─ 部署: systemd 自愈 + 一键安装                    │
└──────────────────────────────────────────────────────┘

用户注册 → POST /api/auth/register
         → bcrypt 哈希密码 → 存入 users 表 → 返回 JWT

用户登录 → POST /api/auth/login
         → 验证 bcrypt/SHA256 → 返回 JWT (24h)

设备认证 → POST /api/devices/auth
         → device_token → 查询 DB → 返回短期 JWT (2h)

API 调用 → Authorization: Bearer <jwt>
         → get_current_user 依赖注入 → 验证 JWT → 查询 DB

POST /api/api-keys/create → 生成 sk-kogun-{uuid} 格式密钥
GET  /api/api-keys        → 列出用户所有密钥

# 调用方式
curl https://api.kogun.site/v1/chat/completions \
  -H "Authorization: Bearer sk-kogun-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}]}'

// 设备 → 服务端
{"type":"device.heartbeat","gpu_load":45.2,"cpu_load":23.1,"ram_used_gb":8.5,
 "is_computing":false,"uptime_hours":1.5,"agent_version":"2.4",
 "gpu_virt":{"max_concurrent":3,"free_slots":2},"cached_models":["abc123"]}

{"type":"task.progress","task_id":123,"progress":45,"message":"处理中"}
{"type":"task.complete","task_id":123,"output":"result...","compute_time":125.3}

// 服务端 → 设备
{"type":"server.connected","device_id":"123","message":"设备已连接"}
{"type":"task.dispatch","task_id":123,"task_type":"llm_inference",
 "payload":{"model":"qwen2.5:7b","prompt":"你好"},"priority":2}

任务到达 → ① 缓存感知路由 (CacheIndex — 优先选已缓存模型的节点)
         → ② 贡献者优先 (GPU评分 + free_slots + 可靠性排序)
         → ③ 平台节点兜底 (无贡献者时)
         → ④ 社区算力盒子 (预留)
         → ⑤ 云弹性扩容 (预留)

综合算力 = GPU_TFLOPS/BENCHMARK × 0.41 + VRAM系数 × 0.26 + CPU系数 × 0.19
          + RAM系数 × 0.09 + Storage系数 × 0.05

时收益 = 时基价 × 综合系数 × 阶梯加成 × 高峰溢价
贡献者收益 = 时收益 × 70%（平台抽成 25% + 公益捐赠 5%）

~/.kogun/cache/
├── models/             # 模型权重缓存
│   ├── <md5_hash>/     # 每个模型独立目录
│   └── .cached         # 标记文件
└── results/            # 推理结果缓存
    └── <hash>.json     # LRU 淘汰，上限 1000 条

kogun-worker.py v2.4
├── WorkerConfig        # 配置管理 (JSON/YAML)
├── HardwareDetector    # 硬件检测: CPU/GPU/RAM/Storage
├── GPUManager          # GPU虚拟化: VRAM→并发数 + Semaphore控制
├── LocalCache          # 本地NVMe缓存: 模型权重 + 推理结果
├── HermesConnector     # LLM推理引擎代理
├── ThreadPoolExecutor  # 多任务并发执行
├── WSClient            # WebSocket 实时通道 (主)
├── PGPoller            # PG NOTIFY 兜底通道 (备)
├── HeartbeatManager    # 心跳上报 (15s间隔, 含gpu_virt+cache)
└── TaskExecutor        # 任务执行抽象层

# 使用已有 Token
python3 kogun-worker.py --token kdt-xxxxxxxx

# 自动登录 + 注册
python3 kogun-worker.py --login 用户名 密码

# 一键部署
curl -sL https://api.kogun.site/deploy | bash

curl -sL https://api.kogun.site/deploy | bash

curl https://api.kogun.site/api/health
# {
#   "api": "ok",
#   "version": "8.2.1",
#   "database": "ok",
#   "scheduler": "running",
#   "scheduler_coroutines": 5,
#   "ws_connections": 0
# }

GET /api/community/map

# 返回:
{
  "地区": [
    {
      "地区": "北京",
      "节点数": 15,
      "社区数": 3,
      "社区列表": [
        {
          "社区名": "中关村算力社区",
          "设备数": 8,
          "总分数": 750.5,
          "设备列表": [...]
        }
      ]
    }
  ],
  "总计": {
    "地区数": 2,
    "节点数": 29,
    "社区数": 2,
    "总算力分": 1234.5
  }
}

POST /api/devices/register
{
  "gpu_name": "RTX 4090",
  "community": "中关村算力社区",
  "region_city": "北京",
  "region_district": "海淀区"
}

-- migration_v8_community.sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS agreement_signed BOOLEAN NOT NULL DEFAULT FALSE;
ALTER TABLE users ADD COLUMN IF NOT EXISTS real_name VARCHAR(100);
ALTER TABLE users ADD COLUMN IF NOT EXISTS id_number VARCHAR(20);

CREATE TABLE IF NOT EXISTS agreements (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id),
    agreement_type VARCHAR(50),
    signed BOOLEAN NOT NULL DEFAULT TRUE,
    signed_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

ALTER TABLE agreements ADD COLUMN IF NOT EXISTS signature_data TEXT;
ALTER TABLE agreements ADD COLUMN IF NOT EXISTS real_name VARCHAR(100);
ALTER TABLE agreements ADD COLUMN IF NOT EXISTS id_number VARCHAR(20);

CREATE INDEX IF NOT EXISTS idx_agreements_user_id ON agreements(user_id);
CREATE INDEX IF NOT EXISTS idx_users_community ON users(community) WHERE community IS NOT NULL;

# API 服务
sudo systemctl status kogun
sudo systemctl restart kogun
sudo journalctl -u kogun -f

# Worker 服务
systemctl --user status kogun-worker
systemctl --user restart kogun-worker

curl https://api.kogun.site/health
# {"api":"ok","version":"8.2.1","database":"ok","scheduler":"running",
#  "scheduler_coroutines":5,"ws_connections":0}

curl -H "Authorization: Bearer <token>" \
  https://api.kogun.site/api/admin/system-status

# 返回: WS连接、缓存索引、GPU虚拟化、任务吞吐、PG消息总线状态

PGPASSWORD=kogun2026 psql -h localhost -U kogun -d kogun_v7

# 常用查询
SELECT id, username, role FROM users;
SELECT id, status, gpu_name FROM nodes WHERE status='online';
SELECT status, count(*) FROM tasks GROUP BY status;
SELECT count(*) FROM withdrawals WHERE status='pending';

测试模块               端点数    结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
公开页面                   6     ✅ 6/6
仪表盘 Tab                 6     ✅ 6/6
设备节点 Tab               5     ✅ 5/5
任务市场 Tab               6     ✅ 6/6
收益中心 Tab               8     ✅ 8/8
算力社区 Tab               4     ✅ 4/4
我的 Tab                   8     ✅ 8/8
下载 Tab                   6     ✅ 6/6
协议 Tab                   2     ✅ 2/2
通知 Tab                   4     ✅ 4/4
企业 Tab                   2     ✅ 2/2
Admin管理面板             10     ✅ 10/10
POST操作                   7     ✅ 7/7
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
合计                      75     100%