Kamixitong/docs/auth_validator_usage_guide.md

AuthValidator 授权验证器使用指南

概述

auth_validator.py 是一个现代化的软件授权验证器，提供了完整的激活码/卡密验证功能。该验证器采用在线验证模式，确保软件授权的实时性和安全性。

主要功能

1. 在线验证 - 每次启动都进行服务器验证，防止后台禁用后仍能使用
2. 自动保存/读取历史卡密 - 用户无需重复输入卡密
3. 现代化深色主题 UI - 提供友好的用户界面
4. 机器码一键复制 - 方便用户联系客服
5. 设备绑定管理 - 支持解绑卡密和解绑设备
6. 签名验证 - 使用 SHA256 签名确保请求安全
7. PyInstaller 支持 - 完美支持打包后的可执行文件

系统要求

Python 环境

• Python 3.6 或更高版本
• 依赖库：
  • requests - HTTP 请求
  • customtkinter - 现代化 UI 框架

安装依赖

pip install requests customtkinter

PyInstaller 打包环境

如果使用 PyInstaller 打包，需要添加证书处理：

pip install certifi

快速开始

1. 基本使用

在你的 Python 软件入口文件（如 main.py）中添加以下代码：

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import sys
import os

# 添加 auth_validator.py 所在路径
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

# 导入验证器
from auth_validator import AuthValidator

def main():
    """主程序入口"""

    # 创建验证器实例
    validator = AuthValidator(
        software_id="YOUR_SOFTWARE_ID",  # 你的软件唯一标识
        api_url="http://your-server.com/api/v1",  # 授权服务器地址
        secret_key="YOUR_SECRET_KEY"  # 授权密钥（与服务器配置一致）
    )

    # 执行验证
    if not validator.validate():
        # 验证失败，退出程序
        print("授权验证失败，程序将退出。")
        sys.exit(1)

    # 验证成功，继续执行主程序
    print("授权验证成功，欢迎使用！")
    # ... 你的主程序逻辑 ...

if __name__ == '__main__':
    main()

2. 配置参数说明

参数	类型	必需	说明
software_id	string	是	软件唯一标识符，与服务器产品ID一致
api_url	string	是	授权服务器 API 地址，如 http://localhost:5000/api/v1
secret_key	string	是	授权密钥，与服务器配置一致
timeout	int	否	请求超时时间（秒），默认 5

详细使用说明

初始化验证器

from auth_validator import AuthValidator

validator = AuthValidator(
    software_id="my_software",
    api_url="http://license.example.com/api/v1",
    secret_key="my_secret_key_12345",
    timeout=10  # 可选，设置超时时间为10秒
)

执行验证

# 阻塞式验证，会弹出现代化 UI 窗口
is_valid = validator.validate()

if is_valid:
    print("验证成功！")
    # 继续执行主程序
else:
    print("验证失败！")
    # 退出程序
    sys.exit(1)

验证流程

1. 启动 UI 窗口 - 显示现代化深色主题界面
2. 读取历史卡密 - 自动填入上次使用的卡密（如果有）
3. 自动验证 - 如果有历史卡密，自动进行验证
4. 手动验证 - 用户可以输入新卡密并点击验证
5. 验证结果 - 根据服务器返回结果显示成功或失败
6. 保存卡密 - 验证成功后自动保存卡密供下次使用

高级功能

1. 机器码管理

验证器会自动生成稳定的机器码，基于以下信息：

• 主机名
• 操作系统架构
• MAC 地址
• Windows UUID（如果是 Windows 系统）

机器码会缓存到 .machine_id 文件中，确保同一台机器的机器码保持不变。

2. 配置管理

验证器会自动管理以下配置：

• auth_config.json - 保存最后一次成功的卡密
• .auth_{software_id}.token - 保存验证成功后的 Token 数据

3. 解绑功能

验证器提供两种解绑方式：

解绑当前卡密

用户可以在 UI 中点击"解绑当前卡密"按钮，解除卡密与设备的绑定。

解绑当前设备

用户可以在 UI 中点击"解绑当前设备"按钮，解除当前设备与所有卡密的绑定。

4. 签名验证

所有 API 请求都使用 SHA256 签名验证，确保请求的安全性：

签名数据 = software_id + license_key + machine_code + timestamp
签名 = SHA256(签名数据 + secret_key)

时间戳有效期为 5 分钟，防止重放攻击。

API 接口

验证器会调用以下服务器 API：

1. 验证卡密

端点: POST /auth/verify

请求参数:

{
    "software_id": "string",
    "license_key": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string",
    "software_version": "string"
}

响应示例:

{
    "success": true,
    "message": "验证成功",
    "data": {
        "license_key": "XXXXX-XXXXX-XXXXX-XXXXX",
        "type": 1,
        "type_name": "正式",
        "expire_time": "2025-12-31T23:59:59",
        "remaining_days": 365,
        "product_name": "我的软件"
    }
}

