akmon/push-receiver-service/DEPLOYMENT.md

# 🚀 推送消息接收服务部署指南

这个独立的推送消息接收服务专门用于接收和存储各种推送消息到 Supabase 数据库。

## 📋 服务概述

- **目的**: 专门接收推送信息的独立服务
- **数据库**: Supabase PostgreSQL
- **端口**: 3001 (可配置)
- **功能**: 接收、存储、去重、统计、监控推送消息

## 🚀 快速部署

### 1. 准备 Supabase 项目

1. **创建 Supabase 项目**:
   ```
   访问: https://supabase.com/dashboard
   点击: "New project"
   记录: Project URL 和 API Keys
   ```

2. **执行数据库脚本**:
   - 打开 Supabase Dashboard > SQL Editor
   - 复制并执行 `push-receiver-service/database/supabase-init.sql`

### 2. 本地部署

```bash
# 进入服务目录
cd push-receiver-service

# 安装依赖
npm install

# 配置环境
cp .env.supabase .env
# 编辑 .env 文件，配置您的 Supabase 信息

# 初始化数据库
npm run setup-supabase

# 启动服务
npm start
```

### 3. 使用便捷脚本

**Windows:**
```cmd
cd push-receiver-service
start.bat
```

**Linux/Mac:**
```bash
cd push-receiver-service
chmod +x start.sh
./start.sh
```

**或者从主项目目录:**
```bash
npm run push-receiver:setup    # 初始化
npm run push-receiver          # 启动服务
npm run push-receiver:test     # 运行测试
```

## 🌐 暴露的服务地址

启动成功后，推送接收服务将暴露以下地址：

### 本地开发
```
服务信息: http://localhost:3001/
健康检查: http://localhost:3001/api/health
推送消息: http://localhost:3001/api/push/message
批量推送: http://localhost:3001/api/push/batch
```

### 生产环境部署

1. **云服务器部署**:
   ```
   https://your-domain.com:3001/api/push/message
   ```

2. **反向代理 (推荐)**:
   ```
   https://your-domain.com/api/push/message
   https://push.your-domain.com/api/push/message
   ```

3. **Serverless 部署**:
   ```
   https://your-function-url/api/push/message
   ```

## 📊 数据库设计

### 核心表结构

```sql
-- 推送消息主表
push_messages (
    id,                    -- 消息唯一ID
    push_type,             -- 推送类型 (SOS, HEALTH, LOCATION, etc.)
    user_id,               -- 用户ID
    device_id,             -- 设备ID
    raw_data,              -- 原始数据 (JSONB)
    parsed_data,           -- 解析数据 (JSONB)
    received_at,           -- 接收时间
    processing_status,     -- 处理状态
    is_duplicate,          -- 是否重复
    source_ip,             -- 来源IP
    latitude, longitude    -- 地理位置
)

-- 其他支持表
push_types              -- 推送类型配置
message_processing_logs -- 处理日志
devices                 -- 设备信息
users                   -- 用户信息
system_stats           -- 系统统计
```

### 支持的推送类型

| 类型 | 说明 | 优先级 | 示例数据 |
|------|------|--------|----------|
| `SOS` | 紧急求救 | 1 | `{emergencyLevel: "HIGH"}` |
| `HEALTH` | 健康数据 | 3 | `{H: 75, O: 98, T: 36.5}` |
| `LOCATION` | 位置信息 | 4 | `{lat: 39.9042, lng: 116.4074}` |
| `ALERT` | 告警信息 | 2 | `{alertType: "fall", severity: "high"}` |
| `DEVICE_STATUS` | 设备状态 | 4 | `{status: "online", battery: 85}` |
| `ACTIVITY` | 活动数据 | 5 | `{type: "running", duration: 1800}` |

## 🔧 推送设备配置

### API 调用格式

```http
POST http://localhost:3001/api/push/message
Content-Type: application/json
X-API-Key: your-api-key

{
  "pushType": "HEALTH",
  "userId": "user_12345",
  "deviceId": "device_001",
  "H": 75,
  "O": 98,
  "T": 36.5
}
```

### 各种语言调用示例

**JavaScript:**
```javascript
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: 'user_12345',
        H: 105, O: 88
    })
});
```

**Python:**
```python
import requests

requests.post('http://localhost:3001/api/push/message', 
    headers={'X-API-Key': 'your-api-key'},
    json={'pushType': 'HEALTH', 'userId': 'user_12345', 'H': 105, 'O': 88}
)
```

**cURL:**
```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":"user_12345","H":105,"O":88}'
```

## 🔒 安全配置

### 环境变量配置

```env
# Supabase 配置
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# 安全配置
API_KEY=your-secure-api-key-2025
ALLOWED_ORIGINS=https://your-app.com,https://your-admin.com
RATE_LIMIT_MAX_REQUESTS=1000

# 服务配置
PORT=3001
LOG_LEVEL=info
```

### 生产环境安全建议

1. **使用强 API 密钥**
2. **配置 CORS 白名单**
3. **启用请求频率限制**
4. **使用 HTTPS**
5. **定期备份数据**

## 📈 监控和维护

### 健康检查

```bash
curl http://localhost:3001/api/health
```

### 统计信息

```bash
curl http://localhost:3001/api/stats
```

### 日志监控

```bash
# 查看日志
tail -f push-receiver-service/logs/supabase-push-service.log

# 查看错误日志
tail -f push-receiver-service/logs/supabase-push-service-error.log
```

### 数据清理

```bash
# 清理30天前的数据
curl -X POST http://localhost:3001/api/cleanup \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"days": 30}'
```

## 🚀 部署到生产环境

### 1. 云服务器部署

```bash
# 使用 PM2 管理进程
npm install -g pm2
pm2 start supabase-server.js --name "push-receiver"
pm2 startup
pm2 save
```

### 2. Docker 部署

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install --production
EXPOSE 3001
CMD ["node", "supabase-server.js"]
```

### 3. Nginx 反向代理

```nginx
location /api/push/ {
    proxy_pass http://localhost:3001/api/push/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

## 📞 故障排除

### 常见问题

1. **无法连接 Supabase**:
   - 检查 SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY
   - 确认网络连接正常

2. **API 调用失败**:
   - 检查 API_KEY 是否正确
   - 确认请求格式正确

3. **服务无法启动**:
   - 检查端口 3001 是否被占用
   - 查看错误日志获取详细信息

### 调试步骤

1. 运行测试脚本: `npm test`
2. 检查日志文件
3. 验证环境配置
4. 测试 Supabase 连接

---

## 📋 总结

这个推送消息接收服务提供了：

✅ **完整的推送消息接收和存储**  
✅ **基于 Supabase 的可扩展数据库**  
✅ **详细的日志和监控功能**  
✅ **安全的 API 访问控制**  
✅ **支持多种推送消息类型**  
✅ **重复消息检测和处理**  
✅ **批量消息处理能力**  
✅ **生产级的部署支持**  

推送设备或系统只需要向 `http://your-server:3001/api/push/message` 发送 POST 请求即可完成消息推送。所有消息都会被完整保存到 Supabase 数据库中，供后续业务处理使用。