buff2.0/项目文档归档/数字员工文档/技术数字员工/游铛铛-技术方案-后端API.md

游铛铛后台API技术方案

一、技术栈

• 框架：FastAPI / Flask
• 数据库：MySQL 8.0
• ORM：SQLAlchemy
• 加密：cryptography (RSA)
• 文档：Swagger/OpenAPI

二、数据库设计

2.1 用户表 (users)

CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    email VARCHAR(100),
    machine_code VARCHAR(64),
    card_id INT,
    expire_time DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.2 卡密表 (cards)

CREATE TABLE cards (
    id INT PRIMARY KEY AUTO_INCREMENT,
    card_code VARCHAR(32) UNIQUE NOT NULL,
    software_code VARCHAR(50) NOT NULL,
    days INT NOT NULL,
    discount DECIMAL(5,2) DEFAULT 1.0,
    user_id INT,
    activated_at DATETIME,
    expire_time DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.3 软件表 (software)

CREATE TABLE software (
    id INT PRIMARY KEY AUTO_INCREMENT,
    code VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(100),
    daily_price DECIMAL(10,2),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.4 密钥表 (api_keys)

CREATE TABLE api_keys (
    id INT PRIMARY KEY AUTO_INCREMENT,
    public_key TEXT NOT NULL,
    private_key TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE
);

2.5 公告表 (announcements)

CREATE TABLE announcements (
    id INT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(200),
    content TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.6 日志表 (api_logs)

CREATE TABLE api_logs (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT,
    endpoint VARCHAR(200),
    method VARCHAR(10),
    request_data TEXT,
    response_data TEXT,
    ip_address VARCHAR(50),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.7 管理员表 (admins)

CREATE TABLE admins (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

三、核心接口

3.1 客户端接口

用户认证

• POST /api/user/register - 用户注册
• POST /api/user/login - 用户登录
• POST /api/user/unbind - 机器解绑
• POST /api/user/heartbeat - 心跳检测

软件信息

• GET /api/software/info - 获取软件信息
• GET /api/announcement - 获取公告

密钥管理

• GET /api/keys/public - 获取公钥

3.2 管理端接口

管理员认证

• POST /admin/login - 管理员登录
• POST /admin/logout - 退出登录

用户管理

• GET /admin/users - 用户列表
• GET /admin/users/:id - 用户详情

软件管理

• GET /admin/software - 软件列表
• POST /admin/software - 创建软件
• PUT /admin/software/:id - 更新软件

卡密管理

• POST /admin/cards/generate - 生成卡密
• GET /admin/cards - 卡密列表
• GET /admin/cards/:id/activate - 卡密激活信息

密钥管理

• GET /admin/keys/current - 当前密钥
• GET /admin/keys/history - 历史密钥
• PUT /admin/keys/cycle - 更新周期配置

日志管理

• GET /admin/logs - 日志列表
• GET /admin/logs/export - 导出日志

公告管理

• GET /admin/announcements - 公告列表
• POST /admin/announcements - 创建公告
• PUT /admin/announcements/:id - 更新公告

四、加密机制

4.1 加密开关

# config.py
ENCRYPT_ENABLED = os.getenv('ENCRYPT_ENABLED', 'true') == 'true'

4.2 加密中间件

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa

def decrypt_request(data):
    if not ENCRYPT_ENABLED:
        return data
    
    # 使用私钥解密
    private_key = get_current_private_key()
    decrypted = private_key.decrypt(
        base64.b64decode(data),
        padding.OAEP(...)
    )
    return json.loads(decrypted)

4.3 密钥轮换

def rotate_keys():
    # 生成新密钥对
    private_key = rsa.generate_private_key(
        public_exponent=65537,
        key_size=2048
    )
    public_key = private_key.public_key()
    
    # 保存到数据库
    save_keys_to_db(public_key, private_key)
    
    # 标记旧密钥为非活跃
    deactivate_old_keys()

五、实现要点

5.1 用户注册

@app.post("/api/user/register")
async def register(data: dict):
    # 解密请求
    decrypted = decrypt_request(data['encrypted'])
    
    # 验证用户名唯一性
    if user_exists(decrypted['username']):
        return {"code": 400, "msg": "用户名已存在"}
    
    # 验证卡密
    card = validate_card(decrypted['card_code'])
    if not card:
        return {"code": 400, "msg": "卡密无效"}
    
    # 创建用户并绑定机器码
    user = create_user(
        username=decrypted['username'],
        password=hash_password(decrypted['password']),
        email=decrypted['email'],
        machine_code=decrypted['machine_code'],
        card_id=card.id
    )
    
    return {"code": 200, "data": {"user_id": user.id}}

5.2 心跳检测

@app.post("/api/user/heartbeat")
async def heartbeat(data: dict):
    decrypted = decrypt_request(data['encrypted'])
    user = get_user(decrypted['user_id'])
    
    # 检查是否过期
    if user.expire_time < datetime.now():
        return {"code": 401, "msg": "卡密已过期"}
    
    return {"code": 200, "data": {"expire_time": user.expire_time}}

5.3 日志记录

def log_api_call(user_id, endpoint, method, request_data, response_data, ip):
    db.execute("""
        INSERT INTO api_logs 
        (user_id, endpoint, method, request_data, response_data, ip_address)
        VALUES (?, ?, ?, ?, ?, ?)
    """, (user_id, endpoint, method, request_data, response_data, ip))