# license-services

**Repository Path**: liudegui/license-server

## Basic Information

- **Project Name**: license-services
- **Description**: 基于 C++/Boost 的局域网 TCP license 认证服务
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 6
- **Created**: 2018-09-22
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Cpp, LICENSE, 认证服务, boost, TCP

## README

# License Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](README.md)

基于硬件绑定的密码学许可证管理服务器，带 Web 管理界面。

## 概述

采用 **FastAPI (Python) + C++17 原生模块 (pybind11)** 双层架构，兼顾开发效率和加密性能。

部署目标：树莓派 5、ARM-Linux 边缘设备或小型 Linux 云服务器。

### 核心特性

- **多种许可证模型**：永久、限时、订阅、试用、设备锁定、浮动并发、功能授权、离线
- **硬件指纹绑定**：多因子 (CPU/MAC/磁盘) 支持精确匹配和模糊匹配
- **Ed25519 签名离线许可证文件**：客户端无需联网即可验证
- **浮动并发许可证**：基于租约 + 心跳机制
- **Web 管理界面**：Jinja2 SSR + Bootstrap 5 + HTMX，全实体 CRUD
- **RESTful API**：OpenAPI/Swagger 文档，管理端 JWT 认证
- **C++17 原生加密模块**：Ed25519 签名/验证、AES-256-GCM、硬件指纹采集 (pybind11)
- **C++17 License Agent**：客户端守护进程，独立部署在客户设备
- **后台任务**：许可证过期检查、租约清理、心跳监控
- **审计日志**：全部操作记录 IP 和时间戳
- **频率限制**：按端点可配置
- **Docker 部署**：多阶段构建，入口自动初始化

## 架构

```
+--------------------------------------------------+
|            Web 管理界面 (Jinja2 SSR)              |
|          Bootstrap 5 CDN + HTMX 2.0 CDN          |
+--------------------------------------------------+
                        |
               HTTPS REST API (TLS 1.3)
                        |
+--------------------------------------------------+
|           FastAPI 应用服务器                       |
|                                                   |
|  API 路由       中间件           后台任务          |
|  /v1/licenses  - JWT 认证      - 过期检查         |
|  /v1/machines  - 频率限制      - 租约清理         |
|  /v1/admin/*   - 审计日志      - 心跳监控         |
|                - CORS                              |
|                                                   |
|  核心业务逻辑 (Python)                            |
|  许可证引擎 | 浮动管理器 | 指纹匹配               |
|                                                   |
|  C++17 原生模块 (pybind11)                        |
|  Ed25519 | AES-256-GCM | 硬件指纹 | HKDF         |
|                                                   |
|  SQLAlchemy ORM (SQLite / PostgreSQL)             |
+--------------------------------------------------+

========= 客户端 (ARM-Linux 设备) ==================

+--------------------------------------------------+
|         License Agent (C++17 守护进程)            |
|  HTTP 客户端 | Ed25519 验证 | 硬件指纹采集        |
|  License 文件缓存 | 心跳 | 本地 REST API          |
+--------------------------------------------------+
```

## 项目结构

```
license-server/
├── server/                  # Python FastAPI 服务端
│   ├── main.py              # 应用入口
│   ├── config.py            # YAML 配置管理
│   ├── api/                 # REST API 路由
│   │   ├── v1/licenses.py   # 公共许可证端点
│   │   ├── v1/machines.py   # 心跳、租约
│   │   └── v1/admin/        # 管理端 CRUD
│   ├── core/                # 核心业务逻辑
│   ├── models/              # SQLAlchemy ORM 模型
│   ├── schemas/             # Pydantic 请求/响应模型
│   ├── middleware/          # 审计、频率限制
│   ├── tasks/               # 后台调度任务
│   └── web/                 # Jinja2 SSR 管理界面
│       ├── templates/       # HTML 模板
│       └── static/          # CSS
├── native/                  # C++17 加密模块
│   ├── include/             # 头文件
│   ├── src/                 # 实现
│   ├── bindings/            # pybind11 Python 绑定
│   └── tests/               # Catch2 单元测试
├── agent/                   # C++17 License Agent 守护进程
│   ├── include/
│   ├── src/
│   └── tests/
├── config/server.yaml       # 服务端配置
├── scripts/                 # 密钥生成、数据库初始化、管理员创建
├── docker/                  # Dockerfile, docker-compose, 入口脚本
├── tests/                   # Python 集成测试
├── docs/                    # 设计文档
├── CMakeLists.txt           # C++ 原生模块构建
└── pyproject.toml           # Python 项目配置 (PEP 621)
```

