462 lines
10 KiB
Markdown
462 lines
10 KiB
Markdown
# 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** - 专业的软件授权验证解决方案
|