2. 解绑卡密

端点: POST /auth/unbind

请求参数:

{
    "software_id": "string",
    "license_key": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string"
}

3. 解绑设备

端点: POST /auth/unbind_device

请求参数:

{
    "software_id": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string"
}

错误处理

常见错误及解决方案

1. 无法连接到服务器

   • 检查 api_url 是否正确
   • 检查网络连接
   • 检查服务器是否运行

2. 签名验证失败

   • 检查 secret_key 是否正确
   • 检查时间是否同步

3. 卡密不存在

   • 检查 license_key 是否正确
   • 检查卡密是否属于该软件

4. 卡密已过期

   • 联系管理员续费
   • 使用新的卡密

错误示例

try:
    validator = AuthValidator(
        software_id="my_software",
        api_url="http://localhost:5000/api/v1",
        secret_key="wrong_key"
    )

    if validator.validate():
        print("验证成功")
    else:
        print("验证失败，程序退出")
        sys.exit(1)

except Exception as e:
    print(f"验证器初始化失败: {e}")
    sys.exit(1)

PyInstaller 打包

1. 打包命令

pyinstaller --onefile --windowed --name="MySoftware" main.py

2. 特殊处理

验证器已经内置了 PyInstaller 支持，会自动处理以下问题：

• SSL 证书问题
• 资源文件路径
• 临时文件清理

3. 打包后测试

# 在打包后的目录中测试
./dist/MySoftware

部署到生产环境

1. 服务器端配置

确保授权服务器已正确配置：

• 部署 KaMiXiTong 授权管理系统
• 配置产品信息
• 生成卡密
• 设置 AUTH_SECRET_KEY 环境变量

2. 客户端配置

在客户端软件中：

• 设置正确的 software_id（与服务器产品ID一致）
• 设置正确的 api_url（授权服务器地址）
• 设置正确的 secret_key（与服务器一致）

3. 测试验证

在部署前进行充分测试：

• 测试有效卡密验证
• 测试无效卡密拒绝
• 测试过期卡密处理
• 测试解绑功能
• 测试网络异常处理

安全建议

1. 保护密钥 - 不要将 secret_key 硬编码在代码中，应使用配置文件或环境变量
2. 定期更新 - 定期更新软件和验证器版本
3. 日志监控 - 监控验证日志，及时发现异常
4. 备份策略 - 定期备份卡密数据库
5. 网络安全 - 使用 HTTPS 保护 API 通信

故障排除

1. UI 界面无法显示

# 检查是否安装了 customtkinter
import customtkinter as ctk
print(ctk.__version__)

2. 网络请求失败

# 测试网络连接
import requests
try:
    response = requests.get("http://your-server.com/api/v1/auth/verify", timeout=5)
    print("网络连接正常")
except Exception as e:
    print(f"网络连接失败: {e}")

3. 机器码问题

# 清除机器码缓存，重新生成
import os
if os.path.exists(".machine_id"):
    os.remove(".machine_id")
    print("机器码缓存已清除，重启程序后重新生成")

4. 配置问题

# 清除所有缓存，重新配置
import os
files_to_remove = ["auth_config.json", ".machine_id", ".auth_my_software.token"]
for file in files_to_remove:
    if os.path.exists(file):
        os.remove(file)
        print(f"已删除: {file}")

示例项目

完整的示例项目结构：

my_software/
├── main.py                 # 主程序入口
├── auth_validator.py       # 验证器文件
├── config.py              # 配置文件
├── requirements.txt       # 依赖列表
├── build.py               # 打包脚本
└── README.md              # 使用说明

requirements.txt

requests>=2.25.0
customtkinter>=5.0.0
pyinstaller>=4.0

main.py 示例

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import sys
import os
from auth_validator import AuthValidator

def load_config():
    """加载配置"""
    # 从环境变量或配置文件读取
    return {
        'software_id': os.getenv('SOFTWARE_ID', 'my_software'),
        'api_url': os.getenv('API_URL', 'http://localhost:5000/api/v1'),
        'secret_key': os.getenv('SECRET_KEY', 'your_secret_key')
    }

def main():
    """主程序入口"""
    # 加载配置
    config = load_config()

    # 创建验证器
    validator = AuthValidator(**config)

    # 执行验证
    print("正在验证软件授权...")
    if not validator.validate():
        print("授权验证失败！")
        sys.exit(1)

    print("授权验证成功！")
    # ... 你的主程序逻辑 ...

if __name__ == '__main__':
    main()

技术支持

如有问题，请联系：

• 邮箱：support@example.com
• QQ：123456789
• 微信：taiyi1224

更新日志

v1.0.0 (2025-12-27)

• 初始版本发布
• 支持在线验证
• 支持现代化 UI
• 支持 PyInstaller 打包
• 支持解绑功能

许可证

本软件仅供学习和研究使用，请遵守相关法律法规。

---

Powered by AuthValidator - 专业的软件授权验证解决方案