# Lucky-Auth

**Repository Path**: xiaodu6/lucky-auth

## Basic Information

- **Project Name**: Lucky-Auth
- **Description**: 面向软件开发者的云端授权服务：软件/版本/变量配置、卡密生成与计费（免费/时间收费/点数收费）、单卡/账密两种登录模式、代理分销体系、在线验证与监控。客户端（如易语言编写的软件）通过加密接口接入。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网络授权验证系统

软件授权验证平台（Lucky-Auth）。面向软件开发者的云端授权服务：软件/版本/变量配置、卡密生成与计费（免费/时间收费/点数收费）、单卡/账密两种登录模式、代理分销体系、在线验证与监控。客户端（如易语言编写的软件）通过加密接口接入。

## 功能特性

- **软件管理**：软件列表、启停、重置加密密钥、签名过期时间、心跳有效时间、同账号在线数限制、绑定设备（1 台）
- **版本管理**：版本号、更新日志、强制更新标记、启用/停用，客户端「检测更新」返回最新已发布版本
- **变量回复**：软件级 key-value 动态配置，可要求携带登录 token，按版本维度覆盖
- **计费模式（软件级）**：
  - 免费：任意账号直接登录，不校验授权状态
  - 时间收费：卡密充值时长，过期失效
  - 点数收费：预充点数，提供扣点接口，点数为 0 失效
- **登录模式**：单卡（卡密即凭证）/ 账密（注册 → 登录 → 卡密充值），创建后锁定不可切换
- **卡密体系**：策略化生成（时长卡/点数卡、可配前缀）、批次管理、Excel 导出、未使用卡密作废退款、封禁/解封（卡密首次使用/充值时自动激活）
- **代理分销**：代理账号、余额充值、软件级代理等级折扣、分配软件、代理独立后台（工作台/发卡/我的卡密/我的客户/余额明细）
- **用户列表**：按软件维度展示用户与授权状态，详情抽屉（充值记录/绑定设备/扣点流水/验证日志）、封禁、踢下线、解绑设备、重置密码
- **在线监控**：实时在线会话、按版本筛选、批量踢出旧版本、心跳判活
- **公告**：面向代理的公告（全部/指定代理）
- **日志中心**：操作日志 + 客户端验证日志（登录/充值/扣点/退出），按日归档
- **仪表盘**：今日验证次数、今日充值数、在线数、卡密库存、趋势图、卡密状态分布
- **权限管理**：RBAC 用户/角色/菜单/按钮权限，超管与代理双后台

## 技术栈

| 端  | 技术                                                                                                  |
| -- | --------------------------------------------------------------------------------------------------- |
| 后端 | Java 17 · Spring Boot 3.2.5 · MyBatis Plus 3.5.7 · Sa-Token 1.39.0 · MySQL 8.0 · Redis · Apache POI |
| 前端 | Vue 3.4 · TypeScript · Vite 5 · Element Plus 2.7 · Pinia · Vue Router · ECharts · axios             |
| 安全 | 接口签名（SHA-256）+ 业务数据加密（AES-256-CBC）、密码 BCrypt、设备指纹 SHA-256                                           |

## 项目结构

```
├── server/                 # 后端服务（Spring Boot，端口 8088）
│   └── src/main/java/com/auth
│       ├── common/         # 通用：Result、异常、加解密、签名、Excel、启动初始化
│       ├── config/         # MyBatis Plus、Sa-Token、BCrypt 配置
│       └── module/         # 业务模块：agent/card/client/dashboard/device/
│                           # license/log/notice/online/sys/system/user
├── web/                    # 前端管理后台（Vue 3 + Vite，端口 5173）
│   └── src
│       ├── api/            # 接口封装
│       ├── layouts/        # AdminLayout（超管）/ AgentLayout（代理）
│       ├── router/         # 路由（登录/超管/代理/404，动态路由按菜单渲染）
│       ├── stores/         # Pinia（登录态/用户信息）
│       └── views/          # admin（超管）/ agent（代理）/ login
├── sql/
│   └── schema.sql          # 数据库初始化脚本（含表结构与种子数据）
├── docs/                   # VuePress 文档站（guide 使用指南 / client 客户端对接）
└── apifox-客户端对接API.json # Apifox 客户端接口导入文件
```

## 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- Redis 6+（Sa-Token 与在线会话使用，默认 `localhost:6379`）
- Node.js 18+

## 快速开始

### 1. 初始化数据库

先创建数据库，再导入表结构（脚本只包含建表与种子数据，不含建库语句）：

```bash
# 1. 建库（库名可自定义，需与后端 application-dev.yml 一致）
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS auth_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci"

# 2. 导入表结构 + 种子数据
mysql -u root -p auth_system < sql/schema.sql
```

