258 lines
7.0 KiB
Markdown
258 lines
7.0 KiB
Markdown
# 实时推送功能部署指南
|
||
|
||
## 📋 部署清单
|
||
|
||
### 1. 后端部署
|
||
|
||
```bash
|
||
# 1.1 进入后端目录
|
||
cd /path/to/dingdanquanliucheng/backend
|
||
|
||
# 1.2 安装依赖（redis 已在 requirements.txt 中）
|
||
pip install -r requirements.txt
|
||
|
||
# 1.3 确保 Redis 服务已安装并运行
|
||
# 检查 Redis 状态
|
||
redis-cli ping
|
||
# 如果返回 PONG 表示 Redis 正常运行
|
||
|
||
# 如果 Redis 未安装，可以使用以下命令安装（Ubuntu/Debian）：
|
||
# sudo apt update
|
||
# sudo apt install redis-server
|
||
# sudo systemctl start redis
|
||
# sudo systemctl enable redis
|
||
|
||
# 1.4 重启后端服务
|
||
# 如果使用 systemd：
|
||
sudo systemctl restart order-flow
|
||
|
||
# 如果使用 uvicorn 直接运行：
|
||
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 2. 小程序部署
|
||
|
||
```bash
|
||
# 2.1 进入小程序目录
|
||
cd /path/to/dingdanquanliucheng/frontend/mini-app
|
||
|
||
# 2.2 使用微信开发者工具编译上传
|
||
# 注意：subscribe.js 中的模板ID已配置完成，无需修改
|
||
|
||
# 2.3 在微信公众平台确认以下模板已添加：
|
||
# - 订单状态变更通知
|
||
# - 订单待审批通知
|
||
# - 物流任务分配通知
|
||
# - 物流超时提醒
|
||
# - 欠款提醒
|
||
# - 客户沉默提醒
|
||
```
|
||
|
||
### 3. Web 端部署
|
||
|
||
```bash
|
||
# 3.1 编译管理员端
|
||
cd /path/to/dingdanquanliucheng/frontend/web-admin
|
||
npm run build
|
||
# 将 dist 目录部署到 dda.gaowenbu.cn
|
||
|
||
# 3.2 编译业务员端
|
||
cd /path/to/dingdanquanliucheng/frontend/web-sales
|
||
npm run build
|
||
# 将 dist 目录部署到 ddy.gaowenbu.cn
|
||
```
|
||
|
||
### 4. Nginx 配置
|
||
|
||
```bash
|
||
# 4.1 复制 Nginx 配置文件
|
||
sudo cp /path/to/dingdanquanliucheng/deploy/dda.gaowenbu.cn.conf /www/server/panel/vhost/nginx/
|
||
sudo cp /path/to/dingdanquanliucheng/deploy/ddy.gaowenbu.cn.conf /www/server/panel/vhost/nginx/
|
||
|
||
# 4.2 测试 Nginx 配置
|
||
sudo nginx -t
|
||
|
||
# 4.3 重新加载 Nginx
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 验证部署
|
||
|
||
### 1. 检查后端 WebSocket 端点
|
||
|
||
```bash
|
||
# 访问 WebSocket 状态接口
|
||
curl https://dda.gaowenbu.cn/ws/status
|
||
|
||
# 应该返回：
|
||
# {"active_users":0,"connections":{}}
|
||
```
|
||
|
||
### 2. 检查 Redis 连接
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
redis-cli ping
|
||
|
||
# 应该返回：
|
||
# PONG
|
||
```
|
||
|
||
### 3. 检查 WebSocket 连接
|
||
|
||
打开浏览器开发者工具（F12），在 Console 中执行：
|
||
|
||
```javascript
|
||
// 检查 WebSocket 是否连接
|
||
const ws = new WebSocket('wss://dda.gaowenbu.cn/ws/reminders?token=YOUR_TOKEN');
|
||
ws.onopen = () => console.log('连接成功');
|
||
ws.onmessage = (e) => console.log('收到消息:', e.data);
|
||
ws.onerror = (e) => console.error('连接错误:', e);
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 功能说明
|
||
|
||
### 实时推送流程
|
||
|
||
```
|
||
业务事件触发
|
||
↓
|
||
event_bus.emit() 创建提醒记录
|
||
↓
|
||
┌───────────────────────────────────────┐
|
||
│ 后台线程异步执行： │
|
||
│ 1. Redis Pub/Sub → WebSocket 推送 │
|
||
│ 2. 微信订阅消息 API → 小程序推送 │
|
||
└───────────────────────────────────────┘
|
||
↓
|
||
┌───────────────────────────────────────┐
|
||
│ 客户端接收： │
|
||
│ - Web端：WebSocket + 声音 + 桌面通知 │
|
||
│ - 小程序：微信服务通知 + Tab角标 │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
|
||
### 触发场景
|
||
|
||
| 场景 | 触发位置 | 通知对象 |
|
||
|------|----------|----------|
|
||
| 订单创建 | `order_service.create_order` | 管理层 |
|
||
| 订单审批通过 | `order_service.approve_order` | 业务员 |
|
||
| 订单审批拒绝 | `order_service.approve_order` | 业务员 |
|
||
| 订单发厂 | `order_service.confirm_supplier_text` | 业务员 |
|
||
| 物流任务分配 | `logistics_service.create_task` | 司机 |
|
||
| 物流状态更新 | `logistics_service._change_task_status` | 业务员+管理层 |
|
||
| 欠款超期 | `reminder_service.check_arrears` | 业务员 |
|
||
| 物流超时 | `reminder_service.check_logistics_timeout` | 业务员 |
|
||
| 沉默客户 | `reminder_service.check_inactive_customers` | 业务员 |
|
||
|
||
---
|
||
|
||
## ⚠️ 故障排查
|
||
|
||
### 1. WebSocket 连接失败
|
||
|
||
**症状**：Web端通知铃铛不更新，需要手动刷新
|
||
|
||
**排查步骤**：
|
||
```bash
|
||
# 1. 检查 Nginx 配置是否包含 WebSocket 代理
|
||
grep -r "location /ws/" /www/server/panel/vhost/nginx/
|
||
|
||
# 2. 检查后端是否启动
|
||
curl https://dda.gaowenbu.cn/health
|
||
|
||
# 3. 检查 Redis 是否运行
|
||
redis-cli ping
|
||
|
||
# 4. 查看后端日志
|
||
tail -f /path/to/backend/logs/app.log | grep -i "websocket\|redis"
|
||
```
|
||
|
||
### 2. 小程序收不到推送
|
||
|
||
**症状**：小程序没有收到微信服务通知
|
||
|
||
**排查步骤**：
|
||
1. 检查用户是否授权了订阅消息
|
||
2. 检查 `.env` 中的 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 是否正确
|
||
3. 检查模板ID是否与微信公众平台一致
|
||
4. 查看后端日志是否有微信API调用错误
|
||
|
||
```bash
|
||
# 查看微信通知相关日志
|
||
tail -f /path/to/backend/logs/app.log | grep -i "wechat\|subscribe"
|
||
```
|
||
|
||
### 3. Tab 角标不显示
|
||
|
||
**症状**：小程序 Tab 上没有显示数字
|
||
|
||
**排查步骤**：
|
||
1. 检查 `badge.js` 是否正确引入
|
||
2. 检查 API 接口是否正常返回数据
|
||
3. 在小程序开发者工具中查看 Console 日志
|
||
|
||
---
|
||
|
||
## 🔄 回滚方案
|
||
|
||
如果实时推送功能出现问题，可以快速回滚：
|
||
|
||
### 1. 禁用 WebSocket（保留原有功能）
|
||
|
||
编辑 `backend/app/main.py`，注释掉 WebSocket 路由：
|
||
|
||
```python
|
||
# 挂载 WebSocket 路由（不通过 api_router，直接挂载）
|
||
# app.include_router(ws_router) # 注释此行
|
||
```
|
||
|
||
### 2. 禁用微信推送
|
||
|
||
编辑 `backend/.env`，清空微信配置：
|
||
|
||
```env
|
||
WECHAT_APP_ID=
|
||
WECHAT_APP_SECRET=
|
||
```
|
||
|
||
### 3. 重启服务
|
||
|
||
```bash
|
||
sudo systemctl restart order-flow
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 配置文件清单
|
||
|
||
| 文件 | 说明 | 是否需要修改 |
|
||
|------|------|--------------|
|
||
| `backend/.env` | 后端环境变量 | ✅ 已配置完成 |
|
||
| `backend/app/core/pubsub.py` | Redis Pub/Sub | ❌ 无需修改 |
|
||
| `backend/app/api/ws.py` | WebSocket 端点 | ❌ 无需修改 |
|
||
| `backend/app/services/event_bus.py` | 事件总线 | ❌ 无需修改 |
|
||
| `frontend/mini-app/utils/subscribe.js` | 订阅消息授权 | ❌ 已配置模板ID |
|
||
| `frontend/mini-app/utils/badge.js` | Tab角标管理 | ❌ 无需修改 |
|
||
| `frontend/web-admin/src/utils/websocket.js` | Web端WebSocket | ❌ 无需修改 |
|
||
| `frontend/web-sales/src/utils/websocket.js` | Web端WebSocket | ❌ 无需修改 |
|
||
| `deploy/dda.gaowenbu.cn.conf` | Nginx配置 | ✅ 已添加WebSocket代理 |
|
||
| `deploy/ddy.gaowenbu.cn.conf` | Nginx配置 | ✅ 已添加WebSocket代理 |
|
||
|
||
---
|
||
|
||
## ✅ 部署完成检查清单
|
||
|
||
- [ ] Redis 服务运行正常
|
||
- [ ] 后端服务重启完成
|
||
- [ ] Nginx 配置已更新并重新加载
|
||
- [ ] Web端已重新编译并部署
|
||
- [ ] 小程序已上传新版本
|
||
- [ ] 访问 `https://dda.gaowenbu.cn/ws/status` 返回正常
|
||
- [ ] 创建测试订单，检查是否收到实时通知
|