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

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

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

---

## 一、准备工作

### 1. 生成安全密钥

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

```bash
# 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
```

**预期响应**（成功）：
```json
{
  "success": true,
  "message": "订单状态同步完成",
  "total": 0,
  "synced": 0,
  "expired": 0,
  "error": 0,
  "duration": 123
}
```

**如果响应 401 错误**：
```json
{
  "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 登录服务器：
```bash
ssh root@你的服务器IP

cd /www/wwwroot/soul

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

添加以下内容：
```bash
# 定时任务密钥（与宝塔任务中的 secret 保持一致）
# CRON_SECRET 已写死在代码，无需配置

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

保存后重启项目：
```bash
pm2 restart soul
```

---

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

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

### 步骤 1：添加任务

任务类型选择：`Shell 脚本`

### 步骤 2：填写脚本

```bash
#!/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 环境

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

# 安装依赖
pip3 install pymysql requests
```

### 步骤 2：上传脚本

确保脚本已上传到服务器：
```
/www/wwwroot/soul/scripts/sync_order_status.py
```

### 步骤 3：宝塔添加任务

- 任务类型：`Shell 脚本`
- 脚本内容：
  ```bash
  cd /www/wwwroot/soul && python3 scripts/sync_order_status.py >> /www/wwwlogs/sync_orders.log 2>&1
  ```
- 执行周期：每 5 分钟

---

## 八、验证是否生效

### 1. 创建测试订单

```sql
-- 通过宝塔面板 → 数据库 → 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. 查询订单状态

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

**预期结果**：
- 状态应该变为 `expired`（因为超过 30 分钟）

### 4. 清理测试数据

```sql
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. 或查看自定义日志文件：
   ```bash
   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`。若需微信支付查询订单状态，可配置：

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

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

---

## 完成！

配置完成后，系统会：
- ✅ 每 5 分钟自动检查未支付订单
- ✅ 查询微信支付状态并同步
- ✅ 超时订单自动标记为 expired
- ✅ 支付成功订单自动解锁内容

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