Initial commit of akmon project
This commit is contained in:
405
push-receiver-service/README.md
Normal file
405
push-receiver-service/README.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 基于 Supabase 的推送消息接收服务
|
||||
|
||||
专门用于接收和存储各种推送消息到 Supabase 数据库的独立服务。
|
||||
|
||||
## 🌟 特性
|
||||
|
||||
- ✅ **基于 Supabase**: 使用 Supabase PostgreSQL 数据库
|
||||
- ✅ **推送消息接收**: 支持多种类型的推送消息（SOS、健康、位置、告警等）
|
||||
- ✅ **批量处理**: 支持单个和批量消息处理
|
||||
- ✅ **重复检测**: 自动检测和处理重复消息
|
||||
- ✅ **实时监控**: 提供详细的统计和监控功能
|
||||
- ✅ **安全保护**: API 密钥验证和请求频率限制
|
||||
- ✅ **完整日志**: 详细的操作日志记录
|
||||
- ✅ **优雅关闭**: 支持服务的优雅启动和关闭
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd push-receiver-service
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. 配置 Supabase
|
||||
|
||||
1. **创建 Supabase 项目**:
|
||||
- 访问 [https://supabase.com/dashboard](https://supabase.com/dashboard)
|
||||
- 点击 "New project" 创建新项目
|
||||
- 记录项目的 URL 和 API Keys
|
||||
|
||||
2. **⚠️ 重要：数据库适配说明**:
|
||||
- 本服务已适配现有的 `ak_users` 和 `ak_devices` 表
|
||||
- 推送消息相关表使用 `ps_` 前缀（`ps_push_messages`、`ps_push_types` 等）
|
||||
- 请确保现有的基础表已存在于您的 Supabase 项目中
|
||||
- 详细适配信息请查看 [`SUPABASE_ADAPTATION.md`](./SUPABASE_ADAPTATION.md)
|
||||
|
||||
3. **执行数据库初始化脚本**:
|
||||
- 在 Supabase Dashboard 中打开 "SQL Editor"
|
||||
- 复制 `database/supabase-init.sql` 文件内容
|
||||
- 粘贴到 SQL Editor 中并执行
|
||||
|
||||
4. **配置环境变量**:
|
||||
```bash
|
||||
cp .env.supabase .env
|
||||
```
|
||||
|
||||
然后编辑 `.env` 文件：
|
||||
```env
|
||||
SUPABASE_URL=https://your-project-ref.supabase.co
|
||||
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
|
||||
API_KEY=your-custom-api-key
|
||||
```
|
||||
|
||||
### 3. 初始化数据库
|
||||
|
||||
```bash
|
||||
node setup-supabase.js
|
||||
```
|
||||
|
||||
### 4. 启动服务
|
||||
|
||||
```bash
|
||||
node supabase-server.js
|
||||
```
|
||||
|
||||
服务将在 `http://localhost:3001` 启动。
|
||||
|
||||
## 📋 API 端点
|
||||
|
||||
### 基础信息
|
||||
|
||||
- **服务信息**: `GET /`
|
||||
- **健康检查**: `GET /api/health`
|
||||
|
||||
### 推送消息接收
|
||||
|
||||
- **单个消息**: `POST /api/push/message`
|
||||
- **批量消息**: `POST /api/push/batch`
|
||||
|
||||
### 数据查询
|
||||
|
||||
- **统计信息**: `GET /api/stats`
|
||||
- **消息列表**: `GET /api/messages`
|
||||
- **清理数据**: `POST /api/cleanup`
|
||||
|
||||
## 🔧 API 使用示例
|
||||
|
||||
### 发送单个推送消息
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3001/api/push/message \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"pushType": "HEALTH",
|
||||
"userId": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"deviceId": "987fcdeb-51a2-43d7-8f9e-123456789abc",
|
||||
"H": 75,
|
||||
"O": 98,
|
||||
"T": 36.5
|
||||
}'
|
||||
```
|
||||
|
||||
> **注意**: `userId` 和 `deviceId` 必须使用 UUID 格式，且必须是现有 `ak_users` 和 `ak_devices` 表中的有效记录。
|
||||
|
||||
### 发送批量推送消息
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3001/api/push/batch \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"messages": [
|
||||
{
|
||||
"pushType": "SOS",
|
||||
"userId": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"emergencyLevel": "HIGH",
|
||||
"lat": 39.9042,
|
||||
"lng": 116.4074
|
||||
},
|
||||
{
|
||||
"pushType": "HEALTH",
|
||||
"userId": "456e7890-e89b-12d3-a456-426614174001",
|
||||
"H": 80,
|
||||
"O": 95
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### JavaScript 调用示例
|
||||
|
||||
```javascript
|
||||
// 发送单个推送消息
|
||||
const response = await fetch('http://localhost:3001/api/push/message', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': 'your-api-key'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
pushType: 'HEALTH',
|
||||
userId: '123e4567-e89b-12d3-a456-426614174000',
|
||||
deviceId: '987fcdeb-51a2-43d7-8f9e-123456789abc',
|
||||
H: 105,
|
||||
O: 88
|
||||
})
|
||||
});
|
||||
|
||||
const result = await response.json();
|
||||
console.log('推送结果:', result);
|
||||
```
|
||||
|
||||
### Python 调用示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# 发送单个推送消息
|
||||
response = requests.post('http://localhost:3001/api/push/message',
|
||||
headers={
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': 'your-api-key'
|
||||
},
|
||||
json={
|
||||
'pushType': 'HEALTH',
|
||||
'userId': 'user_12345',
|
||||
'H': 105,
|
||||
'O': 88
|
||||
}
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
print('推送结果:', result)
|
||||
```
|
||||
|
||||
## 📊 支持的推送类型
|
||||
|
||||
| 类型 | 说明 | 优先级 | 必需字段 |
|
||||
|------|------|--------|----------|
|
||||
| `SOS` | 紧急求救 | 1 (最高) | `userId` |
|
||||
| `ALERT` | 告警信息 | 2 | `userId`, `alertType` |
|
||||
| `HEALTH` | 健康数据 | 3 | `userId` |
|
||||
| `LOCATION` | 位置信息 | 4 | `userId` |
|
||||
| `DEVICE_STATUS` | 设备状态 | 4 | `deviceId` |
|
||||
| `ACTIVITY` | 活动数据 | 5 | `userId` |
|
||||
|
||||
## 🗄️ 数据库结构
|
||||
|
||||
### 主要数据表
|
||||
|
||||
1. **push_messages**: 推送消息主表
|
||||
2. **push_types**: 推送类型配置表
|
||||
3. **message_processing_logs**: 消息处理日志表
|
||||
4. **devices**: 设备信息表
|
||||
5. **users**: 用户信息表
|
||||
6. **system_stats**: 系统统计表
|
||||
|
||||
### 消息数据结构
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"push_type": "HEALTH",
|
||||
"user_id": "user_12345",
|
||||
"device_id": "device_001",
|
||||
"raw_data": { "完整的原始数据" },
|
||||
"parsed_data": { "解析后的结构化数据" },
|
||||
"received_at": "2025-06-25T10:30:00Z",
|
||||
"processing_status": "processed",
|
||||
"priority": 3,
|
||||
"is_duplicate": false,
|
||||
"source_ip": "192.168.1.100",
|
||||
"user_agent": "Device Client/1.0"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔒 安全配置
|
||||
|
||||
### API 密钥验证
|
||||
|
||||
在环境变量中设置 `API_KEY`：
|
||||
|
||||
```env
|
||||
API_KEY=your-secure-api-key
|
||||
```
|
||||
|
||||
所有 API 请求（除健康检查外）都需要在请求头中包含：
|
||||
|
||||
```
|
||||
X-API-Key: your-secure-api-key
|
||||
```
|
||||
|
||||
### 请求频率限制
|
||||
|
||||
- 默认：每分钟最多 1000 个请求
|
||||
- 可通过环境变量配置：`RATE_LIMIT_MAX_REQUESTS`
|
||||
|
||||
### CORS 配置
|
||||
|
||||
可通过 `ALLOWED_ORIGINS` 环境变量配置允许的来源。
|
||||
|
||||
## 📈 监控和日志
|
||||
|
||||
### 日志文件
|
||||
|
||||
- `logs/supabase-push-service.log`: 一般日志
|
||||
- `logs/supabase-push-service-error.log`: 错误日志
|
||||
- `logs/database.log`: 数据库操作日志
|
||||
|
||||
### 统计信息
|
||||
|
||||
访问 `/api/stats` 获取详细的统计信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"service": {
|
||||
"uptime": 3600,
|
||||
"requestCount": 150,
|
||||
"messageCount": 120,
|
||||
"errorCount": 2
|
||||
},
|
||||
"messages": [
|
||||
{
|
||||
"push_type": "HEALTH",
|
||||
"total_count": 80,
|
||||
"processed_count": 78,
|
||||
"failed_count": 2,
|
||||
"pending_count": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 环境配置
|
||||
|
||||
### 完整的环境变量配置
|
||||
|
||||
```env
|
||||
# 服务器配置
|
||||
PORT=3001
|
||||
HOST=0.0.0.0
|
||||
NODE_ENV=production
|
||||
|
||||
# Supabase 配置
|
||||
SUPABASE_URL=https://your-project-ref.supabase.co
|
||||
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
|
||||
|
||||
# 安全配置
|
||||
API_KEY=your-secure-api-key
|
||||
ALLOWED_ORIGINS=*
|
||||
RATE_LIMIT_MAX_REQUESTS=1000
|
||||
|
||||
# 日志配置
|
||||
LOG_LEVEL=info
|
||||
LOG_DIR=./logs
|
||||
|
||||
# 消息处理配置
|
||||
MAX_MESSAGE_SIZE=1048576
|
||||
BATCH_SIZE_LIMIT=1000
|
||||
ENABLE_DUPLICATE_CHECK=true
|
||||
|
||||
# 数据清理配置
|
||||
AUTO_CLEANUP_ENABLED=true
|
||||
AUTO_CLEANUP_DAYS=30
|
||||
```
|
||||
|
||||
## 🚀 部署
|
||||
|
||||
### Docker 部署
|
||||
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm install --production
|
||||
|
||||
COPY . .
|
||||
|
||||
EXPOSE 3001
|
||||
|
||||
CMD ["node", "supabase-server.js"]
|
||||
```
|
||||
|
||||
### PM2 部署
|
||||
|
||||
```bash
|
||||
npm install -g pm2
|
||||
pm2 start supabase-server.js --name "supabase-push-receiver"
|
||||
pm2 startup
|
||||
pm2 save
|
||||
```
|
||||
|
||||
### 云服务部署
|
||||
|
||||
支持部署到：
|
||||
- Vercel
|
||||
- Netlify
|
||||
- Railway
|
||||
- Heroku
|
||||
- AWS Lambda
|
||||
- 腾讯云函数
|
||||
|
||||
## 🛠️ 开发
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
push-receiver-service/
|
||||
├── lib/
|
||||
│ └── supabase-database.js # Supabase 数据库操作类
|
||||
├── database/
|
||||
│ └── supabase-init.sql # 数据库初始化脚本
|
||||
├── logs/ # 日志目录
|
||||
├── supabase-server.js # 主服务器文件
|
||||
├── setup-supabase.js # 数据库设置脚本
|
||||
├── package.json
|
||||
├── .env.supabase # Supabase 环境配置模板
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 测试 Supabase 连接
|
||||
node setup-supabase.js
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 🤝 业务集成
|
||||
|
||||
### 与现有系统集成
|
||||
|
||||
1. **配置推送地址**: 将设备或系统的推送地址指向此服务
|
||||
2. **设置API密钥**: 确保所有推送请求都包含正确的API密钥
|
||||
3. **监控日志**: 定期检查服务日志确保正常运行
|
||||
4. **数据分析**: 使用 Supabase Dashboard 或 API 进行数据分析
|
||||
|
||||
### 数据流处理
|
||||
|
||||
```
|
||||
设备/系统 → 推送消息 → 接收服务 → Supabase → 业务处理
|
||||
↓
|
||||
实时通知/告警
|
||||
```
|
||||
|
||||
## 📞 支持
|
||||
|
||||
如果您在使用过程中遇到问题：
|
||||
|
||||
1. 检查日志文件获取详细错误信息
|
||||
2. 确认 Supabase 配置正确
|
||||
3. 验证 API 密钥和网络连接
|
||||
4. 查看 Supabase Dashboard 的数据库状态
|
||||
|
||||
---
|
||||
|
||||
**注意**: 这是一个专门的消息接收服务，只负责接收和存储推送消息。业务逻辑处理需要另外实现。
|
||||
Reference in New Issue
Block a user