CardAuth 卡密授权管理系统使用教程

它是什么、适合谁

CardAuth（卡密授权管理系统）是一套自建的「卖授权」全套方案：你生成一批卡密（激活码），客户付款后拿到卡密或者自动收到绑定机器的授权，你的软件/客户端在启动时调它的 API 核验授权是否有效、还剩几天。它解决的是独立软件作者常见的三件事——收钱（在线支付商城 + 易支付回调）、发卡（手动批量 / 支付后自动发卡）、管人（代理分销、黑名单、到期提醒）。

它面向两类人：软件作者/站长（管理后台，管项目、套餐、卡密、授权、订单、代理、公告、版本）和最终用户/代理（公开的购买中心、代理端登录页），另外还有客户端开发者——调它的验证 API 即可完成授权校验、检查新版本、上报安装。

快速开始（Docker 部署，推荐）

cp .env.docker .env
# 编辑 .env：设置 JWT_SECRET（openssl rand -base64 48 生成）和数据库密码
docker compose up -d

启动完成后浏览器访问 http://localhost:8881（compose 映射 8881:80；以你 .env 里的 APP_URL 为准）。首次启动自动完成前端构建、数据库初始化、Nginx + PHP-FPM 启动。

默认管理员：

用户名	密码
admin	admin123456

首次登录后请立即修改密码。生产环境务必在 .env 里固定 JWT_SECRET，否则容器每次重启密钥都会变、所有人被登出。

不想用 Docker 也可以传统部署（Nginx + PHP 8.1+ + MySQL 8.0+），项目根目录一键脚本：

sudo bash deploy.sh your-domain.com

脚本会自动做环境检查、前端构建、文件部署、数据库初始化、Nginx 配置和权限设置。

常用操作

1. 建项目、拿 API Key

登录管理后台 → 项目管理 → 创建项目（填名称、描述）。每个项目有独立 API Key（POST /api/projects/{id}/regenerate-key 可重新生成），你的客户端程序验证授权时用它做 X-Api-Key 鉴权。

2. 建套餐

项目下创建套餐（商品）：名称（如「月卡」）、duration_days 时长、price 售价、agent_cost 代理价。套餐会自动出现在购买中心。

3. 生成卡密

卡密管理 → 批量生成：选项目、选套餐、填数量与前缀（如 CA）。支持导入、批量改状态、批量删除、导出 CSV/Excel。

4. 发布版本（客户端自动更新）

版本推送页上传安装包（zip/tar/gz/7z/exe/dmg/apk/msi/pkg/rar/bin，≤200MB），填版本号、更新说明，可设「强制更新」is_force 或最低版本 min_client_version。客户端调 POST /api/public/installations/check-update 或 POST /api/public/verify 时会拿到 update_available、update_required、download_url、checksum 等字段。注意：强制更新只是客户端提示，不会阻断授权。

5. 客户端接入授权校验

客户端验证授权（项目 API Key）：

curl -X POST https://your-domain/api/public/verify \
  -H "X-Api-Key: *** API Key>" \
  -H "Content-Type: application/json" \
  -d '{"bot_qq": "123456789", "card_key": "CA-XXXX-XXXX"}'

返回 valid、expire_time、days_left，成功时还附带版本更新字段。QQ 授权场景用 bot_qq；App/IPTV 这类按机器授权的场景建议用 POST /api/public/installations/check-update（传 machine_id 设备指纹）。

6. 自动发卡（App/IPTV 直购）

创建订单时不填 bot_qq，并在 contact_info 里写入机器码：

{
  "project_id": 1,
  "card_type_id": 1,
  "amount": 29.90,
  "pay_type": "wxpay",
  "contact_info": "MACHINE:TV-123456"
}

支付成功后系统自动从同项目同套餐的未用卡池取 1 张卡、绑定机器码、标记已使用，订单关联 card_id。客户端可用 GET /api/public/orders/query?order_no=... 查回自己的卡密。

7. 代理分销

代理注册页自助注册（带图形验证码），管理员给代理充值额度；代理在代理商城按代理价生成/导入卡密，余额自动扣费，还能发展下级代理。

8. 公告推送

业务管理 → 公告推送，发布系统/更新/活动/通知类公告，可选置顶、客户端弹窗、起止时间、关联项目。客户端拉取：

GET /api/public/announcements?target=client&project_id=1&limit=10

9. 到期邮件提醒

系统配置 → SMTP 邮件配置填好 SMTP 信息，然后加一条定时任务每 6 小时触发一次：

0 */6 * * * curl -s http://your-domain/api/cron/notify-expiring > /dev/null

授权到期前 N 天会自动发提醒邮件到联系人的 QQ 邮箱。

常见问题

支付回调「签名验证失败」怎么办？ v1.3.0 已修复：签名改用网关原始回调串重算。请保持易支付网关侧与系统版本一致，旧版本请升级。
支付成功但订单里没有卡密？ 订单不含 bot_qq 时才走自动发卡；若卡池没有未用卡，订单仍标记已支付但 card_id 为空，需要在卡密管理补卡后手动处理。
客户端提示强制更新会拒绝授权吗？ 不会。update_required=true 只是让客户端弹不可关闭的更新提示，verify 的授权结果照常返回。
安装次数怎么统计的？ 每次安装独立记录（含已删除），total_installs = 存活 + 已删除；同一台机器删掉重装会再次计入。时间统一为北京时间。
忘了默认密码？ 全新部署默认 admin / admin123456，登录后应立即修改；代理密码可由管理员在代理管理里重置。
部署后外部请求全部超时/499？ 如果用了宝塔反代，把站点 proxy_pass 指向 127.0.0.1 对应端口，不要用公网 IP 回环访问自己。

更新与版本

仓库 CHANGELOG.md 最近记录：

v1.3.0：支付结果页展示卡密（一键复制）；代理端改为自绘 SVG 图形验证码（替代 Turnstile，管理员登录仍用 Turnstile）；后台内容区全屏铺满；修复支付同步回调签名验证失败、SMTP 主题乱码。
v1.2.0：公告推送（新表、管理端页面、公开接口、置顶/弹窗/起止时间）。
v1.1.1：自动发卡补丁说明；安装统计时间统一为北京时间（MySQL/PHP 时区调整）。
v1.1.0：安装统计与版本推送（安装记录表、版本表、管理端页面、客户端 check-update / heartbeat 接口、强制推送）。
v1.0.0：初始版本（卡密授权、项目/套餐/卡密管理、代理分销、在线支付商城、授权验证 API、黑名单、SMTP 到期提醒、Docker 部署）。

已有数据库升级时执行 backend/database/migrations/ 下对应 SQL；全新安装的 schema.sql 已包含新表。

CardAuth 卡密授权管理系统 使用教程