5.9 KiB
5.9 KiB
自动解绑API配置说明
📋 接口信息
API 地址
GET https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
功能说明
自动解绑过期的推荐关系，条件：
- ✅
status = 'active'（活跃状态） - ✅
expiry_date < NOW()（已过期） - ✅
purchase_count = 0（从未购买）
规则说明：
- 只解绑「活跃 + 过期 + 未购买」的绑定
- 如果用户购买过（
purchase_count > 0），即使过期也不解绑 - 保留有价值的推荐关系记录
🔧 宝塔面板配置
步骤1: 创建计划任务
- 登录宝塔面板
- 点击左侧菜单「计划任务」
- 点击「添加计划任务」
步骤2: 配置任务参数
任务类型: 访问URL
任务名称: 自动解绑过期推荐关系
执行周期: N分钟
分钟选择: 30（每30分钟执行一次）
URL地址:
https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
备注: 自动解绑过期且未购买的推荐关系
步骤3: 保存并测试
- 点击「保存」
- 点击「执行」按钮手动测试一次
- 查看执行日志，确认任务正常运行
📊 返回数据格式
成功响应（有数据）
{
"success": true,
"message": "自动解绑完成",
"unbound": 5,
"updatedReferrers": 3,
"details": [
{
"refereeId": "user_123",
"referrerId": "user_456",
"bindingDate": "2026-01-05T10:30:00.000Z",
"expiryDate": "2026-02-04T10:30:00.000Z",
"daysExpired": 1
}
],
"duration": 245
}
成功响应（无数据）
{
"success": true,
"message": "无需解绑的记录",
"unbound": 0,
"duration": 12
}
失败响应（密钥错误）
{
"success": false,
"error": "未授权访问"
}
🔍 日志示例
控制台输出
[UnbindExpired] ========== 自动解绑任务开始 ==========
[UnbindExpired] 找到 5 条需要解绑的记录
[UnbindExpired] 1. 用户 user_123
推荐人: user_456
绑定时间: 2026/1/5
过期时间: 2026/2/4 (已过期 1 天)
购买次数: 0
累计佣金: ¥0.00
[UnbindExpired] 2. 用户 user_789
推荐人: user_456
绑定时间: 2026/1/10
过期时间: 2026/2/3 (已过期 2 天)
购买次数: 0
累计佣金: ¥0.00
...
[UnbindExpired] 已成功解绑 5 条记录
[UnbindExpired] 更新推荐人 user_456 的 referral_count (-3)
[UnbindExpired] 更新推荐人 user_999 的 referral_count (-2)
[UnbindExpired] 解绑完成: 5 条记录，更新 2 个推荐人
[UnbindExpired] ========== 任务结束 (耗时 245ms) ==========
🔐 安全说明
密钥保护
- 密钥硬编码在代码中：
soul_cron_unbind_2026 - 只能通过正确的密钥访问接口
- 如果需要修改密钥，编辑
app/api/cron/unbind-expired/route.ts第 24 行
访问权限
- ✅ 只支持 GET 请求
- ✅ 需要提供正确的 secret 参数
- ✅ 错误的密钥返回 401 未授权
⏰ 推荐执行频率
每30分钟（推荐）
- ✅ 及时处理过期绑定
- ✅ 不会给服务器造成压力
- ✅ 符合业务需求
其他选项
- 每15分钟：如果需要更实时的解绑
- 每1小时：如果对实时性要求不高
- 每天凌晨3点：如果只需要每日清理
🧪 手动测试
方法1: 浏览器测试
直接在浏览器访问：
https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
方法2: curl 命令
curl "https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026"
方法3: 宝塔面板手动执行
- 进入「计划任务」
- 找到"自动解绑过期推荐关系"任务
- 点击「执行」按钮
- 查看「日志」了解执行结果
📝 数据库操作
查询将被解绑的记录（测试用）
SELECT
id,
referrer_id,
referee_id,
binding_date,
expiry_date,
purchase_count,
total_commission,
DATEDIFF(NOW(), expiry_date) as days_expired
FROM referral_bindings
WHERE status = 'active'
AND expiry_date < NOW()
AND purchase_count = 0
ORDER BY expiry_date ASC;
查看解绑历史
SELECT
id,
referrer_id,
referee_id,
binding_date,
expiry_date,
status,
purchase_count,
total_commission
FROM referral_bindings
WHERE status = 'expired'
ORDER BY expiry_date DESC
LIMIT 20;
🔄 对比：API vs 脚本
旧方案（Node.js 脚本）
# 缺点：
- ❌ 需要配置服务器环境变量
- ❌ 需要手动配置数据库连接
- ❌ 需要确保 Node.js 路径正确
- ❌ 依赖外部脚本文件
新方案（API接口）
# 优点：
- ✅ 无需配置环境变量
- ✅ 无需手动配置数据库（使用现有连接）
- ✅ 宝塔面板直接调用URL
- ✅ 集成在应用代码中
- ✅ 更易于维护和监控
📊 监控与告警
监控指标
- 解绑数量（
unbound） - 执行时长（
duration） - 成功率
查看执行历史
在宝塔面板的「计划任务」→「日志」中查看每次执行的结果。
建议
- 如果单次解绑数量 > 100，检查是否有异常
- 如果连续失败，检查数据库连接或接口状态
✅ 部署检查清单
部署前确认：
- ✅ API 文件已创建：
app/api/cron/unbind-expired/route.ts - ✅ 代码已部署到服务器
- ✅ PM2 服务已重启
部署后确认：
- ✅ 手动访问接口测试成功
- ✅ 宝塔计划任务已创建
- ✅ 执行周期设置为 30 分钟
- ✅ 手动执行一次测试成功
- ✅ 查看日志确认正常运行
🚀 快速配置命令
宝塔面板 - 计划任务配置
任务类型: 访问URL
URL地址: https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
执行周期: N分钟 → 30
任务名称: 自动解绑过期推荐关系
配置完成后，系统将每30分钟自动解绑过期且未购买的推荐关系！