soul-yongping/开发文档/8、部署/宝塔面板配置订单同步定时任务.md

宝塔面板配置订单同步定时任务

适用于：有宝塔面板的服务器
难度：⭐（非常简单，3 分钟搞定）

---

一、准备工作

1. 生成安全密钥

打开终端（本地电脑），执行：

# Windows PowerShell
-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})

# 或手动生成一个 32 位随机字符串，例如：
# 密钥已写死在代码里，见下文 URL

接口使用的固定密钥：soul_cron_sync_orders_2026（无需自己生成）

---

二、宝塔面板配置步骤

步骤 1：登录宝塔面板

1. 浏览器打开：http://你的服务器IP:8888
2. 输入账号密码登录

步骤 2：打开计划任务

1. 左侧菜单点击 "计划任务"
2. 点击右上角 "添加任务"

步骤 3：配置任务（方案 A - 访问 URL，推荐）

在弹出的对话框中填写：

字段	填写内容	说明
任务类型	选择 访问URL	下拉框选择
任务名称	订单状态同步	随便填，方便识别
执行周期	选择 N分钟	下拉框选择
分钟选择	填 5	表示每 5 分钟执行一次
URL地址	https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026	密钥已写死在代码里，无需修改

完整 URL 示例（密钥已写死在代码里，直接用即可）：

https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026

步骤 4：点击保存

点击底部的 "提交" 或 "确定" 按钮。

步骤 5：验证任务已添加

在任务列表中应该能看到：

• ✅ 任务名称：订单状态同步
• ✅ 类型：访问URL
• ✅ 周期：每 5 分钟
• ✅ 状态：正常（绿色）

---

三、立即测试执行

方法 1：宝塔面板手动执行

1. 在任务列表中找到刚添加的任务
2. 点击右侧的 "执行" 按钮
3. 查看执行结果：
   • 成功：显示 JSON 响应 {"success":true,...}
   • 失败：显示错误信息

方法 2：浏览器测试

直接在浏览器打开：

https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET

预期响应（成功）：

{
  "success": true,
  "message": "订单状态同步完成",
  "total": 0,
  "synced": 0,
  "expired": 0,
  "error": 0,
  "duration": 123
}

如果响应 401 错误：

{
  "success": false,
  "error": "未授权访问"
}

说明密钥不对，检查 URL 中的 secret 参数。

---

四、查看执行日志

宝塔面板查看

1. 计划任务列表
2. 找到"订单状态同步"任务
3. 点击右侧的 "日志" 按钮
4. 查看最近的执行记录

正常日志示例：

[2026-02-04 21:00:00] 开始执行
[2026-02-04 21:00:01] 状态码: 200
[2026-02-04 21:00:01] 响应: {"success":true,"synced":0,"expired":0}
[2026-02-04 21:00:01] 执行完成

---

五、配置环境变量（重要！）

定时任务需要密钥验证，必须在项目中配置：

方法 1：通过宝塔面板配置

1. 左侧菜单 → 网站
2. 找到 soul.quwanzhi.com 网站
3. 点击 设置
4. 左侧选择 "伪静态" 或 "配置文件"（取决于宝塔版本）
5. 找到 Node.js 项目的启动配置

方法 2：在项目根目录创建 .env.production

SSH 登录服务器：

ssh root@你的服务器IP

cd /www/wwwroot/soul

# 编辑 .env.production
nano .env.production

添加以下内容：

# 定时任务密钥（与宝塔任务中的 secret 保持一致）
# CRON_SECRET 已写死在代码，无需配置

# 微信支付 API 密钥（从微信商户平台获取）
WECHAT_API_KEY=你的32位API密钥

保存后重启项目：

pm2 restart soul

---

六、方案 B：Shell 脚本（备选）

如果不想用 URL 方式，也可以用 Shell 脚本：

步骤 1：添加任务

任务类型选择：Shell 脚本

步骤 2：填写脚本

#!/bin/bash
curl -X GET "https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET" >> /www/wwwlogs/cron_sync_orders.log 2>&1

步骤 3：设置执行周期

• 类型：N分钟
• 周期：5

---

七、方案 C：Python 脚本（高级）

如果你想用 Python 脚本直接执行：

步骤 1：确保 Python 环境

# SSH 登录服务器
ssh root@你的服务器IP

# 安装依赖
pip3 install pymysql requests

