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. 本地部署

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

# 安装依赖
npm install

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

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

# 启动服务
npm start

3. 使用便捷脚本

Windows:

cd push-receiver-service
start.bat

Linux/Mac:

cd push-receiver-service
chmod +x start.sh
./start.sh

或者从主项目目录:

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
   

📊 数据库设计

核心表结构

-- 推送消息主表
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 调用格式

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:

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:

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:

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}'

🔒 安全配置

环境变量配置

# 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. 定期备份数据

📈 监控和维护

健康检查

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

统计信息

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

日志监控

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

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

数据清理

# 清理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. 云服务器部署

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

2. Docker 部署

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

3. 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 数据库中，供后续业务处理使用。