xfcloudcard 1.0.0

云控卡密验证客户端库 - 支持 AES+HMAC 加密通信、心跳保活、离线上报

xfcloudcard

云控卡密验证客户端库，支持 AES-256-CBC + HMAC-SHA256 加密通信、心跳保活、离线上报、卡密过期回调。

安装

pip install xfcloudcard

快速开始

方式一：上下文管理器（推荐）

from xfcloudcard import CardClient

def on_expire():
    print("卡密已过期！")

with CardClient(
    server_url="http://localhost:8000",
    key="your-key",
    on_expire=on_expire,   # 卡密过期时自动调用
) as client:
    result = client.verify("CARD-XXXX-XXXX-XXXX-XXXX")
    if result['success']:
        # 业务代码写这里
        pass
# 退出 with 块时自动停止心跳 + 发送离线通知

方式二：装饰器

from xfcloudcard import require_card

@require_card(
    server_url="http://localhost:8000",
    key="your-key",
    on_expire=lambda: print("卡密过期！"),
)
def main():
    # 仅当卡密验证通过后才执行
    print("验证通过，执行业务逻辑...")

main()

方式三：命令行

# 交互模式
xfcloudcard

# 直接验证
xfcloudcard --card CARD-XXXX-XXXX-XXXX-XXXX

# 只验证，不启动心跳
xfcloudcard --card CARD-XXXX-... --once

API

CardClient(server_url, key, heartbeat_interval=60, on_expire=None)

参数 / 方法	说明
server_url	服务器 URL，默认 http://localhost:8000
key	加密密钥（必须与服务器端相同）
heartbeat_interval	心跳间隔秒数（默认 60）
on_expire	卡密过期时的回调函数（可选）
verify(card_key)	验证卡密，成功后自动启动心跳
verify_only(card_key)	只验证，不启动心跳
close()	停止心跳并发送离线通知
is_online()	返回心跳是否运行中

on_expire 回调行为：

• 心跳线程检测到卡密剩余时间 <= 0 时自动触发
• 触发后自动停止心跳
• 回调函数抛出异常不会影响主流程

require_card(server_url, key, heartbeat_interval=60, exit_on_fail=True, on_expire=None)

装饰器，在业务函数执行前自动验证卡密。

卡密过期处理

方案：心跳线程自动检测过期，触发 on_expire 回调。

def my_handler():
    print("卡密已过期，请续费！")
    # 可以设置标志位让业务代码优雅退出

with CardClient(..., on_expire=my_handler) as client:
    result = client.verify("CARD-XXXX-...")
    # 业务代码正常运行
    # 到期后 my_handler 会被自动调用

依赖

• requests >= 2.25.0
• pycryptodome >= 3.15.0

协议

MIT