1023 lines
27 KiB
Markdown
1023 lines
27 KiB
Markdown
# CardAuth - 卡密授权管理系统
|
||
|
||
一个轻量级的卡密(激活码)+ 机器授权管理系统,支持多项目管理、代理分销、在线支付购买,适用于软件授权、会员激活等场景。
|
||
|
||
> **当前版本:v1.2.0** · 更新日志见 [CHANGELOG.md](./CHANGELOG.md)
|
||
|
||
## 界面预览
|
||
|
||
> 截图为示例/公开页,敏感信息已打码或使用占位符。
|
||
|
||
| 登录页 | 系统文档(含自动发卡说明) |
|
||
|--------|---------------------------|
|
||
|  |  |
|
||
|
||
- 文档页:`/#/docs`(系统介绍、自动发卡、安装统计与版本推送、API 对接)
|
||
- 登录页:`/#/login`
|
||
- 购买中心:`/#/shop`
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| 后端 | PHP 8.1+ 自研框架(Router + Middleware + Controller) |
|
||
| 数据库 | MySQL 8.0+ |
|
||
| 前端 | Vue 3 + Element Plus + Pinia + ECharts |
|
||
| 构建 | Vite |
|
||
|
||
## 功能概览
|
||
|
||
### 角色体系
|
||
- **超级管理员**:全部权限,用户管理、项目管理、系统配置、操作日志
|
||
- **项目管理员**:仅管理指定项目(不会看到代理信息),可操作卡密、授权、订单
|
||
- **代理**:代理商城、卡密生成/导入(余额扣费)、授权管理,可发展下级代理
|
||
|
||
### 核心功能
|
||
- 项目与 API 密钥管理(每个项目独立密钥,API 鉴权)
|
||
- 商品/套餐管理(自定义时长、价格、代理价格)
|
||
- 卡密生成、批量导入、状态追踪
|
||
- 在线授权(直接创建授权,不依赖卡密;代理按代理价扣费)
|
||
- 代理余额体系(充值记录、扣费追溯、额度查询)
|
||
- 订单管理(代客手动完成 / 手动确认)
|
||
- **自动发卡(IPTV/App 直购闭环)**:支付成功后自动从未用卡池取卡并绑定机器码(v1.1 补丁)
|
||
- **公告推送(v1.2.0)**:管理端发布通知/更新/活动公告,支持置顶、定时、客户端弹窗
|
||
- 在线购买商城(公开页面,支持 epay/codepay 支付回调)
|
||
- **安装统计**:项目安装次数、存活/已删除、最后上线时间(v1.1.0)
|
||
- **版本推送**:上传安装包并推送客户端下载,支持强制更新提示(v1.1.0)
|
||
- 黑名单系统(机器码/IP 封禁,可配置封禁策略)
|
||
- SMTP 邮件通知(授权快到期自动发送提醒到联系人 QQ 邮箱)
|
||
- 仪表盘统计图表(收入趋势、授权趋势、套餐销售占比)
|
||
- 操作日志
|
||
|
||
### 内置页面
|
||
- `/` 仪表盘
|
||
- `/login` 管理员登录
|
||
- `/agent/login` 代理登录
|
||
- `/agent/register` 代理注册
|
||
- `/shop` 自助购买(公开页面)
|
||
- `/docs` 系统介绍与使用文档(含安装统计/版本推送说明)
|
||
- `/installations` 安装统计(v1.1.0)
|
||
- `/project-versions` 版本推送(v1.1.0)
|
||
- `/announcements` 公告推送(v1.2.0)
|
||
|
||
### 公告推送(v1.2.0)
|
||
|
||
管理后台 **业务管理 → 公告推送**(仅 admin / project_admin 可发布):
|
||
|
||
- 类型:系统 / 更新 / 活动 / 通知
|
||
- 对象:全部 / 管理端 / 代理端 / 客户端
|
||
- 支持置顶、客户端弹窗、起止时间、关联项目、跳转链接、上下线
|
||
|
||
客户端拉取:
|
||
|
||
```
|
||
GET /api/public/announcements?target=client&project_id=1&limit=10
|
||
```
|
||
|
||
响应含 `list`(列表)与 `popup`(需弹窗),仅返回生效中的公告。
|
||
|
||
### 订单支付后如何发卡
|
||
|
||
支付成功(异步回调 / 同步完成 / 手动补单 / 免费商品)统一走 `OrderController::processOrderPaid`:
|
||
|
||
| 场景 | 行为 |
|
||
|------|------|
|
||
| 订单含 `bot_qq` + `contact_qq` | 创建或续费 QQ 授权记录(`ca_authorizations`) |
|
||
| 订单**不含** `bot_qq`(App/IPTV 直购) | **自动发卡**:从同项目同套餐的未用卡池取 1 张,绑定机器码后标记为已使用 |
|
||
| 卡池无未用卡 | 订单仍标记为已支付,`card_id` 为空,请在卡密管理补卡后手动处理 |
|
||
|
||
**自动发卡机器码约定:** 下单时把电视/App 机器码写入 `contact_info`,格式:
|
||
|
||
```text
|
||
MACHINE:TV-XXXXXX
|
||
```
|
||
|
||
示例:`MACHINE:TV-E2E-TEST`。系统用正则 `MACHINE:([A-Za-z0-9\-_]+)` 解析;未填写时使用 `AUTO-{订单号}` 占位并仍完成绑定。
|
||
|
||
发卡结果:
|
||
- 卡密 `status=used`,`bind_info` 含 `machine_id / order_no / device_info=auto-delivery / first_bind_at`
|
||
- 订单写入 `card_id`,可在订单详情、导出中查看卡密
|
||
- 支付成功接口 / `GET /api/public/orders/query` 可返回关联卡密
|
||
|
||
## 快速开始
|
||
|
||
### 方式一:Docker 部署(推荐)
|
||
|
||
```bash
|
||
# 1. 配置环境变量
|
||
cp .env.docker .env
|
||
# 编辑 .env,设置 JWT_SECRET 和数据库密码
|
||
|
||
# 2. 一键启动
|
||
docker compose up -d
|
||
|
||
# 3. 访问
|
||
http://localhost:8080
|
||
```
|
||
|
||
首次启动自动完成:前端构建 → 数据库初始化 → Nginx + PHP-FPM 启动。
|
||
|
||
### 方式二:Docker Compose部署
|
||
|
||
上面「方式一」使用的仓库根目录 `docker-compose.yml` 完整内容(与仓库文件一致,含全部 ports / volumes / environment):
|
||
|
||
```yaml
|
||
version: "3.8"
|
||
|
||
services:
|
||
db:
|
||
image: mysql:8.0
|
||
container_name: cardauth-db
|
||
restart: unless-stopped
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root_secret_change_me}
|
||
MYSQL_DATABASE: ${DB_NAME:-card_auth}
|
||
MYSQL_USER: ${DB_USER:-card_auth}
|
||
MYSQL_PASSWORD: ${DB_PASS:-card_auth_pass}
|
||
volumes:
|
||
- mysql_data:/var/lib/mysql
|
||
- ./backend/database/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql:ro
|
||
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --default-time-zone=+08:00
|
||
healthcheck:
|
||
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 5
|
||
networks:
|
||
- cardauth
|
||
|
||
app:
|
||
build: .
|
||
container_name: cardauth-app
|
||
restart: unless-stopped
|
||
ports:
|
||
- "8881:80"
|
||
environment:
|
||
APP_ENV: production
|
||
APP_DEBUG: "false"
|
||
APP_URL: ${APP_URL:-http://localhost:8881}
|
||
DB_HOST: db
|
||
DB_PORT: "3306"
|
||
DB_NAME: ${DB_NAME:-card_auth}
|
||
DB_USER: ${DB_USER:-card_auth}
|
||
DB_PASS: ${DB_PASS:-card_auth_pass}
|
||
DB_PREFIX: ca_
|
||
JWT_SECRET: ${JWT_SECRET:-}
|
||
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root_secret_change_me}
|
||
PAYMENT_TYPE: ${PAYMENT_TYPE:-epay}
|
||
PAYMENT_API_URL: ${PAYMENT_API_URL:-}
|
||
PAYMENT_APP_ID: ${PAYMENT_APP_ID:-}
|
||
PAYMENT_APP_KEY: ${PAYMENT_APP_KEY:-}
|
||
depends_on:
|
||
db:
|
||
condition: service_healthy
|
||
networks:
|
||
- cardauth
|
||
volumes:
|
||
# PHP 上传限制:容器内 ini 改动不持久,用挂载固化(容器重建也生效)
|
||
- ./php/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini:ro
|
||
# 安装包与头像持久化:否则容器重建后已发布版本文件丢失
|
||
- ./backend/public/uploads:/var/www/public/uploads
|
||
|
||
volumes:
|
||
mysql_data:
|
||
driver: local
|
||
|
||
networks:
|
||
cardauth:
|
||
driver: bridge
|
||
```
|
||
|
||
启动 / 停止:
|
||
|
||
```bash
|
||
# 1. 配置环境变量
|
||
cp .env.docker .env
|
||
# 编辑 .env,设置 JWT_SECRET 和数据库密码
|
||
|
||
# 2. 启动(与方式一等价)
|
||
docker compose up -d
|
||
|
||
# 3. 查看状态 / 停止
|
||
docker compose ps
|
||
docker compose down
|
||
```
|
||
|
||
不使用 Compose 时,等价的最小 `docker run` 启动方式(先建网络与 MySQL,再构建并启动应用):
|
||
|
||
```bash
|
||
docker network create cardauth
|
||
|
||
docker run -d --name cardauth-db --network cardauth \
|
||
-e MYSQL_ROOT_PASSWORD=root_secret_change_me \
|
||
-e MYSQL_DATABASE=card_auth \
|
||
-e MYSQL_USER=card_auth \
|
||
-e MYSQL_PASSWORD=card_auth_pass \
|
||
-v cardauth_mysql_data:/var/lib/mysql \
|
||
-v ./backend/database/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql:ro \
|
||
mysql:8.0 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --default-time-zone=+08:00
|
||
|
||
docker build -t cardauth-app:latest .
|
||
|
||
docker run -d --name cardauth-app --network cardauth -p 8881:80 \
|
||
-e APP_ENV=production -e APP_DEBUG=false \
|
||
-e APP_URL=http://localhost:8881 \
|
||
-e DB_HOST=cardauth-db -e DB_PORT=3306 \
|
||
-e DB_NAME=card_auth -e DB_USER=card_auth -e DB_PASS=card_auth_pass \
|
||
-e DB_PREFIX=ca_ -e JWT_SECRET=change_me_to_random_64_chars \
|
||
-v ./backend/public/uploads:/var/www/public/uploads \
|
||
cardauth-app:latest
|
||
```
|
||
|
||
### 方式二:传统部署
|
||
|
||
#### 环境要求
|
||
- Linux 服务器(CentOS 7+ / Ubuntu 18+ / Debian 10+)
|
||
- Nginx 1.18+
|
||
- PHP 8.1+(需启用 PDO、PDO_MySQL、mbstring、bcmath)
|
||
- PHP-FPM
|
||
- MySQL 8.0+
|
||
- Node.js 18+(仅构建阶段需要,部署后不需要)
|
||
- Composer
|
||
|
||
#### 1. 一键部署脚本
|
||
|
||
```bash
|
||
# 在项目根目录执行,按提示输入配置
|
||
sudo bash deploy.sh your-domain.com
|
||
```
|
||
|
||
脚本自动完成:环境检查 → 前端构建 → 文件部署 → 数据库初始化 → Nginx 配置 → 权限设置。
|
||
|
||
### 方式二:手动部署
|
||
|
||
#### 1. 初始化数据库
|
||
```bash
|
||
mysql -u root -p < backend/database/schema.sql
|
||
```
|
||
|
||
#### 2. 配置环境变量
|
||
```bash
|
||
cd backend
|
||
cp .env.example .env
|
||
# 编辑 .env,确保:
|
||
# APP_ENV=production
|
||
# APP_DEBUG=false
|
||
# DB_* 填入实际数据库信息
|
||
# JWT_SECRET 填入随机 64 位字符串
|
||
```
|
||
|
||
#### 3. 安装依赖
|
||
```bash
|
||
cd backend && composer install --no-dev --optimize-autoloader
|
||
cd ../frontend && npm install && npm run build
|
||
```
|
||
|
||
构建产物输出到 `frontend/dist/`,将其复制到 `backend/public/`:
|
||
```bash
|
||
cp -r frontend/dist/* backend/public/
|
||
```
|
||
|
||
#### 4. 配置 Nginx
|
||
|
||
参考 [deploy/nginx.conf](deploy/nginx.conf),核心配置:
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name your-domain.com;
|
||
root /www/wwwroot/your-site/public;
|
||
index index.php index.html;
|
||
|
||
# 前端 SPA fallback
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API 路由到 PHP
|
||
location /api {
|
||
try_files $uri $uri/ /index.php?$query_string;
|
||
}
|
||
|
||
location ~ \.php$ {
|
||
fastcgi_pass unix:/tmp/php-cgi-74.sock; # 按实际 PHP 版本调整
|
||
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
||
include fastcgi_params;
|
||
}
|
||
|
||
# 安全加固
|
||
location ~ /\.(?!well-known) { deny all; }
|
||
location ~* \.(env|sql|log|md)$ { deny all; }
|
||
location ~* ^/(storage|config|routes)/ { deny all; }
|
||
}
|
||
```
|
||
|
||
#### 5. 设置权限
|
||
```bash
|
||
chown -R www:www /www/wwwroot/your-site
|
||
chmod -R 755 /www/wwwroot/your-site
|
||
chmod 600 /www/wwwroot/your-site/.env
|
||
```
|
||
|
||
#### 6. 默认管理员
|
||
| 用户名 | 密码 |
|
||
|--------|------|
|
||
| admin | admin123456 |
|
||
|
||
> 首次登录后请立即修改密码。
|
||
|
||
## SMTP 邮件通知配置
|
||
|
||
在系统配置 -> SMTP邮件配置中填写 SMTP 信息,系统将自动在授权到期前 N 天发送提醒邮件到联系人的 QQ 邮箱(`contact_qq@qq.com`)。
|
||
|
||
### 定时任务 (Cron)
|
||
建议设置每 6 小时执行一次过期检查:
|
||
```bash
|
||
# Linux crontab
|
||
0 */6 * * * curl -s http://your-domain/api/cron/notify-expiring > /dev/null
|
||
|
||
# Windows 任务计划程序
|
||
curl -s http://your-domain/api/cron/notify-expiring
|
||
```
|
||
|
||
---
|
||
|
||
# API 文档
|
||
|
||
## 鉴权说明
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| **JWT Token** | 登录后获取,请求头 `Authorization: Bearer <token>`,有效期 **24 小时** |
|
||
| **API Key** | 项目密钥,仅用于授权验证接口,请求头 `X-Api-Key: <key>` |
|
||
| **公开接口** | 无需认证,有频率限制(60秒内 30 次) |
|
||
|
||
---
|
||
|
||
## 一、公开接口(无需认证)
|
||
|
||
### 1.1 查询授权状态(按机器人QQ)
|
||
|
||
```
|
||
GET /api/public/authorizations/query?bot_qq=123456789
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"bot_qq": "123456789",
|
||
"total": 2,
|
||
"active_count": 1,
|
||
"expired_count": 1,
|
||
"revoked_count": 0,
|
||
"has_valid_auth": true,
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"card_key": "CA-XXXX-XXXX",
|
||
"project_name": "演示项目",
|
||
"bot_qq": "123456789",
|
||
"contact_qq": "987654321",
|
||
"contact_name": "张三",
|
||
"duration_days": 30,
|
||
"status": "active",
|
||
"authorized_at": "2026-01-01 12:00:00",
|
||
"expire_time": "2026-01-31 12:00:00",
|
||
"is_expired": false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 验证授权有效性(客户端调用)
|
||
|
||
```
|
||
POST /api/public/authorizations/verify
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"bot_qq": "123456789",
|
||
"card_key": "CA-XXXX-XXXX", // 可选
|
||
"contact_qq": "987654321" // 可选
|
||
}
|
||
```
|
||
|
||
**响应示例(有效):**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"valid": true,
|
||
"bot_qq": "123456789",
|
||
"contact_qq": "987654321",
|
||
"card_key": "CA-XXXX-XXXX",
|
||
"project_name": "演示项目",
|
||
"expire_time": "2026-01-31 12:00:00",
|
||
"days_left": 20,
|
||
"has_valid_auth": true,
|
||
"message": "授权有效"
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例(无效):**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"valid": false,
|
||
"bot_qq": "123456789",
|
||
"has_valid_auth": false,
|
||
"message": "未找到有效授权"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 API Key 授权验证
|
||
|
||
```
|
||
POST /api/public/verify
|
||
X-Api-Key: <项目的 API Key>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"bot_qq": "123456789",
|
||
"contact_qq": "987654321" // 可选
|
||
}
|
||
```
|
||
|
||
**响应格式同 1.2,并额外附带更新提示字段(成功时):**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"valid": true,
|
||
"message": "授权有效",
|
||
"type": "月卡",
|
||
"duration_days": 30,
|
||
"expire_time": "2026-11-01 12:00:00",
|
||
"is_permanent": false,
|
||
"remaining_days": 24,
|
||
"update_available": true,
|
||
"update_required": false,
|
||
"current_version": "1.0.0",
|
||
"latest_version": "1.2.0",
|
||
"version": "1.2.0",
|
||
"download_url": "/uploads/packages/1/pkg_1_xxx.zip",
|
||
"file_size": 10485760,
|
||
"checksum": "sha256...",
|
||
"changelog": "修复若干问题",
|
||
"min_client_version": "",
|
||
"is_force": 0,
|
||
"install_id": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
> 说明:`update_required` 仅作客户端强制更新提示,不阻断授权结果。
|
||
|
||
### 1.3.1 安装检查更新 / 心跳(客户端)
|
||
|
||
```
|
||
POST /api/public/installations/check-update
|
||
X-Api-Key: <项目的 API Key>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"machine_id": "设备唯一指纹",
|
||
"client_version": "1.0.0", // 可选
|
||
"card_key": "CA-XXXX-XXXX", // 可选
|
||
"device_info": "Windows 11" // 可选
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"update_available": true,
|
||
"update_required": true,
|
||
"current_version": "1.0.0",
|
||
"latest_version": "2.0.0",
|
||
"version": "2.0.0",
|
||
"download_url": "/uploads/packages/1/pkg_1_xxx.zip",
|
||
"file_size": 20971520,
|
||
"checksum": "sha256...",
|
||
"changelog": "重大更新",
|
||
"min_client_version": "1.1.0",
|
||
"is_force": 1,
|
||
"install_id": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
```
|
||
POST /api/public/installations/heartbeat
|
||
X-Api-Key: <项目的 API Key>
|
||
Content-Type: application/json
|
||
|
||
{ "machine_id": "设备唯一指纹", "client_version": "1.0.0", "card_key": "..." }
|
||
```
|
||
|
||
**客户端接入建议:**
|
||
- 启动/周期心跳时调用 `check-update`
|
||
- `update_available=true` 且 `update_required=false` → 弹出「发现新版本,是否下载?」
|
||
- `update_required=true` → 强制更新提示(不可关闭),引导下载 `download_url`
|
||
- 授权验证 `verify` 时也会同步更新安装记录的 `last_online_at`,并附带相同更新字段
|
||
|
||
### 1.4 获取项目列表(商城用)
|
||
|
||
```
|
||
GET /api/public/projects
|
||
```
|
||
|
||
### 1.5 获取项目套餐列表
|
||
|
||
```
|
||
GET /api/public/projects/{project_id}/card-types
|
||
```
|
||
|
||
### 1.6 创建订单
|
||
|
||
```
|
||
POST /api/public/orders
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"project_id": 1,
|
||
"card_type_id": 1,
|
||
"amount": 29.90,
|
||
"pay_type": "wxpay",
|
||
"contact_qq": "987654321", // QQ授权场景选填
|
||
"bot_qq": "123456789", // QQ授权场景选填;填写则走授权续费/新建
|
||
"contact_info": "MACHINE:TV-123456", // App/IPTV 自动发卡:写入机器码
|
||
"coupon_code": "" // 可选,优惠码
|
||
}
|
||
```
|
||
|
||
**自动发卡说明(App/IPTV 直购):**
|
||
- 订单**不填** `bot_qq`,且支付成功时,系统从同项目同套餐未用卡池自动取 1 张卡
|
||
- `contact_info` 中 `MACHINE:TV-XXXX` 会被解析为绑定机器码;未填则用 `AUTO-{订单号}`
|
||
- 自动发卡后,`GET /api/public/orders/query` 返回中可包含 `card_key`、到期时间等
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"order_no": "2026062317530410859",
|
||
"pay_url": "https://pay.example.com/xxx",
|
||
"is_renew": false,
|
||
"contact_qq_warn": null,
|
||
"contact_qq": "987654321"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.7 查询订单
|
||
|
||
```
|
||
GET /api/public/orders/query?order_no=2026062317530410859
|
||
```
|
||
|
||
---
|
||
|
||
## 二、认证接口
|
||
|
||
### 2.1 管理员登录
|
||
|
||
```
|
||
POST /api/auth/admin-login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"username": "admin",
|
||
"password": "admin123456"
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"token": "eyJ...",
|
||
"user": { "id": 1, "username": "admin", "role": "admin" }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 代理登录
|
||
|
||
```
|
||
POST /api/auth/agent-login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"username": "agent001",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
### 2.3 代理注册
|
||
|
||
```
|
||
POST /api/auth/agent-register
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"username": "new_agent",
|
||
"password": "123456",
|
||
"nickname": "新代理"
|
||
}
|
||
```
|
||
|
||
### 2.4 刷新 Token
|
||
|
||
```
|
||
POST /api/auth/refresh
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 2.5 获取当前用户信息
|
||
|
||
```
|
||
GET /api/auth/me
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
---
|
||
|
||
## 三、仪表盘
|
||
|
||
### 3.1 仪表盘数据
|
||
|
||
```
|
||
GET /api/dashboard
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**响应包含:**
|
||
- 统计数字(项目数、卡密数、订单数、收入等)
|
||
- `order_trend`: 近 7 天订单趋势
|
||
- `revenue_trend_30`: 近 30 天收入趋势
|
||
- `auth_trend_30`: 近 30 天新增授权趋势
|
||
- `package_distribution`: 套餐销售占比
|
||
- `expiring_soon`: 即将过期授权数
|
||
|
||
---
|
||
|
||
## 四、项目与套餐管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects` | 项目列表 |
|
||
| GET | `/api/projects/all` | 全部项目(下拉用) |
|
||
| GET | `/api/projects/{id}` | 项目详情 |
|
||
| POST | `/api/projects` | 创建项目 |
|
||
| PUT | `/api/projects/{id}` | 更新项目 |
|
||
| DELETE | `/api/projects/{id}` | 删除项目 |
|
||
| POST | `/api/projects/{id}/regenerate-key` | 重新生成 API Key |
|
||
| GET | `/api/projects/{id}/card-types` | 某项目的套餐列表 |
|
||
| POST | `/api/projects/{id}/card-types` | 创建套餐 |
|
||
| PUT | `/api/projects/{id}/card-types/{typeId}` | 更新套餐 |
|
||
| DELETE | `/api/projects/{id}/card-types/{typeId}` | 删除套餐 |
|
||
| GET | `/api/products` | 全量商品列表 |
|
||
| GET | `/api/products/export` | 导出商品 |
|
||
|
||
### 创建项目
|
||
|
||
```
|
||
POST /api/projects
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "我的项目",
|
||
"description": "项目描述"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四之二、安装统计与版本推送
|
||
|
||
### 权限说明
|
||
|
||
| 功能 | admin | project_admin | agent |
|
||
|------|-------|---------------|-------|
|
||
| 查看安装统计 | 全部 | 仅绑定项目 | 仅本人卡密相关 |
|
||
| 删除/恢复安装 | ✓ | ✓ | ✗ |
|
||
| 发布/修改/删除版本 | ✓ | ✓ | ✗(仅只读列表) |
|
||
| 强制推送开关 | ✓ | ✓ | ✗ |
|
||
|
||
### 安装统计
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/installations` | 安装列表(分页/筛选) |
|
||
| GET | `/api/installations/stats` | 统计:总安装(含已删除)、存活、已删除、今日新增、最后上线 |
|
||
| GET | `/api/installations/{id}` | 安装详情 |
|
||
| DELETE | `/api/installations/{id}` | 标记已删除(软删除) |
|
||
| POST | `/api/installations/{id}/restore` | 恢复为存活 |
|
||
| POST | `/api/installations/batch-delete` | 批量删除 `{ids:[]}` |
|
||
| GET | `/api/installations/export` | 导出 CSV |
|
||
|
||
**统计响应示例:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"total_installs": 1280,
|
||
"active": 1150,
|
||
"deleted": 130,
|
||
"today_new": 12,
|
||
"week_new": 80,
|
||
"last_online_at": "2026-10-08 10:30:00",
|
||
"projects": [
|
||
{
|
||
"project_id": 1,
|
||
"project_name": "演示项目",
|
||
"total_installs": 500,
|
||
"active": 450,
|
||
"deleted": 50,
|
||
"today_new": 5,
|
||
"last_online_at": "2026-10-08 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
列表 query 参数:`project_id`、`status`(active/deleted)、`keyword`、`date_from`、`date_to`、`page`、`page_size`。
|
||
|
||
### 版本推送管理
|
||
|
||
| 方法 | 路径 | 角色 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/projects/{projectId}/versions` | 三角色 | 版本列表 |
|
||
| GET | `/api/projects/{projectId}/versions/{id}` | 三角色 | 版本详情 |
|
||
| POST | `/api/projects/{projectId}/versions` | admin/project_admin | 上传发布(multipart) |
|
||
| PUT | `/api/versions/{id}` | admin/project_admin | 更新说明/强制/最低版本/状态 |
|
||
| PUT | `/api/versions/{id}/force` | admin/project_admin | 强制推送开关 |
|
||
| PUT | `/api/versions/{id}/latest` | admin/project_admin | 设为最新版本 |
|
||
| DELETE | `/api/versions/{id}` | admin/project_admin | 删除版本及文件 |
|
||
|
||
**发布版本(multipart/form-data):**
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `version` | 是 | 版本号,同项目唯一 |
|
||
| `file` | 是 | 安装包(zip/tar/gz/7z/exe/dmg/apk/msi/pkg/rar/bin,≤200MB) |
|
||
| `changelog` | 否 | 更新说明 |
|
||
| `is_force` | 否 | 0/1,默认 0;1=客户端强制更新提示 |
|
||
| `min_client_version` | 否 | 低于此版本强制更新 |
|
||
| `is_latest` | 否 | 默认 1;设为 1 时旧版本自动取消 latest |
|
||
|
||
强制推送语义:仅返回 `update_required=true` 提示客户端弹窗,**不阻断** `verify` 授权。
|
||
|
||
**安装次数口径:** `total_installs = COUNT(*)`(存活 + 已删除);每次安装独立记录,同机器删除后重装会再次计入。
|
||
|
||
### 创建套餐
|
||
|
||
```
|
||
POST /api/projects/1/card-types
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "月卡",
|
||
"duration_days": 30,
|
||
"price": 29.90,
|
||
"agent_cost": 20.00,
|
||
"sort": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、卡密管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/cards` | 卡密列表(支持分页、筛选、排序) |
|
||
| GET | `/api/cards/stats` | 卡密统计 |
|
||
| GET | `/api/cards/{id}` | 卡密详情 |
|
||
| POST | `/api/cards/generate` | 批量生成卡密 |
|
||
| POST | `/api/cards/import` | 导入卡密 |
|
||
| POST | `/api/cards/batch-status` | 批量修改状态 |
|
||
| POST | `/api/cards/batch-delete` | 批量删除 |
|
||
| PATCH | `/api/cards/{id}/status` | 单个卡密启用/禁用 |
|
||
| GET | `/api/cards/export` | 导出卡密(CSV/Excel) |
|
||
|
||
### 生成卡密
|
||
|
||
```
|
||
POST /api/cards/generate
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"project_id": 1,
|
||
"card_type_id": 1,
|
||
"count": 100,
|
||
"prefix": "CA"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、授权管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/authorizations` | 授权列表 |
|
||
| GET | `/api/authorizations/stats` | 授权统计 |
|
||
| GET | `/api/authorizations/{id}` | 授权详情 |
|
||
| POST | `/api/authorizations` | 新增授权 |
|
||
| PUT | `/api/authorizations/{id}/revoke` | 撤销授权 |
|
||
| DELETE | `/api/authorizations/{id}` | 删除授权 |
|
||
| POST | `/api/authorizations/batch-delete` | 批量删除 |
|
||
| GET | `/api/authorizations/export` | 导出授权 |
|
||
|
||
### 新增授权
|
||
|
||
```
|
||
POST /api/authorizations
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"project_id": 1,
|
||
"card_type_id": 1,
|
||
"bot_qq": "123456789",
|
||
"contact_qq": "987654321",
|
||
"contact_name": "张三"
|
||
}
|
||
```
|
||
|
||
**续费逻辑**:若 `bot_qq + contact_qq` 已存在活跃授权,自动续费延长过期时间。
|
||
|
||
### 撤销授权
|
||
|
||
```
|
||
PUT /api/authorizations/{id}/revoke
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"reason": "用户违规"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、订单管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/orders` | 订单列表 |
|
||
| GET | `/api/orders/{id}` | 订单详情 |
|
||
| POST | `/api/orders/{id}/complete` | 手动完成订单 |
|
||
| GET | `/api/orders/export` | 导出订单 |
|
||
|
||
---
|
||
|
||
## 八、用户管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/users` | 用户列表 |
|
||
| GET | `/api/users/stats` | 用户统计 |
|
||
| POST | `/api/users` | 创建用户 |
|
||
| PUT | `/api/users/{id}` | 更新用户 |
|
||
| DELETE | `/api/users/{id}` | 删除用户 |
|
||
| POST | `/api/users/batch-delete` | 批量删除 |
|
||
| GET | `/api/users/export` | 导出用户 |
|
||
|
||
---
|
||
|
||
## 九、代理管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/agents` | 代理列表 |
|
||
| GET | `/api/agents/my-quota` | 当前代理额度 |
|
||
| POST | `/api/agents/recharge` | 充值额度 |
|
||
| POST | `/api/agents/adjust-quota` | 调整额度 |
|
||
| GET | `/api/agents/quota-logs` | 额度变动日志 |
|
||
| POST | `/api/agents/{id}/reset-password` | 重置代理密码 |
|
||
|
||
---
|
||
|
||
## 十、优惠券
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/coupons` | 优惠券列表 |
|
||
| POST | `/api/coupons` | 创建优惠券 |
|
||
| PUT | `/api/coupons/{id}` | 更新优惠券 |
|
||
| DELETE | `/api/coupons/{id}` | 删除优惠券 |
|
||
|
||
---
|
||
|
||
## 十一、黑名单
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/blacklists` | 黑名单列表 |
|
||
| POST | `/api/blacklists` | 添加黑名单 |
|
||
| POST | `/api/blacklists/batch` | 批量添加 |
|
||
| POST | `/api/blacklists/import` | 导入黑名单 |
|
||
| PUT | `/api/blacklists/{id}` | 更新黑名单 |
|
||
| DELETE | `/api/blacklists/{id}` | 删除黑名单 |
|
||
| POST | `/api/blacklists/batch-delete` | 批量删除 |
|
||
|
||
---
|
||
|
||
## 十二、系统配置
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/system/configs?keys=key1,key2` | 获取配置 |
|
||
| POST | `/api/system/configs` | 保存配置 |
|
||
| GET | `/api/system/smtp-config` | 获取 SMTP 配置 |
|
||
| POST | `/api/system/smtp-config` | 保存 SMTP 配置 |
|
||
| POST | `/api/system/test-smtp` | 发送测试邮件 |
|
||
| POST | `/api/system/notify-expiring` | 手动触发过期提醒 |
|
||
|
||
---
|
||
|
||
## 十三、定时任务
|
||
|
||
```
|
||
POST /api/cron/notify-expiring
|
||
GET /api/cron/notify-expiring
|
||
```
|
||
|
||
无需认证,检查即将过期的授权并向联系人 QQ 邮箱发送提醒。
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| code | 说明 |
|
||
|------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 参数错误 |
|
||
| 401 | 未登录 / Token 无效 |
|
||
| 403 | 无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 429 | 请求过于频繁 |
|
||
| 500 | 服务器错误 |
|
||
|
||
通用错误响应:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数错误描述"
|
||
}
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
card/
|
||
├── backend/ # PHP 后端
|
||
│ ├── app/
|
||
│ │ ├── Controllers/ # 控制器 (12 个模块)
|
||
│ │ ├── Core/ # 框架核心 (Router/Controller/Database/Middleware/Validator)
|
||
│ │ ├── Middleware/ # 中间件 (Auth/JWT/RateLimit/ApiKey/Blacklist/Role)
|
||
│ │ └── Services/ # 服务层 (Jwt/Blacklist/Permission/Snowflake)
|
||
│ ├── config/ # 配置文件
|
||
│ ├── database/ # SQL 与 Migration
|
||
│ └── routes/ # 路由定义
|
||
├── frontend/ # Vue 3 前端
|
||
│ └── src/
|
||
│ ├── api/ # 接口封装
|
||
│ ├── composables/ # 组合式函数
|
||
│ ├── router/ # 路由配置
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ └── views/ # 页面组件 (管理后台 + 代理 + 公开)
|
||
├── docker/ # Docker 配置
|
||
│ ├── nginx.conf # Nginx 容器配置
|
||
│ ├── supervisord.conf # Supervisor 进程管理
|
||
│ └── entrypoint.sh # 容器入口脚本
|
||
├── deploy/ # 传统部署配置 (Nginx + 宝塔)
|
||
├── Dockerfile # Docker 多阶段构建
|
||
├── docker-compose.yml # Docker 编排 (MySQL + App)
|
||
└── .env.docker # Docker 环境变量模板
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|