> 已包含种子数据：角色（超级管理员/代理）、菜单与权限、系统用户、默认系统参数。表结构所有字段均带 COMMENT。

### 2. 启动后端

后端已按「开发 / 生产」拆分配置（详见 [环境与配置](docs/guide/environment.md)）：

- **本地开发**：修改 `server/src/main/resources/application-dev.yml` 中的 MySQL / Redis 连接后启动：

```bash
cd server
mvn spring-boot:run
```

- **生产部署**：修改 `application-prod.yml` 后以生产 profile 打包：

```bash
mvn clean package -DskipTests -Pprod
```

> 后端启动时若检测到 `admin` 用户不存在会自动创建（admin/123456），本初始化脚本已显式插入，不会重复创建。

### 3. 启动前端

```bash
cd web
npm install
npm run dev
```

访问 `http://localhost:5173`，开发环境 `/api` 已代理到 `http://localhost:8088`。

### 4. 文档站（可选）

项目自带 VuePress 文档站（`docs/`），包含使用指南、客户端对接、部署上线等章节。

**本地开发预览：**

```bash
cd docs
npm install
npm run docs:dev      # 开发服务器，端口 8081，修改 Markdown 后自动热更新
```

**生产构建与部署：**

```bash
cd docs
npm run docs:build    # 静态产物输出到 docs/.vuepress/dist/
```

- 将 `docs/.vuepress/dist/` 目录放到任意静态文件托管（如 Nginx）即可访问
- 本地预览构建产物：`npm run docs:preview`（端口 8081，与 `docs:dev` 一致）
- 完整部署说明见 [部署上线](docs/guide/deploy.md) 第 8 节

## 默认账号

| 账号       | 密码         | 角色    | 说明                               |
| -------- | ---------- | ----- | -------------------------------- |
| `admin`  | `123456`   | 超级管理员 | ID=1，全部权限                        |
| `agent1` | `agent123` | 代理    | ID=2，代理后台（工作台/发卡/我的卡密/我的客户/余额明细） |

## 客户端对接

客户端接口位于 `/api/client`，全部为 POST + JSON，传输加密：

- 请求体：`softwareId` + `timestamp` + `data`（业务参数 AES-256-CBC 密文）+ `sign`（SHA-256 签名）
- 响应：`{ code, msg, data }`，`code=0` 时 `data` 为密文，用软件「接口加密密钥」解密
- 失败响应统一为 `{ "code": 1, "msg": "失败原因", "data": {} }`，客户端直接展示 `msg` 即可

接口一览（12 个）：

| 接口      | 路径                                         | 用途                 | 是否需登录          |
| ------- | ------------------------------------------ | ------------------ | -------------- |
| 检查连接    | `POST /api/client/connect`                 | 连通性探测              | 否              |
| 取软件信息   | `POST /api/client/software/info`           | 计费方式/心跳参数/注册开关等    | 否              |
| 取软件版本信息 | `POST /api/client/version`                 | 最新版本 + 当前版本 + 历史列表 | 否              |
| 软件注册    | `POST /api/client/software/register`       | 账密账号注册             | 否              |
| 软件登录    | `POST /api/client/software/login`          | 免费/单卡/账密           | 否（登录获取 token）  |
| 已登录心跳   | `POST /api/client/software/heartbeat`      | 保活 + 换发 token      | 是              |
| 软件充值    | `POST /api/client/software/useCard`        | 账密用卡密续期/加点         | **否**（凭账号）     |
| 功能扣点    | `POST /api/client/software/deduct`         | 点数扣费               | 是              |
| 取变量回复   | `POST /api/client/software/variable`       | 公告/配置              | 需登录变量才需要       |
| 修改密码    | `POST /api/client/software/changePassword` | 账密改密               | **否**（凭账号+旧密码） |
| 查询授权信息  | `POST /api/client/software/authInfo`       | 授权详情/绑定设备          | 是              |
| 主动退出    | `POST /api/client/software/logout`         | 退出下线本端             | 是              |

> **免登录自助**：授权过期/点数用尽时用户无法登录软件，因此「充值」凭账号、「改密」凭账号+旧密码**均无需登录态**，过期用户可自助续费/改密。

对接文档：

- 在线文档 [客户端对接](./docs/client/index.md) — 完整接口参数、签名与 AES 加解密算法、错误对照（易语言注意点见 [易语言对接](./docs/client/e-language.md)）
- [apifox-客户端对接API.json](./apifox-客户端对接API.json) — Apifox 导入文件（12 个接口请求/响应定义）