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 框架

### 安装依赖

```bash
pip install requests customtkinter
```

### PyInstaller 打包环境

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

```bash
pip install certifi
```

## 快速开始

### 1. 基本使用

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

```python
#!/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 |

## 详细使用说明

### 初始化验证器

```python
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秒
)
```

### 执行验证

```python
# 阻塞式验证，会弹出现代化 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`

**请求参数:**
```json
{
    "software_id": "string",
    "license_key": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string",
    "software_version": "string"
}
```

**响应示例:**
```json
{
    "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`

**请求参数:**
```json
{
    "software_id": "string",
    "license_key": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string"
}
```

### 3. 解绑设备

**端点:** `POST /auth/unbind_device`

**请求参数:**
```json
{
    "software_id": "string",
    "machine_code": "string",
    "timestamp": "integer",
    "signature": "string"
}
```

## 错误处理

### 常见错误及解决方案

1. **无法连接到服务器**
   - 检查 `api_url` 是否正确
   - 检查网络连接
   - 检查服务器是否运行

2. **签名验证失败**
   - 检查 `secret_key` 是否正确
   - 检查时间是否同步

3. **卡密不存在**
   - 检查 `license_key` 是否正确
   - 检查卡密是否属于该软件

4. **卡密已过期**
   - 联系管理员续费
   - 使用新的卡密

### 错误示例

```python
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. 打包命令

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

### 2. 特殊处理

验证器已经内置了 PyInstaller 支持，会自动处理以下问题：
- SSL 证书问题
- 资源文件路径
- 临时文件清理

### 3. 打包后测试

```bash
# 在打包后的目录中测试
./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 界面无法显示

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

### 2. 网络请求失败

```python
# 测试网络连接
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. 机器码问题

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

### 4. 配置问题

```python
# 清除所有缓存，重新配置
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 示例

```python
#!/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** - 专业的软件授权验证解决方案