- jwt_ttl 7200 → 86400 (24h) - 管理登录/代理登录/代理注册 接入 Turnstile - 前端 TurnstileWidget 组件, 未完成验证不可提交 - 密钥通过 env TURNSTILE_SITE_KEY/SECRET_KEY 配置
24 KiB
CardAuth - 卡密授权管理系统
一个轻量级的卡密(激活码)+ 机器授权管理系统,支持多项目管理、代理分销、在线支付购买,适用于软件授权、会员激活等场景。
当前版本:v1.2.0 · 更新日志见 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,格式:
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 部署(推荐)
# 1. 配置环境变量
cp .env.docker .env
# 编辑 .env,设置 JWT_SECRET 和数据库密码
# 2. 一键启动
docker compose up -d
# 3. 访问
http://localhost:8080
首次启动自动完成:前端构建 → 数据库初始化 → Nginx + PHP-FPM 启动。
方式二:传统部署
环境要求
- 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. 一键部署脚本
# 在项目根目录执行,按提示输入配置
sudo bash deploy.sh your-domain.com
脚本自动完成:环境检查 → 前端构建 → 文件部署 → 数据库初始化 → Nginx 配置 → 权限设置。
方式二:手动部署
1. 初始化数据库
mysql -u root -p < backend/database/schema.sql
2. 配置环境变量
cd backend
cp .env.example .env
# 编辑 .env,确保:
# APP_ENV=production
# APP_DEBUG=false
# DB_* 填入实际数据库信息
# JWT_SECRET 填入随机 64 位字符串
3. 安装依赖
cd backend && composer install --no-dev --optimize-autoloader
cd ../frontend && npm install && npm run build
构建产物输出到 frontend/dist/,将其复制到 backend/public/:
cp -r frontend/dist/* backend/public/
4. 配置 Nginx
参考 deploy/nginx.conf,核心配置:
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. 设置权限
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 小时执行一次过期检查:
# 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
响应示例:
{
"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" // 可选
}
响应示例(有效):
{
"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": "授权有效"
}
}
响应示例(无效):
{
"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,并额外附带更新提示字段(成功时):
{
"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" // 可选
}
响应:
{
"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、到期时间等
响应示例:
{
"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"
}
响应示例:
{
"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 |
统计响应示例:
{
"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 | 服务器错误 |
通用错误响应:
{
"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