步骤 2：上传脚本

确保脚本已上传到服务器：

/www/wwwroot/soul/scripts/sync_order_status.py

步骤 3：宝塔添加任务

• 任务类型：Shell 脚本
• 脚本内容：

  cd /www/wwwroot/soul && python3 scripts/sync_order_status.py >> /www/wwwlogs/sync_orders.log 2>&1
  

• 执行周期：每 5 分钟

---

八、验证是否生效

1. 创建测试订单

-- 通过宝塔面板 → 数据库 → soul_miniprogram → SQL窗口
INSERT INTO orders (id, order_sn, user_id, open_id, product_type, product_id, amount, status, created_at, updated_at)
VALUES ('TEST_SYNC', 'TEST_SYNC_001', 'test_user', 'test_openid', 'section', '1.2', 1.00, 'created', DATE_SUB(NOW(), INTERVAL 35 MINUTE), DATE_SUB(NOW(), INTERVAL 35 MINUTE));

2. 等待定时任务执行（最多 5 分钟）

或手动执行：宝塔面板 → 计划任务 → 点击"执行"

3. 查询订单状态

SELECT order_sn, status, created_at, updated_at 
FROM orders 
WHERE order_sn = 'TEST_SYNC_001';

预期结果：

• 状态应该变为 expired（因为超过 30 分钟）

4. 清理测试数据

DELETE FROM orders WHERE order_sn = 'TEST_SYNC_001';

---

九、常见问题排查

Q1: 任务显示"执行失败"

可能原因：

1. URL 地址错误
2. 密钥不对（401 错误）
3. 服务器网络问题

解决方案：

1. 检查 URL 是否完整
2. 检查 secret 参数是否与 .env.production 中一致
3. 在浏览器中手动访问该 URL 测试

Q2: 返回 401 未授权

原因：密钥不匹配

解决方案：

1. 密钥已写死，无需配置 CRON_SECRET
2. 确认宝塔任务 URL 中的 secret 参数
3. 确保两者完全一致
4. 重启项目：pm2 restart soul

Q3: 返回 500 错误

可能原因：

1. 数据库连接失败
2. 代码有 bug

解决方案：

1. 查看应用日志：pm2 logs soul
2. 检查数据库是否正常
3. 检查环境变量是否配置

Q4: 看不到执行日志

解决方案：

1. 宝塔面板 → 计划任务 → 点击任务右侧的"日志"
2. 或查看自定义日志文件：

   tail -f /www/wwwlogs/cron_sync_orders.log
   

---

十、监控与优化

设置告警（可选）

宝塔面板 → 监控 → 进程守护，添加监控项：

• 监控类型：URL 监控
• URL：https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET
• 监控周期：5 分钟
• 告警方式：邮件/企业微信

调整执行频率

根据实际情况调整：

• 订单少：10 分钟 / 15 分钟
• 订单多：3 分钟 / 5 分钟
• 高峰期：1 分钟（不推荐，增加服务器负载）

---

十一、配置清单（Checklist）

完成以下步骤，确保定时任务正常运行：

• 宝塔面板添加计划任务（访问 URL，密钥已写死：soul_cron_sync_orders_2026）
• 配置 .env.production 中的 WECHAT_API_KEY（可选，用于查询微信订单状态）
• 重启项目：pm2 restart soul
• 手动执行测试（宝塔面板点击"执行"）
• 验证响应正常（{"success":true}）
• 查看日志确认任务执行
• 创建测试订单验证（可选）
• 清理测试数据（可选）

---

十二、最终配置示例

宝塔计划任务配置

任务名称: 订单状态同步
任务类型: 访问URL
执行周期: N分钟 -> 5
URL地址: https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026

项目环境变量 .env.production（可选）

密钥已写死，无需配置 CRON_SECRET。若需微信支付查询订单状态，可配置：

# 微信支付 API 密钥（从商户平台获取，用于同步时查询订单真实状态）
WECHAT_API_KEY=YOUR_32_CHAR_API_KEY_HERE

# 其他环境变量...
DATABASE_URL=mysql://...

---

完成！

配置完成后，系统会：

• ✅ 每 5 分钟自动检查未支付订单
• ✅ 查询微信支付状态并同步
• ✅ 超时订单自动标记为 expired
• ✅ 支付成功订单自动解锁内容

再也不用担心支付回调丢失导致用户无法解锁内容了！🎉