Kamixitong/docs/INTEGRATION.md

# 软件授权系统集成指南

本文档介绍如何将KaMiXiTong授权验证器集成到您的Python软件中。

## 快速开始

### 1. 获取验证器模块

将 `auth_validator.py` 文件复制到您的项目中，或者通过以下方式导入：

```python
# 方式1: 复制文件到项目
from auth_validator import AuthValidator

# 方式2: 如果系统已安装
from kamaxitong import AuthValidator
```

### 2. 基本集成

在您的主程序入口处添加以下代码：

```python
from auth_validator import AuthValidator

def main():
    # 创建验证器实例
    validator = AuthValidator(
        software_id="YOUR_SOFTWARE_ID",  # 在后台创建产品时获得
        api_url="http://your-domain.com/api/v1",  # 后台API地址
        gui_mode=True  # 使用图形界面输入卡密（可选）
    )

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

    # 验证成功，继续执行您的程序逻辑
    print("授权验证通过，启动程序...")
    your_main_program()

if __name__ == "__main__":
    main()
```

### 3. 配置参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `software_id` | str | 必填 | 软件ID，在后台创建产品时自动生成 |
| `api_url` | str | http://localhost:5000/api/v1 | 后台API地址 |
| `secret_key` | str | default-secret-key | 验证密钥，需与后台配置一致 |
| `cache_days` | int | 7 | 离线缓存有效期（天） |
| `timeout` | int | 3 | 网络请求超时时间（秒） |
| `gui_mode` | bool | False | 是否使用图形界面输入卡密 |

## 高级用法

### 1. 自定义错误处理

```python
from auth_validator import AuthValidator

class MyValidator(AuthValidator):
    def _show_message(self, title, message, is_error=False):
        # 自定义消息显示方式
        if is_error:
            print(f"❌ {title}: {message}")
        else:
            print(f"✅ {title}: {message}")

validator = MyValidator(software_id="YOUR_SOFTWARE_ID")
validator.validate()
```

### 2. 获取软件信息

```python
validator = AuthValidator(software_id="YOUR_SOFTWARE_ID")

# 获取软件更新信息
software_info = validator.get_software_info()
if software_info:
    print(f"最新版本: {software_info.get('latest_version')}")
    print(f"下载地址: {software_info.get('download_url')}")
```

### 3. 清除本地缓存

```python
validator = AuthValidator(software_id="YOUR_SOFTWARE_ID")
validator.clear_cache()  # 清除授权缓存
```

## 部署建议

### 1. 打包发布

使用 PyInstaller 打包时，建议包含验证器文件：

```bash
pip install pyinstaller
pyinstaller --onefile --add-data "auth_validator.py;." your_program.py
```

### 2. 代码混淆

为了增加安全性，建议对验证器进行混淆：

```python
# 安装 PyArmor
pip install pyarmor

# 混淆验证器
pyarmor obfuscate auth_validator.py --output dist_obf

# 使用混淆后的文件
from dist_obf.auth_validator import AuthValidator
```

### 3. 环境变量配置

建议使用环境变量管理配置：

```python
import os
from auth_validator import AuthValidator

validator = AuthValidator(
    software_id=os.environ.get('SOFTWARE_ID'),
    api_url=os.environ.get('AUTH_API_URL'),
    secret_key=os.environ.get('AUTH_SECRET_KEY')
)
```

## 常见问题

### Q: 验证器无法连接到服务器怎么办？

A: 验证器支持离线缓存模式。如果用户曾经成功验证过，在缓存有效期内（默认7天）可以离线使用。

### Q: 如何处理用户更换硬件？

A: 用户更换硬件后机器码会改变，需要重新激活。管理员可以在后台解绑原设备，允许用户在新设备上重新激活。

### Q: 如何防止验证器被绕过？

A: 建议采取以下安全措施：
1. 使用代码混淆工具
2. 将验证逻辑分散到程序的多个关键位置
3. 定期更新验证器版本
4. 在后台监控异常验证行为

### Q: 支持哪些操作系统？

A: 验证器支持 Windows、Linux 和 macOS，通过以下方式生成机器码：
- Windows: 使用 WMI 获取硬件信息
- Linux: 读取 /sys/class/dmi/id/ 下的系统信息
- macOS: 使用 system_profiler 命令

## 示例项目

### GUI应用程序示例

```python
import tkinter as tk
from tkinter import messagebox
from auth_validator import AuthValidator

class MyApp:
    def __init__(self):
        self.root = tk.Tk()
        self.root.title("我的软件")

        # 验证授权
        if not self.check_license():
            self.root.destroy()
            return

        self.setup_ui()

    def check_license(self):
        validator = AuthValidator(
            software_id="MY_APP_ID",
            gui_mode=False  # 自定义GUI
        )

        if not validator.validate():
            messagebox.showerror("授权失败", "软件授权验证失败，程序无法启动")
            return False
        return True

    def setup_ui(self):
        label = tk.Label(self.root, text="欢迎使用我的软件", font=("Arial", 16))
        label.pack(pady=50)

    def run(self):
        self.root.mainloop()

if __name__ == "__main__":
    app = MyApp()
    app.run()
```

### 命令行工具示例

```python
import click
from auth_validator import AuthValidator

@click.command()
@click.option('--software-id', required=True, help='软件ID')
@click.option('--api-url', default='http://localhost:5000/api/v1', help='API地址')
def main(software_id, api_url):
    """我的命令行工具"""

    validator = AuthValidator(
        software_id=software_id,
        api_url=api_url
    )

    if not validator.validate():
        click.echo("❌ 授权验证失败")
        return

    click.echo("✅ 授权验证通过")
    # 您的程序逻辑

if __name__ == "__main__":
    main()
```

## 技术支持

如需技术支持或报告问题，请联系：
- 邮箱: support@example.com
- 文档: https://docs.example.com
- GitHub: https://github.com/example/kamaxitong