84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
本文件为消息推送（Push Server）与云函数投递的精简说明，聚焦：该服务的职责、运行要点、快速启动命令与云函数调用约定。
|
||
|
||
目标读者：后端开发、联调/运维人员。更详细的实现细节请参考对应子文档与源码链接（下文有指引）。
|
||
|
||
概览
|
||
- 组件：
|
||
- webhook-receiver：接收第三方物流回调并写入 `platform_express_*`（见 pages/mall/delivery/webhook-server）。
|
||
- notify-worker：从 `notify_queue` 生成 `express_notifications`（消息中心记录）。
|
||
- push-server：管理设备 CID、入队通知、消费者轮询并调用云函数下发推送（见 server/push-server.js）。
|
||
|
||
运行要点（快速）
|
||
- 一键启动（Windows PowerShell）：
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\server\scripts\start-delivery-backend.ps1
|
||
```
|
||
- 停止：
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\server\scripts\stop-delivery-backend.ps1
|
||
```
|
||
|
||
脚本说明（Windows PowerShell 5.1）：
|
||
- PID 文件：`server/.runtime/delivery-backend.pids.json`（由 start 脚本写入，UTF-8 无 BOM）。
|
||
- stop 脚本优先按 PID 停止，异常时会兜底释放端口（7201/7301）。
|
||
- 不停止直接重复启动，常见会报端口占用（`EADDRINUSE`）或出现多实例重复消费。
|
||
- 单独启动 push-server（示例）：
|
||
```powershell
|
||
$env:CONFIG_FILE=(Resolve-Path .\server\config.json)
|
||
node server/push-server.js
|
||
```
|
||
- 启动 notify-worker：
|
||
```powershell
|
||
node server/notify-worker.js
|
||
```
|
||
- 启动 webhook-receiver（开发）：
|
||
```powershell
|
||
node .\pages\mall\delivery\webhook-server\webhook-receiver.js
|
||
# 测试脚本
|
||
node .\pages\mall\delivery\webhook-server\test-send.js
|
||
```
|
||
|
||
必备环境变量（最常用）
|
||
- `SUPA_URL`、`SUPA_KEY`（或 `SERVICE_ROLE_KEY`）— Supabase/PostgREST 地址与服务 key（后端专用）。
|
||
- `CLOUD_FUNC_URL` — 云函数 HTTP invoke 地址（push-server consumer 调用）。
|
||
- `PUSH_TOKEN` — 可选：云函数鉴权 token（由 push-server 透传）。
|
||
- `ENABLE_CONSUMER` / `CONSUMER_POLL_MS` — 是否启用消费者与轮询间隔。
|
||
|
||
云函数调用约定（push-server → 云函数）
|
||
- POST body（JSON）示例：
|
||
```json
|
||
{
|
||
"token":"<PUSH_TOKEN>",
|
||
"push_clientid":"<CID>",
|
||
"title":"...",
|
||
"content":"...",
|
||
"payload": { }
|
||
}
|
||
```
|
||
- 云函数兼容性提示：部分云厂商将真实请求体放在 `event.body`（字符串），云函数需先尝试解析 `event.body`。
|
||
- 成功判定：HTTP 2xx 且（可选）返回 JSON `{ errCode:0 }`。
|
||
|
||
快速验证（端到端）
|
||
- 确保有一个活跃设备（写入 `server/data/push_devices.json` 或 Supabase `push_devices`）。
|
||
- 写入通知：
|
||
```bash
|
||
curl -X POST http://localhost:7301/api/v1/notifications -H "Content-Type: application/json" -d '{"aud":"user","recipient_id":123,"notification":{"title":"测试","body":"hello"}}'
|
||
```
|
||
- 等待消费者轮询并在 push-server 日志或 Supabase `express_notifications.send_status` 查看处理结果。
|
||
|
||
移除/精简说明
|
||
- 本文件已删除冗长的逐行排障示例、重复的 PowerShell 编码说明与历史已弃用的代理字段（如 `PUSH_PROXY_URL` 注释）。详细故障排查请看 `DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md` 与各子文档。
|
||
|
||
重要链接
|
||
- push-server 源码： [server/push-server.js](../push-server.js)
|
||
- 完整全链路数据流转分析：`DELIVERY_NOTIFICATION_DATA_FLOW.md`
|
||
- 运行与变更记录：`PUSH_SERVER_README.md`
|
||
- 消息生成Worker服务：`NOTIFY_WORKER_README.md`
|
||
- 云函数集成指引：`UNI_PUSH2_CLOUD_FUNCTION.md`
|
||
- 排错指南：`DELIVERY_E2E_TROUBLESHOOTING_20260310.md`
|
||
- webhook-receiver：`../../pages/mall/delivery/webhook-server/README.md`
|
||
- 部署脚本： [server/scripts/start-delivery-backend.ps1](../scripts/start-delivery-backend.ps1)
|
||
- 迁移脚本与 SQL： pages/mall/delivery/doc/需求文档/
|
||
|
||
如需我把这份精简后的内容合并到 `DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md` 或把常用启动命令加入到仓库根 README，我可以继续提交修改。
|