## 快速开始

### 前置要求

- Python 3.10+
- CMake 3.14+ 和 C++17 编译器 (原生模块，可选)
- libsodium-dev (C++ 加密依赖)

### 1. 安装依赖

```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .
```

### 2. 初始化

```bash
# 生成加密密钥
python scripts/generate_keys.py

# 初始化数据库并创建管理员
python scripts/init_db.py
python scripts/create_admin.py --username admin --password admin123
```

### 3. 启动服务器

```bash
uvicorn server.main:app --host 0.0.0.0 --port 8443 --reload
```

### 4. 访问

- Web 管理界面：http://localhost:8443/web/dashboard
- API 文档：http://localhost:8443/docs
- 健康检查：http://localhost:8443/health

默认管理员账户：`admin` / `admin123`

## Docker 部署

```bash
cd docker
docker compose up -d
```

入口脚本自动完成数据库初始化、密钥生成和管理员账户创建。

## 配置

所有配置在 `config/server.yaml`：

| 配置段 | 主要设置 |
|--------|---------|
| `server` | 主机、端口、工作进程数、TLS 证书路径 |
| `database` | SQLite (默认) 或 PostgreSQL 连接 URL |
| `auth` | JWT 密钥、令牌有效期、bcrypt 轮数 |
| `crypto` | Ed25519 密钥路径、AES 主密钥、HMAC 密钥 |
| `rate_limit` | 各端点频率限制 |
| `tasks` | 后台任务执行间隔 |
| `logging` | 日志级别、文件路径、轮转 |
| `web_ui` | 启用/禁用 Web 管理界面 |

## API 端点

### 公共端点 (License Key 认证)

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/v1/licenses/validate` | 验证许可证 |
| POST | `/v1/licenses/activate` | 激活设备 |
| POST | `/v1/licenses/deactivate` | 停用设备 |
| POST | `/v1/licenses/checkout` | 获取离线许可证文件 |
| POST | `/v1/machines/heartbeat` | 浮动许可证心跳 |
| POST | `/v1/machines/release` | 释放浮动租约 |

### 管理端点 (JWT 认证)

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/v1/admin/auth/login` | 获取 JWT 令牌 |
| GET/POST | `/v1/admin/products` | 产品 CRUD |
| GET/POST | `/v1/admin/policies` | 策略 CRUD |
| GET/POST | `/v1/admin/licenses` | 许可证 CRUD |
| GET/POST | `/v1/admin/features` | 功能 CRUD |
| GET | `/v1/admin/machines` | 设备列表 |
| GET | `/v1/admin/audit-logs` | 审计日志 |
| GET | `/v1/admin/dashboard/stats` | 仪表板统计 |

### Web 管理界面 (Cookie 认证)

| 路径 | 说明 |
|------|------|
| `/web/dashboard` | 仪表板概览 |
| `/web/products` | 产品管理 |
| `/web/policies` | 策略管理 |
| `/web/licenses` | 许可证管理 |
| `/web/features` | 功能管理 |
| `/web/audit` | 审计日志查看 |
| `/web/keys` | 密钥管理 |

## C++ 原生模块

`native/` 目录包含性能关键的加密操作：

- **Ed25519**：密钥生成、签名、验证 (libsodium)
- **AES-256-GCM**：许可证文件加密/解密
- **硬件指纹**：CPU 序列号、MAC 地址、磁盘序列号采集
- **许可证文件**：签名文件生成和验证
- **HKDF**：从主密钥派生子密钥

单独构建：
```bash
cmake -B build-native -DCMAKE_BUILD_TYPE=Release
cmake --build build-native
ctest --test-dir build-native
```

当原生模块不可用时，服务器自动回退到 Python `cryptography` 库。

## License Agent (C++ 守护进程)

`agent/` 目录包含独立的 C++17 守护进程，部署在客户设备上：

- 本地 REST API 供应用程序集成
- 定期与服务器进行许可证验证
- 离线许可证文件缓存
- 硬件指纹采集
- 浮动许可证心跳

构建：
```bash
cd agent && cmake -B build && cmake --build build
```

## 测试

```bash
# Python 测试
pytest tests/ -v

# C++ 原生模块测试
ctest --test-dir build-native -V

# C++ Agent 测试
ctest --test-dir agent/build -V
```

## 许可证

MIT